Immediate mode rendering can be invoked outside of a clump callback provided that
· An immediate mode context is established via RwImmediateBegin() and RwImmediateEnd().
· The rendering is within the RwBeginCameraUpdate() and RwEndCameraUpdate() cliché.
If either of these criteria are not fulfilled, the results of immediate mode rendering outside of a clump callback are undefined -- and could potentially lead to a crash.
Imperative immediate mode rendering should be initialised by a call to RwImmediateBegin().
This takes as a single parameter a pointer to a rectangle which defines the pixel area where Z-Buffering will occur. If this parameter is passed as NULL then no Z-Buffering can be performed.
If a valid rectangle is passed RenderWare will initialise the Z-Buffer in that area. The rectangle is specified in pixel space with (0,0) at the top left hand corner of the camera image irrespective of whether the camera's viewport is offset. Note that the initialisation costs CPU cycles. If Z-Buffering is not required a NULL rectangle should not be passed to ensure optimum performance. Also note that rendering of Z-Buffered polygons should only take place within the specified area. If this is exceeded, the Z-Buffer will contain uninitialised values and the result of the rendering is undefined.
Immediate mode rendering is terminated by RwImmediateEnd(), thereafter standard retained rendering techniques is re-established. Within the immediate mode context between RwImmediateBegin() and RwImmediateEnd() no calls can be made to retained rendering functions such as RwRenderClump() or RwRenderScene(). Thus if these functions are required it is necessary to `pop' and `push' the context with RwImmediateEnd() and RwImmediateBegin() respectively. For example:
RwImmediateBegin(NULL);
...
Perform some immediate mode rendering
...
RwImmediateEnd();
RwRenderClump(clump);
RwImmediateBegin(NULL);
...
Continue with immediate mode rendering
...
RwImmediateEnd();
is valid, whereas the following is not:
RwImmediateBegin(NULL);
...
Perform some immediate mode rendering
RwRenderClump(clump); /* Will not function correctly
!!!!!!*/
Immediate mode rendering cannot be continued.
...
RwImmediateEnd();