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

From Higher Intellect Vintage Wiki
Jump to navigation Jump to search
Foundation.gif
RotatingQ.gif
AnimatedCube.gif

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.

QuickDraw 3D: Apple's Foundation for 3D Graphics

Apple Macintosh computers have long been the desktop platform of choice for graphics professionals due to Apple's innovation in ease of use, consistency in application interface, and the development of revolutionary graphics and multimedia technologies. Over the years, Apple has extended the Macintosh computer's lead by adding capabilities to the Mac OS such as QuickTime & QuickTime VR. These technologies have given personal computer users unprecedented control and flexibility over 2D graphics, the printed page, photography, and most recently, digital video.

In the summer 1995, with the introduction of QuickDraw 3D, Apple will extend its innovation into the complex world of 3D graphics.

QuickDraw 3D, for the first time on any personal computer, integrates 3D graphics technology into a "mainstream" operating system and takes full advantage of the PowerPC RISC chip found at the heart of Power Macintosh, the leading volume RISC platform.

The introduction of QuickDraw 3D - and the spread of applications that use QuickDraw 3D - will let users create, manipulate, and incorporate 3D graphics into their documents and presentations as easily as they do with 2D graphics today. Additionally, 3D applications that have been modified to support QuickDraw 3D and its associated user interface guidelines will move users toward a more standard approach to 3D graphics that will coexist with all of their current applications.

QuickDraw 3D snapshot

QuickDraw 3D helps eliminate many of the problems that have dogged 3D graphics by providing a consistent file format; a standard, extensible, cross-platform 3D API; and a set of 3D interface standards and guidelines-complete with a developer's toolkit for implementing them.

Consistent file format

The new 3D metafile (3DMF) format is a cross-platform file format that supports 3D data - not simply geometry but all the information that represents a particular view or scene. The 3DMF format enables users to share 3D images among applications with the same ease that they currently share PICT images.

Standard developer API

The QuickDraw 3D API gives developers an easy way to access a standard set of 3D operations, so they don't have to reinvent common 3D functions. It includes a complete set of 3D geometry, a shading and rendering architecture, a device and acceleration manager, and a common approach to 3D pointing devices.

Consistent user interface standards and guidelines

Consistent user interface standards and guidelines have been key to the success of the Macintosh. QuickDraw 3D will provide the first set of desktop user interface standards and guidelines for 3D graphics applications in the industry. With these standards - and a complete developer's toolkit -developers won't have to reinvent common interface elements, so users can apply their 2D interface knowledge to 3D applications, and even extend their 3D familiarity across 3D programs.

Extensibility and plug and play

Perhaps most important, each of the components of the API is extensible, making QuickDraw 3D one of the most open architectures in the industry. The file format, interface architecture, geometry engine, and "plug-in" shading and rendering architecture are all designed to allow developers-and ultimately customers-to add their own value to the system. In addition, the 3D acceleration manager allows for plug-and-play hardware accelerators. Using this manager, the user can add a 3D accelerator card to a Macintosh, and the interactive renderer is accelerated in any application that makes use of it.

Cross-platform support

Apple is also committed to helping developers protect their investments in time, effort, and innovation; QuickDraw 3D has been developed from the outset as a machine-independent, cross-platform application programming interface (API). Apple will release QuickDraw 3D for Windows within 6 months after the initial release of QuickDraw 3D for the Macintosh. The API for Windows software will let developers leverage their Macintosh development efforts onto the Windows platform, while still enjoying all of the benefits of ease of use, interface consistency, and standards-based development that they've come to expect on the Macintosh. A QuickDraw 3D Cross-platform Parser for Windows & Unix machines lets any application on any platform read and write QuickDraw 3D Metafile formats. The QuickDraw 3D Parser is available now.

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

Summary of QuickDraw 3D

Qt3d.gif

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