libogc/GX

From devkitPro
Revision as of 18:32, 17 March 2010 by Ccfreak2k (talk | contribs) (Fixed info on vtx fmt ordering.)
Jump to navigation Jump to search


THIS ARTICLE IS A WORK IN PROGRESS AND IS CURRENTLY NOT TO BE CONSIDERED AN AUTHORITATIVE SOURCE OF INFORMATION. YOU HAVE BEEN WARNED.

Preface

Some concepts in this article require some prerequisite knowledge about 3D programming in general, the GX API specifically or both. The NeHe OpenGL lessons are an excellent supplementary resource for learning the specifics of OpenGL and can work hand-in-hand with the OpenGL textbooks. libogc also has lessons 1 through 10 converted to the GX and gu APIs, so cross-referencing the source code for those lessons can help you understand what is going on.

You'll definitely need to have a handle on how to program in C, especially concerning things such as floating-point numbers and pointers, both of which are used heavily. The functions, compiler directives and other parts of the API are viewable in the Doxygen pages. Some functions have real documentation with them (the most often-used ones usually), but almost all of the GX Doxygen listings have no accompanying description, and you may find yourself having to wing it while learning and writing GX. If you get completely hung-up on how a particular function or block of functions affects the system, remember that Google is your friend; sometimes you can find the answer on the devkitpro forums (use site:forums.devkitpro.org in Google to search there); sometimes it can be found elsewhere (the wiibrew forums are sometimes useful, but avoid their wiki!), and sometimes you won't get any useful results at all. Hopefully, the Doxygen documentation will be expanded in time, but until then, you'll be put through a trial-by-fire.

This article was initially written by me, ccfreak2k. shagkur originally wrote most of the GX backend code in libogc, and as such could be considered the authority on the subject, but he has not been around for a while. As such, this article includes what I believe to be correct information, and is all the information I have compiled on the subject thus far. I have done my best to make sure that the information is as accurate as possible (since wrong information is worse than no information!). The examples provided with libogc are known to be correct implementations of GX, so defer to those if there's a conflict on how something works.

Most important of all, however, is that you understand how your code works. Becoming a cargo cult programmer is a bad idea, so make the effort to understand what you're writing and why you're writing it.

Introduction

Among the GameCube's many subsystems lies probably one of the biggest: GX. GX is the name of the API used to draw graphics using the famous Flipper chip.

