GRRLIB

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.4.0 From Previous Versions of GRRLIB
  • ...I upgraded and now my programs won't compile properly!?
• Using GitHub
  • ...What is this Git thing that the L337 devs keep talking about?
• Credits
  • ...Who do I thank for all this free stuff?
• Licence
  • ...When you say "free" do you actually mean something else?

Introduction

GRRLIB is a C/C++ 2D/3D graphics library for Wii application developers. It is essentially a wrapper which presents a friendly interface to the Nintendo GX core.

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'. GRRLIB has FileIO functions to allow real-time loading and saving of graphical data, and thus requires 'libfat'. GRRLIB also has the possibility to use TrueType fonts, so 'libfreetype' is also required.

libgrrlib          <- 2D/3D graphics library
├── libfat         <- File I/O
├── libjpeg        <- JPEG image processor
├── libpngu        <- Wrapper for libpng
│   └── libpng     <- PNG image processor
└── libfreetype    <- TrueType font processor

Developing for the Wii

Do not progress until you have installed and configured devkitPro. Guides are and assistance are available at https://devkitpro.org/index.php

If you have just performed a clean (re)install on your Windows PC, be sure to reboot before you continue.

Downloading GRRLIB

You are invited to use "the latest Git master version" of GRRLIB at all times.

The Git repository is located at: https://github.com/GRRLIB/GRRLIB

There is a simple guide to "Using GitHub" later in this document.

This document will presume that you have downloaded "the latest Git master version" to a directory called C:\grr

Installing GRRLIB

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
libpngu     is supplied as source code
libpng      is supplied via devkitPro pacman (ppc-libpng)
libfreetype is supplied via devkitPro pacman (ppc-freetype)
libjpeg     is supplied via devkitPro pacman (ppc-libjpeg-turbo)
libfat      is supplied via devkitPro pacman (libfat-ogc)

First, you need to make sure that all required library dependencies are installed. Install them with a single command:

  pacman --sync --needed --noconfirm libfat-ogc ppc-libpng ppc-freetype ppc-libjpeg-turbo

Go to the directory where the code was downloaded:

  c:
  cd \grr

To install GRRLIB with Make in a single command:

  make -C GRRLIB clean all install

If you prefer to use CMake, it can also be installed with a few commands:

  /opt/devkitpro/portlibs/wii/bin/powerpc-eabi-cmake -B build
  cmake --build build --target install

This process may take some time depending on the speed of your PC.

If you used the method above the following steps are not required, GRRLIB is installed and you are ready to start developing Wii homebrew games.

Each library could also be installed individually:

To install libpngu:

  cd GRRLIB\lib\pngu
  make clean all install

To install libgrrlib for Wii:

  cd GRRLIB\GRRLIB
  make clean all install

To install libgrrlib for GameCube:

  cd GRRLIB\GRRLIB
  make PLATFORM=cube clean all install

Using GRRLIB

After everything is installed, simply put

#include <grrlib.h>

at the top of your .c/.cpp file and use the functions as required

You will need to add

-lgrrlib -lpngu `$(PREFIX)pkg-config freetype2 libpng libjpeg --libs` -lfat

to the libs line in your makefile

...Remember the order of the libraries is critical. You may (need to) insert 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.

Also add $(PORTLIBS) to the LIBDIRS line in your makefile

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\examples\template\source

Upgrading to v4.4.0 From Previous Versions of GRRLIB

This version now uses the ported libraries for the Wii.

To install them, use this command line:

  pacman --sync --needed --noconfirm libfat-ogc ppc-libpng ppc-freetype ppc-libjpeg-turbo

You will need to add $(PORTLIBS) to the LIBDIRS line in your makefile.

Previously it could have looked like this:

LIBDIRS	:=

Now it needs to be like this:

LIBDIRS	:= $(PORTLIBS)

The FreeType library is now compiled with dependencies, so freetype2 must be added to pkg-config in your makefile.

For example:

LIBS	:= -lgrrlib -lpngu `$(PREFIX)pkg-config freetype2 libpng libjpeg --libs` -lfat

Since GRRLIB and libpngu are now installed into the porlibs folder, make sure you don't have any leftovers from previous installations. You will need to manually delete unneeded libraries in devkitPro\libogc\lib\wii as well as include files in devkitPro\libogc\include

Using GitHub

GitHub 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.

To obtain the "cutting edge" codebase go to https://github.com/GRRLIB/GRRLIB/tree/master

1. Create a directory to hold the code (e.g. C:\grr)
2. Click the Download ZIP button if you don't have the proper tools installed on your PC or Clone the following URL https://github.com/GRRLIB/GRRLIB.git

All official releases can be found here https://github.com/GRRLIB/GRRLIB/releases

Credits

Project Leader

• NoNameNo

Documentation

• Crayon
• BlueChip

Lead Coder

• NoNameNo

Support Coders

• Crayon
• Xane
• DragonMinded
• BlueChip
• elisherer

Advisors

• RedShade
• Jespa

Licence

GRRLIB is released under the MIT Licence. If we had chosen the GPL licence you would be +forced+ (legally required) to release your source code. But in the spirit of "free as in FREE" we have left you with the +option+ to release your source code.

We do +request+ that you tell others about us by naming our library (GRRLIB) in the credits of your game/application. And, if you +choose+ to do that, we encourage you to use our logo to achieve it; You can find our logo here: C:\grr\docs\grrlib_logo.png and here: https://grrlib.github.io/GRRLIB/grrlib_logo.png