From GTAMods Wiki
Jump to navigation Jump to search

This page has notes on RenderWare's PS2All pipelines as used in GTA Vice City and San Andreas. GTA III uses the earlier PS2Manager pipeline which ist not discussed here; it was superseded by PS2All with RW 3.2.

For a description of the custom pipelines used in SA check out Rockstar PS2 pipelines.

The page is not a replacement for the PS2 specific user guide that comes with the RW SDK.


RW pipelines can be attached to both objects and materials. Object pipelines are attached to Atomics and WorldSectors (of which only the former are used by GTA). PS2 object pipelines always consist of a single PS2All node, material pipelines consist of a single PS2AllMat node. Both nodes can be configured by callbacks and various other things.

To render geometry the raw geometry data is sent to the VU1 together with other things like matrices, lighting data, material properties and other custom pipeline specific data. The geometry is then further processed by by a program running on the VU1 and kicked to the GS for rasterization. The VU program's job is to transform vertex data, perform lighting calculation, clip or cull triangles and kick off the geometry to the GS. More complicated pipelines may do more than that like generating texture coordinates and rendering multiple passes to simulate reflections.

VU memory layout

The VU1 has separate data and instruction memory (Harvard architecture), each 16kb (= 1024 qwords) large.

VU transformation is done using a double buffer mechanism: there are two input buffers and at least two output buffers. Some data must be reserved for lighting, transformation etc. the rest is used for the input and output buffers. This non-vertex data occupies the high memory. In many pipelines the high memory starts at 0x3D0 with the light buffer, which extends to 0x3F0. The remaining 16 words are used for other constant data.

The size of the buffers depends on this high mark and the size/stride of the input and output vertices (measured in qwords, like everything). The input stride varies per pipeline but the output stride is almost always 3 (texture coordinates, vertex color, and position). Each output buffer has to include space not only for the vertices but also for the GIFtag to kick the geometry to the GS.

The two input buffers start at offsets 0 and vifOffset resepctively where vifOffset is the size of the input buffer. Double buffering is set up by pointing the BASE register to 0 and the OFFSET register to vifOffset at the beginning of a mesh; This switches the TOPS register -- the current input buffer's base address -- between BASE and OFFSET for every acitvation of the VU1 microprogram. The progam can query the last value of TOPS with the XTOP instruction.

Located above the input buffers are the output buffers. Their addresses are set up when the microprogram is first activated for a mesh and they are cycled by the program always after the execution of an XGKICK instruction (which kicks off a GIF packet).

With the size of the high memory, the number of output buffers and the vertex strides known, the maximum number of vertices to fit into these buffers and the buffer sizes can be calculated:

 vertexCount = (highMark-numOutputBuffers)/(2*inputStride + numOutputBuffers*outputStride)
 inputSize = vertexCount*inputStride

The configuration of the output buffers are more complicated when the VU1 program has to clip triangles because additional triangles are generated.

VIF transfers

To render geometry an object pipeline uploads the per-object data to the VU1:

  • Lighting data (a world to object space matrix and a list of lights)
  • Fog parameters
  • Camera(raster) parameters
  • Zbuffer parameters
  • Clipping parameters
  • An object- to clip-space matrix
  • A render state switch
  • Other custom pipeline data

Each mesh's material pipeline then uploads per-mesh data:

  • A GIF tag for the output geometry
  • The material color
  • The surface properties
  • Other custom pipeline data
  • The actual geometry batches

This is done by building a DMA chain. The geometry is referenced by a DMAcall tag, which ends with a DMAret tag after all geometry has been sent off. For the format of the geometry in this DMA sub-chain see PS2 Native Geometry.