QuickDraw 3D

Software API for Macintosh 3D graphics. QuickDraw 3D is a Code Fragment Manager-based shared library, with a C-based API. It runs on all Power Macintosh computers and offers high-performance 3D rendering and other features that make working with 3D data easier.

QuickDraw 3D is a graphics library developed by Apple Computer that you can use to create, configure, and render three-dimensional objects. It is specifically designed to be useful to a wide range of software developers, from those with very little knowledge of 3D modeling concepts and rendering techniques to those with very extensive experience with those concepts and techniques.

At the most basic level, you can use the file format and file-access routines provided by QuickDraw 3D to read and display 3D graphics created by some other application. For example, a word-processing application might want to import a picture created by a 3D modeling or image-capturing application. QuickDraw 3D supports the 3D Viewer, which you can use to display 3D data and objects in a window and allow users limited interaction with that data, without having to learn any of the core QuickDraw 3D application programming interfaces.

Modeling and Rendering

To create images, you typically engage in at least two distinguishable main tasks: modeling and rendering. Modeling is the process of creating a representation of real or abstract objects, and rendering is the process of creating an image (on the screen or some other medium) of a model. QuickDraw 3D subdivides each of these tasks into a number of subtasks.

In QuickDraw 3D, modeling involves

• creating, configuring, and positioning basic geometric objects and groups of geometric objects. QuickDraw 3D defines many basic types of geometric objects and a large number of ways to transform such objects.
• assigning sets of attributes (such as diffuse and specular colors) to objects and parts of objects.
• applying textures to surfaces of objects.
• configuring a model's lights and shading. QuickDraw 3D supplies four types of lights (ambient light, directional lights, spot lights, and point lights) and several types of shaders.

In QuickDraw 3D, rendering involves

• specifying a camera position and type. A camera type is defined by a method of projecting the model onto a flat surface, called the view plane. QuickDraw 3D provides two types of cameras that use perspective projection (the aspect ratio and view plane cameras) and one type of camera that uses parallel projection (the orthographic camera).
• specifying a renderer or method of rendering. QuickDraw 3D provides a wireframe and an interactive renderer. Renderers support different styles of rendering (for example, points, edges, or filled shapes).
• creating a view (a collection of a group of lights, a camera, and a renderer and its styles) and rendering the model using the view to create an image.

Interacting

Often, modeling and rendering are not easily separable, particularly in applications that support interactive 3D modeling. When, for example, the user selects a sphere and drags it using the mouse or other pointing device, the application needs to change the model (reposition the sphere) and render a new image. (Indeed, the application may generate a series of new images to show the sphere changing location as the user drags it.) QuickDraw 3D supports a third main task, interacting with a model (that is, selecting and manipulating objects in the model).

In QuickDraw 3D, interacting involves

• determining what kinds of pointing devices are available on a particular computer and possibly configuring one or more of those devices to control items in a 3D model (such as a camera or a light).
• identifying the objects in a model that are close to the cursor when the user clicks or drags in the model's image. This is called picking.

QuickDraw 3D supplies an extensive set of routines that you can use to perform these tasks.

QuickDraw 3D RAVE (rendering acceleration virtual engine)

See the main article at QuickDraw 3D RAVE.

3D Rave Methods (ATi3D)

The following 3D Rave methods are supported by the ATi3D extension:

• QABitmapDelete
• QADrawBitmap
• QADrawContextDelete
• QADrawContextNew
• QADrawLine
• QADrawPoint
• QADrawTriGouraud
• QADrawTriMeshGouraud
• QADrawTriMeshTexture
• QADrawTriTexture
• QADrawVGouraud
• QADrawVTexture
• QAEngineGestalt
• QAFlush
• QAGetFloat
• QAGetInt
• QAGetPtr
• QARenderAbort
• QARenderEnd
• QARenderStart
• QASetFloat
• QASetInt
• QASetPtr
• QASync
• QATextureDetach
• QATextureNew

Documentation

• QuickDraw 3D: A New Dimension for Macintosh Graphics
• Adding Custom Data to QuickDraw 3D Objects
• Easy 3D With the QuickDraw 3D Viewer
• New QuickDraw 3D Geometries
• Game Controls for QuickDraw 3D
• NURB Curves: A Guide for the Uninitiated
• Graphical Truffles: Making the Most of QuickDraw 3D
• The Basics of QuickDraw 3D Geometries

Summary of QuickDraw 3D

C Summary

Constants

Gestalt Selector and Response Values

enum {
   gestaltQD3D                      = 'qd3d',
   gestaltQD3DNotPresent            = 0,
   gestaltQD3DAvailable             = 1
}

