OCOSMO 3D Manual de usuario

Cosmo 3D™Programmer’s GuideDocument Number 007-3445-002

xContents4. Scene Graph Nodes 55What Is a Node 56Node Types 56Leaf Nodes 57csShape 57Group Nodes 58Group Node Types 58Using csSwi

74Chapter 5: Building a Scene GraphLoading a VRML Scene GraphExample 5-2 shows a portion of vrml.cxx. The example illustrates how to load a VRMLscene

Saving Scene Graphs75Saving Scene GraphsThe data in the scene graph database is not necessarily static. You might, therefore, needto save scene graph

77Chapter 66. Placing Shapes in a SceneWhen you create a geometry, it has a specified size, location, and orientation, as definedin its own space. You p

78Chapter 6: Placing Shapes in a SceneOverriding the Default Order of Layering ShapesTo override this layering effect, you can use the csContext::setc

Transforming Shapes to New Locations, Sizes, and Orientations79Transforming Shapes to New Locations, Sizes, and OrientationsThe csTransform node• Allo

80Chapter 6: Placing Shapes in a SceneSetting the TransformationThe csTransform node allows you to set the location (translation), rotation, and scale

Transforming Shapes to New Locations, Sizes, and Orientations81Figure 6-2 Scaling in Different OrientationsAll of these methods invisibly set a transf

82Chapter 6: Placing Shapes in a SceneWhen you reverse the order of the transformations, the end result is different. Since thecenter of rotation is t

83Chapter 77. Traversing the Scene GraphOnce you create a scene graph, you apply an action to the root node to trigger the eventsprescribed in the sce

ContentsxiTransforming Shapes to New Locations, Sizes, and Orientations 79Placing Transform Nodes 79Setting the Transformation 80Ordering Tra

84Chapter 7: Traversing the Scene GraphThe action-specific responses taken by a node are implemented in the following nodefunctions:• draw()—for csDraw

Scene Graph Actions85You invoke an action by creating an instance of an action class and applying it to a node(commonly the root node), for example:cs

86Chapter 7: Traversing the Scene GraphPlaying Sound FilescsSoundAction plays sound files. The csSound node indirectly specifies—throughcsAudioClip and

The Order In Which Actions Are Passed Between Nodes87Figure 7-1 The Flow of an Action Through A Scene GraphA top-down traversal means that a node can

89Chapter 88. Lighting and FogThis chapter discusses two features implemented by subclasses of csEnvironment,lighting and fog.• Lights illuminate shap

90Chapter 8: Lighting and FogcsLightcsLight is an abstract base class for light sources. It provides the following methods forsetting light values:voi

Using Lights in Scenes91csSpotLightcsSpotLight is a directional light source. Because csSpotLight is subclassed fromcsPointLight, csSpotLight can be p

92Chapter 8: Lighting and FogLimiting the Scope of LightscsEnvironment defines the scope of environmental effects, such as how far light from acsLight

Using Fog in Scenes93// add the lights to the environment light arraypark->light()->append(3, spot);park->light()->append(4, flood);Using

xiiContentscsOrthoCamera 101csPerspCamera 101Setting the Frustum 102Setting the Clip Planes 103Setting the Fields of View 103Offsetting

94Chapter 8: Lighting and FogAll types of geometric primitives can be fogged, including points and lines. Using the fogeffect on points and lines is a

Using Fog in Scenes95In general whoever is OFF has precedence.• If csContext::fogEnable is OFF, no fog is drawn unless there is a csAppearance thathas

97Chapter 99. Viewing the SceneTo view a scene, you must define:• The size of the viewport.• The position and the orientation of the camera.This chapte

