SDL port to Nintendo GameCube/Wii

This port uses the libogc library and is meant to be built with the devkitPPC toolchain, available from http://www.devkitpro.org

This project is a fork of the devkitPro/SDL repository1 which adds accelerated 2D operations and a few other improvements. I'm working to get these changes accepted upstream.

Installation instructions

It is strongly recommended to only use the pre-built packages available from the devkitPro repository, which can be installed via the pacman tool. This is the only supported way of using libSDL on the Nintendo GameCube/Wii.

Build instructions

If you need to hack on libSDL itself and you are aware that doing so can conflict with your devkitPro installation and even render it unusable, you can build it using the source code from this repository. Unfortunately, despite all our good intentions, it's unlikely that you'll get any more support than this README file itself. So, be warned that you are doing this AT YOUR OWN RISK.

Make sure you have setup the environment to build under devkitPro. This is typically done by running the command

source /etc/profile.d/devkit-env.sh

Then, libSDL can be built using the following commands:

source ${DEVKITPRO}/wiivars.sh
./autogen.sh  # this will print lots of warnings, hich are safe to ignore
./configure --prefix="${PORTLIBS_PREFIX}" \
    --host=powerpc-eabi \
    --disable-shared \
    --enable-static \
    --enable-nintendo-wii \
    ac_cv_header_signal=no \
    ac_cv_header_signal_h=no \
    ac_cv_func_sigaction=no
make
# To install the library into devkitPro's rootfs
sudo PATH=$PATH make install

Should these instructions become obsolete, please have a look at devkitPro's pacman recipe for SDL, which will probably give you a hint on how to update these manual build commands.

Usage hints

The SDL_FillRect and the SDL_BlitSurface are accelerated using the OGC/Wii GX graphic processor, but getting the best performance out of it requires understanding a few things:

1. Only operations to the main screen surface are currently accelerated.

2. Acceleration is only enabled if the SDL_HWSURFACE flag was passed to the SDL_SetVideoMode() function.

3. Blits are accelerated only if the source surface has the SDL_HWSURFACE flag, too.

4. Some libraries, such as SDL_ttf, generate surfaces that lack the SDL_HWSURFACE flag. In order to accelerated their blit, convert the surface to an accelerated one:

   SDL_Surface *s = TTF_RenderUTF8_Blended(font, text, color);
   // 's' is a software surface, its blit will be slow
   SDL_Surface *surface = SDL_DisplayFormatAlpha(s);
   SDL_FreeSurface(s);
   // The blit of `surface` to the screen will be accelerated

5. Calls to SDL_LockSurface() on the hardware surfaces have a strong negative impact on performance, because they require the surface to be reconverted from and to the GX texture format. If you really cannot avoid them, try at least to group them up so that they are not intervalled with accelerated calls.

6. Non accelerated blits are implemented by libSDL by software pixel operations performed after locking the surface, so what is written in the point above holds true for them, too. Make sure that all the surfaces that you blit to the main screen have the SDL_HWSURFACE flag set.

7. Palettized 8-bit mode and 8-bit textures have been poorly tested. If you encounter some issues, please file a bug.

8. To find out whether your blits are accelerated, you can set the SDL_OGC_DEBUG_ACCEL environment variable to "1" before initializing SDL, and then all the accelerated operations will be rendered only in half, as triangles; while this is obviously not suitable for the final product, this will give you a simple way to find out which operations are not accelerated while developing or fine-tuning your application: if they appear correctly on the screen (that is, as full rectangles), then they are not accelerated.

9. To quickly switch off hardware acceleration, you can set the SDL_OGC_DISABLE_ACCEL environment variable to "1".