Defined Types

typedef Q3_CALLBACK_API_C (TQ3Boolean, TQ3MacOSDialogEventHandler) (
    const EventRecord *theEvent
);

Discussion

Mac OS application event callback.

Modal renderer configure dialogs invoke this callback with events which are not handled by the dialog. If the application handles the event it should return kQ3True, or kQ3False to have the dialog pass the event to the system unhandled.

Parameter Descriptions

theEvent

The event to process.

function result

Did the application handle the event.

typedef Q3_CALLBACK_API_C (void, TQ3RaveDestroyCallback) (
    TQ3RendererObject theRenderer
);

Discussion

RAVE destroy callback.

Not supported in Quesa.

Parameter Descriptions

theRenderer

The renderer being destroyed.

typedef Q3_CALLBACK_API_C (void, TQ3XRendererCancelMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate
);

Discussion

Cancel the current rendering frame.

This method is invoked if a frame is cancelled within a rendering loop, and allows renderers to clean up as the current render is terminated.

This method is required.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererEndFrameMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    TQ3DrawContextObject theDrawContext
);

Discussion

Invoked by Q3View_Sync via Q3View_EndRendering to end the current frame.

This method is optional and should only be implemented by asynchronous renderers.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

theDrawContext

The draw context associated with the view.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3ViewStatus, TQ3XRendererEndPassMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate
);

Discussion

Invoked by Q3View_EndRendering to end the current pass.

The renderer should return kQ3ViewStatusRetraverse if the view should loop and submit another pass for the current frame, or kQ3ViewStatusDone if the scene has been rendered successfully.

If rendering was cancelled, this method will not be called and the view will return kQ3ViewStatusCancelled to the application.

This method is required.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

function result

The result for the view submit loop.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererFlushFrameMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    TQ3DrawContextObject theDrawContext
);

Discussion

Invoked by Q3View_Flush to flush rendering.

The renderer should flush the rendering of objects which have been submitted so far, and produce an image from the currently accumulated drawing state.

This method is optional and should only be implemented by asynchronous renderers.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

theDrawContext

The draw context associated with the view.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererGetConfigurationDataMethod) (
    TQ3RendererObject theRenderer,
    unsigned char *dataBuffer,
    TQ3Uns32 bufferSize,
    TQ3Uns32 *actualDataSize,
    void *rendererPrivate
);

Discussion

Get the renderer configuration data.

If dataBuffer is NULL, actualDataSize returns the size in bytes of a buffer which could receive the renderer data.

This method is optional.

Parameter Descriptions

theRenderer

The renderer object.

dataBuffer

Buffer to receive the renderer configuration data.

bufferSize

The number of bytes pointed to by dataBuffer.

actualDataSize

Receives the number of bytes written to dataBuffer.

rendererPrivate

Renderer-specific instance data.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererGetNickNameStringMethod) (
    unsigned char *dataBuffer,
    TQ3Uns32 bufferSize,
    TQ3Uns32 *actualDataSize
);

Discussion

Get the renderer "nick name".

The "nick name" is the user-visible name for the renderer, and should be suitable for display in a menu or window (e.g., it may need to be localised for the current language).

If dataBuffer is NULL, actualDataSize returns the size in bytes of a buffer which could receive the entire renderer nick name.

This method is optional.

Parameter Descriptions

dataBuffer

Buffer to receive the renderer nick name.

bufferSize

The number of bytes pointed to by dataBuffer.

actualDataSize

Receives the number of bytes written to dataBuffer.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3Boolean, TQ3XRendererIsBoundingBoxVisibleMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    const TQ3BoundingBox *theBounds
);

Discussion

Renderers should return a TQ3Boolean indicating whether the bounding box would affect the current rendering pass. This method is used for group culling.

This may simply require testing for intersection with the view frustum, as with Q3View_IsBoundingBoxVisible. Some renderers may require more complex tests. For instance, in some cases, an object outside the view frustum might contribute to the scene by reflections. In other cases, an object might be within the view frustum and yet not contribute to a lighting pass, due to being beyond the reach of the light.

This method is optional. If it is not supplied, Quesa will behave as if the method returned true.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

theBounds

The local bounding box to test.

function result

