Special care should be taken with the 2-D immediate rendering mode since this is the lowest level of rendering primitives in RenderWare, and therefore imposes the most obligations on the user. The important points for 2-D rendering are as follows:
· RenderWare performs no clipping during 2-D rendering. Any required clipping must be performed by the user. If a primitive is 2-D rendered of which any part is not within the camera viewport, the results are undefined and could lead to a crash.
· Z values at vertices are required for Z-Buffering and perspectively correct texture mapping. The `2-D' Z value (pixel space Z value) must be set before Z-Buffering. The value should be a/z where a is a constant and z is the camera space z value of the point mapping to the pixel. The determination of the `a' value is explained below.
· For perspectively correct texture mapping, BOTH the CAMERA Z AND the 2-D Z values must be set EVEN IF THE PRIMITIVE IS NOT Z-BUFFERED. Both these Z values are required by the perspectively correct texturing algorithm.
· When querying a clump's vertices in 2-D with RwGetClumpImmVertex(), the 2-D information will not be returned if the point is outside the viewing frustrum. This information can be found with RwImmVertexPixelSpace(), but the values returned will not be usable by RenderWare for 2-D rendering as they will be outside the cameras viewport.
Note: none of these problems apply for the other types of co-ordinates specification -- vertex number and 3-D co-ordinates -- as the appropriate values for these will be generated by RenderWare automatically.
Z-Buffer In Immediate Mode
When Z-Buffering with vertex numbers or 3d co-ordinates within an immediate mode callback or in an immediate mode context established by RwImmediateBegin(), the correct Z-Buffering values are automatically calculated. If Z-Buffering is required with 2-D vertex specifications then user input is required; in particular Z-Buffer values must be calculated for such vertices. A 2-D Z value can be calculated from a camera space Z value with the function:
RwFixed
RwImmZBufferDepth(RwCamera * cam, RwReal depth);
This should be applied before Z-Buffering within an immediate mode callback with the vertices specified in 2-D. It is important to call this function in preference to the RwGetDeviceInfo() method described later as the Z-Buffer values from RenderWare will be different from 'hand generated' Z-Buffer values. Note that the depth values passed must be within the range of the clump's bounding box in camera space. Depth arguments outside this range will produce incorrect Z values.
The effective Z-Buffering domain of this mapping may be tuned with the function:
void
RwSetImmediateZRange(RwReal nNear, RwReal nFar);
This function may be exploited when an immediate mode context is has been established between RwImmediateBegin() and RwImmediateEnd(). When RwImmediateBegin() is called, the effective Z-Buffering range will be between the near and far clipping planes of the camera associated with the RwBeginCameraUpdate() and RwEndCameraUpdate() cliché. This may be overly conservative if an object has thin Z range in camera space. In such circumstances the rendered image may contain artefacts due to the limited precision of the Z-Buffer. Tuning the effective Z-range to the actual Z-range occupied by the objects to be rendered optimises Z-Buffering to make full use of the available resolution.
There are lower level methods of setting Z-Buffer values. The minimum and maximum values stored in the Z-buffer can be found with RwGetDeviceInfo(). Given these values, a Z-Buffer value can be calculated over the depth range Rmin to Rmax for a perspective camera as :
and for a parallel camera as:
The zmax and zmin values can be queried with RwGetDeviceInfo() with rwMAXZBUFFERZ to return the maximum Z-Buffer value rwMINZBUFFERZ to return the minimum Z-Buffer value. Note the values returned are the entire range of values stored in the Z-Buffer. Any values supplied to RenderWare outside this range could cause incorrect rendering, particularly for large polygons.