The Tile Accelerator (3D acceleration) really deserves its own book, but for completeness (and my hands are getting tired =) I'm just going to go over the basics of setting it up and the functions you use to do so. For more specific information, look around on the web for various documents describing the TA, and look in the examples. Hopefully this section can be more fleshed out in future versions.
The TA is exactly what it says: the screen in the PVR 3D chip is broken up into 32x32 pixel tiles. So in 640x480, you'd really have a 20x15 tile field, not a 640x480 pixel field. The PVR's 3D magic happens by taking each of these tiles along with a ``display list'' describing what is to be displayed on the screen, and doing internal z-buffering. This means that each polygon is drawn only once, so even though there is not a standard z-buffer present, the end result looks like there is one. Opaque polygons, opaque volume modifiers (fog, etc), translucent polygons, translucent modifiers, and punch-through polygons (which can ``cut'' pieces of other polygons out, I think) must be sent to the TA, in that order. Each list is rendered in that order as well, for each tile, and so the more lists you send, the slower the rendering process gets. Opaque polygons are the fastest obviously, followed by punch-throughs, translucent polygons, and then the volume modifiers.
Because of the tile system, there is no user clipping neccessary: the TA works backwards by intersecting polygons and volumes with each tile before rendering. The end result of all of this is that all you have to do as a user is cull out the completely useless polygons (if you feel like it), arrange things in polygon ``strips'' as much as possible, and then throw the various lists to the TA. Then sit back and wait for it to do its work.
The PVR chip is not magic: it is powerful and can accelerate the drawing process to an amazing degree, but it still draws in terms of screen coordinates. So it is really a fancy 2D accelerator with perspective correction support for textures, and z-buffering.
Coordinates in the PVR start at 0,0 (all coordinates are floating point numbers) and go to 640,480, in the normal mode. Any coordinates outside this will work but will be clipped. Z coordinates start at 0 and move out of the screen towards the viewer. As far as I can tell, in normal mode, it wants Z and not 1/Z (W). I may be wrong of course. I'm no 3D hardware expert.
All that being said, the basic operation goes something like this:
Holds all the internal rendering data for the page flipper and renderer. This is useful mainly if you want to do something like take a screen shot (you can find the current frame buffer).
The background plane polygon. The background plane is currently automatically a 640x480, three-point opaque polygon. I'm not even sure if you can change this. For the values to load into this, take a look at one of the 3D example programs. If you want to do color shifting you can change this on the fly.
A polygon header; this is always four flag long-words and four dummy words. The four dummy words are actually used with different types of shading and volume modifiers, but these are not supported yet in libdream. You should fill this structure directly (if you know what you're doing) or use ta_build_poly_hdr.
Represents a single opaque/colored vertex with floating point coordinates and ARGB values. Actually it works fine for translucent polygons also but the naming convention stuck.
Represents a single opaque/textured vertex with floating point coordinates and ARGB values. Actually it works fine for translucent polygons also.
The current working page (out of ta_page_values above).
Initializes the TA and prepares for page flipped 3D.
Sends one (or two) store queue(s) full of data to the TA.
Call before you start drawing a frame.
Sends one polygon header to the TA. This needs to be done when you want to change drawing modes; e.g., opaque color, opaque textured, translucent color, translucent textured.
Sends one vertex to the TA; this can be a vertex_oc_t or vertex_ot_t. Pass along the result of sizeof() on the vertex.
Sends the ``end of list'' marker to the TA. This ought to be used after all opaque polygons are sent, and again after all translucent polygons are sent.
Call after you've finished sending all data. This completes the rendering process in the alternate screen buffer and then waits for a vertical blank to switch to the new page.
Parameters omitted for brevity: int translucent, int textureformat, int tw, int th, uint32 textureaddr, int filtering. This builds a polygon header for you so you don't have to diddle with bitfields. Translucent should be one of TA_OPAQUE or TA_TRANSLUCENT. Textureformat needs to be one of the texture format constants or TA_NO_TEXTURE. This includes whether it's twiddled or not (for info on twiddled textures, look for the PVR E3 presentation online). The rest of the parameters are only relevant if textureformat is not TA_NO_TEXTURE. tw and th are the texture width and height, and must be powers of two between 8 and 1024. Textureaddr is the address within the PVR RAM that you loaded the texture, and it must be aligned on an 8-byte boundary. Filtering should be TA_NO_FILTER or TA_BILINEAR_FILTER. Note that bi-linear filtering is a fairly expensive operation unless you store your textures in the PVR RAM in twiddled format, in which case it's free.
Loads a texture into PVR ram at the given offset. ``size'' must be a multiple of 4 and will be rounded up if it's not already. A seperate function is required because the PVR requires you to send all texture data to 0xa4000000, not 0xa5000000. This must also be done after ta_init.
Maps a given PVR offset to a texture space. You should use this if you want to write directly into texture ram. Once again, it must be done after ta_init.