The visibility of the bounding box.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererModalConfigureMethod) (
    TQ3RendererObject theRenderer,
    TQ3DialogAnchor dialogAnchor,
    TQ3Boolean *wasCancelled,
    void *rendererPrivate
);

Discussion

Display a modal configure dialog for the renderer.

If the renderer provides a user interface for adjusting its preferences, a modal configure dialog can be displayed by this method.

The dialog should contain OK and Cancel buttons, and return the selected button through the wasCancelled parameter.

This method is optional.

Parameter Descriptions

theRenderer

The renderer whose configure dialog is to be displayed.

dialogAnchor

Platform-specific dialog data.

wasCancelled

Receives the OK/Cancel state of the dialog.

rendererPrivate

Renderer-specific instance data.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererPopMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate
);

Discussion

Pop the current renderer state.

Renderers which implement the RendererPush/RendererPop methods must maintain their own view state stack while rendering. If a renderer does not supply these methods, Quesa will automatically send the required state changes to implement a push/pop operation.

This method is optional.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererPushMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate
);

Discussion

Push the current renderer state.

Renderers which implement the RendererPush/RendererPop methods must maintain their own view state stack while rendering. If a renderer does not supply these methods, Quesa will automatically send the required state changes to implement a push/pop operation.

This method is optional.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererSetConfigurationDataMethod) (
    TQ3RendererObject theRenderer,
    unsigned char *dataBuffer,
    TQ3Uns32 bufferSize,
    void *rendererPrivate
);

Discussion

Set the renderer configuration data.

This method is optional.

Parameter Descriptions

theRenderer

The renderer object.

dataBuffer

Buffer containing the renderer configuration data.

bufferSize

The number of bytes pointed to by dataBuffer.

rendererPrivate

Renderer-specific instance data.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererStartFrameMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    TQ3DrawContextObject theDrawContext
);

Discussion

Invoked by Q3View_StartRendering to start a new frame.

The renderer should prepare to render another frame. This may require the initialisation of per-frame state, and the clearing of the draw context (depending on the draw context's clear method).

This method is required.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

theDrawContext

The draw context associated with the view.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererStartPassMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    TQ3CameraObject theCamera,
    TQ3GroupObject theLights
);

Discussion

Invoked by Q3View_StartRendering to start a new pass.

The renderer should prepare to render another pass of the current frame. This may require the initialisation of per-pass state, and setting up the renderer's camera and light representations for rendering.

This method is required.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

theCamera

The camera associated with the view.

theLights

The light group associated with the view.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3XFunctionPointer, TQ3XRendererSubmitCameraMetaHandlerMethod) (
    TQ3ObjectType cameraType
);

Discussion

Return the submit method for a camera type.

Renderers should return a TQ3XRendererSubmitCameraMethod to be invoked when a camera of the supplied type is used for rendering.

This method is optional.

Parameter Descriptions

cameraType

The camera type whose submit method is requested.

function result

The submit method for cameras of type cameraType.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererSubmitCameraMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    TQ3CameraObject theCamera,
    const void *publicData
);

Discussion

Submits a camera object for rendering.

Note that the camera used for rendering is also passed to the StartPass method.

This method is required.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

theCamera

The camera object being submitted, or NULL.

publicData

The public data for the camera being submitted.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3XFunctionPointer, TQ3XRendererSubmitGeometryMetaHandlerMethod) (
    TQ3ObjectType geometryType
);

Discussion

Return the submit method for a geometry type.

Renderers should return a TQ3XRendererSubmitGeometryMetaHandlerMethod to be invoked when a geometry of the supplied type is submitted for rendering. If a particular geometry type is not supported, return NULL.

Geometries which do not have their own submit method will be decomposed to more primitive geometry types, which will then be submitted as one of the following types (which all renderers must support):

kQ3GeometryTypeTriangle kQ3GeometryTypeLine kQ3GeometryTypePoint kQ3GeometryTypeMarker kQ3GeometryTypePixmapMarker

This method is required.

Parameter Descriptions

geometryType

The geometry type whose submit method is requested.

function result

The submit method for geometries of type geometryType.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererSubmitGeometryMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    TQ3GeometryObject theGeometry,
    const void *publicData
);

