
Klimt for GP32
==============

1. What's new, doc?
----------------------------

- 0.1.9
  -----
   Unstable version for testing
   Based on Klimt's cvs (September 2004)
   Ready for Mr.Mirko SDK 0.90
   Optimized ARM math library merged in (speed boost)
   "shapes" example disabled (working weird)
   "torus" example included (klimt demo)
   FPS counter added to most examples
   Toggle Color correction in most examples by using B button

- 0.1
  ---
   First public version
   Based on Klimt 0.6.1
   Using Mr.Mirko's SDK ver 0.85
   Basic OpenGL funcionality
   Portrait mode
   Conversion to RGB555 color mode with the "torgb555" user space external function



2. About
--------

Klimt for GP32 is a port of Klimt, the 3D graphics library for mobile devices, to the
GP32 console made by Gamepark.

The target of this port is to give the GP32 the ability to work with 3D graphics using
the popular API OpenGL, which Klimt does indeed implement.

Klimt was originally developed for small handheld devices (PocketPC, Smartphone, ...) but
with enough math and horsepower to process 3D graphics operations. Many of these devices
have a lot in common with the GP32 (ARM9 processor, 8 MB of RAM, ...) so porting Klimt to
the GP32 seemed doable and obvious.

Klimt for GP32 relies heavily in Mr.Mirko's SDK replacement and in a cross-compiling to ARM
environment based on GCC and another free (as in speech and beer) tools.

As the software in which it's based, Klimt for GP32 es entirely Free (as in speech) Software
and it is released and protected under the GPL license made by the Free Software Foundation.

The main motivation for porting Klimt to the GP32 was to make easy for my fellow graphic
programmers at my scener group (Necrostudios) to develop demos for the console, allowing it
to "understand their own language" :-) Of course, the same idea of being able to code the
GP32 using OpenGL will become interesting by itself, I pressume :-)



3. Installation & Setup
-----------------------

In order to develop with Klimt for GP32, a cross-compiling environmente based on a recent
version of GCC is needed. Mr.Miko's SDK is also needed in order to handle all the platform-
dependant issues. Both must be compiled supporting floating point math operation done
BY SOFTWARE (-msoft-float).

It's quite a good step to use the automated script for setting up the environment that
Mr.Mirko has in his own webpage.

At the moment of this writing, Klimt for GP32 has been successfully built in computers using
the Linux OS over PowerPC G4 and AMD K7 processors or using Windows in conjuction with the
Cygwin environment. Right now, I honestly don't know if it will work on other platforms, I
haven't tested it.

The first thing to do is to set up Mr.Mirko's SDK for it to compile programs correctly using
Klimt for GP32 (if it hasn't already been done). Inside the lib.src/ directory we'll find the
sources. Besides, divided in subdirectories inside that directory there are all the sub-parts
that conform the whole SDK. We should go inside each one of them and edit the Makefile file
for it to use some good compilation flags, for instance:

-s -march=armv4t -marm -msoft-float -ffast-math -fshort-enums -mstructure-size-boundary=8

We could also set one -O type flag for further optimization.

It is important to note that wherever assembler files are used, it is mandatory to specify
at least the -msoft-float cflag at the time of "compiling" those .S files.

Once fixed all the Makefile files, we go back to the lib.src/ directory an do:

make

And we go to the lib/ directory and do:

make

With this, the SDK should build itself, despite having a few compilation warnings showing up.

If the SMC access source code is not present, we can just copy it from a previous version of
the SDK (like 0.85) and uncomment the related Makefile files for it to compile.

Once we've finished with Mr.Mirko's SDK, we're ready to go with compiling Klimt for GP32.
At the root directory of the distribution we do:

cd klimt/build/GP32

There we have to again manually modify the Makefile file to adjust it to the correct
parameters of our system (specially the paths to the files). We clean and compile it:

make clean
make

That shoud do it for Klimt for GP32. We should have a fully working libKlimt.a compiled
for use with our GP32.



4. Examples
-----------

Inside the klimt/test/simple_gp32 directory there are several examples (some of them from
the excellent OpenGL tutorials from NeHe) of the use of the library and a rather self-
explanatory Makefile example (which you'll probably want to edit to make it fit in your
system) for compiling projects using both Klimt for GP32 and Mr.Mirko's SDK.

I've tried to code the examples as didactically as possible, although I know they lack a
lot of documentation, but I was supposed to focus on the code, right? ;-)

The "simple.cpp" example is a port of the basic Klimt test example where the 
"klutSolidCube" primitive is used for generating a cube.

The "shapes.cpp" example is a basic example from one of the first NeHe OpenGL Lessons
which shows a spinning couple of solid 3D figures with no texture.

The "glxgears.cpp" example is the classic testing program for OpenGL wich shows three
gears in movement. The figures can be rotated using the D-Pad from the console. Right
now, this example has some bugs.

The "texture.c" example is coded in C because Mr.Mirko's file access functions don't seem
to work quite well from C++ (at least I haven't been able to make them work :-)) . It is
based on another NeHe basic lesson (in fact it uses his texture) and shows four textured
cubes rotating while some old school music is played in the background. It does still have
some bugs too, most blatant is that the texture appears backwards and I don't exactly
know why. Remember to put in this case the .fxe file in the GP32 /GPMM directory with the
.bmp file containing the texture itself.

The "torus" example is a basic wireframe rendering example. It shows a torus that can be
rotated around its axis using the D button.

All the examples reset the console when the A button is pressed.
Color correction can be toggled on/off on most examples by pressing the B button.



5. Thanks & Greetings
---------------------

This port would not have been possible without the priceless help from Corsario from TLOTB,
the king of 3D graphics in mobile devices ;-)

I'd also like to thank my scener group Necrostudios for all the help and support they've been
giving since I started the port at the Xplanada Party 2004.
Necrostudios is: Octal, Polge, Lemoniac, aTMsa, Piedachu, Slack, PPlux, Pixel and Maulo (that's
me :-)) .

As tradition rules, greetings to:
TLOTB
PPG
Alicante Zone
Lucera
Stravaganza
Threepixels
Zon@n
RGBA
Collapse
Insiders
Capsule
Dust Inc
Level 64
Unknown
Sector Omega
Concept
Spntz
xplsv
Polinux

My respect to:
Farbrausch
Future Crew
Ozone

Thanks to:
Corsario, 3D would not be the same without you ;-)
Anarchy, for being the force behind the GP32 scene in Spain and for selling me one :-)
Mr.Mirko, for his SDK
NeHe, for his lessons
Locke, for making something beautiful with my library :-)
uVe, for everything



6. Links & references
---------------------

www.gp32spain.com -- The place to go if you've got a GP32 and speak Spanish :-)
www.mirkoroller.de/gp32  -- Mr.Mirko's homepage, the great guru :-)
nehe.gamedev.net -- The best place to learn OpenGL
studierstube.org/klimt/ -- Klimt official homepage



Made by Maulo <maulo_AT_on.to>