98Chapter 9: Viewing the SceneFigure 9-1 ViewportYou set the size of the viewport using the following csContext method:static void setViewport(csInt x

csCamera99csCameracsCamera is an abstract base class from which all other cameras are derived. csCameradefines the viewing volume. The viewing volume i

100Chapter 9: Viewing the SceneFigure 9-3 Changing the Window Without Changing the Image’s AspectIt is important, therefore, to change the aspect of t

csOrthoCamera101csOrthoCameracsOrthoCamera defines an orthographic projection. An orthographic projection uses aparallelepiped (box) frustum. Unlike th

102Chapter 9: Viewing the SceneFigure 9-4 Perspective ExplainedIf you compare the height of an object in the near clipping plane to the height of the

csPerspCamera103Setting the Clip PlanesYou use the following fields to set the distance to the near and far clip planes:void setNearClip(csFloat nearCl

Contentsxiii11. Sensors 121csTimeSensor 122Enabling csTimeSensor 122Updating csTimeSensor 123Updating with csWindow 123Setting the Star

104Chapter 9: Viewing the SceneFigure 9-5 Horizontal and Vertical Fields of View OffsetsThe offset angles are measured starting at the -z axis, follow

csFrustumCamera105csFrustumCameracsFrustumCamera allows you to work directly with a frustum without worrying aboutthe specifics of a camera. You define

107Chapter 1010. Scene Graph EnginesThere are classes that work with scene graphs, but are not nodes; they cannot be part ofthe scene graph, but they

108Chapter 10: Scene Graph EnginesInput and Output FieldscsEngine has input and output fields. csEngine updates its output fields according to thefuncti

Engines109Engine TypesMany engines interpolate between two values at specified increments. For example, arotation interpolator might take the beginning

110Chapter 10: Scene Graph EnginescsInterpolator is the base class for the following engines:• csColorInterpolator• csCoordinateInterpolator• csNormal

Engines that Interpolate Values111Interpolator nodes are designed for linear, keyframed animation, that is, an interpolatornode defines a piecewise lin

112Chapter 10: Scene Graph EnginescsInterpolator FieldsThe fields in csInterpolator include:void setFraction(float fraction);float

Engines that Interpolate Values113Keys and Key ValuesIn Figure 10-3, the X axis represents keys, such as time, and the Y axis represents anyattribute

xivContentscsTouchSensor 134Associating csTouchSensor and Geometry 134Scope of csTouchSensor 135csTouchSensor Output 135isOver Event 13

114Chapter 10: Scene Graph EnginescsColorInterpolatorThis node interpolates among a set of key values in a csMFColor to produce a csSFColor(RGB) color

Engines that Interpolate Values115When P and Q are pointed in opposite directions, they are on opposite sides of the unitsphere, and therefore all arc

116Chapter 10: Scene Graph EnginescsPositionInterpolatorcsPositionInterpolator linearly interpolates between sets of values in a SFVec3f. This isappro

Engines That Change Shapes117csSelectorEng3F and csSelectorEng4FcsSelectorEng3F and csSelectorEng4F sets the output value to the nth item in the input

118Chapter 10: Scene Graph EnginescsMorphEng FieldscsMorphEng contains the following fields:csMFInt* count() const;csMFInt* index

Engines That Change Shapes119Example 10-1 Building a Morph Engine: the Worm// Build morph engine MorphCoords = new csMorphEng3f; // “Neutral” is

120Chapter 10: Scene Graph EnginescsTransformEng FieldscsTransformEng has the following fields:void setTransformType(TransformTypeEnum t

121Chapter 1111. SensorsSensors are used to detect one of the following:• Time passing.• Pointer device events.Sensors are often implemented to perfor

122Chapter 11: SensorscsTimeSensorcsTimeSensor generates timer events either once or repeatedly for a specified interval. AcsTimeSensor is typically us

csTimeSensor123Updating csTimeSensorcsTimeSensors are not automatically evaluated. The following method triggers theevaluation of all instantiated csT

ContentsxvBack Patch Culling 152Back Patch Culling Advantage 153When to Use Back Patch Culling 154Method of Calculation 154Updating the Vi

124Chapter 11: SensorsYou can, for example, trigger events based on the time of day usingcsTime::getTimeOfDay(), which returns the current time of day

csTimeSensor125Continuing Timer EventscsTimeSensor::loop() takes a boolean value. If it is TRUE, the csTimeSensor continuesto generate events after th

126Chapter 11: SensorscsSphereSensorcsSphereSensor maps the drag motion of a pointer device into a spherical rotation abouta virtual sphere. The rotat

csSphereSensor127csSphereSensor EventsA csSphereSensor begins generating events when both of the following conditions aremet:• The pointer device curs

128Chapter 11: SensorsUpdating csSphereSensorcsSphereSensor is not updated automatically. You customarily update it explicitly whenpointer device even

csSphereSensor129Figure 11-2 Placing csSphereSensor in a Scene GraphA csSphereSensor is activated when the pointer device is depressed over its associ

130Chapter 11: SensorscsPlaneSensorA csPlaneSensor maps the drag motion of a pointer device’s events into a translation inthe XY plane of the local or

csPlaneSensor131Figure 11-3 Placing csPlaneSensor in a Scene GraphScope of csPlaneSensorA csPlaneSensor translates all geometries in the scene graph “

132Chapter 11: SensorsUpdating csPlaneSensorcsPlaneSensor is not updated automatically. You customarily update it explicitly whenpointer device events

csPlaneSensor133TrackPoint events represent unclamped drag positions of the geometry in the XY planeof local or world space, depending on the value se

xviContentsSpecifying Audio Files 174Manipulating the Audio Samples Directly 176Example Setting a csAudioSamples Node 176Playing Sound in Imm

134Chapter 11: SensorscsTouchSensorcsTouchSensor tracks the location of the pointer device cursor and generates up to fiveoutputs when the cursor is ov

csTouchSensor135Scope of csTouchSensorA csTouchSensor monitors all geometries in the scene graph “below” the parent node ofthe csTouchSensor. Not only

136Chapter 11: SensorsHit EventscsTouchSensor generates the following three hit events whenever the pointing device isover a geometry associated with

137Chapter 1212. User Interface MechanismsCosmo 3D applications either appear within a csWindow object or a window object thatyou create using X windo

138Chapter 12: User Interface MechanismsTo reposition or reshape the window after its initial display, use the following methods:static void p

Handling User Input139Handling User InputEvents, such as mouse motion, key presses, and window resize, are converted to csEventobjects and queued on t

140Chapter 12: User Interface MechanismsWhen csWindow::setFreeRun() is TRUE, callbacks are invoked only when the main loopgoes idle, similar to the CO

Selecting Screen Objects141Figure 12-1 Ray Pick ActionThe shape closest to the origin of the csSeg and intersected by the line segment isrecorded in a

142Chapter 12: User Interface MechanismsStoring Selected Screen ObjectscsHit objects hold pointers to objects selected using a variety of mechanisms.

Creating Your Own Window143Creating Your Own WindowInstead of using the window provided by Cosmo 3D, csWindow, you can create yourown window using X11

ContentsxviiB. Cosmo 3D Sample Application 193Cube.cxx Explained 195Understanding the Different Parts of Cube.cxx 202Scene Graph for Cube.cxx

145Chapter 1313. MultiprocessingIf you would like to display two views of the same scene graph, you need to use themultiprocessing capabilities of Cos

146Chapter 13: MultiprocessingImplementing MultiprocessingOne rule that you must follow when implementing multiprocessing is the scene graphcannot be

Implementing Multiprocessing147To create a thread and bind it appropriately, use the following procedure:1. Create a thread, as follows:csThread* draw

148Chapter 13: MultiprocessingThread ParametersThread-related parameters include the following csThread methods:• numProcessors()—returns the number o

Thread Blocking149Figure 13-2 Blocking Action of Multiple ThreadsThe general order of events displayed in Figure 13-2 is as follows:1. The application

150Chapter 13: MultiprocessingCleaning the csContext FieldsBefore rendering, the application thread must call csField::cleanFields() to clean thecsCon

151Chapter 1414. Optimizing RenderingOne of the greatest challenges developers face is optimizing application performance.This chapter describes the C

152Chapter 14: Optimizing RenderingFace CullingWhen solid, three-dimensional geometry is rendered, the side of it facing away from thecamera is normal

Back Patch Culling153Figure 14-1 shows the same geometry before and after back patch culling.Figure 14-1 Before and After Back Patch CullingBack Patch

154Chapter 14: Optimizing RenderingBack patch culling usually reduces the work done by the graphics hardware but it doesincrease the workload of the h

Back Patch Culling155Updating the View VectorAs long as you use csDrawAction::apply() to initiate the back patch culling, you neverneed to calculate t

156Chapter 14: Optimizing RenderingFigure 14-4 Direction of NormalsChoosing the Type of NormalThe csGeoSet method, setBPCullVertNormModeEnable(), sets

Back Patch Culling157Face normals are used by default with the following primitive types:• csPolySet• csQuadSet• csTriFanSet• csTriSet• csTriStripSetI

158Chapter 14: Optimizing RenderingBuilding Back Patch Culling Data for a csGeoSetBefore calling a csDrawAction, which triggers back patch culling, yo

Back Patch Culling159Back Patch Culling CodeNow that you understand all the facets of back patch culling, Example 14-1 presents theseries of calls you

160Chapter 14: Optimizing RenderingCulling the View FrustumView frustum culling eliminates from the rendering list all of those shapes not in theviewi

Level of Detail Reduced for Performance161csLOD allows you to reach a compromise between performance and the level of detailrendered. For high quality

162Chapter 14: Optimizing RenderingThe camera may disregard range values and• Display an already-fetched level of detail while a higher level of detai

Performance Programming Techniques163Performance Programming TechniquesThe following sections provide programming tips for improving the performance o

xixList of FiguresFigure 1-1 Cube Scene Graph 8Figure 1-2 Two Transformations into World Space 10Figure 2-1 Primitives in a csGeoSet 18Figure

164Chapter 14: Optimizing RenderingIndexing csGeoSet AttributesYou can specify the appearance of all the csGeoSet elements making up a geometryeither

Performance Programming Techniques165Figure 14-6 Arranging Scene Graph NodesWhen an action traverses a scene graph, the more nodes it visits, the long

167Chapter 1515. Adding Sounds To Virtual WorldsYou can incorporate sound into your virtual worlds by including at least one csSoundnode in a scene gr

168Chapter 15: Adding Sounds To Virtual WorldsOverviewA csSound node contains the location of a sound file and the parameters used for playingit. To pl

Overview169csSound FieldsThe fields in csSound specify the sound source to play by specifying a csAudioClipobject. csSound can optionally specify the l

170Chapter 15: Adding Sounds To Virtual WorldsTo choose a starting location in a sound file, pass the starting frame to thesetCurrentFrame() field. A fr

Overview171Figure 15-2 Sound DirectionIn this figure, (1.0, 1.0, 0.0) is passed as the direction vector to setDirection(). The ellipsetips, accordingly

172Chapter 15: Adding Sounds To Virtual WorldsOutside of the maximum intensity perimeter, the intensity of the sound attenuates overdistance until it

How to Play a Sound File173How to Play a Sound FileYou use csAudioClip to specify how to play the sound files referenced in thecsAudioSamples node.csAu

Cosmo 3D™ Programmer’s GuideDocument Number 007-3445-002CONTRIBUTORSWritten by George EckelIllustrated by Dany Galgani and Martha LevineProduction by

xxList of FiguresFigure 9-1 Viewport 98Figure 9-2 Aspect Ratio 99Figure 9-3 Changing the Window Without Changing the Image’s Aspect 100Figure

174Chapter 15: Adding Sounds To Virtual WorldsExample 15-1 sets all of the fields in a csAudioSamples node.Example 15-1 Setting the Fields in a csAudio

Specifying Audio Files175csAudioSamples has the following fields:void setFileName(const csString& fileName);void setN

176Chapter 15: Adding Sounds To Virtual WorldsManipulating the Audio Samples DirectlycsAudioSample::samples() returns the multivalued array field that

Playing Sound in Immediate Mode177Playing Sound in Immediate ModeWhen a csSoundAction is invoked on a scene graph, the action traverses the scene grap

167Chapter 1515. Adding Sounds To Virtual WorldsYou can incorporate sound into your virtual worlds by including at least one csSoundnode in a scene gr

168Chapter 15: Adding Sounds To Virtual WorldsOverviewA csSound node contains the location of a sound file and the parameters used for playingit. To pl

Overview169csSound FieldsThe fields in csSound specify the sound source to play by specifying a csAudioClipobject. csSound can optionally specify the l

170Chapter 15: Adding Sounds To Virtual WorldsTo choose a starting location in a sound file, pass the starting frame to thesetCurrentFrame() field. A fr

Overview171Figure 15-2 Sound DirectionIn this figure, (1.0, 1.0, 0.0) is passed as the direction vector to setDirection(). The ellipsetips, accordingly

xxiList of TablesTable 2-1 Geometry Terminology 16Table 2-2 Fields in a csGeoSet 19Table 2-3 Attribute Bindings 21Table 4-1 Examples of Field

172Chapter 15: Adding Sounds To Virtual WorldsOutside of the maximum intensity perimeter, the intensity of the sound attenuates overdistance until it

How to Play a Sound File173How to Play a Sound FileYou use csAudioClip to specify how to play the sound files referenced in thecsAudioSamples node.csAu

174Chapter 15: Adding Sounds To Virtual WorldsExample 15-1 sets all of the fields in a csAudioSamples node.Example 15-1 Setting the Fields in a csAudio

Specifying Audio Files175csAudioSamples has the following fields:void setFileName(const csString& fileName);void setN

176Chapter 15: Adding Sounds To Virtual WorldsManipulating the Audio Samples DirectlycsAudioSample::samples() returns the multivalued array field that

Playing Sound in Immediate Mode177Playing Sound in Immediate ModeWhen a csSoundAction is invoked on a scene graph, the action traverses the scene grap

179Appendix AA. Cosmo Basic TypesThis chapter discusses all of the basic types that are used in other Cosmo 3D classes. Thebasic class types fall into

180Appendix A: Cosmo Basic TypesArray Storage Class TypesThe array classes store data.• csData—stores raw data.• csArray—is a virtual array class.• Ar

Array Storage Class Types181Array ClassescsArray is a virtual array class from which all other array classes are derived. Arrays areused as storage ve

182Appendix A: Cosmo Basic TypesTo fill an array, or to retrieve values from an array, use one of the set() or get() methodsin the class, respectively,

Vector Classes183• Use the append() method to add a value after the last value in an array.• Use the insert() method to insert a value at a specified i

184Appendix A: Cosmo Basic TypesVector MathVectors are used in a variety of ways in Cosmo 3D. Commonly, they are used to defineorientation, rotation, a

Vector Classes185The classes contain the following methods:csBool equal(const csVec4f& v) const;csBool almostEqual(const csVec4f& v

186Appendix A: Cosmo Basic TypesThe classes also provide the following write and operator methods:void write(csOutput *out);csVec4f& ope

Bounding Volumes187• A csVec3f::xformPt(const csVec3f& v, const csMatrix4f& m) transform vector sets acsVec3f vector, v, to be the first three

188Appendix A: Cosmo Basic TypesCosmo 3D provides two bounding shapes as well as an abstract class from which you canderive your own bounding shapes.•

Field Classes189csFieldcsField is the abstract class from which all of the other field classes are derived. Becauseit does not have a constructor, you

190Appendix A: Cosmo Basic TypesThe editDone() method allows you to signal when you have finished manipulating thecsMField object so that, for example,

Other Math Classes191You can fill an array by setting groups of values using the following methods:void setRange(int i, int count, csInt vals[])

xxiiiAbout This GuideCosmo 3D is a new toolkit that brings 3D graphics programming to desktop applications.Cosmo 3D is a scene graph API; its concepts

192Appendix A: Cosmo Basic TypescsPlanecsPlane represents a half space with a normal and an offset, which together form theparameters of the tradition

193Appendix BB. Cosmo 3D Sample ApplicationThis appendix discusses a simple Cosmo 3D application, called cube.cxx. The files are inthe following locati

194Appendix B: Cosmo 3D Sample ApplicationThese are the sections in this chapter:•“Cube.cxx Explained” on page 195.•“Understanding the Different Parts

Cube.cxx Explained195Cube.cxx ExplainedExample B-1 shows the cube.cxx application. It also includes embedded comments (notfound in the cube.cxx file) t

196Appendix B: Cosmo 3D Sample Application//Start the application hereintmain(int argc, char *argv[]){int doOrthoCam = 0, doFullScreen = 0;if(argc >

Cube.cxx Explained197// define render windowif (doFullScreen) {csWindow::initPosition(0, 0);csWindow::initSize(csWindow::get(csWindow::SCREEN_WIDTH),

198Appendix B: Cosmo 3D Sample Applicationintframe(void*){static int frame = 0;const csEventArray &elist = csWindow::getCurrent()->getEvents();

Cube.cxx Explained199// swap bufferscsWindow::swapBuffers();frame++;return csWindow::CONTINUE;}//Create a cube; the cube will be rendered twice.static

200Appendix B: Cosmo 3D Sample ApplicationcsQuadSet *gset = new csQuadSet;// cube verticescsCoordSet3f *cset = new csCoordSet3f(numCubeCoords);cset-&g

Cube.cxx Explained201highlight = new csAppearance;highlight->setMaterial(hlMaterial);highlight->setLightEnable(1);// red cubecsMaterial *redMate

xxivAbout This Guidexxiv• Chapter 3, “Specifying the Appearance of Geometries,” describes the appearancefields in csContext and csAppearance.• Chapter

202Appendix B: Cosmo 3D Sample Application// environmentcsPointLight *lt = new csPointLight;csEnvironment *environment = new csEnvironment;environment

Scene Graph for Cube.cxx203Scene Graph for Cube.cxxScene graphs provide the structure for Cosmo 3D applications. Cosmo 3D applicationsuse scene graphs

204Appendix B: Cosmo 3D Sample ApplicationIn cube.cxx, csGeometry defines a cube and the csAppearance nodes specify the greenand red colors of the cube

Scene Graph for Cube.cxx205Figure B-3 Two Transformations Into World SpaceIn Figure B-3, after the leaf node is transformed twice, it is placed in wor

206Appendix B: Cosmo 3D Sample ApplicationCreating the User InterfacecsWindow encapsulates the user interface: it includes the methods you use to cons

Scene Graph for Cube.cxx207SummaryThe following procedure summarizes the steps you take to create and render a verysimple scene graph.1. Create csAppe

209Appendix CC. Cosmo 3D Class HierarchyThe following list shows the class hierarcy in Cosmo 3D.csActionFunTablecsArraycsByteArraycsFloatArraycsIntArr

210Appendix C: Cosmo 3D Class HierarchycsFieldcsMFieldcsMFBytecsMFFloatcsMFIntcsMFMatrix4fcsMFRefcsMFRotationcsMFStringcsMFVec2fcsMFVec3fcsMFVec3scsMF

211csFieldInfocsMFByteInfocsMFFloatInfocsMFIntInfocsMFMatrix4fInfocsMFRefInfocsMFRotationInfocsMFStringInfocsMFVec2fInfocsMFVec3fInfocsMFVec3sInfocsMF

About This GuidexxvRelated ReadingReference pages for Cosmo 3D are obtained by pointing your web browser at:• For IRIX: /usr/share/Optimizer/doc/devel

212Appendix C: Cosmo 3D Class HierarchycsObjectcsActioncsCompileActioncsTransformActioncsIsectActioncsSoundActioncsVFCullActioncsDrawActioncsContainer

213csNodecsEnginecsInterpolatorcsColorInterpolatorcsCoordinateInterpolatorcsNormalInterpolatorcsOrientationInterpolatorcsPositionInterpolatorcsScalarI

214Appendix C: Cosmo 3D Class HierarchycsTexCoordSetcsTexCoordSet2fcsTexGencsTexturecsImageTexturecsContextcsDatacsDispatchcsEventcsHitcsOverrideGeoPr

215Aactions, 67, 83addChild(), 66ambient color, 51animate, 121animation, creating, 124application, simple, 193aspect ratio, 99atmospheric effec

216IndexcsEnvironment, 12, 59, 92csFog, 94csField, 5, 189csFieldInfo, 189csFog, 94fields, 94csFrustum, 105, 192csFrustumCamera, 105csGeoMath.h,

217IndexcsThread, 146csTimeSensor, 122csTimeSensor, active or not, 124csTimeSensors, updating, 123csTouchSensor, 134csTouchSensor, scope of, 135

218Indexflight simulationfog, use of, 93fog, 93-??, 94example program, 95FOV, 104fractionChanged, 125frustum, 160, 192frustum culling, 160Ggeome

219IndexOOBJECT_LINEAR, 50offset, rotation, 126opBarrier, 146OpenGL, 37OpenGL Optimizer, 1optimize, 151optimize,setCullFace(), 152optimizing pe

220IndexsetMatrix(), 81setNearClip(), 103setPolyMode(), 52setPosition(), 100setScaleOrientation(), 80setTexGen(), 50setting fields, 61setTransla

221IndexVviewusing camera, 98viewport, 97virtual sphere, 126visual simulationfog, use of, 93VRML, 74Wwait(), 148window, creating your own, 143w

xxviAbout This GuidexxviStyle ConventionsThese style conventions are used in this guide:• Bold—Functions, class names, node names, data members, and d

Tell Us About This ManualAs a user of Silicon Graphics products, you can help us to better understand your needsand to improve the quality of our docu

1Chapter 11. Getting Started with Cosmo 3DCosmo 3D is a scene graph API that brings 3D graphics programming to desktopapplications. Cosmo 3D speeds up

2Chapter 1: Getting Started with Cosmo 3DUnderstanding a Cosmo 3D Scene GraphA scene graph is a directed acyclical graph of nodes that embodies the se

Scene Graph Base Classes3The csObject ClassThe csObject class is the base class for all objects in a scene; where an object is an entitythat you can p

iiiContents at a GlanceList of Figures xxiList of Tables xxiiiAbout This Guide xxvWhat This Guide Contains xxvRelated Reading xxviiWho

4Chapter 1: Getting Started with Cosmo 3DExample 1-1 demonstrates how reference counts are incremented and decremented.Example 1-1 Objects and Referen

Scene Graph Base Classes5The csContainer ClasscsContainer objects contain data associated with scene graphs. The data in csContainerobjects is grouped

6Chapter 1: Getting Started with Cosmo 3DSingle-Item and Multi-Item FieldsEach field contains either a single value of a simple data type, such as a flo

Scene Graph Construction Classes7Scene Graph Construction ClassesThis section discusses several essential elements of a scene graph.These elements are

8Chapter 1: Getting Started with Cosmo 3DFigure 1-1 Cube Scene GraphThe csGroup ClassThe csGroup class allows applications to group a list of csNodes.

Scene Graph Construction Classes9The csTransform ClassA csTransform is a csGroup that allows applications to apply a transformation to all ofits child

10Chapter 1: Getting Started with Cosmo 3DFigure 1-2 Two Transformations into World SpaceGroup nodeLeaf nodeGroup nodeTransform nodeTransform node

Scene Graph Construction Classes11The csShape ClasscsShape nodes, derived from csNode, define a textured geometry by associating acsAppearance, which d

12Chapter 1: Getting Started with Cosmo 3DClasses That Determine How Things Are DrawnThe set of nodes discussed in this section determines how things

Classes defining Geometric Objects13Classes defining Geometric ObjectsThe actual geometric objects in a Cosmo 3D scene graph are derived as follows:• A

ivContents at a Glance3. Specifying the Appearance of Geometries 35csContext Overview 35Changing the Context 39Using csAppearance 40Applyi

14Chapter 1: Getting Started with Cosmo 3D5. Add the csTransform node as a child of a csGroup-type node.For more information about adding nodes to sce

15Chapter 22. Creating GeometriescsGeometry is an abstract class. All derivations of the class represent one or moregeometric objects, either concrete

16Chapter 2: Creating GeometriesGeometry TerminologyTable 2-1 briefly summarizes the geometry terminology used in this manual.Understanding the key ter

Creating csGeoSet Objects17Each class has methods that allow you to set and retrieve the values necessary to definethe geometry, including (where appro

18Chapter 2: Creating GeometriesFigure 2-1 Primitives in a csGeoSetThese attributes are captured in csGeoSet fields.StripLengthsPrimCoordsColorBindMorm

Creating csGeoSet Objects19csGeoSet FieldsThe fields in a csGeoSet object can be grouped in the following manner:The remainder of this section describe

20Chapter 2: Creating GeometriescsGeoSet AttributescsGeoSet is a virtual class from which all geometric primitives are derived. Cosmo3D-supplied csGeo

csGeoSet Attributes21For example, a single color can be specified for the entire collection of primitives, forindividual primitives, or per vertex. One

22Chapter 2: Creating GeometriesThe enumerated binding values that are valid for each of the attributes coincide with theentries in Table 2-3.enum Nor

Setting Attributes23This pattern continues, as shown in Figure 2-2.Figure 2-2 Sequential Specification of Attributes Per PrimitiveIndexing AttributesAn

Contents at a Glancev9. Viewing the Scene 97Setting the Screen Display of the Scene 97csCamera 99csOrthoCamera 101csPerspCamera 101csFr

24Chapter 2: Creating GeometriesFigure 2-3 Indexed AttributesWhen to Index AttributesFor all primitives in a csGeoSet, you have to decide whether to u

Setting Attributes25Figure 2-4 Deciding Whether to Index AttributesIn the triangle strip, each vertex is shared by two adjoining triangles. In the squ

26Chapter 2: Creating GeometriesSpecifying AttributesWhether you index your attributes or not, you must use the following set...() methods incsGeoSet

Setting Attributes27The first constructor allows you to specify the number of array primitives, n.The second constructor allows you to reference an arr

28Chapter 2: Creating GeometriesIndexing AttributesAn indexed csGeoSet object uses a list of unsigned short integers to index an attributearray. Four

Setting Attributes29// Set the attribute bindingsgset->setNormalBind(csGeoSet::PER_VERTEX_NORMS);gset->setColorBind(csGeoSet::PER_PRIM_COLORS);/

30Chapter 2: Creating GeometriesCosmo 3D-Derived csGeoSet Objects Cosmo 3D provides the following csGeoSet collections. Each is a derivative ofcsGeoSe

Cosmo 3D-Derived csGeoSet Objects31Using csLineSetA csLineSet object contains a collection of lines of equal length. The fields allow you toset and ret

32Chapter 2: Creating GeometriesUsing csTriFanSetA csTriFanSet is a set of triangles all of which share one common vertex, as shown inFigure 2-6.Figur

Cosmo 3D-Derived csGeoSet Objects33csTriStripSet contains the following field:csMFInt* stripLength() const;This field allows you to specify and find out

viContents at a Glance15. Adding Sounds To Virtual Worlds 167Overview 168How to Play a Sound File 173Specifying Audio Files 174Playing Sou

34Chapter 2: Creating Geometriesvoid setCreaseAngle(csFloat creaseAngle);void setColorPerVertex(csBool colorPerVertex);void setNo

35Chapter 33. Specifying the Appearance of GeometriesThe geometry and appearance of a shape are independent of one another. Theappearance of a shape i

36Chapter 3: Specifying the Appearance of GeometriesThere is an inheritance mask in each csAppearance that specifies which appearancevalues are inherit

csContext Overview37..csAppearance *app = new csAppearance;app->setMaterial(mtl);shape->setAppearance(app);Figure 3-1 Inheritance MaskAll 0 bits

38Chapter 3: Specifying the Appearance of GeometriesWarning: It is critical that such a callback not alter the OpenGL state.You can avoid altering the

Changing the Context39Overriding Appearances and Geometry Properties with csContextIn general, csAppearance settings override csContext default values

40Chapter 3: Specifying the Appearance of GeometriesIn this example, the second context replaces the first.• display is a pointer to the X window displ

Using csAppearance41The csAppearance class includes a series of set...() methods to define the appearancecharacteristics of a geometry. A series of cor

42Chapter 3: Specifying the Appearance of GeometriesApplying Textures to GeometriesOne way to affect the appearance of a geometry is to apply a textur

Applying Textures to Geometries43Figure 3-3 Texture CoordinatesTexture coordinates are assigned to each vertex of a geometry either by you or by Cosmo

viiContentsList of Figures xixList of Tables xxiAbout This Guide xxiiiWhat This Guide Contains xxiiiRelated Reading xxvWho Should Read

44Chapter 3: Specifying the Appearance of GeometriesSpecifying a Texture ImageTo apply a texture to a geometry, supply a csTexture object in the argum

Applying Textures to Geometries45When you choose the NON_PERSP_TEX mode, Cosmo 3D applies the texture to ageometry without proper perspective. For exa

46Chapter 3: Specifying the Appearance of GeometriesTexture Environment SettingsTexture environment variables specify how texture colors are blended w

Applying Textures to Geometries47Color ComponentsA texture image can have up to four components per texture element:• A one-component image consists o

48Chapter 3: Specifying the Appearance of GeometriesSpecifying Texture CoordinatesThere are two ways to specify how a texture is applied to a geometry

Applying Textures to Geometries49The setTexGen() method specifies• Whether or not the texture plane is repeated across the geometry.• Whether the textu

50Chapter 3: Specifying the Appearance of GeometriesSetting the csTexGen ModeIf you think of the texture plane as being projected onto the surface of

Material Settings51Material SettingsThe material field in csAppearance defines the surface qualities of a geometry, such ashow well it reflects light, wh

52Chapter 3: Specifying the Appearance of GeometriesShininess describes how much of the surroundings are reflected by an object, for example,a mirror w

Shade Model Settings53Shade Model SettingsYou set the shading model using the setShadeModel() method with one of the followingcsContext::ShadeModelEnu

viiiContentsClasses That Determine How Things Are Drawn 12csContext 12The csEnvironment Classes 12Classes defining Geometric Objects 13Ste

54Chapter 3: Specifying the Appearance of GeometriesTo use the setAlphaFunc() method, you first set the reference value against which youmeasure the al

55Chapter 44. Scene Graph NodesA node is an object that can be part of or entirely comprise a scene graph. Typically, a nodeis a collection of one or

56Chapter 4: Scene Graph NodesWhat Is a NodeA node is a collection of one or more fields and methods. Each field is a C++ class withdata members and met

Leaf Nodes57Leaf NodesLeaf nodes are responsible for defining the visual and aural elements portrayed in ascene. Leaf nodes cannot have child nodes.The

58Chapter 4: Scene Graph NodesGroup NodesGroup nodes associate other nodes into a hierarchy known as a scene graph. Only groupnodes can have children.

Group Nodes59• csLOD—(level-of-detail) is a switch that selects one of its children based on thedistance between the camera and the shape encapsulated

60Chapter 4: Scene Graph NodesUsing csBillboardcsBillboard is a subclass of csGroup. It is used to rotate its children to face the viewer atall times.

Setting the Values in Scene Graph Nodes61Setting the Values in Scene Graph NodesCosmo 3D allows you to set the values for nodes in two ways: either us

62Chapter 4: Scene Graph NodesUsing Tokens to Set and Get Single-Value FieldsTo use tokens to set or get single-value fields, you1. Get a handle to the

Setting the Values in Scene Graph Nodes63Using Tokens to Set and Get Multiple-Value FieldsTo use tokens to set or get multiple-value fields, you1. Get

Contentsix3. Specifying the Appearance of Geometries 35csContext Overview 35State Machine 36Inheritance Mask 36Accessing States 37What

65Chapter 55. Building a Scene GraphA scene graph can be a single node or a hierarchy of nodes, as shown in Figure 5-1.Figure 5-1 Scene GraphThe hiera

66Chapter 5: Building a Scene GraphThis chapter includes the following sections:•“Creating Scene Graphs” on page 66.•“Diagramming Scene Graphs” on pag

Creating Scene Graphs67Figure 5-2 Multiple Root NodesApplying Actions to Multiple Root NodesIf a scene graph has multiple root nodes, an action applie

68Chapter 5: Building a Scene GraphCreating A Sample Scene GraphExample 5-1 is a simple scene graph.Example 5-1 A Simple Scene Graph// create the root

Diagramming Scene Graphs69Diagramming Scene GraphsDiagramming a scene graph is helpful in visualizing the structure of a Cosmo 3Dapplication. Figure 5

70Chapter 5: Building a Scene GraphFor more information about the order in which nodes are acted upon, see “The Order InWhich Actions Are Passed Betwe

Diagramming Scene Graphs71In the subgraph shown in Figure 5-5, you can see that the foot, leg, and torso nodes areparts which, when rendered together,

72Chapter 5: Building a Scene GraphFigure 5-6 Showing the Same Geometry in Two LocationsIn this example, the scene graph makes it easy to see that a c

Altering Scene Graphs73Altering Scene GraphsAfter using csGroup::addChild() to create a scene graph, you can use the followingmethods to edit it:void