The immediate mode primitives provided by RenderWare are the triangle and the line. Rendering is controlled through an immediate mode rendering structure 'RwImmediate'.
All access to this structure should be performed with the built in RenderWare macros. Before being used, this structure to be 'set up' via one of the functions
void
RwSetupImmediateTriangle(RwImmediate *imm);
void
RwSetupImmediateLine(RwImmediate *imm);
These initialise the structure for immediate mode rendering. Thereafter, rendering may be controlled with the following macros:
Rendering Mode Types
There are three major rendering mode types:
RWSETIMMEDIATE3D(imm)
Vertices are specified in 3-D world space co-ordinates within a context created with RwImmediateBegin(), or in a clumps local space from within an immediate mode callback. Such vertices are automatically be transformed to pixel space before rendering. The vertex positions should be set with the RWSETIMMVERTEX3DX/Y/Z macros.
RWSETIMMEDIATE2D(imm)
Vertices are specified in 2-D pixel space co-ordinates. The vertex position should be set via the RWSETIMMVERTEX2DX/Y/Z and RWSETIMMVERTEXCAMERAZ macros. This vertex specification has some significant restrictions. Firstly RenderWare does not clip the object - the triangles or lines to be rendered must be wholly on screen otherwise the result is undefined and could lead to a crash. The other restriction is that additional rendering values may be required, such as the 'camera z' and the 'pixel z', depending on what type of rendering.
RWSETIMMEDIATEVERTICES(imm)
This mode of operation is only functional within an immediate mode callback. The polygons drawn are specified with reference to vertices within the clump. The boundary points of the polygon or line are specified by the indices of the vertices within the clump; indices are set with the macro RWSETIMMVERTEXNO. The characteristics of the vertices can be changed with RwGetClumpImmVertex() and the immediate mode vertex macros.
Texture Mapping In Immediate Mode
Vertex texture UV co-ordinates at vertices are specified differently in immediate mode to the retained mode specification calls such as RwVertexExt(). In previous releases of RenderWare which did not tile texture maps, a U value of 0 referred to the minimum U texel whilst a value of 1 meant the maximum U value. With the introduction of texture tiling the value of 1 changed to mean the first texel in the second tile of the texture. In other words, the [0,1] range which was previously inclusive at both ends is now inclusive below and exclusive above.
For example, with doubly inclusive texture co-ordinates:
(0,0) (1,0)
| |
V V
+--------------+
| |
| |
| |
| |
| |
| |
| |
+--------------+
But with texture tiling and texture co-ordinates exclusive above:
(0,0) (1,0)
| |
V V
+--------------+--------------
| |
| |
| |
| | 2nd repeat of texture
| |
| |
| |
+--------------+------------
| |
| 2nd repeat |
| of |
| texture |
| |
To provide backwards compatibility, the API slightly decreases values around 1.0 to the mid-point of the previous texel and increases values around 0 to the midpoint of the current texel.
When querying U and V co-ordinates in Immediate mode, the values returned are the actual values used for rendering. A value of 1.0 will be the first texel in the second repeat of the texture map.
Thus when setting U and V's in immediate mode:
With 128 by 128 textures
1.0 to the API means CFIX(1.0 - ((1.0/128)/2)) to immediate
mode
0.0 to the API means CFIX(((1.0/128)/2)) to immediate mode
With 256 by 256 textures
1.0 to the API means CFIX(1.0 - ((1.0/256)/2)) to immediate
mode
0.0 to the API means CFIX(((1.0/256)/2)) to immediate mode
Note the texture co-ordinate correction factor changes with the texture map texel size.
Rendering Mode Options
Rendering options in immediate mode may be set with RWSETIMMEDIATEMATERIAL(imm) For lines, this is restricted to the specification of light sampling frequency, rwFACET or rwVERTEX. For triangles the material defines the full gamut of rendering modes available in `retained mode' RenderWare. A NULL material -- the default when the RwImmediate structure is initialised -- specifies that the current material, that is the material returned by RwCurrentMaterial().
The material set in the RwImmediate structure may be queried with RWGETIMMEDIATEMATERIAL(imm). NULL indicates that the current material is being used.
An immediate rendering primitive to be Z-Buffered must be so enabled with the macro: RWSETIMMEDIATEZBUFFERON(imm) If there is a Z-Buffer set up then the immediate mode primitive will be rendered with Z-Buffering.
An immediate rendering primitive not to be Z-Buffered may be so identified with the macro: RWSETIMMEDIATEZBUFFEROFF(imm) Irrespective if whether a Z-Buffer is enabled or not, Z-Buffering will not occur thereafter on the immediate mode primitive.
The current state of whether the primitive is a candidate for Z-buffering is returned by the macro: RWGETIMMEDIATEZBUFFER(imm)
Vertex Characteristics
The L-value of a vertex structure within the immediate mode structure may be found with the macro: RWIMMVERTEX(imm, vert_no) Specifying vert_no 0 gives the first vertex in the structure. These RwImmVertex3d structures should be filled in if using the 2-D or 3d rendering modes.
· The x local or world co-ordinate space value is set with: RWSETIMMVERTEX3DX(ivV, nX)
· The y local or world co-ordinate space value is set with: RWSETIMMVERTEX3DY(ivV, nY)
· The z local or world co-ordinate space value is set with: RWSETIMMVERTEX3DZ(ivV, nZ)
· The x local or world co-ordinate space value is queried by: RWGETIMMVERTEX3DX(ivV, nX)
· The y local or world co-ordinate space value is queried by: RWGETIMMVERTEX3DY(ivV, nY)
· The z local or world co-ordinate space value is queried by: RWGETIMMVERTEX3DZ(ivV, nZ)
· The x pixel space co-ordinate value is set with: RWSETIMMVERTEX2DX(ivV, nX)
· The y pixel space co-ordinate value is set with: RWSETIMMVERTEX2DY(ivV, nY)
· The z pixel space co-ordinate value is set with: RWSETIMMVERTEX2DZ(ivV, nZ)
This latter value is used for Z-Buffering, and is also required by any perspectively correct texture mapping. This value can be found with RwImmZBufferDepth() if the camera space z value is known.
· The Z camera space co-ordinate value is set with: RWSETIMMVERTEX2DCAMERAZ(ivV, nZ) This value is required by any perspectively correct texture mapping.
· The x pixel space value is queried by: RWGETIMMVERTEX2DX(ivV)
· The y pixel space value is queried by: RWGETIMMVERTEX2DY(ivV)
· The z pixel space value, - The Z-Buffering value is queried by: RWGETIMMVERTEX2DZ(ivV)
· The z camera space value is queried by: RWGETIMMVERTEX2DCAMERAZ(ivV)
· The validity of the pixel space co-ordinates of a vertex may be tested with: RWISVERTEXVALID(ivV) The vertex must be one retrieved from a clump by RwGetClumpImmVertex(). A vertex is only valid if within the view frustrum. An invalid vertex can be forced into pixel space co-ordinates by RwImmVertexPixelSpace(). Once this has been called, the pixel space co-ordinates are guaranteed to be in the 2-D entries within the immediate mode RwImmVertex3d structure. Because an invalid vertex is not in the view volume, the screen space co-ordinates of such a point can have a negative value or be greater than the maximum camera width and height.
· When using an indexed color device -- one which uses an arbitrary palette -- the luminance of a vertex is set with: RWSETIMMVERTEXLUM(ivV, nL) The maximum luminance value can be queried by RwGetDeviceInfo() with the rwMAXLUMINANCE parameter. Any value between 0 and this value can be applied.
· When using an indexed color device -- one which uses an arbitrary palette -- the luminance of a vertex may be queried by RWGETIMMVERTEXLUM(ivV)
· When using a 'true color' device -- one which does not use a palette -- the luminance channels of a vertex are set with: RWSETIMMVERTEXRGB(ivV, nR, nG, nB)
· When using a 'true color' device -- one which does not use a palette -- the red luminance channel of a vertex may be queried by: RWGETIMMVERTEXRED(ivV) Similarly, the green luminance channel of a vertex may be queried by: RWGETIMMVERTEXGREEN(ivV) whilst the blue luminance channel of a vertex may be queried by: RWGETIMMVERTEXBLUE(ivV)
· Texture U and V co-ordinate values of a vertex are set with: RWSETIMMVERTEXTEXUV(ivV, nU, nV) These values should be no more than the devices maximum tiling value, which can be queried in the devices RwDeviceCapabilities structure.
· The Texture U co-ordinate value of a vertex may be queried by: RWGETIMMVERTEXTEXU(ivV)
· The Texture V co-ordinate value of a vertex may be queried by: RWGETIMMVERTEXTEXV(ivV)
Polygon and Line Characteristics
· When using an 'indexed color' device, a primitive's luminance is set with: RWSETIMMPOLYLUM(pPoly, nL) This will apply when the primitive is rwFACET light sampled -- i.e. 'flat' shaded.
· When using an 'indexed color' device, a primitive's luminance may be queried with: RWGETIMMPOLYLUM(pPoly) This is the luminance used when the primitive is rwFACET light sampled -- i.e. 'flat' shaded.
· When using a 'true color' device the red, green and blue luminance channels of the luminance of the primitive are set with: RWSETIMMPOLYRGB(pPoly, nR, nG, nB) These will apply when the primitive is rwFACET light sampled -- i.e. 'flat' shaded.
· When using a 'true color' device, the red channel of the primitives luminance may be queried by RWGETIMMPOLYRED(pPoly). Similarly, the green channel of the primitives luminance may be queried by RWGETIMMPOLYGREEN(pPoly) whilst, the blue channel of the primitives luminance may be queried by RWGETIMMPOLYBLUE(pPoly) These are the luminance values used when the primitive is rwFACET light sampled -- i.e. 'flat' shaded.