Improved beginners guide

This commit is contained in:
csBlueChip 2009-08-17 03:42:21 +00:00
parent 83b327e7f9
commit 7bc6b09a4f

View file

@ -2,6 +2,41 @@
<!-- --------------------- This file is this wide -------------------------- --> <!-- --------------------- This file is this wide -------------------------- -->
<center><img src="grrlib_logo.png" /></center> <center><img src="grrlib_logo.png" /></center>
<pre><b> <pre><b>
Table of Contents
-----------------
Introduction
...What is it?
Developing for the Wii
...How do I even start?
Downloading GRRLIB
...Where do I get it from?
Installing GRRLIB
...How do I get it to a useable state?
Using GRRLIB
...What essentials do I need to know to get going?
Upgrading to v4.1.0 From Previous Versions of GRRLIB
...I upgraded and now my programs won't compile properly!?
Error: guVector redefined
...How do I get rid of this error?
Using SVN
...
Credits
...Who do I thank for all this free stuff?
Licence
...When you say "free" do you actually mean something else?
Introduction Introduction
------------ ------------
@ -9,7 +44,10 @@ GRRLIB is a C/C++ 2D Graphics library for Wii application developers. It is
essentially a wrapper which presents a friendly interface to the Nintendo GX essentially a wrapper which presents a friendly interface to the Nintendo GX
core. core.
As of v4.10., GRRLIB is supplied as a standard C/C++ library (aka. archive) This document is written to be viewed with equal clarity in either a web browser
or a text editor.
As of v4.1.0, GRRLIB is supplied as a standard C/C++ library (aka. archive)
called 'libgrrlib'. Because GRRLIB processes JPEG and PNG images, it requires called 'libgrrlib'. Because GRRLIB processes JPEG and PNG images, it requires
the installation of the 'libjpeg' and 'libpngu' libraries. 'libpngu', in turn, the installation of the 'libjpeg' and 'libpngu' libraries. 'libpngu', in turn,
requires 'libpng' and 'libpng' requires 'libz'. requires 'libpng' and 'libpng' requires 'libz'.
@ -34,9 +72,8 @@ reboot before you continue.
Downloading GRRLIB Downloading GRRLIB
------------------ ------------------
You are advised to use "the latest SVN trunk version" of GRRLIB at all times. You are invited to use "the latest SVN trunk version" of GRRLIB at all times.
There is a simple guide to "Using SVN" here: There is a simple guide to "Using SVN" later in this document.
http://grrlib.santo.fr/forum/viewtopic.php?id=182
This document will presume that you have downloaded "the latest SVN trunk This document will presume that you have downloaded "the latest SVN trunk
version" to a directory called C:\grr\trunk version" to a directory called C:\grr\trunk
@ -48,41 +85,48 @@ This guide is for Windows. If you are using Linux, I am going to presume you
are smart enough to convert these instructions. are smart enough to convert these instructions.
GRRLIB is supplied as source code. GRRLIB is supplied as source code.
libjpeg is supplied as a precompiled library.* libjpeg is supplied as a precompiled library *1
libpngu is supplied as source code libpngu is supplied as source code
libpng is supplied as a precompiled library libpng is supplied as a precompiled library
libz is supplied with devkitpro (Ie. preinstalled) libz is supplied with devkitpro (Ie. preinstalled)
*The version of libjpeg supplied with GRRLIB v4.1.0 contains bug fixes not *1 The version of libjpeg supplied with GRRLIB v4.1.0 contains bug fixes not
available in the official release. If you can track down the original author, available in the official release. If you can track down the original
please tell him about these fixes. author, please tell him about these fixes.
Because of the way dependancies work, the libraries must be installed in reverse Because of the way dependancies work, the libraries must be installed in reverse
order. order.
libz comes preinstalled with devkitPro, so we can move directly to libpng... libz comes preinstalled with devkitPro, so we can move directly to libpng...
To install libpng To install libpng *2
c: c:
cd \grr\trunk\GRRLIB\lib\png cd \grr\trunk\GRRLIB\lib\png
make install make install
Next up the list is libpngu Next up the list is libpngu *2
c: c:
cd \grr\trunk\GRRLIB\lib\pngu cd \grr\trunk\GRRLIB\lib\pngu
make clean make clean
make all make all
make install make install
Next up the list is libjpeg* Next up the list is libjpeg *2 *3
c: c:
cd \grr\trunk\GRRLIB\lib\jpeg cd \grr\trunk\GRRLIB\lib\jpeg
make install make install
*The version of libjpeg supplied with GRRLIB v4.1.0 contains bug fixes not *2 A Windows batch-file and a Linux shell-script are included which will
install the libpng, libpngu and libjpeg libraries in a single command:
c:
cd \grr\trunk\GRRLIB\lib
install <- If you are using Linux, type `./install.sh` instead
*3 The version of libjpeg supplied with GRRLIB v4.1.0 contains bug fixes not
available in the official release. available in the official release.
Finally, we can now install libgrrlib After all three image processing libraries are installed, we can now install
libgrrlib:
c: c:
cd \grr\trunk\GRRLIB\GRRLIB cd \grr\trunk\GRRLIB\GRRLIB
make clean make clean
@ -94,7 +138,7 @@ Using GRRLIB
------------ ------------
After everything is installed, simply put After everything is installed, simply put
#include <grrlib.h> #include &lt;grrlib.h> <!-- #include <grrlib.h> -->
at the top of your .c file and use the functions as required at the top of your .c file and use the functions as required
You will also need to add You will also need to add
@ -105,13 +149,44 @@ other libraries in the middle of the list, you may need to add others to the
start, or even the end - but do _not_ change the order of the libraries shown start, or even the end - but do _not_ change the order of the libraries shown
here. here.
You do NOT need to placce /anything/ in your application directory. You do NOT need to place /anything/ in your application directory.
If you would like to see a working example of this, you can look at the example If you would like to see a working example of this, you can look at the example
found in: C:\grr\trunk\examples\bluechip\composition found in: C:\grr\trunk\examples\bluechip\composition
...This example also includes a "Makefile" which tries to make it clear what is ...This example also includes a "Makefile" which tries to make it clear what is
happening (unlike the more comprehensive cross-platform Makefile supplied with happening (unlike the more comprehensive cross-platform Makefile supplied with
the devkitPro template application). the devkitPro 'template' application).
Upgrading to v4.1.0 From Previous Versions of GRRLIB
----------------------------------------------------
Older versions of GRRLIB, required a line such as:
#include "../../../GRRLIB/GRRLIB/GRRLIB.h"
...to be placed at the top of each C file which uses GRRLB.
Because GRRLIB is now installed as a system library, this must be replaced with:
#include &lt;grrlib.h> <!-- #include <grrlib.h> -->
Older versions of GRRLIB required the 'GRRLIB.h' and 'GRRLIB.c" files to be
present in every project which uses GRRLIB.
Because GRRLIB is now installed as a system library, these files are no longer
required and must be erased.
*WARNING* Be careful if you have edited (either of) these files.
Older versions of GRRLIB "passed 'structs'" and therefore Textured Images were
defined with:
GRRLIB_texImg tex1, tex2;
Because GRRLIB now "passes 'pointers'" these definitions should be changed to:
GRRLIB_texImg *tex1, *tex2;
With older versions of GRRLIB if the programmer (you) required access to the
mode and frame information, you were required to add one or more of the
following three lines:
extern GXRModeObj *rmode;
extern void *xfb[2];
extern u32 fb;
Because GRRLIB now does this for you automatically, these lines must be removed
from your code.
Error: guVector redefined Error: guVector redefined
@ -138,13 +213,68 @@ will not be a hinderance
Thanks to Nicksasa for reporting this problem Thanks to Nicksasa for reporting this problem
Using SVN
---------
SVN stands for "SubVersioN" ...No it doesn't mean much to me either.
It allows the developers to submit changes to the code in such a way that
these changes can be easily monitored, quickly merged together with other
changes. and (if necessary) reverted.
It also allows the power-users to gain access to the latest (often "in-test")
features.
SVN is classically divided in to three chunks:
trunk - The main development & release code.
branches - Sometimes a developer may spend a week-or-more making their changes,
so (s)he will work in a copy of the code until the changes are
approved by the project leader ...then the changes are "merged" back
in to trunk.
tags - These are just copies of the code at critical points, such as
official releases.
GRRLIB conforms to this official guideline.
To obtain the "cutting edge" codebase (ie. the latest in SVN) you need an SVN
tool ...The same as: if you want to view a web page, you need a web browser
For Windows you will choose: TortoiseSVN
For Debian you will choose: apt-get install subversion
For others you will need to do a bit of research (I only use Debian & Windows)
Windows:
Create a directory to hold the code (Eg. C:\grr)
Right click it and choose "svn checkout"
Enter the URL of the SVN 'repository': http://grrlib.googlecode.com/svn/
Click the [...] button and choose the trunk*
Leave advanced options alone (Ie. fully recursive, head)
Hit OK
Linux:
Create a directory to hold the code (Eg. `mkdir -p /home/user/src/grr`)
Change to that directory (Eg. `cd /home/user/src/grr`)
type `svn checkout http://grrlib.googlecode.com/svn/trunk/ grrlib-read-only`*
* You may choose to check-out any part of the repository you wish, but if you
venture outide 'trunk' you are likely to get old or broken code.
If you network connection dies half-way through the download
Windows: ...simply right-click the directory again and choose "SVN Update"
Linux: ...Simply type `svn update`
You may also perform an "update" any time you like to get the latest & greatest
code changes. But be warned, if you have edited the GRRLIB source code things
can (and often do) get messy. The best help you can get about this is probably
here: http://svnbook.red-bean.com/en/1.1/svn-book.html#svn-ch-3-sect-5.4
Credits Credits
------- -------
Project Leader : NoNameNo Project Leader : NoNameNo
Documentation : Crayon Documentation : Crayon, BlueChip
Lead Coder : NoNameNo, Lead Coder : NoNameNo,
Support Coders : BlueChip, DragonMinded, Xane Support Coders : Xane, DragonMinded, BlueChip
Advisors : RedShade Advisors : RedShade