Inside Macintosh: /

QuickDraw 3D RAVE / QuickDraw 3D RAVE Reference

QuickDraw 3D RAVE Routines / Manipulating Draw Contexts

QARenderStart

You can use the QARenderStart function to initialize a draw context before an engine performs any rendering into that context.

#define QARenderStart(drawContext,dirtyRect,initialContext) \
(drawContext)->renderStart (drawContext,dirtyRect,initialContext)

drawContext

A draw context.

dirtyRect

The minimum area of the specified draw context to clear, or the value NULL.

initialContext

A previously cached draw context, or the value NULL.

DESCRIPTION

The QARenderStart function performs any operations necessary to initialize the draw context specified by the drawContext parameter. This includes clearing the z buffer and the color buffers of the draw context. If the value of the initialContext parameter is NULL, then QARenderStart clears the z buffer to 1.0 and sets the color buffers to the values of the kQATag_ColorBG_a, kQATag_ColorBG_r, kQATag_ColorBG_g, and kQATag_ColorBG_b draw context state variables. If, however, the value of the initialContext parameter is not NULL, then QARenderStart uses the previously cached draw context specified by that parameter to initialize the draw context specified by the drawContext parameter.

The dirtyRect parameter indicates the minimum area of the specified draw context to clear on initialization. If the value of the dirtyRect parameter is NULL, the entire draw context is cleared. If the value of the dirtyRect parameter is not NULL, it indicates the rectangle in the draw context to clear. Some drawing engines may exhibit improved performance when an area that is smaller than the entire draw context rectangle is passed. However, the interpretation of the dirtyRect parameter is dependent on the drawing engine, which may choose to initialize the entire draw context. As a result, you should not use this parameter as a means to avoid clearing all of a draw context or to perform incremental rendering. Instead, you should use the initialContext parameter to achieve such effects.

SPECIAL CONSIDERATIONS

You should call QARenderStart before performing any rendering operations in the specified draw context, and you should call either QARenderEnd to signal the end of rendering operations or QARenderAbort to cancel rendering operations. However, when a drawing engine is performing OpenGL rendering, the QARenderStart function operates just like the OpenGL function glClear. In OpenGL mode, it is not necessary that a call to QARenderStart always be balanced by a matching call to QARenderEnd, and drawing commands may occur at any time.

SEE ALSO

See "Using a Draw Context as a Cache" (page 1-20) for information on creating a draw context cache (that is, a draw context you can use as the initial context specified in the initialContext parameter).