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 functionQ3View_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 theQ3View_StartRendering
function. Then you specify the model to be drawn and callQ3View_EndRendering
. Because the renderer might not have had sufficient memory to complete the rendering when you callQ3View_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 callQ3View_StartRendering
andQ3View_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);TheQ3View_EndRendering
function returns a view status value that indicates the status of the rendering process. IfQ3View_EndRendering
returns the valuekQ3ViewStatusRetraverse
, you should reenter your rendering loop. IfQ3View_EndRendering
returnskQ3ViewStatusDone
,kQ3ViewStatusError
, orkQ3ViewStatusCancelled
, 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 theQ3Geometry_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_SubmitTo 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.
Main | Top of Section | What's New | Apple Computer, Inc. | Find It | Feedback | Help