Basic Constants

typedef enum TQ3Boolean {
   kQ3False,
   kQ3True
} TQ3Boolean;
typedef enum TQ3Status {
   kQ3Failure,
   kQ3Success
} TQ3Status;
typedef enum TQ3Axis {
   kQ3AxisX,
   kQ3AxisY,
   kQ3AxisZ
} TQ3Axis;

QuickDraw 3D Routines

Initializing and Terminating QuickDraw 3D

TQ3Status Q3Initialize(void);
TQ3Status Q3Exit(void);
TQ3Boolean Q3IsInitialized(void);

Getting Version Information

TQ3Status Q3GetVersion(unsigned long *majorRevision,
unsigned long *minorRevision);

Managing Sets

TQ3SetObject Q3Set_New(void);
TQ3ObjectType Q3Set_GetType(TQ3SetObject set);
TQ3Status Q3Set_Add(TQ3SetObject set, 
TQ3ElementType type, 
const void *data);
TQ3Status Q3Set_Get(TQ3SetObject set, 
TQ3ElementType type, 
void *data);
TQ3Boolean Q3Set_Contains(TQ3SetObject set, TQ3ElementType type);
TQ3Status Q3Set_GetNextElementType (
TQ3SetObject set, TQ3ElementType *type);
TQ3Status Q3Set_Empty(TQ3SetObject target);
TQ3Status Q3Set_Clear(TQ3SetObject set, TQ3ElementType type);

Managing Shapes

TQ3ObjectType Q3Shape_GetType(TQ3ShapeObject shape);
TQ3Status Q3Shape_GetSet(TQ3ShapeObject shape, TQ3SetObject *set);
TQ3Status Q3Shape_SetSet(TQ3ShapeObject shape, TQ3SetObject set);

Managing Strings

TQ3ObjectType Q3String_GetType(TQ3StringObject stringObj);
TQ3StringObject Q3CString_New(const char *string);
TQ3Status Q3CString_GetLength(TQ3StringObject stringObj, 
unsigned long *length);
TQ3Status Q3CString_GetString(TQ3StringObject stringObj, 
char **string);
TQ3Status Q3CString_SetString(TQ3StringObject stringObj, 
const char *string);
TQ3Status Q3CString_EmptyData(char **string);

Errors, Warnings, and Notices

kQ3ErrorInternalError
kQ3ErrorNoRecovery
kQ3ErrorNotInitialized
kQ3ErrorAlreadyInitialized
kQ3ErrorUnimplemented
kQ3ErrorRegistrationFailed
kQ3ErrorMemoryLeak
kQ3ErrorOutOfMemory
kQ3ErrorNULLParameter
kQ3ErrorParameterOutOfRange
kQ3ErrorInvalidParameter
kQ3ErrorInvalidData
kQ3ErrorAcceleratorAlreadySet
kQ3ErrorInvalidObject
kQ3ErrorInvalidObjectType
kQ3ErrorInvalidObjectName
kQ3ErrorObjectClassInUse
kQ3ErrorAccessRestricted
kQ3ErrorMetaHandlerRequired
kQ3ErrorNeedRequiredMethods
kQ3ErrorNoSubClassType
kQ3ErrorUnknownElementType
kQ3ErrorNotSupported
kQ3ErrorNoExtensionsFolder
kQ3ErrorExtensionError
kQ3ErrorPrivateExtensionError
kQ3ErrorBadStringType
kQ3WarningInternalException
kQ3WarningNoObjectSupportForDuplicateMethod
kQ3WarningNoObjectSupportForWriteMethod
kQ3WarningNoObjectSupportForReadMethod
kQ3WarningNoObjectSupportForDrawMethod
kQ3WarningUnknownElementType
kQ3WarningTypeAndMethodAlreadyDefined
kQ3WarningTypeIsOutOfRange
kQ3WarningTypeHasNotBeenRegistered
kQ3WarningInvalidSubObjectForObject
kQ3WarningInvalidHexString
kQ3WarningUnknownObject
kQ3WarningInvalidTableOfContents
kQ3WarningUnresolvableReference
kQ3WarningNoAttachMethod
kQ3WarningInconsistentData
kQ3WarningLowMemory
kQ3WarningPossibleMemoryLeak
kQ3NoticeDataAlreadyEmpty
kQ3NoticeMethodNotSupported
kQ3NoticeObjectAlreadySet

QuickDraw 3D Sample Gallery

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

See Also

• Apple QuickDraw 3D Accelerator Card
• QuickDraw 3D RAVE
• Apple Computer

Application Programming Interface