3D Graphics Programming with QuickDraw 3D

13 Using View Objects

QuickDraw3D supplies routines that you can use to create view objects, attach cameras, renderers, and other objects to them, and render images in those view objects. This section describes how to accomplish these tasks.

13 Creating and Configuring a View

You create a view object by calling the function Q3View_New. If successful, Q3View_New returns a new empty view object. You must then configure the view object by specifying a renderer, a camera, a group of lights, and a model. Listing 1-9 on page 130 illustrates how to create and configure a view. Only one object of each of these types can be associated with a view object at a given time. You can, however, have multiple view objects in your application, each associated with a different window.

The group of lights is optional. A view, however, must contain a camera, a renderer, and a draw context.<8bat>u

13 Rendering an Image

Once you have created and configured a view, you can use it to render an image of a model. To do so, you need to enter into the rendering state by calling the Q3View_StartRendering function. Then you specify the model to be drawn and call Q3View_EndRendering. Because the renderer might not
have had sufficient memory to complete the rendering when you call Q3View_EndRendering, you might need to respecify the model, to give the renderer another pass at the model's data. As a result, you almost always call Q3View_StartRendering and Q3View_EndRendering in a rendering loop, shown in outline in Listing 13-1.

Listing 13-1 Rendering a model

Q3View_StartRendering(myView);
do {
 /*submit the model here*/
} while (Q3View_EndRendering(myView) == 
           kQ3ViewStatusRetraverse);
The Q3View_EndRendering function returns a view status value that indicates the status of the rendering process. If Q3View_EndRendering returns the value kQ3ViewStatusRetraverse, you should reenter your rendering loop. If Q3View_EndRendering returns kQ3ViewStatusDone, kQ3ViewStatusError, or kQ3ViewStatusCancelled, you should exit the loop.

As you know, QuickDraw3D supports immediate mode, retained mode, and mixed mode rendering. You use a rendering loop for all these rendering modes, but they differ in how you create and draw the objects in a model. To use retained mode rendering, you let QuickDraw3D allocate memory to hold
the data associated with a particular object or group of objects. For example,
to render a box in retained mode, you must first create the box by calling
the Q3Box_New function. Then you draw the box by calling the Q3Geometry_Submit function, as illustrated in Listing 13-2.

Listing 13-2 Creating and rendering a retained object

TQ3BoxData       myBoxData;
TQ3GeometryObject       myBox;

Q3Point3D_Set(&myBoxData.origin, 1.0, 1.0, 1.0);
Q3Vector3D_Set(&myBoxData.orientation, 0, 2.0, 0);
Q3Vector3D_Set(&myBoxData.minorAxis, 2.0, 0, 0);
Q3Vector3D_Set(&myBoxData.majorAxis, 0, 0, 2.0);
myBox = Q3Box_New(&myBoxData);

Q3View_StartRendering(myView);
do {
 Q3Geometry_Submit(myBox, myView);
} while (Q3View_EndRendering(myView) == 
           kQ3ViewStatusRetraverse);
In general, you use retained mode rendering when much of the model remains unchanged from frame to frame. For retained mode rendering, you can use the following routines inside a rendering loop:

Q3Style_Submit
Q3Geometry_Submit
Q3Transform_Submit
Q3Group_Submit
To use immediate mode rendering, you allocate memory for an object yourself and draw the object using an immediate mode drawing routine, as illustrated in Listing 13-3.

Listing 13-3 Creating and rendering an immediate object

TQ3BoxData        myBoxData;

Q3Point3D_Set(&myBoxData.origin, 1.0, 1.0, 1.0);
Q3Vector3D_Set(&myBoxData.orientation, 0, 2.0, 0);
Q3Vector3D_Set(&myBoxData.minorAxis, 2.0, 0, 0);
Q3Vector3D_Set(&myBoxData.majorAxis, 0, 0, 2.0);

Q3View_StartRendering(myView);
do {
 Q3Box_Submit(myBoxData, myView);
} while (Q3View_EndRendering(myView) == 
           kQ3ViewStatusRetraverse);
In general, you use immediate mode when your application does not need to retain the geometric data for subsequent use.

13 - Creating and Configuring a View
13 - Rendering an Image

3D Graphics Programming with QuickDraw 3D - 17 OCT 1995

© Apple Computer, Inc.

Let us know what you think of these prototype pages.

Generated with Harlequin WebMaker