Title Banner

Previous Book Contents Book Index Next

Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /
Chapter 13 - View Objects


Using View Objects

QuickDraw 3D 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.

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 1-28 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.

Note
The group of lights is optional. A view, however, must contain a camera, a renderer, and a draw context.

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, QuickDraw 3D 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 QuickDraw 3D 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.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
11 JUL 1996




Navigation graphic, see text links

Main | Top of Section | What's New | Apple Computer, Inc. | Find It | Feedback | Help