Discussion

Submits a geometry object for rendering.

If a geometry object is submitted in retained mode, theGeometry will be a valid geometry object and publicData will point to the public data structure describing that object.

If a geometry is submitted in immediate mode, theGeometry will be NULL and publicData will point to the data structure submitted for rendering.

Renderers should therefore try and render from the data contained in the publicData structure, however a reference to the geometry object may be useful (and can be retained if necessary, provided it is later released) in some circumstances.

This method is required.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

theGeometry

The geometry object being submitted, or NULL.

publicData

The public data for the geometry being submitted.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3XFunctionPointer, TQ3XRendererSubmitLightMetaHandlerMethod) (
    TQ3ObjectType lightType
);

Discussion

Return the submit method for a light type.

Renderers should return a TQ3XRendererSubmitLightMethod to be invoked when a light of the supplied type is used for rendering.

This method is optional.

Parameter Descriptions

cameraType

The camera type whose submit method is requested.

function result

The submit method for cameras of type cameraType.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererSubmitLightMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    TQ3LightObject theLight,
    const void *publicData
);

Discussion

Submits a light object for rendering.

Note that the light group used for rendering is also passed to the StartPass method.

This method is required.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

theLight

The light object being submitted, or NULL.

publicData

The public data for the light being submitted.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3XFunctionPointer, TQ3XRendererUpdateAttributeMetaHandlerMethod) (
    TQ3AttributeType attributeType
);

Discussion

Return the update method for an attribute type.

Renderers should return a TQ3XRendererUpdateAttributeMethod to be invoked when the state of the supplied attribute type is changed while rendering.

This method is optional.

Parameter Descriptions

attributeType

The attribute type whose update method is requested.

function result

The update method for attributes of type attributeType.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererUpdateAttributeMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    const void *publicData
);

Discussion

Update the the state of an attribute while rendering.

This method is optional.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

publicData

The public data for the attribute being submitted.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3XFunctionPointer, TQ3XRendererUpdateMatrixMetaHandlerMethod) (
    TQ3ObjectType matrixType
);

Discussion

Return the update method for a matrix type.

Renderers should return a TQ3XRendererUpdateMatrixMethod to be invoked when the state of the supplied matrix type is changed while rendering.

This method is optional.

Parameter Descriptions

matrixType

The matrix type whose update method is requested.

function result

The update method for matrices of type matrixType.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererUpdateMatrixMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    const TQ3Matrix4x4 *theMatrix
);

Discussion

Update the the state of a matrix while rendering.

This method is optional.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

publicData

The public data for the matrix being submitted.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3XFunctionPointer, TQ3XRendererUpdateShaderMetaHandlerMethod) (
    TQ3ObjectType shaderType
);

Discussion

Return the update method for a shader type.

Renderers should return a TQ3XRendererUpdateShaderMethod to be invoked when the state of the supplied shader type is changed while rendering.

This method is optional.

Parameter Descriptions

shaderType

The shader type whose update method is requested.

function result

The update method for shaders of type shaderType.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererUpdateShaderMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    TQ3Object *theShader
);

Discussion

Update the the state of a shader while rendering.

This method is optional.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

publicData

The public data for the shader being submitted.

function result

Success or failure of the callback.

typedef Q3_CALLBACK_API_C (TQ3XFunctionPointer, TQ3XRendererUpdateStyleMetaHandlerMethod) (
    TQ3ObjectType styleType
);

Discussion

Return the update method for a style type.

Renderers should return a TQ3XRendererUpdateStyleMethod to be invoked when the state of the supplied style type is changed while rendering.

This method is optional.

Parameter Descriptions

styleType

The style type whose update method is requested.

function result

The update method for styles of type styleType.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XRendererUpdateStyleMethod) (
    TQ3ViewObject theView,
    void *rendererPrivate,
    const void *publicData
);

Discussion

Update the the state of a style while rendering.

This method is optional.

Parameter Descriptions

theView

The view being rendered to.

rendererPrivate

Renderer-specific instance data.

publicData

The public data for the style being submitted.

function result

Success or failure of the callback.

© 1999-2008 Quesa Developers (Last Updated 5/10/2008)