From: autodesk!prs@uunet.UU.NET (Pete Samson) Newsgroups: sci.virtual-worlds Subject: SOFTWARE: Description of CDK Keywords: CDK, Cyberspace Developer Kit, virtual reality toolkit Date: 12 Jul 93 18:19:06 GMT Organization: Autodesk, Inc. Lines: 1352 CyTechnicalNote #1 CYBERSPACE DEVELOPER KIT CONCEPTS & COMPONENTS ASCII version: June 30, 1993 for CDK Release 1.0 Copyright 1993 by Autodesk, Inc. ABOUT THIS TECHNICAL NOTE: This is the first of a projected series of technical notes or white papers about the Autodesk Cyberspace Developer Kit (CDK) and related issues. The series is meant to convey information to cyberspace developers and other interested people quickly and in a concise format. Later notes will supplement the CDK DEVELOPER'S MANUAL. This first note, number 1, contains material from the DEVELOPER'S MANUAL. The intended audience is developers who aren't yet familiar with the contents or structure of the CDK. This note has been converted to ASCII and lightly edited for on-line posting. A section on pricing and availability is included. 1. BASIC CDK CONCEPTS ===================== The Autodesk Cyberspace Developer Kit (CDK) is an object-oriented programming library for creating interactive, three-dimensional visualization and simulation software -- also known as "virtual reality" applications. The CDK provides a unified, comprehensive set of classes that professional developers can combine and extend to make finished applications for a variety of hardware configurations. It also supports interactive hands-on experimentation and prototyping. The CDK contains more than 140 predefined classes, which in turn comprise more than 1200 publicly accessible member functions. Applications that benefit the most from virtual reality techniques tend to have some or all of the following characteristics: o They model behavior as well as appearance of objects. o They emphasize real-time visualization of three-dimensional geometry. o They allow a user to experience ergonomic issues in a design. o They explore innovative interaction techniques. To create such applications, you often need the following: o Convenient ways to import and export geometrical models as well as techniques for dynamically creating new geometry o Reliable access to a variety of relatively unusual input devices for manipulating objects in three dimensions The CDK provides a consistent framework that solves these and other problems in building virtual reality applications. Specifically, the class library presents abstractions for the following activities: o Definition and display of three-dimensional geometry, including complex objects o Interaction with the geometry o Simulation of physical properties and other object behavior o Proper sequencing of events within a simulation frame o Access to a variety of sensing devices o Support for audio through a MIDI interface The point of CDK programs is to create a kind of interactive simulation, sometimes called a "cyberspace," or simply a "space." Although the classes within the CDK don't require that an application conform to a rigid structure, they are designed with a particular model in mind. A user "enters" a space using a "deck." A deck is a computer that has one or more input devices, such as a glove or a mouse, and an output device, such as a head-mounted display or a VGA screen. Input devices are called "sensors." A sensor can be a simple device such as a mouse or a complex device that gives six-dimensional input. (A six- dimensional sensor gives three-dimensional position plus the rotational dimensions of roll, pitch, and yaw.) Output devices are called "displays" or "effectors." A display can be as simple as a VGA board or it can be a sophisticated three-dimensional display device. The term effector includes displays as well as devices such as MIDI synthesizers and physical feedback devices. One advantage of the CDK is that you do not necessarily need to know what sensors or effectors will be available to the user of the program. You usually write the program so that it looks at environment variables to determine what devices are in the deck. Spaces can contain "simulated objects" and "dynamics." Simulated objects may have a certain appearance or behavior or both appearance and behavior. Dynamics are objects that control interactions between simulated objects, such as spring behavior or gravity. A special kind of simulated object is a "viewer." Viewers represent the user's point of view in the space. 1.1 Terminology =============== Since cyberspace is a new field, no consistently defined terms exist to describe its experience, content, or structure. The following definitions are the ones used in CDK documentation: cyberspace The simulated environment experienced by a user who is running a developer's cyberspace software application. space Same as cyberspace. simulated object An entity in a cyberspace that may have an appearance and may have a behavior. Sometimes simply called an "object." deck The total hardware system, including sensors and effectors, required to run a cyberspace application. dynamics Objects that control interactions between simulated objects. effector A device that transmits information to the user. Also called "output peripheral" or "display" (for example, a monitor, headmount display, or MIDI device). Rather than being directly concerned with the device that the user perceives, CDK programs actually deal with hardware such as video cards. sensor A device that collects information from the user. Also called "input peripheral" (for example, a mouse, trackball, or glove). method A C++ class member function. utility classes CDK classes providing generally useful abstractions that can be included in applications other than cyberspace. 1.1.1 Time Terminology and Concepts Because the CDK deals with simulation, time and the relationships between real time and simulation time are important. The following time terms and concepts are used in dealing with time in the CDK: real time Clock time. simulated time Time within the context of a simulation. This may not be the same as real time. You can use a CyClockSync object to coordinate simulated time and real time. time scale The ratio between real time and simulated time. deck frame Usually called a frame. One traversal of the Canonical Scheduling Tree (CST). All activity within a frame takes place at the same simulated time. simulation frame One invocation of the Simulate method of a space. Sometimes this is done multiple times within a deck frame. You can tell the CDK how many simulation frames you want per deck frame by calling CySpace::SetSimsPerFrame. dt Simulated time per deck frame, sometimes called a clock tick or a tick. You define this value by calling CySpace::SetDt. (You can also set this value in the dynamics and the resolver, but that is not recommended.) A CyClockSync object adjusts this value to keep a constant time scale. frame rate The number of frames per second of real time. You can use an object of type CyLoopTimer to obtain this value. frame number A number used to refer to a given deck frame. You can obtain the current frame number by calling CyDeck::GetFrameNumber. 1.2 AVAILABILITY ================ The CDK is available from authorized CDK dealers. To locate a dealer near you, call 800-964-6432 from the U.S. or Canada, or fax your request to 415-491-8303 (from Latin America) or 415-491-8398 (from Asia and the Pacific). The Suggested Retail Price of the CDK in the U.S. is $2,495.00 per copy. This includes the right to make and sell end-user application programs incorporating the CDK (or parts of it) in executable object-code form, with no further payments or royalties. For more details about currently supported software and hardware, contact your CDK dealer. You might also want to contact the manufacturer of a device you are interested in, as drivers for additional devices are under development. 1.3 REQUIREMENTS ================ You need the following technical expertise, hardware, and software to use the CDK. 1.3.1 Technical Expertise In order to use the CDK, you need to know how to program in C++ and be familiar with object-oriented programming concepts. The CDK DEVELOPER'S MANUAL is designed to get you started without a great deal of knowledge, but it does not teach the language or object-oriented programming. In addition, creating cyberspace applications requires some knowledge of computer graphics. If you need help in this area, you may want to read a graphics textbook such as J.D. Foley and A. Van Dam, COMPUTER GRAPHICS PRINCIPLES AND PRACTICE (Reading, Massachusetts: Addison-Wesley, 1990). Familiarity with AutoCAD or 3D Studio, and with the fundamentals of linear algebra is helpful -- although not strictly necessary. Due to their interactive nature, cyberspace programs generally use specialized input and output equipment. Familiarity with this equipment will help you produce useful programs. 1.3.2 Hardware You need at least the following hardware to develop CDK applications: o A PC-compatible 386 or 486 computer o 8 megabytes of main memory (4 megabytes is possible, though you may not be able to run a debugger on CDK programs) o An 80 megabyte disk drive o A 1.44 megabyte, 3 1/2 -inch floppy disk drive If you need real-time interaction with geometry, you probably need some type of hardware graphics accelerator. The CDK supports a variety of input and output devices, including head mount displays, sound displays, and six-dimensional sensors. Many of these are listed in the descriptions of the classes for "Displays," "Audio," and "Sensors," below. The simplest supported set of I/O devices is this typical PC configuration: o A VGA video monitor that is VESA 1.2 compliant o A standard keyboard and keypad o A Microsoft mouse or equivalent 1.3.3 Software You need the following software to develop CDK applications: o Zortech 386 C++ or Metaware High C/C++. o The Phar Lap 386|DOS Extender Software Development Kit. This includes the 386|DOS Extender, the 386|LINK program, and RUN386. o The Phar Lap program BIND|386, which you need only if you want to produce real-mode (.exe) executables. NOTE: BIND|386 is sold separately from the DOS Extender SDK. AutoCAD and 3D Studio aren't required, but can be very useful for creating geometrical models to display in cyberspace. 1.3.4 Network Hardware and Software You don't need network hardware and software unless you wish to run distributed simulations. The CDK's distributed simulation software assumes you have an Ethernet-compatible network card and an appropriate TCP/IP protocol stack kernel for the card. 2. CDK CLASS ARCHITECTURE ========================= The CDK is a set of C++ classes and related routines. Writing a cyberspace applicationinvolves creating objects from these classes to build the virtual environment -- the deck, the space, geometry within the space with associated behavior (physical or otherwise), and I/O objects that enable the user to observe the space and affect it. About 40 percent of the CDK classes inherit from the class CyBase, which defines event-handling methods. The most important subclass of CyBase is CySimBase, and most of the classes that inherit from CyBase are descendants of CySimBase. Class CySimBase defines the Simulate method. When you tell your deck to run, it calls the Simulate method of the space once each simulation cycle. The space, in turn, calls the Simulate methods of all objects in the space. Classes that don't inherit from CyBase and CySimBase are primarily those that display information to the user, provide mathematical entities, and perform utility functions. These include the important display and geometry classes. The classes in the CDK can be grouped into twelve primary categories: o Geometry o Geometry import and export o Displays o Audio o Sensors o Scheduling o Events o Physics o Viewers o Distributed simulation o Linear Algebra o Utility The following sections discuss each group in turn. NOTE: After each section head is a list of the classes in that category, arranged to show inheritance. The base classes (classes that do not have parents) are on the left, and the inheritance hierarchy proceeds toward the right. 2.1 Geometry ============ CyComponent | +--CyAssembly | +--CyLeaf | +--CyRBESet | | | +--CyRigidBody | | | | | +-------------CySection | | | +--CyNonRigidBody | +--CySolid | +--CySolBox | +--CySolPyr | +--CySolCon | +--CySolNos | +--CySolDom | +--CySolBal | +--CySolSph | +--CySolTor | +--CySolRed | +--CySolExt | +--CySolRev | +--CySolBool CyRBE | +--CyPolygon3 | +--CyPolymesh | +--CyRectmesh CyCompInst | +--CySolInst CyPolicy | +--CyAnimPolicy | +--CyDistPolicy CyPicker CyPickRec The CDK has four kinds of geometrical objects: rigid bodies, non-rigid bodies, solid bodies, and assemblies. o You can model many objects in terms of the geometric primitives polygons (CyPolygon3), polymeshes (CyPolymesh), and rectangular meshes (CyRectmesh), which are rigid body elements and thus subclasses of CyRBE. You group these primitives into rigid bodies sets (CyRBESet), of which there are two types of rigid bodies (CyRigidBody) and non-rigid bodies (CyNonRigidBody). o You can create other objects as solid bodies (CySolid). Solid bodies include objects such as spheres, balls, boxes, and cones, and also include more complex objects created as Boolean combinations of solid bodies. A CySection is a rigid body made from a section of a solid. o You can combine geometrical objects into assemblies (CyAssembly). An assembly might, for example, represent an articulated machine where parts can move with some independence. An assembly is also used as the top-level container for all the geometry in a space. Rigid bodies, non-rigid bodies, solid bodies, and assemblies are types of "components" (CyComponent). A component is a template for a geometrical object. When you make a particular instance of the object, you create a "component instance" (CyCompInst or CySolInst, which is specialized for solids). A component instance has a reference to the component (or several components) along with surface properties (such as color) and a rigid motion. A policy (CyPolicy) object determines which specific representation of an object is appropriate to display at a particular time. CyPolicy is a base class that you never instantiate. The CDK includes two subclasses of CyPolicy that implement two kinds of policies: CyDistPolicy decides which representation to use based on the distance between the viewer and the object; CyAnimPolicy implements animation by cycling through a sequence of representations of an animated object. A picker (CyPicker) is an object that is used to select or pick component instances. A picker object returns a CyPickRec object. CyLeaf is an abstract class that exists for organizational purposes in the class hierarchy. 2.2 Geometry Import and Export ============================== CyGfile | +--CyGfileADS | +--CyGfileDXF | +--CyGfile3DS You can create a geometric structure from within a program (most easily by using the solid modeling package), but you may find it easier to import geometry that you created somewhere else. In addition, once you create or modify geometry in a CDK program, you may want to export it for use in programs such as AutoCAD. This capability is provided CyGfileDXF and CyGfileADS. The utility class CyGfile is a base class for classes that translate geometry from external formats into CDK-style components and translate components into external geometry. CyGfile has three predefined subclasses: o CyGfileDXF translates graphical elements in DXF (Drawing Interchange Format). This class can also translate graphical elements from a CDK program into DXF. o CyGfileADS translates graphics over an AutoCAD Development System link from a running AutoCAD session. o CyGfile3DS translates graphical elements from a 3D Studio file. Animation information is not translated. For importing AutoCAD files, geometry can be defined in terms of 3D Face, polyface mesh, or rectangular polygon mesh entities, which can be arbitrarily nested in block references. The CDK does not support scaling and mirroring of block references, however. 2.3 Displays ============ CyDisplay3d | +--CyDViewdisp | +--CySPEAdisp | +--CyVESAdisp | +--CyADIdisp CyBase | +--CySimBase | +--CyLight CySurfaceTable CyTexture Once you define your geometry, you need to load it into a particular display device so that the user can eventually see the geometry. CyDisplay3d implements the capabilities of an ideal display device; the subclasses of CyDisplay3d specialize these capabilities for particular hardware: o CyDViewdisp is for the dView board set from Division, Ltd. o CySPEAdisp is for the VideoSeven SPEA Fire board. o CyVESAdisp is for cards that use the VESA-1.2 standard. o CyADIdisp is for the Autodesk Device Interface 4.2 Rendering Specification. The CyDisplay3d class defines an abstraction that lets your program ignore what kind of display device is used at run time. The abstraction assumes that the device (either through hardware or software) can group graphics primitives into segments. Each segment is given an identifier of type CySegId (currently an integer). Generally, when you add your geometrical models to the space, the space places geometric elements in one or more segments on the display device. (You can manually control which segment the CDK uses for a particular geometric element. In general, though, the space handles this for you.) The space then posts the segments to be drawn. To actually draw the image, the deck calls the display's Regen method. Regen traverses the list of posted segments, telling the corresponding CyComponent instance to redraw. Some displays can render geometry in either shaded or wire frame mode. You can control the mode by calling the SetWireframe method. Polygons can optionally undergo Gouraud shading. CyDisplay3d provides Gouraud shading if you define normals for each vertex of the polygon. The constructors for the polygon, polymesh, and rectangular mesh primitives have the array of normals as an optional argument. If you supply the array of normals, CyDisplay3d displays smoothly shaded polygons. If you don't supply the array, the polygons appear flat. Although the view presented to the user is often controlled by a separate viewer object, you can set the view directly through the display. You can specify a view in one of two ways: o You can supply "from" and "to" vertices and an "up" vector. o You can supply a view matrix that gives a coordinate system for the view. The origin of the coordinate system is the viewer's eye position, the negative Z axis points along the view direction, and the Y axis points "up" with regard to the resulting image. You can use either an orthographic or a perspective projection. Define an orthographic projection by describing a rectangular parallelepiped in view space -- that is, with minimum and maximum coordinates in X, Y, and Z. Define a perspective projection by specifying a view angle and near and far clipping plane distances. A display has a surface table (CySurfaceTable). Each element of the table describes surface properties that can be used for your geometry. The elements of the table are of type CySurface, which is a structure, not a class. The table can contain items of type CyTexture, which define surface textures. CyLight is an abstraction for generating and manipulating light sources within a space. 2.4 Audio ========= CyBase | +--CyAudioDisplay3d | | | +--CyConvolvoTron | +--CySimBase | +--CySequencer You can use the audio classes to produce sound effects in a space through a MIDI interface. In addition, the Convolvotron is a device that can position a sound source in three dimensions. 2.5 Sensors =========== CyBase | +--CySensor | +--CyScalar | | | +--CyComputrainer | +--CySensor2d | | | +--CyADISensor2d | | | +--CyMouse | +--CySensor6d | | | +--CyBoom6d | | | +--CyGeoBall | | | +--CyKeypad6d | | | +--CyADISensor6d | | | +--CyFastrak | | | +--CyLTracker | | | +--CyPolhemus | | | +--CySensor6d_2d | | | +--CyVplGlove | +--CyVTGlove You can use various devices to get user input, and use the input to direct actions within the space. There are four basic kinds of sensors: o Scalar (CyScalar) sensors detect one-dimensional information. A scalar device is used typically to get a measurement between some minimum and maximum value. o Two-dimensional (CySensor2d) sensors detect positions on a plane. Examples of two-dimensional sensors are mouse devices, digitizers, joysticks, and trackballs. They return ordered pairs of real numbers. o Six-dimensional, or six-degree-of-freedom (CySensor6d) sensors detect six dimensions of information: X, Y, and Z positions plus roll, pitch, and yaw. o Gloves return "flex map" data describing the flex angle of certain hand joints. Some gloves also return 6D position data; others do not. The rest of the sensor classes are specialized for particular sensors: o CyComputrainer is a scalar sensor that is tuned specifically for the Racer-Mate Computrainer computer-aided trainer. You can define and use it as a scalar object where it simply returns speed values or as a Computrainer with full access to the device, enabling you to obtain, for example, grade, head wind, inertia settings, calorie consumption, maximum speed, and average speed. o CyADISensor2d gets two-dimensional information from the Autodesk Device Interface protocol. o CyMouse gets two-dimensional information from a Microsoft mouse. o CyBoom6d gets six-dimensional information from the Fake Space Labs BOOM display. o CyKeypad6d uses keypad information to simulate six-dimensional sensor information. o CyADISensor6d gets six-dimensional information from the Autodesk Device Interface protocol. o CyLTracker gets six-dimensional information from the Logitech 2D/6D mouse device. o CyPolhemus gets six-dimensional information from the Polhemus 3SPACE ISOTRAK system. o CyFastrak gets six-dimensional information from the Polhemus 3SPACE FASTRAK six-dimensional sensor. o CySensor6d_2d maps a two-dimensional sensor, such as a mouse, into any two dimensions out of the six dimensions a six-dimensional sensor uses. o CyGeoBall gets six-dimensional information from the CIS Graphics Di6 GEOMETRY BALL. o CyVplGlove represents the VPL Research DataGlove glove device. It gets six-dimensional information as well as glove position information. o CyVTGlove returns glove position information for the Virtual Technologies CyberGlove glove device. The SetRange method governs the range of coordinates that devices generate. The exact interpretation of the range depends on the device, but, in general, the device class maps the range to the range of motion natural to the device. In the case of a digitizer, for example, the range rectangle is mapped directly to the measurable surface of the pad. For a joystick, the range corresponds to the physical limits of the stick's movement. A mouse or trackball, on the other hand, has no inherent limits. In this case, the range, by default, corresponds to the distance covered by a typical use of the device (for example, a movement of about six inches for a mouse). Specific methods are available in these classes for finer control of the mapping between physical movement and returned values. Each interaction with a two-dimensional device can be thought of as moving a particle on a plane. The coordinates of the particle at a given time are returned by the GetXY method. The relative coordinates from a programmer-defined reference point are returned through the GetDeltaXY method. The precise manner in which this particle moves around the plane varies from device to device. There are, however, two main categories of two- dimensional sensors: those with a natural resting position, such as a spring-based joystick, and those without a natural position. Devices that have a natural resting position can operate in one of two modes: "accumulate on" or "accumulate off." With "accumulate off," the particle moves in direct analog to the position of the device; for example, if the joystick is at its center position, the particle will be at the center of the range rectangle. If the user pulls the joystick fully to the left, the particle moves to the left edge of the range rectangle. With "accumulate on," the particle moves along the vector defined by the position of the device. Six-dimensional devices operate like the two-dimensional model outlined above. However, instead of a particle moving along a plane, a six- dimensional sensor has a three-dimensional coordinate system that it moves and orients in space. The GetXY method used for two-dimensional sensors generalizes to GetMat, which returns the matrix representing the position and orientation of the particle. The GetDeltaXY method used for two-dimensional sensors becomes GetDeltaMat, which returns the transformation needed to move from a user-defined reference coordinate system to the current position of the particle. CySensor6d has methods that allows you to obtain raw data from six- dimensional sensors. The GetData and GetDeltaData methods return a record that contains the X, Y, and Z translation values as well as the azimuth, elevation, and roll Euler angles that specify the orientation. Six-dimensional devices can also be grouped into two categories based on the presence of a natural resting position. Devices such as Geoball sensors will naturally return an identity matrix in the absence of user interaction. Devices such as Polhemus trackers do not have any such preferred position. Devices that have a resting position have an "accumulate on" mode to allow them to easily move and orient in a six- dimensional coordinate system. 2.6 Scheduling ============== CyBase | +--CyDeck | +--CySimBase | +--CySpace | | | +--CyNewtonianSpace | +--CyDynamics | +--CyNewtonianDynamics The scheduling classes implement the most important part of the Canonical Scheduling Tree (CST). The CST is a structure for writing a program in which the CDK handles scheduling for you. In a CST program, the user uses the deck (CyDeck) to observe and interact with the space (CySpace). The deck fields incoming events and does the following each time through the simulation cycle: o Polls all sensors o Invokes the Simulate method of the space, which, in turn, invokes the Simulate methods of the objects in the space o Tells the displays to regenerate the graphics, audio, and other feedback o Dispatches events to objects that should receive them The CST is a simple, hierarchical arrangement of C++ class instances in a tree-data structure. Each node of the tree is a C++ object. The following three classes shape the CST. o CyDeck. The center of each program is an object of type CyDeck (called a deck). A deck represents the hardware platform: the computer with effectors (such as display devices) and sensors. The deck has the main control loop. There is always one and only one deck. o CySpace. The space that the user interacts with is represented by an object of type CySpace (called a space). The space contains the objects that inhabit the virtual world. It also has objects that map between external phenomena (such as information received from sensors) and the objects in the space. There is only one current space, but a program can have several spaces and switch between them. o CyDynamics. Physical forces such as gravity and relationships between objects in the space are represented by CyDynamics objects. Here is a conceptual picture of the CST: Deck | +---Sensor(s) | +---Space | | | +---Object(s) | | | +---Dynamics | | | | | +---Physic(s) | | | | | +---Resolver | | | | | +---Collision Server | | | +---Viewer | +---Display 2.7 Events ========== CyBase CyNotifier CyEvent CyBase is the base class for all classes that can send and receive events. This facility is provided primarily so that you can send and receive events when you create subclasses of descendants of CyBase such as CySimObj or CyPhysical. CyBase defines the following event-related methods: o TellMeAbout is called by an object that wants to receive a particular type of event. It is usually called from an class constructor or Establish method. When you call TellMeAbout, you pass in an event template that matches the kind of events you want to receive. o Ignore is called by an object that wants to stop receiving events. o Squawk is called by an object to post an event. o An object's ProcessEvent method is called by the notifier (described below) when the notifier has an event for the object. The notifier, an object of type CyNotifier, distributes events to objects that declared they wanted events of that kind. Only one notifier object exists at a time -- the CDK creates it automatically at start-up. You can access the notifier through the global variable TheNotifier. Events are objects of type CyEvent. Every event has a class, represented by an integer from zero to 255, which is a general grouping such as MOUSEBUTTON or KEYBOARD, and a type, represented by an integer between zero and 63, which is a more specific grouping such as LEFT_DOWN or KEYUP. Events can also have data; keyboard events, for example, have data that indicate which keys are involved in the event. Integers below 128 for classes are reserved for CDK use. Event types are defined per class, so you can use any valid integer for a new type without conflict with the CDK. 2.8 Physics =========== CyBase | +--CySimBase | +--CySimObj | | | +--CyPhysical | +--CyPhysics | | | +--CyGravity | | | +--CyPGravity | | | +--CySpring | | | +--CyFriction | | | +--CyResolve | | | +--CyCollisionServer | | | +--CyCollisionSphere | | | +--CyCollisionBox | +--CyMetric CyCollisionEvent | +--CyCollisionSphereSphere | +--CyCollisionBoxSphere | +--CyCollisionBoxBox CyCBox CyMassProperty | +--CyAMEMassProp | +--CySolMassProp The physics classes provide a means for simulating how objects are affected by external stimuli. A physical object (CyPhysical) provides a bridge between a geometrical representation and physical effects. CyPhysics is the base class for particular physical effects. These effects are implemented by the classes CyGravity, CyPGravity, CySpring, and CyFriction. CyResolve resolves forces applied by the physics classes into velocities and positions for CyPhysical objects. A CyCollisionServer class handles collisions between physical objects. CyCollisionSphere handles sphere-to-sphere collisions. CyCollisionBox handles box-to-box, sphere-to-box, and sphere-to-sphere collisions. A CyCollisionServer creates objects of type CyCollisionEvent to watch for collisions between pairs of objects. CyCollisionSphereSphere handles pairs of spheres; CyCollisionBoxBox handles pairs of boxes; CyCollisionBoxSphere handles pairs made up of a box and a sphere. CyCBox specifies an object's bounding box for collision detection. CyMassProperty is a base class for specifying a solid's mass properties. There are two sub-classes: o CyAMEMassProp is for specifying the mass properties of AME objects. o CySolMassProp is for specifying the mass properties of CySolid objects. 2.9 Viewers =========== CyBase | +--CySimBase | | | +--CySimObj | | | +--CyViewer | | | +--CyDollyView | | | +--CyTargetView | | | +--CyParasiteView | | | +--CyPlatformView | | | +--CyTrackView | +--CyMouseView A viewer (CyViewer) represents the user's point of view in the space; or, if you prefer, a window into the space. Viewers generally move in response to information gathered from sensors. Each simulation cycle, the space draws the objects in the space as seen from the point of view of the viewer and shows the results on the display. A viewer is a special kind of simulated object, an object of type CySimObj, that sets the viewpoint of a given display. The different subclasses of CyViewer implement different strategies for moving the viewer. The Simulate method of each subclass implements that subclass's strategy. The view classes implement the following viewing metaphors: o CyDollyView defines a viewer analogous to a camera mounted on a dolly. You can attach a sensor to the dolly and a sensor to the camera. o CyTargetView defines a viewer in which the camera platform moves toward a target destination either at a constant velocity or at a velocity proportional to the distance remaining to the target (converge mode). While moving, the orientation of the platform is fixed: it is subject only to translation. You can attach a CySensor6d sensor to the camera to move it relative to the platform. o CyPlatformView is a simple example of a viewer. This class moves the view forward or backward along the line of sight in response to events. The class monitors a six-dimensional sensor to determine the line of sight. o CyParasiteView defines a movable viewer that is attached to a CySimObj object. You can attach a CySensor6d sensor to the camera to move it relative to the object. o CyTrackView defines a viewer that is continually oriented to look toward another object in the space. You can attach a CySensor6d sensor to the camera to provide additional movement. CyMouseView is a utility class for use with platform viewers. It receives mouse button events and converts them to platform viewer events. 2.10 Distributed Simulation =========================== CyNetPort CyConsCell CyMsg CyCommunicator CyBase | +--CySimBase These classes provide the distributed (that is, networked) simulation mechanism in the CDK. CyNetPort provides low-level access to the network software. You generally need to use this to create a network facility that suits your application. CyCommunicator is an example of a class that uses CyNetPort to create a distributed application mechanism. A CyCommunicator object communicates between simulation programs running on different computers on the same network. The CyCommunicator object sends CyMsg objects, which contain CyConsCell objects as well as information of other types. CyConsCell implements a LISP-like (cons) cell. CySimBase defines methods that are called by the communicator. Those methods return or interpret CyMsg objects. 2.11 Linear Algebra =================== CyVertex3 CyVector3 CyMatrix CyGMatrix CyRay CyPlane CyQuaternion CyMatInterp The CDK includes a set of classes for basic computations in three dimensions: o CyVertex3 defines a point in three dimensions. o CyVector3 defines a direction and a magnitude. o CyMatrix defines a coordinate system optimized for rigid motion specifications. o CyGMatrix defines a generalized four-by-four matrix. o CyRay defines a semi-infinite line in three-dimensional space. o CyPlane defines a plane by a point and a normal vector. o CyQuaternion is an alternative representation for orientation. Quaternion structures are useful in smoothly interpolating between two orientations. o CyMatInterp interpolates between two rigid motion specifications. 2.12 Utility ============ The CDK utility classes address the following general areas. 2.12.1 DSCVR CyCDFMgr CyVal | +--CyValInt | +--CyValReal | +--CyValName | +--CyValComposite | | | +--CyValTuple | | | +--CyValTupleSpace | | | +--CyCDFDatabase | | | +--CyPointerDatabase | | | +--CyCDFMakerDatabase | +--CyValStruct | +--CyValBlock CyDSCVRReader DSCVR (Distributed Shared Cyberspace Virtual Representation, a Linda variant) serves as a central database facility for the CDK. DSCVR stores information as tuples within the context of a particular "tuplespace." You retrieve objects by matching patterns on key fields within the tuple. You can use DSCVR as a database mechanism, but DSCVR also serves an important role in conjunction with CDK applications. You can use a defined DSCVR structure known as the Cyberspace Description Format (CDF) to specify a display, sensors, and the objects in a particular space by declaring items in a file. Thus, you can populate parts or all of a simulation scheduling tree from an external ASCII file. A CyCDFMgr object controls reading and processing CDF files. A CyDSCVRReader object reads a DSCVR Text Form (DTF) file or string and produces a DSCVR structure. A CyPointerDatabase is a two-level database of pointers. Pointers (actually any 32-bit value) can be stored under symbolic names. For example, a pointer to a CySpace might be stored in the section SPACES with the name myspace: CyPointerDatabase pdb; CySpace *myspaceptr1 = new CySpace(); pdb.AddItem("SPACES", "myspace", myspaceptr1); CySpace *myspaceptr2 = (CySpace *) pdb.GetItem("SPACES", "myspace"); A CyCDFMakerDatabase associates class names with C maker functions that parse CDF into class creation and initialization directives. CyVal is the base class for DSCVR. 2.12.2 Lists CyDqueue | +--CyAssocList CyCons CyAssoc These define general list-management classes. A CyDqueue is a doubly linked list. It has append and concatenation constructors. A CyDqueue object holds CyCons objects. A CyAssocList object is an association list construct. It associates two 32-bit values and keys on the first value. A CyAssocList object holds CyAssoc objects. 2.12.3 Random Number Generator CyRandomizer CyRandomizer is a 32-bit pseudo-random number generator that uses an enhanced implementation of S. Wolfram's "Rule 30" one-dimensional cellular automaton. 2.12.4 Serial CySerialPort CySerialPort provides access to a serial port under Phar Lap extended DOS. It provides internal buffers for record assembly and complete control of all serial communication parameters. 2.12.5 Matcher CyMatcher CyMatcher is a base class for determining the nearest match to a set of templates used for gesture recognition. 2.12.6 LoopTimer CyBase | +--CySimBase | +--CyLoopTimer CyLoopTimer reports at specified intervals on the time a particular simulation cycle uses. This class is intended primarily as a development tool. 2.12.7 ClockSync CyBase | +--CySimBase | +--CyClockSync CyClockSync is designed to monitor the time increment (dt) and adjust it as necessary to simulate intervals of real time. It allows you to simulate different intervals of real time, allowing, for example, one second of real time to be equal to one second or one minute of simulated time. (If you don't use CyClockSync, the relationship between real time and simulated time is arbitrary.) To use CyClockSync, construct a CyClockSync object, passing it the amount of simulated time that should pass for each unit of real time. You should then add the CyClockSync object to the space as a CySimBase in the SP_LAST simulation bin. For example, if space is a CySpace object and clocksync is a CyClockSync object, you would use the following code to add the clocksync object to the space: space->AddSimBase( clocksync, SP_LAST ); CyClockSync monitors the real time that has passed since the program last called CyClockSync::Simulate and adjusts the simulation loop time increment (dt) of the resolver to maintain the time scale parameter that you set. 2.12.8 Interpolator CyInterpolator CyInterpolator interpolates between two real numbers over a specified number of frames or a specified amount of time. 2.12.8 Cursor CyCursor CyCursor displays a fixed target along the line of sight at each simulation frame. ________________________________________________________________________ The following are registered trademarks of Autodesk, Inc.: ADI, Advanced Modeling Extension, AME, Autodesk, the Autodesk logo, AutoCAD, and 3D Studio. The following are trademarks of Autodesk, Inc.: AutoCAD Development System, Autodesk Device Interface, DXF, and HyperChem. All other brand and product names are trademarks or registered trademarks of their respective holders.