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

From Higher Intellect Vintage Wiki
Jump to navigation Jump to search

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.

Contents

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);

Result Codes

kQANoErr0No error
kQAError1Generic error code
kQAOutOfMemory2Insufficient memory for requested operation
kQANotSupported3Requested feature is not supported
kQAOutOfDate4A newer drawing engine was registered
kQAParamErr5Invalid parameter
kQAGestaltUnknown6Requested Gestalt type isn't available
kQADisplayModeUnsupported7Engine cannot render to the display in its current mode

See Also