Improved beginners guide

GRRLIB.html

@@ -2,6 +2,41 @@
 <!-- --------------------- This file is this wide -------------------------- -->
 <center><img src="grrlib_logo.png" /></center>
 <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
 ------------
 
@@ -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
 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
 the installation of the 'libjpeg' and 'libpngu' libraries.  'libpngu', in turn,
 requires 'libpng' and 'libpng' requires 'libz'.
@@ -34,9 +72,8 @@ reboot before you continue.
 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
 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.
 
 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
 libpng  is supplied as a precompiled library
 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
 order.
 
 libz comes preinstalled with devkitPro, so we can move directly to libpng...
 
-To install libpng
+To install libpng *2
   c:
   cd \grr\trunk\GRRLIB\lib\png
   make install
 
-Next up the list is libpngu
+Next up the list is libpngu *2
   c:
   cd \grr\trunk\GRRLIB\lib\pngu
   make clean
   make all
   make install
 
-Next up the list is libjpeg*
+Next up the list is libjpeg *2 *3
   c:
   cd \grr\trunk\GRRLIB\lib\jpeg
   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.
 
-Finally, we can now install libgrrlib
+After all three image processing libraries are installed, we can now install
+libgrrlib:
   c:
   cd \grr\trunk\GRRLIB\GRRLIB
   make clean
@@ -94,7 +138,7 @@ Using GRRLIB
 ------------
 
 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
 
 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
 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
 found in: C:\grr\trunk\examples\bluechip\composition
 ...This example also includes a "Makefile" which tries to make it clear what is
 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
@@ -138,13 +213,68 @@ will not be a hinderance
 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
 -------
 
 Project Leader : NoNameNo
-Documentation  : Crayon
+Documentation  : Crayon, BlueChip
 Lead Coder     : NoNameNo,
-Support Coders : BlueChip, DragonMinded, Xane
+Support Coders : Xane, DragonMinded, BlueChip
 Advisors       : RedShade