When designing the GameCube, Nintendo wanted to address the problems that plagued programmers and their games on the Nintendo 64 system. One of the biggest is the texture cache. On the N64, the texture cache is a mere 4,096 bytes, which means that any given texture image needed to fit in the 4KB cache in order to be painted onto the surface. The appearance of a larger texture could be simulated through the use of clamping, but this had drastic performance implications (Conker's Bad Fur Day is a good example of this). The GameCube, on the other hand, has a texture cache 1MB in size, which allows for much larger and more detailed textures to be worked on at a time.

Much like the Nintendo 64, the GameCube's graphics hardware is tightly integrated with the memory controller and system memory, and it uses that memory extensively to store all of its assets. Of particular importance is the FIFO, which is a small section of RAM that is used to send commands from the CPU to the Flipper. This is typical for many personal computers as well, but the high-level APIs such as Direct3D completely mask this.

GX Setup and Particulars

GX shares some similarities with OpenGL, and differs greatly in many ways as well. OpenGL, by design, masks a lot of the nitty-gritty hardware specifics, leaving implementation of it to hardware vendors, whereas the GX API is very close to the metal and many functions have little, if any, processing performed by the CPU. What this means is that, if you write smart code and know how the hardware works under the hood, you can bring out the best performance of the machine, but you'll also be working with an API that is altogether more complex than writing in a higher-level API such as OpenGL.

Before you start initializing GX, you'll want to make sure you have the VIDEO subsystem set up. Almost every GameCube application that displays anything will do this. This includes allocating framebuffers and acquiring the TV screen attributes. Right after you have VIDEO set up is when you'll generally initialize GX.

To start, you'll need to allocate a "GP FIFO". The GP FIFO, or "graphics processor FIFO" is a portion of memory reserved for uploading commands to the GP. A FIFO is a type of pipe, but that's not necessary to know for now. To initialize the GX subsystem, you'll need to make some room for the FIFO, which you'll do like this: 

void *gp_fifo = NULL;
gp_fifo = memalign(32,DEFAULT_FIFO_SIZE);
memset(gp_fifo,0,DEFAULT_FIFO_SIZE);

The FIFO must be 32-byte aligned, which is what memalign() does. It's like malloc(), except it gives us a block of memory aligned to whatever alignment we specify. We also give DEFAULT_FIFO_SIZE as the size of memory that we want. The size of the FIFO required generally depends on how many commands you're dispatching per unit of time, but the default size is adequate in many cases. memset() clears the FIFO memory to 0 because allocated memory is uninitialized, and we don't want the GP to mistake garbage for commands. With that out of the way, it's time to switch on GX: 

GX_Init(gp_fifo,DEFAULT_FIFO_SIZE);

Here we give it a pointer to the FIFO and the size of the FIFO. From this point on, you probably won't be dealing with the FIFO anymore, as you'll be interfacing with the GP using the GX API now. What manner of initialization happens after this depends greatly on how you're using GX, but one function you'll generally use is this one: 

GXColor background = {0,0,0,0xff};
GX_SetCopyClear(background, 0x00ffffff);

This tells the GP to clear the screen to the specified background color at the beginning of every new frame, which will eliminate the "hall of mirrors effect" that would happen otherwise.

What happens after this will generally mirror initialization in OpenGL with some big exceptions, which we'll discuss below.

Attribute Slots

Many things in GX that can take different formats, such as vertex attributes or texture coordinate matrices, can be stored in slots. This lets you define all of your formats ahead of time and simply switch slots when required to load the stored formats. You're basically required to use at least one slot, even if you redefine the formats every time you change. You'll also find examples of slot usage peppered through this document and through example code, although I have yet to see any code that uses more than one slot. The biggest example involves the TEV, where you might have different settings for different textures, of which you can have eight textures per pass.

Vertex Initialization

One aspect of the close-to-the-hardware nature of GX is in vertex attributes. Before you start drawing triangles, you need to tell GX how they should be drawn. You'll generally do it like this: 

GX_InvVtxCache();
GX_ClearVtxDesc();

GX_SetVtxDesc(GX_VA_POS, GX_DIRECT);
GX_SetVtxDesc(GX_VA_NRM, GX_DIRECT);
GX_SetVtxDesc(GX_VA_TEX0, GX_DIRECT);

GX_SetVtxAttrFmt(GX_VTXFMT0, GX_VA_POS, GX_POS_XYZ, GX_F32, 0);
GX_SetVtxAttrFmt(GX_VTXFMT0, GX_VA_NRM, GX_NRM_XYZ, GX_F32, 0);
GX_SetVtxAttrFmt(GX_VTXFMT0, GX_VA_TEX0, GX_TEX_ST, GX_F32, 0);

GX_InvVtxCache() tells the GP to invalidate the vertex cache. You'll do this at least once as part of initialization, but it might also useful if, you, for example, want to change the scene, which may involve having completely different objects to be drawn.

The call to GX_ClearVtxDesc() clears the vertex attribute table, which is what is defined in the lines following that.

The GX_SetVtxDesc() calls tell the GP how we'll be providing the vertex data. We're specifying the format for vertex positions, normals and texture coordinates, respectively. GX_DIRECT in this context means we'll be specifying them using calls like GX_Position3f() (similar to glVertex3f()).

GX_SetVtxAttrFmt() tells the GP how we're going to specify the information for vertices. Specifically it's the same as the previous three (vertex position, vertex normal and texture coordinates), except we can specify different formats for different vertex format slots. For example, if you were drawing a HUD, you could store its vertex format in a different slot, then call that slot up when drawing the HUD instead of having to reload the vertex attributes yourself every time. You give the slot you want to use in an operation in the call to GX_Begin(), which is detailed below.

Drawing Triangles

The heart of drawing 3D shapes on the screen is more or less identical to OpenGL with a few changes. These steps are almost exactly the same as other primitives that GX supports, except you'd replace GX_TRIANGLES with the appropriate type.

After drawing is set up (textures loaded, matrices applied, etc), the drawing commands can be dispatched. You lead off with this: 

GX_Begin(GX_TRIANGLES,GX_VTXFMT0,3);

The first argument tells the GP what we want to draw. In this case, we're drawing triangles, i.e. every three vertices will be a single triangle on the screen. Other options for this are points, lines, line strip, triangle strip, triangle fan and quads. Which you use depends on what you're drawing and can have huge performance implications with high triangle counts.

The second argument is the vertex format to load. If you read through Vertex Initialization, you'd know that there are eight vertex format slots that you can use, and which one you want to use for that draw operation is specified here.

The last argument is the vertex count. This count must match the number of vertices that you are drawing. If this number is larger than the actual number of vertices that you specify, then the thread will hang as soon as GX_DrawDone() is called.

Once this call is made, you can call functions that give the specific information on each vertex. You need to have position for each, which you can call like this: 

GX_Position3f32(1.0f,0,0);

If you followed Vertex Initialization, you saw that the vertex attribute example gave GX_POS_XYZ for the position vertex attribute, which means the vertices for this VA slot would be coordinates with three members, and here we're specifying the position coordinates for one of them. We would need to make two more of these calls so that we complete a triangle in addition to satisfy the vertex count we gave earlier. If you wanted to specify a normal for each vertex, you would make this call following the previous one: 

GX_Normal3f32(0,0,1.0f);

This works much like glNormal, except you need one of these for every vertex, as opposed to just once as in OpenGL. The same goes to calls to GX_Color*() and GX_TexCoord*(). Each call to a vertex attribute must match the order: Position, normal, color, texcoord.

After you have made the appropriate draw calls, you close it with this: 

GX_End();

In your first GX programs, you might only have a very basic draw block that might only draw a single triangle with three vertices, and you might loop that block for every triangle you want to draw. In these cases, the above lines are sufficient. Obviously, the coordinate values would probably be read from a variable rather than declared statically if you're loading objects at run-time.

Textures

Textures are normally provided in so-called TPL format. These are converted at compile-time to the appropriate format and linked into the final application in binary format. The build system has the necessary configuration already present to handle this. neheGX lessons with textures (such as lesson 5) have a makefile with the necessary lines present to handle conversion.

Accompanied with such TPL files are SCF files. These are XML files which have a list of textures. So far, I have only specified one texture per SCF file, like this: 

<filepath="Mud.bmp" id="mud" colfmt=4 />

filepath is the path, relative to the texture directory, to the image file to be converted. id is the ID to use to identify the texture in code when loading it into GX. colfmt tells gxtexconv what format the resulting texture should be (for example, format 4 is RGB565).


If you are going to use textures the whole time (i.e. you're not intending to unload any textures), then you can use this method of texture loading. First, you'll need to include the headers for each texture. In my example, Mud.bmp, I need to include these: 

#include "mud_tpl.h"
#include "mud.h"

Next, you'll need to declare the texture's in-memory representation struct: 

TPLFile mudTPL;

When performing texture loading (usually some time after you've set up GX and the viewport), you'll use this structure to specify the texture in memory. After that, you'll need to "open" the TPL in memory: 

TPL_OpenTPLFromMemory(&mudTPL, (void *)mud_tpl,mud_tpl_size);

You know that mudTPL has already been declared, but unless you were to peek at the headers included earlier, you won't know where the last two arguments came from. They were generated by gxtexconv and are the binary array and array size, respectively. Now it's time to actually put the texture into a struct to pass on to the GX subsystem. First you'll need to declare the variable somewhere: 

GXTexObj texture;

Then you can load it in: 

TPL_GetTexture(&mudTPL,mud,&texture);

mudTPL is the TPLFile struct from earlier, mud is the ID that we gave in the SCF file and texture is the new GXTexObj struct. From now on, you won't be dealing with the TPL struct.

It is possible to make a texture loader to load images in from the storage media, but WinterMute recommends against this because it can cause severe memory fragmentation during the conversion process. If you decide to do this, the steps are different from the ones above, but the end result will be the same: a GXTexObj with the texture in it.

Now you'll want to make sure that the texture projection (its appearance on the surface) is correct, which we'll do this way: 

Mtx mv,mr;
f32 w = rmode->viWidth;
f32 h = rmode->viHeight;
GX_SetTexCoordGen(GX_TEXCOORD0, GX_TG_MTX3x4, GX_TG_TEX0, GX_IDENTITY);
guLightPerspective(mv, 45, (f32)w/h, 1.05f, 1.0f, 0.0f, 0.0f);
guMtxTrans(mr, 0.0f, 0.0f, -1.0f);
guMtxConcat(mv, mr, mv);
GX_LoadTexMtxImm(mv, GX_TEXMTX0, GX_MTX3x4);
GX_InvalidateTexAll();

GX_SetTexCoordGen() tells the graphics hardware how the texture coordinates should be generated; in other words, it tells the hardware how the textures should appear on the surface. In this example, we're telling it that texture 0 (remember that the hardware can handle eight textures per pass) uses a 3x4 identity matrix, which means that no special transformations should be performed while painting the textures. GX_IDENTITY can alternatively be GX_TEXMTX0 through GX_TEXMTX9 if you want to apply a matrix to a texture.

The calls to guMtxTrans() and guMtxConcat() transform the texture matrix to match our viewpoint. They're subsequently loaded using GX_LoadTexMtxImm() into the first texture matrix slot.

Finally, GX_InvalidateTexAll() tells the graphics hardware to invalidate the textures in its texture cache, which will cause it to reload textures from system memory. You need to call this every time you make a change to a texture.

Most neheGX lessons from 6 up load at least one texture and paint it onto a surface. You can find these lessons in $DEVKITPRO/examples/gamecube/graphics/gx/neheGX/.

Display Lists

Feeding in direct values works for your basic projects, but it can quickly grow out of control. A more intelligent way to handle draw operations, especially on large, complex meshes, is to use a display list. A display list is, basically, a series of commands for the GX to execute. It's exactly the same as what you did for drawing before, except now you're telling libogc to pack it into a concise list.

First you'll need to allocate a section of RAM to hold the list. This section, once again, needs to be 32-byte aligned. It also needs to be a multiple of 32 bytes in size: 

void *dispList;
dispList = memalign(32,640);
memset(dispList,0,640);

The exact size of the second argument to memalign() depends on which commands you're dispatching and how many of them you're dispatching. Each GX command takes a certain number of bytes in the FIFO. For example, GX_Begin() costs three bytes. If you're certain about the size that you'll need, you can use a constant here; otherwise you'll either have to pick a big number or attempt to calculate it. This size must be a multiple of 32 AND be larger than the actual size of the list rounded up to 32 (for example, if your list is 131 bytes, allocating 160 bytes won't work). You'll also want to call memset() to zero out the memory.

You'll also need to flush out the CPU's data cache for this allocation, as the GP will need to be able to access the list: 

DCFlushRange(dispList,640);
DCInvalidateRange(dispList,640);

The first call flushes the data from the cache, which causes all of it to get written to memory immediately. The second call makes any subsequent writes to this memory range go straight to memory instead of being simply cached. Both of these take the same arguments: pointer to the memory range, and the size of the range. Once you do that, you'll need to begin writing to the display list like this: 

GX_BeginDispList(dispList,640);

The first argument is a pointer to memory you allocated earlier. The second argument is the size of the display list, padded to 32 bytes (this should probably be the same size as your memory allocation unless you allocated one big block). After you do this, subsequent commands will be routed into the display list instead of being painted immediately. This behaviour is known as "retained mode," as opposed to "immediate mode" which is what you were doing before. From here, you'll need to call GX_Begin() and the like to start "drawing" what you want to keep in the list, such as a box or a race car. When you're done, do this: 

u32 dispSize;
dispSize = GX_EndDispList();

GX_EndDispList()'s return value is somewhat important. A return value of 0 indicates that the display list size (given by argument 3 to GX_BeginDispList()) is insufficient for the number of commands that you've given it, so a larger list is required. A value greater than 0 represents the effective size of the display list. It's advisable to hold on to this number because you'll need it. If you don't allocate enough space, it's also possible for the return value to be very large (67108864 in my testing).

When you're ready to use the display list, you call a single function to "play back" the commands in the list: 

GX_CallDispList(dispList,dispSize);

The first argument is a pointer to the display list, just like when you created the list. The second argument is the size of the display list, which GX_EndDispList() conveniently gave to you. This call is basically equivalent to all the draw commands you gave earlier, except it's faster and cleaner. If you need to change anything about the object (like a vertex color), you'll need to rebuild the list. An alternative to this is to build multiple similar lists if you need to change only a few parameters.

The neheGX lesson 12 is an example application that uses display lists; it can be found in $DEVKITPRO/examples/gamecube/graphics/gx/neheGX/lesson12/.

FIFO Management

Up until now, you've probably only ever used one FIFO, which was initialized and connected for you during initialization (although you still allocated it yourself). It's not only possible to have multiple FIFOs allocated at the same time, but the CPU and GP don't necessarily need to be connected to the same one at the same time. When the CPU and GP are connected to different FIFOs, it's known as multi-buffered mode (in contrast to immediate mode, which is where they both currently share a single FIFO).

For each new FIFO that you want to use, you'll need to allocate the object for it (using GXFifoObj) as well as some space for the FIFO itself.

In addition, as with any type of pipe, it's possible to overflow it, in this instance with too many commands or too much data. Fortunately, however, the GX API handles flow control for you automatically. When the buffer becomes too full, the GX system stops sending commands. When it becomes nearly (or completely) empty, it will resume sending commands. The function GX_InitFifoLimits() lets you adjust the high and low thresholds for this. Flow control is only active in immediate mode; you're expected to not to overflow a buffer that the GP isn't connected to.

Performance Optimization

There's many ways to optimize GX performance, usually dealing with redundant calls or eliminating calls if data between frames doesn't change (for example, you can save the view matrix after transformations and only create a new one if the viewpoint changes). One way you can optimize is by creating a separate thread for GX drawing operations. This can help if your other threads are almost always busy, such as if, for example, they're keeping track of the game state or managing AI. As soon as any thread is done with any work, it can put itself to sleep until new work can be done, which allows your other threads more CPU time to finish their work. How to use threading in libogc is not discussed here; however, here are some things to keep in mind if you decide to move your rendering code to a separate thread:

  • Use message passing to communicate render state changes. For example, if a new object needs to be rendered, use the message-passing interface of libogc to pass the pointer to the new object and have your rendering thread dereference it and read in the data, passing it to its drawing routines. Additionally, you can also use message passing to tell the render thread when an object should NOT be rendered anymore.
  • Use scheduling, sleep/wakeup and callbacks to your advantage. If your rendering thread is done with its drawing, it should sleep until the next frame. VIDEO_WaitVSync() will put the calling thread in a wait state until the next vertical interrupt occurs, where it will then be woken up.

Even if you're not using a seperate rendering thread, there are other ways to optimize:

  • Compress your textures. This doesn't necessarily increase performance, but if a texture is going to be, say, applied to a wall, you can decrease its in-memory size by setting colfmt to 14 in the SCF file, which converts the texture into a compressed format, much like DXT1. The cost for decompressing is nearly free, and the loss of quality isn't too dramatic, so it's definitely worth it if you're up against the wall.
  • Only call functions when you need to. For example, setting up a texture to be painted only needs to occur once per texture. Uploading a texture (using GX_LoadTexObj()) also only needs to occur once unless you need to upload a new one or a new version of an already-uploaded texture (in which case you need to invalidate it from texture cache too).
  • Use indexed instead of direct data. Data fed to the GP directly takes space in the FIFO, which imposes a limit on the bandwidth available for commands. In addition to freeing up bandwidth for commands by defering vertex loads, the GP will cache vertices that are indexed, which doesn't happen for direct data.
  • Use GX_SetGPMetric() and friends to clock events. These functions have almost zero documentation right now, but they might come in handy if you can find out how to use them.

Matrix Math

Although not strictly related to the GX API, matrices are a big part of 3D graphics, as their versatility is well-suited to the types of operations performed when transforming, such as moving the camera around. libogc includes hand-written assembly routines for matrix math that utilize the Gekko CPU's paired-single instructions, making such operations blazing fast as well. If you need a primer on how matrix math works, take a look at the article here: http://www.gamedev.net/reference/articles/article877.asp

If you are experienced with OpenGL, you'll probably be familiar with functions like glRotate and glTranslate. These types of functions are not present in libogc; you'll need to construct the appropriate chain of matrix functions to do the same thing. Fear not, however, as the matrix functions you'll use instead are very intuitive and aren't too much more difficult.

In your applications, or at least your early ones, matrices transform things such as your viewpoint in two ways: translation and rotation. Translation is the "panning" of something and "rotation" is the spin of it. For example, let's say we want to rotate the camera horizontally to represent the player looking left and right in a level. You might start with this code: 

guVector axis;
Mtx m,v,mv;

axis is a vector (an array with three elements) which will represent the axis that we want to rotate on, and m, v and mv are the matrices that represent the rotation, our view, and the combination of both. Specifically, m represents the new matrix that we're going to get the rotation from, and v is our current view matrix (i.e. it's the matrix that represents where our "camera" is pointing in the world). v is usually already declared and assigned earlier as our view matrix, but here I declared it for the purpose of demonstrating its presence. As per the linked article above, we need to start with a "neutral" matrix, which is the "identity". You'll use this to set it up: 

guMtxIdentity(m);

This sets the given matrix to an identity matrix, and is basically equivalent to initializing it before using it. Next we need to apply the appropriate transformation; in this case, we're going to rotate, say, 90 degrees laterally: 

axis.x = 1.0f;
axis.y = 0;
axis.z = 0;
guMtxRotAxisDeg(m, &axis, 90);

The first argument, m, is our matrix-to-be-rotated. The second argument, axis, tells by what percentage we should rotate on which axes. The last argument, 90 in this case, is the number of degrees to rotate. You would rotate the same amount if axis.x was 0.5 and degrees was 180. In reality, this is actually a wrapper function that changes degrees to rads and then applies it, but this happens behind the scenes. Finally, we need to actually apply this rotation to our view matrix so that the changes are visible. We'll use this function to do that: 

guMtxConcat(m,v,mv);

This function concatenates the matrices m and v together and gives the output in mv. Since mv is the result, we should use it when applying the transformation to our scene instead of v.

Translation would work the same, but there's a shortcut we can use. If we want to translate mv, we can do this: 

xtrans = 1.0f;
ytrans = 0;
ztrans = 0;
guMtxTransApply(mv, mv, xtrans, ytrans, ztrans);

xtrans, ytrans and ztrans are floats that represent the amount that we want to translate in each direction. The trick here is that the source and destination matrix are the same, so we reduce the complexity and number of operations. If mv is our view matrix, we'll need to actually apply it, which we'll do here: 

GX_LoadPosMtxImm(mv, GX_PNMTX0);

This tells GX to load the matrix into the first position matrix slot, of which we have ten. For any position operations done from this point forward, this matrix will be applied to the vertices. Remember that this matrix needs to be updated any time the view changes; otherwise the view will stay the same.

These operations are largely the same for any other matrix transformation, such as for textures or lighting.

Lighting

Much of the information in this section is taken from gl2gx's project wiki, and some of it is derived from code.

Lighting in GX is different from OpenGL. While OpenGL has diffuse, ambient and specular colors, as well as a global ambient color, GX only has diffuse light colors. Additionally, OpenGL has diffuse, ambient, specular and emission material colors, whereas GX has diffuse and ambient.

Retrieved from "https://devkitpro.org/wiki/w/index.php?title=libogc/GX&oldid=263"