1771 lines
55 KiB
C
1771 lines
55 KiB
C
/*
|
|
File: QD3DRenderer.h
|
|
|
|
Contains: Q3Renderer types and routines
|
|
|
|
Version: Technology: Quickdraw 3D 1.6
|
|
Release: QuickTime 7.3
|
|
|
|
Copyright: (c) 2007 (c) 1995-1999 by Apple Computer, Inc., all rights reserved.
|
|
|
|
Bugs?: For bug reports, consult the following page on
|
|
the World Wide Web:
|
|
|
|
http://developer.apple.com/bugreporter/
|
|
|
|
*/
|
|
#ifndef __QD3DRENDERER__
|
|
#define __QD3DRENDERER__
|
|
|
|
#ifndef __QD3D__
|
|
#include <QD3D.h>
|
|
#endif
|
|
|
|
#ifndef __QD3DSET__
|
|
#include <QD3DSet.h>
|
|
#endif
|
|
|
|
#ifndef __QD3DVIEW__
|
|
#include <QD3DView.h>
|
|
#endif
|
|
|
|
#ifndef __RAVE__
|
|
#include <RAVE.h>
|
|
#endif
|
|
|
|
|
|
#if TARGET_OS_MAC
|
|
#ifndef __EVENTS__
|
|
#include <Events.h>
|
|
#endif
|
|
|
|
#endif /* TARGET_OS_MAC */
|
|
|
|
|
|
|
|
#if PRAGMA_ONCE
|
|
#pragma once
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if PRAGMA_IMPORT
|
|
#pragma import on
|
|
#endif
|
|
|
|
#if PRAGMA_STRUCT_ALIGN
|
|
#pragma options align=power
|
|
#elif PRAGMA_STRUCT_PACKPUSH
|
|
#pragma pack(push, 2)
|
|
#elif PRAGMA_STRUCT_PACK
|
|
#pragma pack(2)
|
|
#endif
|
|
|
|
#if PRAGMA_ENUM_ALWAYSINT
|
|
#if defined(__fourbyteints__) && !__fourbyteints__
|
|
#define __QD3DRENDERER__RESTORE_TWOBYTEINTS
|
|
#pragma fourbyteints on
|
|
#endif
|
|
#pragma enumsalwaysint on
|
|
#elif PRAGMA_ENUM_OPTIONS
|
|
#pragma option enum=int
|
|
#elif PRAGMA_ENUM_PACK
|
|
#if __option(pack_enums)
|
|
#define __QD3DRENDERER__RESTORE_PACKED_ENUMS
|
|
#pragma options(!pack_enums)
|
|
#endif
|
|
#endif
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** User Interface Things **
|
|
** **
|
|
*****************************************************************************/
|
|
#if TARGET_OS_MAC
|
|
/*
|
|
* A callback to an application's event handling code. This is needed to
|
|
* support movable modal dialogs. The dialog's event filter calls this
|
|
* callback with events it does not handle.
|
|
* If an application handles the event it should return kQ3True.
|
|
* If the application does not handle the event it must return kQ3False and
|
|
* the dialog's event filter will pass the event to the system unhandled.
|
|
*/
|
|
typedef CALLBACK_API_C( TQ3Boolean , TQ3MacOSDialogEventHandler )(const EventRecord * event);
|
|
struct TQ3DialogAnchor {
|
|
TQ3MacOSDialogEventHandler clientEventHandler;
|
|
};
|
|
typedef struct TQ3DialogAnchor TQ3DialogAnchor;
|
|
#endif /* TARGET_OS_MAC */
|
|
|
|
#if TARGET_OS_WIN32
|
|
struct TQ3DialogAnchor {
|
|
HWND ownerWindow;
|
|
};
|
|
typedef struct TQ3DialogAnchor TQ3DialogAnchor;
|
|
#endif /* TARGET_OS_WIN32 */
|
|
|
|
#if TARGET_OS_UNIX
|
|
struct TQ3DialogAnchor {
|
|
void * notUsed; /* place holder */
|
|
};
|
|
typedef struct TQ3DialogAnchor TQ3DialogAnchor;
|
|
#endif /* TARGET_OS_UNIX */
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer Functions **
|
|
** **
|
|
*****************************************************************************/
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3Renderer_NewFromType()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3RendererObject )
|
|
Q3Renderer_NewFromType(TQ3ObjectType rendererObjectType);
|
|
|
|
|
|
/*
|
|
* Q3Renderer_GetType()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3ObjectType )
|
|
Q3Renderer_GetType(TQ3RendererObject renderer);
|
|
|
|
|
|
|
|
/* Q3Renderer_Flush has been replaced by Q3View_Flush */
|
|
/* Q3Renderer_Sync has been replaced by Q3View_Sync */
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
|
|
/*
|
|
* Q3Renderer_IsInteractive
|
|
* Determine if this renderer is intended to be used interactively.
|
|
*/
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3Renderer_IsInteractive()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Boolean )
|
|
Q3Renderer_IsInteractive(TQ3RendererObject renderer);
|
|
|
|
|
|
|
|
/*
|
|
* Q3Renderer_HasModalConfigure
|
|
* Determine if this renderer has a modal settings dialog.
|
|
*
|
|
* Q3Renderer_ModalConfigure
|
|
* Have the renderer pop up a modal dialog box to configure its settings.
|
|
* dialogAnchor - is platform specific data passed by the client to support
|
|
* movable modal dialogs.
|
|
* MacOS: this is a callback to the calling application's event handler.
|
|
* The renderer calls this function with events not handled by the
|
|
* settings dialog. This is necessary in order to support movable modal
|
|
* dialogs. An application's event handler must return kQ3True if it
|
|
* handles the event passed to the callback or kQ3False if not.
|
|
* An application which doesn't want to support a movable modal configure
|
|
* dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor.
|
|
* Win32: this is the HWND of the owning window (typically an application's
|
|
* main window).
|
|
* canceled - returns a boolean inditacating that the user canceled the
|
|
* dialog.
|
|
*
|
|
*/
|
|
/*
|
|
* Q3Renderer_HasModalConfigure()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Boolean )
|
|
Q3Renderer_HasModalConfigure(TQ3RendererObject renderer);
|
|
|
|
|
|
/*
|
|
* Q3Renderer_ModalConfigure()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3Renderer_ModalConfigure(
|
|
TQ3RendererObject renderer,
|
|
TQ3DialogAnchor dialogAnchor,
|
|
TQ3Boolean * canceled);
|
|
|
|
|
|
/*
|
|
* Q3RendererClass_GetNickNameString
|
|
* Allows an application to get a renderers name string, the
|
|
* renderer is responsible for storing this in a localizable format
|
|
* for example as a resource. This string can then be used to provide
|
|
* a selection mechanism for an application (for example in a menu).
|
|
*
|
|
* If this call returns nil in the supplied string, then the App may
|
|
* choose to use the class name for the renderer. You should always
|
|
* try to get the name string before using the class name, since the
|
|
* class name is not localizable.
|
|
*/
|
|
/*
|
|
* Q3RendererClass_GetNickNameString()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3RendererClass_GetNickNameString(
|
|
TQ3ObjectType rendererClassType,
|
|
TQ3ObjectClassNameString rendererClassString);
|
|
|
|
|
|
|
|
/*
|
|
* Q3Renderer_GetConfigurationData
|
|
* Allows an application to collect private renderer configuration data
|
|
* which it will then save. For example in a preference file or in a
|
|
* style template. An application should tag this data with the
|
|
* Renderer's object name.
|
|
*
|
|
* if dataBuffer is NULL actualDataSize returns the required size in
|
|
* bytes of a data buffer large enough to store private data.
|
|
*
|
|
* bufferSize is the actual size of the memory block pointed to by
|
|
* dataBuffer
|
|
*
|
|
* actualDataSize - on return the actual number of bytes written to the
|
|
* buffer or if dataBuffer is NULL the required size of dataBuffer
|
|
*
|
|
*/
|
|
/*
|
|
* Q3Renderer_GetConfigurationData()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3Renderer_GetConfigurationData(
|
|
TQ3RendererObject renderer,
|
|
unsigned char * dataBuffer,
|
|
unsigned long bufferSize,
|
|
unsigned long * actualDataSize);
|
|
|
|
|
|
/*
|
|
* Q3Renderer_SetConfigurationData()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3Renderer_SetConfigurationData(
|
|
TQ3RendererObject renderer,
|
|
unsigned char * dataBuffer,
|
|
unsigned long bufferSize);
|
|
|
|
|
|
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Interactive Renderer Specific Functions **
|
|
** **
|
|
*****************************************************************************/
|
|
/* CSG IDs attribute */
|
|
#define kQ3AttributeTypeConstructiveSolidGeometryID Q3_OBJECT_TYPE('c','s','g','i')
|
|
/* Object IDs, to be applied as attributes on geometries */
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
#define kQ3SolidGeometryObjNone (-1)
|
|
#define kQ3SolidGeometryObjA 0
|
|
#define kQ3SolidGeometryObjB 1
|
|
#define kQ3SolidGeometryObjC 2
|
|
#define kQ3SolidGeometryObjD 3
|
|
#define kQ3SolidGeometryObjE 4
|
|
/* Possible CSG equations */
|
|
enum TQ3CSGEquation {
|
|
kQ3CSGEquationAandB = (long)0x88888888,
|
|
kQ3CSGEquationAandnotB = 0x22222222,
|
|
kQ3CSGEquationAanBonCad = 0x2F222F22,
|
|
kQ3CSGEquationnotAandB = 0x44444444,
|
|
kQ3CSGEquationnAaBorCanB = 0x74747474
|
|
};
|
|
typedef enum TQ3CSGEquation TQ3CSGEquation;
|
|
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3InteractiveRenderer_SetCSGEquation()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_SetCSGEquation(
|
|
TQ3RendererObject renderer,
|
|
TQ3CSGEquation equation);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_GetCSGEquation()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_GetCSGEquation(
|
|
TQ3RendererObject renderer,
|
|
TQ3CSGEquation * equation);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_SetPreferences()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_SetPreferences(
|
|
TQ3RendererObject renderer,
|
|
long vendorID,
|
|
long engineID);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_GetPreferences()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_GetPreferences(
|
|
TQ3RendererObject renderer,
|
|
long * vendorID,
|
|
long * engineID);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_SetDoubleBufferBypass()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_SetDoubleBufferBypass(
|
|
TQ3RendererObject renderer,
|
|
TQ3Boolean bypass);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_GetDoubleBufferBypass()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_GetDoubleBufferBypass(
|
|
TQ3RendererObject renderer,
|
|
TQ3Boolean * bypass);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_SetRAVEContextHints()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_SetRAVEContextHints(
|
|
TQ3RendererObject renderer,
|
|
unsigned long RAVEContextHints);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_GetRAVEContextHints()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_GetRAVEContextHints(
|
|
TQ3RendererObject renderer,
|
|
unsigned long * RAVEContextHints);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_SetRAVETextureFilter()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_SetRAVETextureFilter(
|
|
TQ3RendererObject renderer,
|
|
unsigned long RAVEtextureFilterValue);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_GetRAVETextureFilter()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_GetRAVETextureFilter(
|
|
TQ3RendererObject renderer,
|
|
unsigned long * RAVEtextureFilterValue);
|
|
|
|
|
|
/*
|
|
* Q3InteractiveRenderer_CountRAVEDrawContexts()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_CountRAVEDrawContexts(
|
|
TQ3RendererObject renderer,
|
|
unsigned long * numRAVEContexts);
|
|
|
|
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
typedef CALLBACK_API_C( void , TQ3RaveDestroyCallback )(TQ3RendererObject renderer);
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3InteractiveRenderer_GetRAVEDrawContexts()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3InteractiveRenderer_GetRAVEDrawContexts(
|
|
TQ3RendererObject renderer,
|
|
TQADrawContext ** raveDrawContextList,
|
|
TQAEngine ** raveDrawingEnginesList,
|
|
unsigned long * numRAVEContexts,
|
|
TQ3RaveDestroyCallback raveDestroyCallback);
|
|
|
|
|
|
|
|
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer View Tools **
|
|
** **
|
|
** You may only call these methods from a plug-in **
|
|
** **
|
|
*****************************************************************************/
|
|
/*
|
|
* Call by a renderer to call the user "idle" method, with progress
|
|
* information.
|
|
*
|
|
* Pass in (view, 0, n) on first call
|
|
* Pass in (view, 1..n-1, n) during rendering
|
|
* Pass in (view, n, n) upon completion
|
|
*
|
|
* Note: The user must have supplied an idleProgress method with
|
|
* Q3XView_SetIdleProgressMethod. Otherwise, the generic idle method is
|
|
* called with no progress data. e.g. the Q3View_SetIdleMethod method
|
|
* is called instead. (current and final are ignored, essentially.)
|
|
*
|
|
* Returns kQ3Failure if rendering is cancelled.
|
|
*/
|
|
/*
|
|
* Q3XView_IdleProgress()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XView_IdleProgress(
|
|
TQ3ViewObject view,
|
|
unsigned long current,
|
|
unsigned long completed);
|
|
|
|
|
|
/*
|
|
* Called by an asynchronous renderer when it completes a frame.
|
|
*/
|
|
/*
|
|
* Q3XView_EndFrame()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XView_EndFrame(TQ3ViewObject view);
|
|
|
|
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer AttributeSet Tools **
|
|
** **
|
|
** You may only call these methods from a plug-in **
|
|
** **
|
|
*****************************************************************************/
|
|
/*
|
|
* Faster access to geometry attribute sets.
|
|
*
|
|
* Returns pointer to INTERNAL data structure for elements and attributes
|
|
* in an attributeSet, or NULL if no attribute exists.
|
|
*
|
|
* For attributes of type kQ3AttributeType..., the internal data structure
|
|
* is identical to the data structure used in Q3AttributeSet_Add.
|
|
*/
|
|
/*
|
|
* Q3XAttributeSet_GetPointer()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( void * )
|
|
Q3XAttributeSet_GetPointer(
|
|
TQ3AttributeSet attributeSet,
|
|
TQ3AttributeType attributeType);
|
|
|
|
|
|
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
enum {
|
|
kQ3XAttributeMaskNone = 0L,
|
|
kQ3XAttributeMaskSurfaceUV = 1 << (kQ3AttributeTypeSurfaceUV - 1),
|
|
kQ3XAttributeMaskShadingUV = 1 << (kQ3AttributeTypeShadingUV - 1),
|
|
kQ3XAttributeMaskNormal = 1 << (kQ3AttributeTypeNormal - 1),
|
|
kQ3XAttributeMaskAmbientCoefficient = 1 << (kQ3AttributeTypeAmbientCoefficient - 1),
|
|
kQ3XAttributeMaskDiffuseColor = 1 << (kQ3AttributeTypeDiffuseColor - 1),
|
|
kQ3XAttributeMaskSpecularColor = 1 << (kQ3AttributeTypeSpecularColor - 1),
|
|
kQ3XAttributeMaskSpecularControl = 1 << (kQ3AttributeTypeSpecularControl - 1),
|
|
kQ3XAttributeMaskTransparencyColor = 1 << (kQ3AttributeTypeTransparencyColor - 1),
|
|
kQ3XAttributeMaskSurfaceTangent = 1 << (kQ3AttributeTypeSurfaceTangent - 1),
|
|
kQ3XAttributeMaskHighlightState = 1 << (kQ3AttributeTypeHighlightState - 1),
|
|
kQ3XAttributeMaskSurfaceShader = 1 << (kQ3AttributeTypeSurfaceShader - 1),
|
|
kQ3XAttributeMaskCustomAttribute = (long)0x80000000,
|
|
kQ3XAttributeMaskAll = 0x800007FF,
|
|
kQ3XAttributeMaskInherited = 0x03FF,
|
|
kQ3XAttributeMaskInterpolated = kQ3XAttributeMaskSurfaceUV | kQ3XAttributeMaskShadingUV | kQ3XAttributeMaskNormal | kQ3XAttributeMaskAmbientCoefficient | kQ3XAttributeMaskDiffuseColor | kQ3XAttributeMaskSpecularColor | kQ3XAttributeMaskSpecularControl | kQ3XAttributeMaskTransparencyColor | kQ3XAttributeMaskSurfaceTangent
|
|
};
|
|
|
|
|
|
typedef unsigned long TQ3XAttributeMask;
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3XAttributeSet_GetMask()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3XAttributeMask )
|
|
Q3XAttributeSet_GetMask(TQ3AttributeSet attributeSet);
|
|
|
|
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer Draw Context Tools **
|
|
** **
|
|
*****************************************************************************/
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
typedef struct OpaqueTQ3XDrawRegion* TQ3XDrawRegion;
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3XDrawContext_GetDrawRegion()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawContext_GetDrawRegion(
|
|
TQ3DrawContextObject drawContext,
|
|
TQ3XDrawRegion * drawRegion);
|
|
|
|
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
enum TQ3XDrawContextValidationMasks {
|
|
kQ3XDrawContextValidationClearFlags = 0x00000000,
|
|
kQ3XDrawContextValidationDoubleBuffer = 1 << 0,
|
|
kQ3XDrawContextValidationShader = 1 << 1,
|
|
kQ3XDrawContextValidationClearFunction = 1 << 2,
|
|
kQ3XDrawContextValidationActiveBuffer = 1 << 3,
|
|
kQ3XDrawContextValidationInternalOffScreen = 1 << 4,
|
|
kQ3XDrawContextValidationPane = 1 << 5,
|
|
kQ3XDrawContextValidationMask = 1 << 6,
|
|
kQ3XDrawContextValidationDevice = 1 << 7,
|
|
kQ3XDrawContextValidationWindow = 1 << 8,
|
|
kQ3XDrawContextValidationWindowSize = 1 << 9,
|
|
kQ3XDrawContextValidationWindowClip = 1 << 10,
|
|
kQ3XDrawContextValidationWindowPosition = 1 << 11,
|
|
kQ3XDrawContextValidationPlatformAttributes = 1 << 12,
|
|
kQ3XDrawContextValidationForegroundShader = 1 << 13,
|
|
kQ3XDrawContextValidationBackgroundShader = 1 << 14,
|
|
kQ3XDrawContextValidationColorPalette = 1 << 15,
|
|
kQ3XDrawContextValidationAll = (long)0xFFFFFFFF
|
|
};
|
|
typedef enum TQ3XDrawContextValidationMasks TQ3XDrawContextValidationMasks;
|
|
|
|
typedef unsigned long TQ3XDrawContextValidation;
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3XDrawContext_ClearValidationFlags()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawContext_ClearValidationFlags(TQ3DrawContextObject drawContext);
|
|
|
|
|
|
/*
|
|
* Q3XDrawContext_GetValidationFlags()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawContext_GetValidationFlags(
|
|
TQ3DrawContextObject drawContext,
|
|
TQ3XDrawContextValidation * validationFlags);
|
|
|
|
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer Draw Region Tools **
|
|
** **
|
|
*****************************************************************************/
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
enum TQ3XDevicePixelType {
|
|
/* These do not indicate byte ordering */
|
|
kQ3XDevicePixelTypeInvalid = 0, /* Unknown, un-initialized type */
|
|
kQ3XDevicePixelTypeRGB32 = 1, /* Alpha:8 (ignored), R:8, G:8, B:8 */
|
|
kQ3XDevicePixelTypeARGB32 = 2, /* Alpha:8, R:8, G:8, B:8 */
|
|
kQ3XDevicePixelTypeRGB24 = 3, /* 24 bits/pixel, R:8, G:8, B:8 */
|
|
kQ3XDevicePixelTypeRGB16 = 4, /* Alpha:1 (ignored), R:5, G:5, B:5 */
|
|
kQ3XDevicePixelTypeARGB16 = 5, /* Alpha:1, R:5, G:5, B:5 */
|
|
kQ3XDevicePixelTypeRGB16_565 = 6, /* 16 bits/pixel, R:5, G:6, B:5 */
|
|
kQ3XDevicePixelTypeIndexed8 = 7, /* 8-bit color table index */
|
|
kQ3XDevicePixelTypeIndexed4 = 8, /* 4-bit color table index */
|
|
kQ3XDevicePixelTypeIndexed2 = 9, /* 2-bit color table index */
|
|
kQ3XDevicePixelTypeIndexed1 = 10 /* 1-bit color table index */
|
|
};
|
|
typedef enum TQ3XDevicePixelType TQ3XDevicePixelType;
|
|
|
|
enum TQ3XClipMaskState {
|
|
kQ3XClipMaskFullyExposed = 0,
|
|
kQ3XClipMaskPartiallyExposed = 1,
|
|
kQ3XClipMaskNotExposed = 2
|
|
};
|
|
typedef enum TQ3XClipMaskState TQ3XClipMaskState;
|
|
|
|
struct TQ3XColorDescriptor {
|
|
unsigned long redShift;
|
|
unsigned long redMask;
|
|
unsigned long greenShift;
|
|
unsigned long greenMask;
|
|
unsigned long blueShift;
|
|
unsigned long blueMask;
|
|
unsigned long alphaShift;
|
|
unsigned long alphaMask;
|
|
};
|
|
typedef struct TQ3XColorDescriptor TQ3XColorDescriptor;
|
|
struct TQ3XDrawRegionDescriptor {
|
|
unsigned long width;
|
|
unsigned long height;
|
|
unsigned long rowBytes;
|
|
unsigned long pixelSize;
|
|
TQ3XDevicePixelType pixelType;
|
|
TQ3XColorDescriptor colorDescriptor;
|
|
TQ3Endian bitOrder;
|
|
TQ3Endian byteOrder;
|
|
TQ3Bitmap * clipMask;
|
|
};
|
|
typedef struct TQ3XDrawRegionDescriptor TQ3XDrawRegionDescriptor;
|
|
enum TQ3XDrawRegionServicesMasks {
|
|
kQ3XDrawRegionServicesNoneFlag = 0L,
|
|
kQ3XDrawRegionServicesClearFlag = 1 << 0,
|
|
kQ3XDrawRegionServicesDontLockDDSurfaceFlag = 1 << 1
|
|
};
|
|
typedef enum TQ3XDrawRegionServicesMasks TQ3XDrawRegionServicesMasks;
|
|
|
|
|
|
typedef unsigned long TQ3XDrawRegionServices;
|
|
typedef CALLBACK_API_C( void , TQ3XDrawRegionRendererPrivateDeleteMethod )(void * rendererPrivate);
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3XDrawRegion_GetDeviceScaleX()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetDeviceScaleX(
|
|
TQ3XDrawRegion drawRegion,
|
|
float * deviceScaleX);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetDeviceScaleY()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetDeviceScaleY(
|
|
TQ3XDrawRegion drawRegion,
|
|
float * deviceScaleY);
|
|
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetDeviceOffsetX()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetDeviceOffsetX(
|
|
TQ3XDrawRegion drawRegion,
|
|
float * deviceOffsetX);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetDeviceOffsetY()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetDeviceOffsetY(
|
|
TQ3XDrawRegion drawRegion,
|
|
float * deviceOffsetX);
|
|
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetWindowScaleX()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetWindowScaleX(
|
|
TQ3XDrawRegion drawRegion,
|
|
float * windowScaleX);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetWindowScaleY()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetWindowScaleY(
|
|
TQ3XDrawRegion drawRegion,
|
|
float * windowScaleY);
|
|
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetWindowOffsetX()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetWindowOffsetX(
|
|
TQ3XDrawRegion drawRegion,
|
|
float * windowOffsetX);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetWindowOffsetY()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetWindowOffsetY(
|
|
TQ3XDrawRegion drawRegion,
|
|
float * windowOffsetY);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_IsActive()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_IsActive(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3Boolean * isActive);
|
|
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetNextRegion()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetNextRegion(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3XDrawRegion * nextDrawRegion);
|
|
|
|
|
|
/*
|
|
* One of the next two functions must be called before using a draw region
|
|
*/
|
|
/*
|
|
* Use this Start function if double buffering/image access services from the
|
|
* Draw Context are not needed, you may still request clear for example
|
|
*/
|
|
/*
|
|
* Q3XDrawRegion_Start()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_Start(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3XDrawRegionServices services,
|
|
TQ3XDrawRegionDescriptor ** descriptor);
|
|
|
|
|
|
/*
|
|
* Use this Start function if double buffering or image access services from
|
|
* the Draw Context are needed.
|
|
*/
|
|
/*
|
|
* Q3XDrawRegion_StartAccessToImageBuffer()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_StartAccessToImageBuffer(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3XDrawRegionServices services,
|
|
TQ3XDrawRegionDescriptor ** descriptor,
|
|
void ** image);
|
|
|
|
|
|
/*
|
|
* This function is used to indicate that access to a DrawRegion is ended.
|
|
*/
|
|
/*
|
|
* Q3XDrawRegion_End()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_End(TQ3XDrawRegion drawRegion);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetDeviceTransform()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetDeviceTransform(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3Matrix4x4 ** deviceTransform);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetClipFlags()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetClipFlags(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3XClipMaskState * clipMaskState);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetClipMask()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetClipMask(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3Bitmap ** clipMask);
|
|
|
|
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
#if TARGET_OS_MAC
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3XDrawRegion_GetClipRegion()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetClipRegion(
|
|
TQ3XDrawRegion drawRegion,
|
|
RgnHandle * rgnHandle);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetGDHandle()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetGDHandle(
|
|
TQ3XDrawRegion drawRegion,
|
|
GDHandle * gdHandle);
|
|
|
|
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
#endif /* TARGET_OS_MAC */
|
|
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* Q3XDrawRegion_GetRendererPrivate()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetRendererPrivate(
|
|
TQ3XDrawRegion drawRegion,
|
|
void ** rendererPrivate);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_SetRendererPrivate()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_SetRendererPrivate(
|
|
TQ3XDrawRegion drawRegion,
|
|
const void * rendererPrivate,
|
|
TQ3XDrawRegionRendererPrivateDeleteMethod deleteMethod);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_SetUseDefaultRendererFlag()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_SetUseDefaultRendererFlag(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3Boolean flag);
|
|
|
|
|
|
/*
|
|
* Q3XDrawRegion_GetUseDefaultRendererFlag()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API_C( TQ3Status )
|
|
Q3XDrawRegion_GetUseDefaultRendererFlag(
|
|
TQ3XDrawRegion drawRegion,
|
|
TQ3Boolean * useDefaultRenderingFlag);
|
|
|
|
|
|
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer Class Methods **
|
|
** **
|
|
*****************************************************************************/
|
|
/*
|
|
* Methods from Object
|
|
* kQ3XMethodTypeObjectClassRegister
|
|
* kQ3XMethodTypeObjectClassUnregister
|
|
* kQ3XMethodTypeObjectNew
|
|
* kQ3XMethodTypeObjectDelete
|
|
* kQ3XMethodTypeObjectRead
|
|
* kQ3XMethodTypeObjectTraverse
|
|
* kQ3XMethodTypeObjectWrite
|
|
*
|
|
* Methods from Shared
|
|
* kQ3MethodTypeSharedEdited
|
|
*
|
|
* Renderer Methods
|
|
*
|
|
* The renderer methods should be implemented according to the type
|
|
* of renderer being written.
|
|
*
|
|
* For the purposes of documentation, there are two basic types of
|
|
* renderers:
|
|
*
|
|
* Interactive
|
|
* Interactive Renderer
|
|
* WireFrame Renderer
|
|
*
|
|
* Deferred
|
|
* a ray-tracer
|
|
* painter's algorithm renderer (cached in a BSP triangle tree)
|
|
* an artistic renderer (simulates a pencil drawing, etc.)
|
|
*
|
|
* The main difference is how each renderer handles incoming state and
|
|
* geometry.
|
|
*
|
|
* An interactive renderer immediately transforms, culls, and shades
|
|
* incoming geometry and performs rasterization. For example, in a
|
|
* single-buffered WireFrame renderer, you will see a new triangle
|
|
* immediately after Q3Triangle_Draw (if it's visible, of course).
|
|
*
|
|
* A deferred renderer caches the view state and each geometry,
|
|
* converting into any internal queue of drawing commands. Rasterization
|
|
* is not actually performed until all data has been submitted.
|
|
*
|
|
* For example, a ray-tracer may not rasterize anything until the
|
|
* end of the rendering loop, or until an EndFrame call is made.
|
|
*/
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer User Interface Methods **
|
|
** **
|
|
*****************************************************************************/
|
|
/*
|
|
* kQ3XMethodTypeRendererIsInteractive
|
|
*
|
|
* There is no actual method with this - the metahandler simply returns
|
|
* "(TQ3XFunctionPointer)kQ3True" for this "method" if the renderer is
|
|
* intended to be used in interactive settings, and
|
|
* "(TQ3XFunctionPointer)kQ3False" otherwise.
|
|
*
|
|
* If neither value is specified in the metahandler, the renderer
|
|
* is *assumed to be non-interactive*!!!
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
enum {
|
|
kQ3XMethodTypeRendererIsInteractive = FOUR_CHAR_CODE('isin')
|
|
};
|
|
|
|
|
|
/*
|
|
* TQ3XRendererModalConfigureMethod
|
|
*
|
|
* This method should pop up a modal dialog to edit the renderer settings
|
|
* found in the renderer private.
|
|
*
|
|
* dialogAnchor - is platform specific data passed by the client to support
|
|
* movable modal dialogs.
|
|
* MacOS: this is a callback to the calling application's event handler.
|
|
* The renderer calls this function with events not handled by the
|
|
* settings dialog. This is necessary in order to support movable modal
|
|
* dialogs. An application's event handler must return kQ3True if it
|
|
* handles the event passed to the callback or kQ3False if not.
|
|
* An application which doesn't want to support a movable modal configure
|
|
* dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor.
|
|
* A renderer should implement a non-movable style dialog in that case.
|
|
* Win32: this is the HWND of the owning window (typically an application's
|
|
* main window). (Win32 application modal dialogs are always movable.)
|
|
* canceled - returns a boolean inditacating that the user canceled the
|
|
* dialog.
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererModalConfigure = FOUR_CHAR_CODE('rdmc')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererModalConfigureMethod )(TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled, void *rendererPrivate);
|
|
/*
|
|
* kQ3XMethodTypeRendererGetNickNameString
|
|
*
|
|
* Allows an application to collect the name of the renderer for
|
|
* display in a user interface item such as a menu.
|
|
*
|
|
* If dataBuffer is NULL actualDataSize returns the required size in
|
|
* bytes of a data buffer large enough to store the renderer name.
|
|
*
|
|
* bufferSize is the actual size of the memory block pointed to by
|
|
* dataBuffer
|
|
*
|
|
* actualDataSize - on return the actual number of bytes written to the
|
|
* buffer or if dataBuffer is NULL the required size of dataBuffer
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererGetNickNameString = FOUR_CHAR_CODE('rdns')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererGetNickNameStringMethod )(unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize);
|
|
/*
|
|
* kQ3XMethodTypeRendererGetConfigurationData
|
|
*
|
|
* Allows an application to collect private configuration data from the
|
|
* renderer which it will then save. For example in a preference file,
|
|
* a registry key (on Windows) or in a style template. An application
|
|
* should tag this data with the renderer's object name.
|
|
*
|
|
* If dataBuffer is NULL actualDataSize returns the required size in
|
|
* bytes of a data buffer large enough to store private data.
|
|
*
|
|
* bufferSize is the actual size of the memory block pointed to by
|
|
* dataBuffer
|
|
*
|
|
* actualDataSize - on return the actual number of bytes written to the
|
|
* buffer or if dataBuffer is NULL the required size of dataBuffer
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererGetConfigurationData = FOUR_CHAR_CODE('rdgp')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererGetConfigurationDataMethod )(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize, void *rendererPrivate);
|
|
/*
|
|
* TQ3XRendererSetConfigurationDataMethod
|
|
*
|
|
* Allows an application to pass private configuration data which has
|
|
* previously been obtained from a renderer via
|
|
* Q3Renderer_GetConfigurationData. For example in a preference file or
|
|
* in a style template. An application should tag this data with the
|
|
* renderer's object name.
|
|
*
|
|
* bufferSize is the actual size of the memory block pointed to by
|
|
* dataBuffer
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererSetConfigurationData = FOUR_CHAR_CODE('rdsp')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSetConfigurationDataMethod )(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, void *rendererPrivate);
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer Drawing State Methods **
|
|
** **
|
|
*****************************************************************************/
|
|
/*
|
|
* TQ3RendererStartFrame
|
|
*
|
|
* The StartFrame method is called first at Q3View_StartRendering
|
|
* and should:
|
|
* - initialize any renderer state to defaults
|
|
* - extract any and all useful data from the drawContext
|
|
*
|
|
* If your renderer passed in kQ3RendererFlagClearBuffer at
|
|
* registration, then it should also:
|
|
* - clear the drawContext
|
|
*
|
|
* When clearing, your renderer may opt to:
|
|
* - NOT clear anything (if you touch every pixel, for example)
|
|
* - to clear with your own routine, or
|
|
* - to use the draw context default clear method by calling
|
|
* Q3DrawContext_Clear. Q3DrawContext_Clear takes advantage of
|
|
* any available hardware in the system for clearing.
|
|
*
|
|
* This call also signals the start of all default submit commands from
|
|
* the view. The renderer will receive updates for the default view
|
|
* state via its Update methods before StartPass is called.
|
|
*
|
|
* REQUIRED
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererStartFrame = FOUR_CHAR_CODE('rdcl')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererStartFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
|
|
/*
|
|
* kQ3XMethodTypeRendererStartPass
|
|
* TQ3XRendererStartPassMethod
|
|
*
|
|
* The StartPass method is called during Q3View_StartRendering but after
|
|
* the StartFrame command. It should:
|
|
* - collect camera and light information
|
|
*
|
|
* If your renderer supports deferred camera transformation, camera is the
|
|
* main camera which will be submitted in the hierarchy somewhere. It
|
|
* is never NULL.
|
|
*
|
|
* If your renderer does not support deferred camera transformation, camera
|
|
* is the transformed camera.
|
|
*
|
|
* If your renderer supports deferred light transformation, lights will be
|
|
* NULL, and will be submitted to your light draw methods instead.
|
|
*
|
|
* This call signals the end of the default update state, and the start of
|
|
* submit commands from the user to the view.
|
|
*
|
|
* REQUIRED
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererStartPass = FOUR_CHAR_CODE('rdst')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererStartPassMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, TQ3GroupObject lightGroup);
|
|
/*
|
|
* kQ3XMethodTypeRendererFlushFrame
|
|
* TQ3XRendererFlushFrameMethod
|
|
*
|
|
* This call is only implemented by asynchronous renderers.
|
|
*
|
|
* The FlushFrame method is called between the StartPass and EndPass
|
|
* methods and is called when the user wishes to flush any asynchronous
|
|
* drawing tasks (which draw to the drawcontext), but does not want
|
|
* to block.
|
|
*
|
|
* The result of this call is that an image should "eventually" appear
|
|
* asynchronously.
|
|
*
|
|
* For asynchronous rendering, this call is non-blocking.
|
|
*
|
|
* An interactive renderer should ensure that all received
|
|
* geometries are drawn in the image.
|
|
*
|
|
* An interactive renderer that talks to hardware should force
|
|
* the hardware to generate an image.
|
|
*
|
|
* A deferred renderer should exhibit a similar behaviour,
|
|
* though it is not required. A deferred renderer should spawn
|
|
* a process that generates a partial image from the currently
|
|
* accumulated drawing state.
|
|
*
|
|
* However, for renderers such as ray-tracers which generally are
|
|
* quite compute-intensive, FlushFrame is not required and is a no-op.
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererFlushFrame = FOUR_CHAR_CODE('rdfl')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererFlushFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
|
|
/*
|
|
* kQ3XMethodTypeRendererEndPass
|
|
* TQ3XRendererEndPassMethod
|
|
*
|
|
* The EndPass method is called at Q3View_EndRendering and signals
|
|
* the end of submit commands to the view.
|
|
*
|
|
* If an error occurs, the renderer should call Q3XError_Post and
|
|
* return kQ3ViewStatusError.
|
|
*
|
|
* If a renderer requires another pass on the renderering data,
|
|
* it should return kQ3ViewStatusRetraverse.
|
|
*
|
|
* If rendering was cancelled, this function will not be called
|
|
* and the view will handle returning kQ3ViewStatusCancelled;
|
|
*
|
|
* Otherwise, your renderer should begin completing the process of
|
|
* generating the image in the drawcontext. If you have buffered
|
|
* any drawing data, flush it. RendererEnd should have a similar
|
|
* effect as RendererFlushFrame.
|
|
*
|
|
* If the renderer is synchronous:
|
|
* - complete rendering of the entire frame
|
|
* if the renderer supports kQ3RendererClassSupportDoubleBuffer
|
|
* - Update the front buffer
|
|
* else
|
|
* - DrawContext will update the front buffer after returning
|
|
*
|
|
* If the renderer is asynchronous
|
|
* - spawn rendering thread for entire frame
|
|
* if the renderer supports kQ3RendererClassSupportDoubleBuffer,
|
|
* - you must eventually update the front buffer asynchronously
|
|
* else
|
|
* - you must eventually update the back buffer asynchronously
|
|
*
|
|
* REQUIRED
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererEndPass = FOUR_CHAR_CODE('rded')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3ViewStatus , TQ3XRendererEndPassMethod )(TQ3ViewObject view, void *rendererPrivate);
|
|
/*
|
|
* kQ3XMethodTypeRendererEndFrame
|
|
* TQ3XRendererEndFrame
|
|
*
|
|
* This call is only implemented by asynchronous renderers.
|
|
*
|
|
* The EndFrame method is called from Q3View_Sync, which is
|
|
* called after Q3View_EndRendering and signals that the user
|
|
* wishes to see the completed image and is willing to block.
|
|
*
|
|
* If your renderer supports kQ3RendererFlagDoubleBuffer
|
|
* - update the front buffer completely
|
|
* else
|
|
* - update the back buffer completely
|
|
*
|
|
* This call is equivalent in functionality to RendererFlushFrame
|
|
* but blocks until the image is completed.
|
|
*
|
|
* If no method is supplied, the default is a no-op.
|
|
*
|
|
* NOTE: Registering a method of this type indicates that your renderer will
|
|
* be rendering after Q3View_EndRendering has been called.
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererEndFrame = FOUR_CHAR_CODE('rdsy')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererEndFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
|
|
/*
|
|
* The RendererCancel method is called after Q3View_StartRendering
|
|
* and signals the termination of all rendering operations.
|
|
*
|
|
* A renderer should clean up any cached data, and cancel all
|
|
* rendering operations.
|
|
*
|
|
* If called before Q3View_EndRendering, the RendererEnd method
|
|
* is NOT called.
|
|
*
|
|
* If called after Q3View_EndRendering, the renderer should kill
|
|
* any threads and terminate any further rendering.
|
|
*
|
|
* REQUIRED
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererCancel = FOUR_CHAR_CODE('rdab')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( void , TQ3XRendererCancelMethod )(TQ3ViewObject view, void *rendererPrivate);
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer DrawContext Methods **
|
|
** **
|
|
*****************************************************************************/
|
|
/*
|
|
* kQ3XMethodTypeRendererPush
|
|
* TQ3XRendererPushMethod
|
|
*
|
|
* kQ3XMethodTypeRendererPop
|
|
* TQ3XRendererPopMethod
|
|
*
|
|
* These methods are called whenever the graphics state in the view
|
|
* is pushed or popped. The user may isolate state by calling:
|
|
*
|
|
* Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &red, view);
|
|
* Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &blue, view);
|
|
* Q3Attribute_Submit(kQ3AttributeTypeSpecularColor, &white, view);
|
|
* Q3Box_Submit(&unitBox, view);
|
|
* Q3TranslateTransform_Submit(&unitVector, view);
|
|
* Q3Push_Submit(view);
|
|
* Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &blue, view);
|
|
* Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &green, view);
|
|
* Q3Box_Submit(&unitBox, view);
|
|
* Q3Pop_Submit(view);
|
|
* Q3TranslateTransform_Submit(&unitVector, view);
|
|
* Q3Box_Submit(&unitBox, view);
|
|
*
|
|
* or by submitting a display group which pushes and pops.
|
|
*
|
|
* If you support RendererPush and RendererPop in your renderer:
|
|
* - you must maintain your drawing state as a stack, as well.
|
|
* - you will not be updated with the popped state after
|
|
* RendererPop is called.
|
|
*
|
|
* If you do not support Push and Pop in your renderer:
|
|
* - you may maintain a single copy of the drawing state.
|
|
* - you will be updated with changed fields after the view stack is
|
|
* popped.
|
|
*
|
|
* A renderer that supports Push and Pop gets called in the following
|
|
* sequence (from example above):
|
|
*
|
|
* RendererUpdateAttributeDiffuseColor(&red,...)
|
|
* RendererUpdateAttributeTransparencyColor(&blue,...)
|
|
* RendererUpdateAttributeSpecularColor(&white,...)
|
|
* RendererUpdateMatrixLocalToWorld(...)
|
|
* RendererSubmitGeometryBox(...)
|
|
* RendererPush(...)
|
|
* RendererUpdateAttributeDiffuseColor(&blue,...)
|
|
* RendererUpdateAttributeTransparencyColor(&green,...)
|
|
* RendererSubmitGeometryBox(...)
|
|
* RendererPop(...)
|
|
* RendererUpdateMatrixLocalToWorld(...)
|
|
* RendererSubmitGeometryBox(...)
|
|
*
|
|
* A renderer that does not supports Push and Pop gets called in the
|
|
* following sequence:
|
|
*
|
|
* RendererUpdateAttributeDiffuseColor(&red,...)
|
|
* RendererUpdateAttributeTransparencyColor(&blue,...)
|
|
* RendererUpdateAttributeSpecularColor(&white,...)
|
|
* RendererUpdateMatrixLocalToWorld(...)
|
|
* RendererSubmitGeometryBox(...)
|
|
* RendererUpdateAttributeDiffuseColor(&blue,...)
|
|
* RendererUpdateAttributeTransparencyColor(&green,...)
|
|
* RendererSubmitGeometryBox(...)
|
|
* RendererUpdateAttributeDiffuseColor(&red,...)
|
|
* RendererUpdateAttributeTransparencyColor(&blue,...)
|
|
* RendererUpdateMatrixLocalToWorld(...)
|
|
* RendererSubmitGeometryBox(...)
|
|
*
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererPush = FOUR_CHAR_CODE('rdps')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererPushMethod )(TQ3ViewObject view, void *rendererPrivate);
|
|
enum {
|
|
kQ3XMethodTypeRendererPop = FOUR_CHAR_CODE('rdpo')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererPopMethod )(TQ3ViewObject view, void *rendererPrivate);
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer Cull Methods **
|
|
** **
|
|
*****************************************************************************/
|
|
/*
|
|
* kQ3XMethodTypeRendererIsBoundingBoxVisible
|
|
* TQ3XRendererIsBoundingBoxVisibleMethod
|
|
*
|
|
* This method is called to cull complex groups and geometries
|
|
* given their bounding box in local space.
|
|
*
|
|
* It should transform the local-space bounding box coordinates to
|
|
* frustum space and return a TQ3Boolean return value indicating
|
|
* whether the box appears within the viewing frustum.
|
|
*
|
|
* If no method is supplied, the default behavior is to return
|
|
* kQ3True.
|
|
*
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererIsBoundingBoxVisible = FOUR_CHAR_CODE('rdbx')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3Boolean , TQ3XRendererIsBoundingBoxVisibleMethod )(TQ3ViewObject view, void *rendererPrivate, const TQ3BoundingBox *bBox);
|
|
|
|
/******************************************************************************
|
|
** **
|
|
** Renderer Object Support Methods **
|
|
** **
|
|
*****************************************************************************/
|
|
/*
|
|
* Drawing methods (Geometry, Camera, Lights)
|
|
*
|
|
*/
|
|
/*
|
|
* Geometry MetaHandler
|
|
*
|
|
* This metaHandler is required to support
|
|
*
|
|
* kQ3GeometryTypeTriangle
|
|
* kQ3GeometryTypeLine
|
|
* kQ3GeometryTypePoint
|
|
* kQ3GeometryTypeMarker
|
|
* kQ3GeometryTypePixmapMarker
|
|
*
|
|
* REQUIRED
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererSubmitGeometryMetaHandler = FOUR_CHAR_CODE('rdgm')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitGeometryMetaHandlerMethod )(TQ3ObjectType geometryType);
|
|
/*
|
|
* The TQ3XRendererSubmitGeometryMetaHandlerMethod switches on geometryType
|
|
* of kQ3GeometryTypeFoo and returns methods of type:
|
|
*/
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitGeometryMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3GeometryObject geometry, const void *publicData);
|
|
/*
|
|
* Camera MetaHandler
|
|
*
|
|
* This metaHandler, if supplied, indicates that your renderer
|
|
* handles deferred transformation of the main camera within a scene.
|
|
*
|
|
* If not supplied, or an unsupported camera is used, the view will do
|
|
* the transformation for the renderer and pass in a camera in the
|
|
* StartPass method.
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererSubmitCameraMetaHandler = FOUR_CHAR_CODE('rdcm')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitCameraMetaHandlerMethod )(TQ3ObjectType cameraType);
|
|
/*
|
|
* The TQ3XRendererSubmitCameraMetaHandlerMethod switches on cameraType
|
|
* of kQ3CameraTypeFoo and returns methods of type:
|
|
*/
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitCameraMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, const void *publicData);
|
|
/*
|
|
* Light MetaHandler
|
|
*
|
|
* This metaHandler, if supplied, indicates that your renderer
|
|
* handles deferred transformation of lights within a scene.
|
|
*
|
|
* If an unsupported light is encountered, it is ignored.
|
|
*
|
|
* OPTIONAL
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererSubmitLightMetaHandler = FOUR_CHAR_CODE('rdlg')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitLightMetaHandlerMethod )(TQ3ObjectType lightType);
|
|
/*
|
|
* The TQ3XRendererSubmitLightMetaHandlerMethod switches on lightType
|
|
* of kQ3LightTypeFoo and returns methods of type:
|
|
*/
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitLightMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3LightObject light, const void *publicData);
|
|
/*
|
|
*
|
|
* Update methods
|
|
*
|
|
* They are called whenever the state has changed. If the renderer supports
|
|
* the RendererPush and RendererPop methods, it must maintain its own state
|
|
* stack. Updates are not called for changed data when the view stack is
|
|
* popped.
|
|
*
|
|
* See the comments for the RendererPush and RendererPop methods above
|
|
* for an example of how data is updated.
|
|
*
|
|
*/
|
|
/*
|
|
* Style
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateStyleMetaHandler = FOUR_CHAR_CODE('rdyu')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateStyleMetaHandlerMethod )(TQ3ObjectType styleType);
|
|
/*
|
|
* The TQ3XRendererUpdateStyleMetaHandlerMethod switches on styleType
|
|
* of kQ3StyleTypeFoo and returns methods of type:
|
|
*/
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateStyleMethod )(TQ3ViewObject view, void *rendererPrivate, const void *publicData);
|
|
/*
|
|
* Attributes
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateAttributeMetaHandler = FOUR_CHAR_CODE('rdau')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateAttributeMetaHandlerMethod )(TQ3AttributeType attributeType);
|
|
/*
|
|
* The TQ3XRendererUpdateStyleMetaHandlerMethod switches on attributeType
|
|
* of kQ3AttributeTypeFoo and returns methods of type:
|
|
*/
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateAttributeMethod )(TQ3ViewObject view, void *rendererPrivate, const void *publicData);
|
|
/*
|
|
* Shaders
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateShaderMetaHandler = FOUR_CHAR_CODE('rdsu')
|
|
};
|
|
|
|
typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateShaderMetaHandlerMethod )(TQ3ObjectType shaderType);
|
|
/*
|
|
* The TQ3XRendererUpdateShaderMetaHandlerMethod switches on shaderType
|
|
* of kQ3ShaderTypeFoo and returns methods of type:
|
|
*/
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateShaderMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3Object *shaderObject);
|
|
/*
|
|
* Matrices
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateMatrixMetaHandler = FOUR_CHAR_CODE('rdxu')
|
|
};
|
|
|
|
typedef TQ3XMetaHandler TQ3XRendererUpdateMatrixMetaHandlerMethod;
|
|
/*
|
|
* The TQ3XRendererUpdateShaderMetaHandlerMethod switches on methods
|
|
* of the form kQ3MethodTypeRendererUpdateMatrixFoo:
|
|
*/
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateMatrixLocalToWorld = FOUR_CHAR_CODE('ulwx')
|
|
};
|
|
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverse = FOUR_CHAR_CODE('ulwi')
|
|
};
|
|
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverseTranspose = FOUR_CHAR_CODE('ulwt')
|
|
};
|
|
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateMatrixLocalToCamera = FOUR_CHAR_CODE('ulcx')
|
|
};
|
|
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateMatrixLocalToFrustum = FOUR_CHAR_CODE('ulfx')
|
|
};
|
|
|
|
enum {
|
|
kQ3XMethodTypeRendererUpdateMatrixWorldToFrustum = FOUR_CHAR_CODE('uwfx')
|
|
};
|
|
|
|
/*
|
|
* and returns methods of type:
|
|
*/
|
|
typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateMatrixMethod )(TQ3ViewObject view, void *rendererPrivate, const TQ3Matrix4x4 *matrix);
|
|
|
|
|
|
#if PRAGMA_ENUM_ALWAYSINT
|
|
#pragma enumsalwaysint reset
|
|
#ifdef __QD3DRENDERER__RESTORE_TWOBYTEINTS
|
|
#pragma fourbyteints off
|
|
#endif
|
|
#elif PRAGMA_ENUM_OPTIONS
|
|
#pragma option enum=reset
|
|
#elif defined(__QD3DRENDERER__RESTORE_PACKED_ENUMS)
|
|
#pragma options(pack_enums)
|
|
#endif
|
|
|
|
#if PRAGMA_STRUCT_ALIGN
|
|
#pragma options align=reset
|
|
#elif PRAGMA_STRUCT_PACKPUSH
|
|
#pragma pack(pop)
|
|
#elif PRAGMA_STRUCT_PACK
|
|
#pragma pack()
|
|
#endif
|
|
|
|
#ifdef PRAGMA_IMPORT_OFF
|
|
#pragma import off
|
|
#elif PRAGMA_IMPORT
|
|
#pragma import reset
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __QD3DRENDERER__ */
|
|
|