Please consider a donation to the Higher Intellect project. See https://preterhuman.net/donate.php or the Donate to Higher Intellect page for more info. |
QuickDraw 3D RAVE
The QuickDraw 3D Renderer Acceleration Virtual Engine (or, more briefly, QuickDraw 3D RAVE) is the part of the Macintosh system software that controls 3D drawing engines. A drawing engine is software that supports low-level rasterization operations--that is, the process of determining values for pixels in an image on the screen or some other medium. You are probably already familiar with QuickDraw, which is a 2D drawing engine. The 3D drawing engines managed by QuickDraw 3D RAVE differ from 2D drawing engines in several important respects:
- A 3D drawing engine must support a z (or depth) value for hidden surface removal (removing any surfaces in a model that are hidden by opaque surfaces of objects).
- A 3D drawing engine typically supports double buffering, the use of two different buffers to store pixel images. Double buffering helps reduce the flashing caused by redrawing an image. Double buffering can also be used to avoid tearing artifacts caused by updating a window at high speed.
- A 3D drawing engine typically supports special rasterization modes, such as texture mapping or constructive solid geometry.
About
QuickDraw 3D RAVE is used internally by QuickDraw 3D, the 3D graphics library from Apple Computer, Inc. that you can use to create, configure, render, and interact with models of three-dimensional objects. For most 3D drawing and interaction, you should use the high-level application programming interfaces provided by QuickDraw 3D. In some cases, however, you might need to use the low-level services provided by QuickDraw 3D RAVE. You can use QuickDraw 3D RAVE if
- you are writing a specialized application (such as a game-development framework) that needs to take advantage of Apple's optimized software rasterizers and any available 3D acceleration hardware
- you are writing interactive software (such as a game or other entertainment software) that requires the extremely fast 3D rendering that can be achieved with a very low-level, lightweight graphics library
- you are developing 3D acceleration hardware or software that is to be accessed by any applications rendering 3D images
QuickDraw 3D RAVE and all registered drawing engines with their associated devices comprise the QuickDraw 3D Acceleration Layer. This layer operates as a hardware abstraction layer that insulates the system software (for instance, QuickDraw 3D) or other clients from the actual video display hardware and graphics acceleration hardware available on a particular Macintosh computer. The QuickDraw 3D Acceleration Layer is intended to provide a basis for 3D rendering at interactive speeds. Accordingly, QuickDraw 3D RAVE is implemented in such a way as to minimize the overhead incurred by communication between an application and a drawing engine.
Drawing Engines
A drawing engine is a plug-in software module that accepts drawing commands and produces a rasterized image. QuickDraw 3D RAVE is designed to make it easy for you to add drawing engines to those already available. When you register a drawing engine, it thereby becomes available for use by any application or system software running on a Macintosh computer.
QuickDraw 3D RAVE expects that a drawing engine will have a certain minimum set of required features and possibly one or more optional features. Every drawing engine must provide these features:
- hidden surface removal (usually accomplished using z buffering with at least 16 bits per pixel)
- point and line drawing, with application-specifiable point and line widths
- drawing of Gouraud-shaded triangles
- drawing of bitmaps having depths of 1, 16, or 32 bits per pixel
- support for double buffering
In addition to the required features, a drawing engine may support one or more of these optional features:
- high-precision hidden surface removal (using z buffering with at least 24 bits per pixel)
- perspective-corrected hidden surface removal
- texture mapping
- triangle meshes (a memory and time optimization that allows rendered triangles to share vertices)
- transparency blending, with or without an alpha channel
- antialiasing
- z-sorted rendering of non-opaque objects
- support for OpenGL features (such as scissoring, multiple blending modes, area and line stipple patterns, and so forth)
The interactive renderer supplied as part of QuickDraw 3D uses a software-only drawing engine that can draw to any available device. In addition to the required features listed earlier, the drawing engine supplied with the interactive renderer supports these optional features:
- z buffering with 16 or 32 bits per pixel
- direct rendering at 16 or 32 bits per pixel (rendering at fewer than 16 bits per pixel is also supported, but with lower performance)
- perspective-corrected texture mapping
It's important to keep in mind that a drawing engine is a low-level 3D driver and hence does not support some features found in higher-level interfaces. The current programming interfaces to drawing engines do not support any of these features:
- transformations, shading, or clipping
- I/O support (such as reading and writing 3D metafiles)
- high-level primitives (such as curved surfaces)
- support for drawing to windows that straddle two or more devices
IMPORTANT - Because of these limitations, most applications should not use QuickDraw 3D RAVE directly. Instead, you should use the high-level programming interfaces provided by QuickDraw 3D or other system software that provides 3D capabilities.
QuickDraw 3D RAVE does not require that a drawing engine be capable of drawing to all devices available on a particular computer. Rather, a particular drawing engine may support only a single output device. For example, a drawing engine that uses a frame buffer's built-in 3D acceleration hardware may be incapable of rendering to any other device. As a result, QuickDraw 3D RAVE won't allow some other device to be associated with that drawing engine. This means that QuickDraw 3D RAVE does not provide automatic support for drawing into windows that cross multiple devices. Instead, it is the application's responsibility to determine when a window does straddle devices and to construct multiple draw contexts (described next) for the output image.
Draw Contexts
Although a drawing engine may be capable of supporting more than one device, it cannot divide a raster across multiple devices. Instead, every drawing command sent to a drawing engine must be destined for a single device. QuickDraw 3D RAVE guarantees this by requiring a calling application to specify a draw context as a parameter for every drawing command. A draw context is a structure (of type TQADrawContext) that maintains state information and other data associated with a particular drawing engine and device.
A hardware device (such as a frame buffer or a video interface) is represented in QuickDraw 3D RAVE by a virtual device, a structure of type TQADevice that determines which one of a variety of types of hardware devices a draw context draws into. On Macintosh computers, QuickDraw 3D RAVE supports two kinds of virtual devices: memory devices and graphics devices. A memory device represents an area of memory, and a graphics device represents a video device (such as a plug-in video card or built-in video interface) that controls a screen, or an offscreen graphics world (which allows your application to build complex images off the screen before displaying them). In effect, a virtual device specifies the buffers into which all drawing commands associated with a draw context write pixels.
Summary of QuickDraw 3D RAVE
C Summary
Constants
Platform Values
#define kQAMacOS 1 #define kQAGeneric 2 #define kQAWin32 3
Version Values
typedef enum TQAVersion { kQAVersion_Prerelease = 0, kQAVersion_1_0 = 1, kQAVersion_1_0_5 = 2, kQAVersion_1_1 = 3 } TQAVersion;
Pixel Types
typedef enum TQAImagePixelType { kQAPixel_Alpha1 = 0, kQAPixel_RGB16 = 1, kQAPixel_ARGB16 = 2, kQAPixel_RGB32 = 3, kQAPixel_ARGB32 = 4, kQAPixel_CL4 = 5, kQAPixel_CL8 = 6 } TQAImagePixelType;
Color Lookup Table Types
typedef enum TQAColorTableType { kQAColorTable_CL8_RGB32 = 0, kQAColorTable_CL4_RGB32 = 1 } TQAColorTableType;
Device Types
typedef enum TQADeviceType { kQADeviceMemory = 0, kQADeviceGDevice = 1, kQADeviceWin32DC = 2, kQADeviceDDSurface = 3 } TQADeviceType;
Clip Types
typedef enum TQAClipType { kQAClipRgn = 0, kQAClipWin32Rgn = 1 } TQAClipType;
Tags for State Variables
typedef enum TQATagInt { kQATag_ZFunction = 0, /*required variables*/ kQATag_Antialias = 8, /*optional variables*/ kQATag_Blend = 9, kQATag_PerspectiveZ = 10, kQATag_TextureFilter = 11, kQATag_TextureOp = 12, kQATag_CSGTag = 14, kQATag_CSGEquation = 15, kQATagGL_DrawBuffer = 100, /*OpenGL variables*/ kQATagGL_TextureWrapU = 101, kQATagGL_TextureWrapV = 102, kQATagGL_TextureMagFilter = 103, kQATagGL_TextureMinFilter = 104, kQATagGL_ScissorXMin = 105, kQATagGL_ScissorYMin = 106, kQATagGL_ScissorXMax = 107, kQATagGL_ScissorYMax = 108, kQATagGL_BlendSrc = 109, kQATagGL_BlendDst = 110, kQATagGL_LinePattern = 111, kQATagGL_AreaPattern0 = 117, kQATagGL_AreaPattern31 = 148, kQATag_EngineSpecific_Minimum= 1000 } TQATagInt; typedef enum TQATagFloat { kQATag_ColorBG_a = 1, /*required variables*/ kQATag_ColorBG_r = 2, kQATag_ColorBG_g = 3, kQATag_ColorBG_b = 4, kQATag_Width = 5, kQATag_ZMinOffset = 6, kQATag_ZMinScale = 7, kQATagGL_DepthBG = 112, /*OpenGL variables*/ kQATagGL_TextureBorder_a = 113, kQATagGL_TextureBorder_r = 114, kQATagGL_TextureBorder_g = 115, kQATagGL_TextureBorder_b = 116 } TQATagFloat; typedef enum TQATagPtr { kQATag_Texture = 13 } TQATagPtr;
Z Sorting Function Selectors
/*values for kQATag_ZFunction*/ #define kQAZFunction_None 0 #define kQAZFunction_LT 1 #define kQAZFunction_EQ 2 #define kQAZFunction_LE 3 #define kQAZFunction_GT 4 #define kQAZFunction_NE 5 #define kQAZFunction_GE 6 #define kQAZFunction_True 7
Antialiasing Selectors
/*values for kQATag_Antialias*/ #define kQAAntiAlias_Off 0 #define kQAAntiAlias_Fast 1 #define kQAAntiAlias_Mid 2 #define kQAAntiAlias_Best 3
Blending Operations
/*values for kQATag_Blend*/ #define kQABlend_PreMultiply 0 #define kQABlend_Interpolate 1 #define kQABlend_OpenGL 2
Z Perspective Selectors
/*values for kQATag_PerspectiveZ*/ #define kQAPerspectiveZ_Off 0 #define kQAPerspectiveZ_On 1
Texture Filter Selectors
/*values for kQATag_TextureFilter*/ #define kQATextureFilter_Fast 0 #define kQATextureFilter_Mid 1 #define kQATextureFilter_Best 2
Texture Operations
/*masks for kQATag_TextureOp*/ #define kQATextureOp_None 0 #define kQATextureOp_Modulate (1 << 0) #define kQATextureOp_Highlight (1 << 1) #define kQATextureOp_Decal (1 << 2) #define kQATextureOp_Shrink (1 << 3)
CSG IDs
/*values for kQATag_CSGTag*/ #define kQACSGTag_None 0xffffffffUL #define kQACSGTag_0 0 #define kQACSGTag_1 1 #define kQACSGTag_2 2 #define kQACSGTag_3 3 #define kQACSGTag_4 4
Texture Wrapping Values
/*values for kQATagGL_TextureWrapU and kQATagGL_TextureWrapV*/ #define kQAGL_Repeat 0 #define kQAGL_Clamp 1
Source Blending Values
/*values for kQATagGL_BlendSrc*/ #define kQAGL_SourceBlend_XXX 0
Destination Blending Values
/*values for kQATagGL_BlendDst*/ #define kQAGL_DestBlend_XXX 0
Buffer Drawing Operations
/*masks for kQATagGL_DrawBuffer*/ #define kQAGL_DrawBuffer_None 0 #define kQAGL_DrawBuffer_FrontLeft (1 << 0) #define kQAGL_DrawBuffer_FrontRight (1 << 1) #define kQAGL_DrawBuffer_BackLeft (1 << 2) #define kQAGL_DrawBuffer_BackRight (1 << 3) #define kQAGL_DrawBuffer_Front \ (kQAGL_DrawBuffer_FrontLeft | kQAGL_DrawBuffer_FrontRight) #define kQAGL_DrawBuffer_Back \ (kQAGL_DrawBuffer_BackLeft | kQAGL_DrawBuffer_BackRight)
Line and Point Widths
/*values for kQATag_Width*/ #define kQAMaxWidth 128.0
Vertex Modes
typedef enum TQAVertexMode { kQAVertexMode_Point = 0, kQAVertexMode_Line = 1, kQAVertexMode_Polyline = 2, kQAVertexMode_Tri = 3, kQAVertexMode_Strip = 4, kQAVertexMode_Fan = 5 } TQAVertexMode;
Gestalt Selectors
typedef enum TQAGestaltSelector { kQAGestalt_OptionalFeatures= 0, kQAGestalt_FastFeatures = 1, kQAGestalt_VendorID = 2, kQAGestalt_EngineID = 3, kQAGestalt_Revision = 4, kQAGestalt_ASCIINameLength = 5, kQAGestalt_ASCIIName = 6, kQAGestalt_AvailableTexMem = 7 } TQAGestaltSelector;
Gestalt Optional Features Response Masks
#define kQAOptional_None 0 #define kQAOptional_DeepZ (1 << 0) #define kQAOptional_Texture (1 << 1) #define kQAOptional_TextureHQ (1 << 2) #define kQAOptional_TextureColor (1 << 3) #define kQAOptional_Blend (1 << 4) #define kQAOptional_BlendAlpha (1 << 5) #define kQAOptional_Antialias (1 << 6) #define kQAOptional_ZSorted (1 << 7) #define kQAOptional_PerspectiveZ (1 << 8) #define kQAOptional_OpenGL (1 << 9) #define kQAOptional_NoClear (1 << 10) #define kQAOptional_CSG (1 << 11) #define kQAOptional_BoundToDevice (1 << 12) #define kQAOptional_CL4 (1 << 13) #define kQAOptional_CL8 (1 << 14)
Gestalt Fast Features Response Masks
#define kQAFast_None 0 #define kQAFast_Line (1 << 0) #define kQAFast_Gouraud (1 << 1) #define kQAFast_Texture (1 << 2) #define kQAFast_TextureHQ (1 << 3) #define kQAFast_Blend (1 << 4) #define kQAFast_Antialiasing (1 << 5) #define kQAFast_ZSorted (1 << 6) #define kQAFast_CL4 (1 << 7) #define kQAFast_CL8 (1 << 8)
Vendor and Engine IDs
#define kQAVendor_BestChoice (-1) #define kQAVendor_Apple 0 #define kQAVendor_ATI 1 #define kQAVendor_Radius 2 #define kQAVendor_Mentor 3 #define kQAVendor_Matrox 4 #define kQAVendor_Yarc 5 #define kQAEngine_AppleSW 0 #define kQAEngine_AppleHW (-1) #define kQAEngine_AppleHW2 1
Triangle Flags Masks
#define kQATriFlags_None 0 #define kQATriFlags_Backfacing (1 << 0)
Texture Flags Masks
#define kQATexture_None 0 #define kQATexture_Lock (1 << 0) #define kQATexture_Mipmap (1 << 1) #define kQATexture_NoCompression (1 << 2) #define kQATexture_HighCompression (1 << 3)
Bitmap Flags Masks
#define kQABitmap_None 0 #define kQABitmap_Lock (1 << 1) #define kQABitmap_NoCompression (1 << 2) #define kQABitmap_HighCompression (1 << 3)
Draw Context Flags Masks
#define kQAContext_None 0 #define kQAContext_NoZBuffer (1 << 0) #define kQAContext_DeepZ (1 << 1) #define kQAContext_DoubleBuffer (1 << 2) #define kQAContext_Cache (1 << 3)
Drawing Engine Method Selectors
typedef enum TQAEngineMethodTag { kQADrawPrivateNew = 0, kQADrawPrivateDelete = 1, kQAEngineCheckDevice = 2, kQAEngineGestalt = 3, kQATextureNew = 4, kQATextureDetach = 5, kQATextureDelete = 6, kQABitmapNew = 7, kQABitmapDetach = 8, kQABitmapDelete = 9, kQAColorTableNew = 10, kQAColorTableDelete = 11, kQATextureBindColorTable = 12, kQABitmapBindColorTable = 13 } TQAEngineMethodTag;
Public Draw Context Method Selectors
typedef enum TQADrawMethodTag { kQASetFloat = 0, kQASetInt = 1, kQASetPtr = 2, kQAGetFloat = 3, kQAGetInt = 4, kQAGetPtr = 5, kQADrawPoint = 6, kQADrawLine = 7, kQADrawTriGouraud = 8, kQADrawTriTexture = 9, kQADrawVGouraud = 10, kQADrawVTexture = 11, kQADrawBitmap = 12, kQARenderStart = 13, kQARenderEnd = 14, kQARenderAbort = 15, kQAFlush = 16, kQASync = 17, kQASubmitVerticesGouraud = 18, kQASubmitVerticesTexture = 19, kQADrawTriMeshGouraud = 20, kQADrawTriMeshTexture = 21, kQASetNoticeMethod = 22, kQAGetNoticeMethod = 23 } TQADrawMethodTag;
Notice Method Selectors
typedef enum TQAMethodSelector { kQAMethod_RenderCompletion = 0, kQAMethod_DisplayModeChanged = 1 } TQAMethodSelector;
Data Types
Basic Data Types
typedef struct TQAEngine TQAEngine; typedef struct TQATexture TQATexture; typedef struct TQABitmap TQABitmap; typedef struct TQAColorTable TQAColorTable; typedef struct TQADrawPrivate TQADrawPrivate;
Memory Device Structure
typedef struct TQADeviceMemory { long rowBytes; TQAImagePixelType pixelType; long width; long height; void *baseAddr; } TQADeviceMemory;
Rectangle Structure
typedef struct TQARect { long left; long right; long top; long bottom; } TQARect;
Macintosh Device and Clip Structures
typedef union TQAPlatformDevice { TQADeviceMemory memoryDevice; GDHandle gDevice; } TQAPlatformDevice; typedef union TQAPlatformClip { RgnHandle clipRgn; } TQAPlatformClip;
Windows Device and Clip Structures
typedef union TQAPlatformDevice { TQADeviceMemory memoryDevice; HDC hdc; struct { LPDIRECTDRAW lpDirectDraw; LPDIRECTDRAWSURFACE lpDirectDrawSurface; }; } TQAPlatformDevice; typedef union TQAPlatformClip { HRGN clipRgn; } TQAPlatformClip
Generic Device and Clip Structures
typedef union TQAPlatformDevice { TQADeviceMemory memoryDevice; } TQAPlatformDevice; typedef union TQAPlatformClip { void *region; } TQAPlatformClip;
Device Structure
typedef struct TQADevice { TQADeviceType deviceType; TQAPlatformDevice device; } TQADevice;
Clip Data Structure
typedef struct TQAClip { TQAClipType clipType; TQAPlatformClip clip; } TQAClip;
Image Structure
struct TQAImage { long width; long height; long rowBytes; void *pixmap; }; typedef struct TQAImage TQAImage;
Vertex Structures
typedef struct TQAVGouraud { float x; float y; float z; float invW; float r; float g; float b; float a; } TQAVGouraud; typedef struct TQAVTexture { float x; float y; float z; float invW; float r; float g; float b; float a; float uOverW; float vOverW; float kd_r; float kd_g; float kd_b; float ks_r; float ks_g; float ks_b; } TQAVTexture;
Draw Context Structure
struct TQADrawContext { TQADrawPrivate *drawPrivate; const TQAVersion version; TQASetFloat setFloat; TQASetInt setInt; TQASetPtr setPtr; TQAGetFloat getFloat; TQAGetInt getInt; TQAGetPtr getPtr; TQADrawPoint drawPoint; TQADrawLine drawLine; TQADrawTriGouraud drawTriGouraud; TQADrawTriTexture drawTriTexture; TQADrawVGouraud drawVGouraud; TQADrawVTexture drawVTexture; TQADrawBitmap drawBitmap; TQARenderStart renderStart; TQARenderEnd renderEnd; TQARenderAbort renderAbort; TQAFlush flush; TQASync sync; TQASubmitVerticesGouraud submitVerticesGouraud; TQASubmitVerticesTexture submitVerticesTexture; TQADrawTriMeshGouraud drawTriMeshGouraud; TQADrawTriMeshTexture drawTriMeshTexture; TQASetNoticeMethod setNoticeMethod; TQAGetNoticeMethod getNoticeMethod; }; typedef struct TQADrawContext TQADrawContext;
Drawing Engine Methods Union
typedef union TQAEngineMethod { TQADrawPrivateNew drawPrivateNew; TQADrawPrivateDelete drawPrivateDelete; TQAEngineCheckDevice engineCheckDevice; TQAEngineGestalt engineGestalt; TQATextureNew textureNew; TQATextureDetach textureDetach; TQATextureDelete textureDelete; TQABitmapNew bitmapNew; TQABitmapDetach bitmapDetach; TQABitmapDelete bitmapDelete; TQAColorTableNew colorTableNew; TQAColorTableDelete colorTableDelete; TQATextureBindColorTable textureBindColorTable; TQABitmapBindColorTable bitmapBindColorTable; } TQAEngineMethod;
Public Draw Context Methods Union
typedef union TQADrawMethod { TQASetFloat setFloat; TQASetInt setInt; TQASetPtr setPtr; TQAGetFloat getFloat; TQAGetInt getInt; TQAGetPtr getPtr; TQADrawPoint drawPoint; TQADrawLine drawLine; TQADrawTriGouraud drawTriGouraud; TQADrawTriTexture drawTriTexture; TQADrawVGouraud drawVGouraud; TQADrawVTexture drawVTexture; TQADrawBitmap drawBitmap; TQARenderStart renderStart; TQARenderEnd renderEnd; TQARenderAbort renderAbort; TQAFlush flush; TQASync sync; TQASubmitVerticesGouraud submitVerticesGouraud; TQASubmitVerticesTexture submitVerticesTexture; TQADrawTriMeshGouraud drawTriMeshGouraud; TQADrawTriMeshTexture drawTriMeshTexture; TQASetNoticeMethod setNoticeMethod; TQAGetNoticeMethod getNoticeMethod; } TQADrawMethod;
Indexed Triangle Structure
typedef struct TQAIndexedTriangle { unsigned long triangleFlags; unsigned long vertices[3]; } TQAIndexedTriangle;
QuickDraw 3D RAVE Routines
Creating and Deleting Draw Contexts
TQAError QADrawContextNew (const TQADevice *device, const TQARect *rect, const TQAClip *clip, const TQAEngine *engine, unsigned long flags, TQADrawContext **newDrawContext); void QADrawContextDelete (TQADrawContext *drawContext);
Creating and Deleting Color Lookup Tables
TQAError QAColorTableNew (const TQAEngine *engine, TQAColorTableType tableType, void *pixelData, long transparentIndexFlag, TQAColorTable **newTable); void QAColorTableDelete (const TQAEngine *engine, TQAColorTable *colorTable);
Manipulating Textures and Bitmaps
TQAError QATextureNew (const TQAEngine *engine, unsigned long flags, TQAImagePixelType pixelType, const TQAImage images[], TQATexture **newTexture); TQAError QATextureDetach (const TQAEngine *engine, TQATexture *texture); TQAError QATextureBindColorTable (const TQAEngine *engine, TQATexture *texture, TQAColorTable *colorTable); void QATextureDelete (const TQAEngine *engine, TQATexture *texture); TQAError QABitmapNew (const TQAEngine *engine, unsigned long flags, TQAImagePixelType pixelType, const TQAImage *image, TQABitmap **newBitmap); TQAError QABitmapDetach (const TQAEngine *engine, TQABitmap *bitmap); TQAError QABitmapBindColorTable (const TQAEngine *engine, TQABitmap *bitmap, TQAColorTable *colorTable); void QABitmapDelete (const TQAEngine *engine, TQABitmap *bitmap);
Managing Drawing Engines
TQAEngine *QADeviceGetFirstEngine (const TQADevice *device); TQAEngine *QADeviceGetNextEngine (const TQADevice *device, const TQAEngine *currentEngine); TQAError QAEngineCheckDevice (const TQAEngine *engine, const TQADevice *device); TQAError QAEngineGestalt (const TQAEngine *engine, TQAGestaltSelector selector, void *response); TQAError QAEngineEnable (long vendorID, long engineID); TQAError QAEngineDisable (long vendorID, long engineID);
Manipulating Draw Contexts
#define QAGetFloat(drawContext,tag) \ (drawContext)->getFloat (drawContext,tag) #define QASetFloat(drawContext,tag,newValue) \ (drawContext)->setFloat (drawContext,tag,newValue) #define QAGetInt(drawContext,tag) \ (drawContext)->getInt (drawContext,tag) #define QASetInt(drawContext,tag,newValue) \ (drawContext)->setInt (drawContext,tag,newValue) #define QAGetPtr(drawContext,tag) \ (drawContext)->getPtr (drawContext,tag) #define QASetPtr(drawContext,tag,newValue) \ (drawContext)->setPtr (drawContext,tag,newValue) #define QADrawPoint(drawContext,v) \ (drawContext)->drawPoint (drawContext,v) #define QADrawLine(drawContext,v0,v1) \ (drawContext)->drawLine (drawContext,v0,v1) #define QADrawTriGouraud(drawContext,v0,v1,v2,flags) \ (drawContext)->drawTriGouraud (drawContext,v0,v1,v2,flags) #define QADrawTriTexture(drawContext,v0,v1,v2,flags) \ (drawContext)->drawTriTexture (drawContext,v0,v1,v2,flags) #define QASubmitVerticesGouraud(drawContext,nVertices,vertices) \ (drawContext)->submitVerticesGouraud(drawContext,nVertices,vertices) #define QASubmitVerticesTexture(drawContext,nVertices,vertices) \ (drawContext)->submitVerticesTexture(drawContext,nVertices,vertices) #define QADrawTriMeshGouraud(drawContext,nTriangle,triangles) \ (drawContext)->drawTriMeshGouraud (drawContext,nTriangle,triangles) #define QADrawTriMeshTexture(drawContext,nTriangle,triangles) \ (drawContext)->drawTriMeshTexture (drawContext,nTriangle,triangles) #define QADrawVGouraud(drawContext,nVertices,vertexMode,vertices,flags) \ (drawContext)->drawVGouraud (drawContext,nVertices,vertexMode,vertices,flags) #define QADrawVTexture(drawContext,nVertices,vertexMode,vertices,flags) \ (drawContext)->drawVTexture (drawContext,nVertices,vertexMode,vertices,flags) #define QADrawBitmap(drawContext,v,bitmap) \ (drawContext)->drawBitmap (drawContext,v,bitmap) #define QARenderStart(drawContext,dirtyRect,initialContext) \ (drawContext)->renderStart (drawContext,dirtyRect,initialContext) #define QARenderEnd(drawContext,modifiedRect) \ (drawContext)->renderEnd (drawContext,modifiedRect) #define QARenderAbort(drawContext) (drawContext)->renderAbort (drawContext) #define QAFlush(drawContext) (drawContext)->flush (drawContext) #define QASync(drawContext) (drawContext)->sync (drawContext) #define QAGetNoticeMethod(drawContext, method, completionCallBack, refCon) \ (drawContext)->getNoticeMethod (drawContext, method, completionCallBack, refCon) #define QASetNoticeMethod(drawContext, method, completionCallBack, refCon) \ (drawContext)->setNoticeMethod (drawContext, method, completionCallBack, refCon)
Registering a Custom Drawing Engine
TQAError QARegisterEngine (TQAEngineGetMethod engineGetMethod); TQAError QARegisterDrawMethod (TQADrawContext *drawContext, TQADrawMethodTag methodTag, TQADrawMethod method);
Application-Defined Routines
Public Draw Context Methods
typedef float (*TQAGetFloat)(const TQADrawContext *drawContext, TQATagFloat tag); typedef void (*TQASetFloat)(TQADrawContext *drawContext, TQATagFloat tag, float newValue); typedef unsigned long (*TQAGetInt)(const TQADrawContext *drawContext, TQATagInt tag); typedef void (*TQASetInt)(TQADrawContext *drawContext, TQATagInt tag, unsigned long newValue); typedef void * (*TQAGetPtr)(const TQADrawContext *drawContext, TQATagPtr tag); typedef void (*TQASetPtr)(TQADrawContext *drawContext, TQATagPtr tag, const void *newValue); typedef void (*TQADrawPoint)(const TQADrawContext *drawContext, const TQAVGouraud *v); typedef void (*TQADrawLine)(const TQADrawContext *drawContext, const TQAVGouraud *v0, const TQAVGouraud *v1); typedef void (*TQADrawTriGouraud)(const TQADrawContext *drawContext, const TQAVGouraud *v0, const TQAVGouraud *v1, const TQAVGouraud *v2, unsigned long flags); typedef void (*TQADrawTriTexture)(const TQADrawContext *drawContext, const TQAVTexture *v0, const TQAVTexture *v1, const TQAVTexture *v2, unsigned long flags); typedef void (*TQASubmitVerticesGouraud) ( const TQADrawContext *drawContext, unsigned long nVertices, const TQAVGouraud *vertices); typedef void (*TQASubmitVerticesTexture) ( const TQADrawContext *drawContext, unsigned long nVertices, const TQAVTexture *vertices); typedef void (*TQADrawTriMeshGouraud) ( const TQADrawContext *drawContext, unsigned long nTriangles, const TQAIndexedTriangle *triangles); typedef void (*TQADrawTriMeshTexture) ( const TQADrawContext *drawContext, unsigned long nTriangles, const TQAIndexedTriangle *triangles); typedef void (*TQADrawVGouraud)(const TQADrawContext *drawContext, unsigned long nVertices, TQAVertexMode vertexMode, const TQAVGouraud vertices[], const unsigned long flags[]); typedef void (*TQADrawVTexture)(const TQADrawContext *drawContext, unsigned long nVertices, TQAVertexMode vertexMode, const TQAVTexture vertices[], const unsigned long flags[]); typedef void (*TQADrawBitmap)(const TQADrawContext *drawContext, const TQAVGouraud *v, TQABitmap *bitmap); typedef void (*TQARenderStart)(const TQADrawContext *drawContext, const TQARect *dirtyRect, const TQADrawContext *initialContext); typedef TQAError (*TQARenderEnd)(const TQADrawContext *drawContext, const TQARect *modifiedRect); typedef TQAError (*TQARenderAbort)(const TQADrawContext *drawContext); typedef TQAError (*TQAFlush)(const TQADrawContext *drawContext); typedef TQAError (*TQASync)(const TQADrawContext *drawContext); typedef TQAError (*TQAGetNoticeMethod) ( const TQADrawContext *drawContext, TQAMethodSelector method, TQANoticeMethod *completionCallBack, void **refCon); typedef TQAError (*TQASetNoticeMethod) ( const TQADrawContext *drawContext, TQAMethodSelector method, TQANoticeMethod completionCallBack, void *refCon);
Private Draw Context Methods
typedef TQAError (*TQADrawPrivateNew) ( TQADrawContext *newDrawContext, const TQADevice *device, const TQARect *rect, const TQAClip *clip, unsigned long flags); typedef void (*TQADrawPrivateDelete) ( TQADrawPrivate *drawPrivate); typedef TQAError (*TQAEngineCheckDevice) ( const TQADevice *device); typedef TQAError (*TQAEngineGestalt) ( TQAGestaltSelector selector, void *response);
Color Lookup Table Methods
typedef TQAError (*TQAColorTableNew)( TQAColorTableType pixelType, void *pixelData, long transparentIndex, TQAColorTable **newTable); typedef void (*TQAColorTableDelete) ( TQAColorTable *colorTable);
Texture and Bitmap Methods
typedef TQAError (*TQATextureNew)(unsigned long flags, TQAImagePixelType pixelType, const TQAImage images[], TQATexture **newTexture); typedef TQAError (*TQATextureDetach) ( TQATexture *texture); typedef TQAError (*TQATextureBindColorTable) ( TQATexture *texture, TQAColorTable *colorTable); typedef void (*TQATextureDelete)(TQATexture *texture); typedef TQAError (*TQABitmapNew)(unsigned long flags, TQAImagePixelType pixelType, const TQAImage *image, TQABitmap **newBitmap); typedef TQAError (*TQABitmapDetach) ( TQABitmap *bitmap); typedef TQAError (*TQABitmapBindColorTable) ( TQABitmap *bitmap, TQAColorTable *colorTable); typedef void (*TQABitmapDelete)(TQABitmap *bitmap);
Method Reporting Methods
typedef TQAError (*TQAEngineGetMethod) ( TQAEngineMethodTag methodTag, TQAEngineMethod *method);
Notice Methods
typedef void (*TQANoticeMethod)(TQADrawContext *drawContext, void *refCon);
<a name="HEADING63-203"></a>
Result Codes
kQANoErr | 0 | No error |
kQAError | 1 | Generic error code |
kQAOutOfMemory | 2 | Insufficient memory for requested operation |
kQANotSupported | 3 | Requested feature is not supported |
kQAOutOfDate | 4 | A newer drawing engine was registered |
kQAParamErr | 5 | Invalid parameter |
kQAGestaltUnknown | 6 | Requested Gestalt type isn't available |
kQADisplayModeUnsupported | 7 | Engine cannot render to the display in its current mode |