Base class: none
Description: This class implements a three-dimensional object, and along with class M3DScene, forms the core of the Magdef 3D framework. Each M3DObject is composed of one or more TriMesh objects; this set is treated as a unit with a single position, orientation, bounding box, etc. Methods are provided for building an M3DObject in several ways, moving it around, and inspecting its position and orientation.
Parameters: None
Description: This is the standard M3DObject constructor. It simply initializes internal data structures. The resulting object is empty, and must have TriMeshes added to it via AddMesh(), AddFrom3DMF(), or AddQD3DObject() before there will be anything to see in the scene.
Parameters: None
Description: M3DObject destructor. All internal data is freed, and any TriMeshes that have been added to this object are destroyed.
Parameters:
| M3DObject | *orig=0 | original object (users should omit this parameter) |
Return value: M3DObject *replica a copy of this M3DObject
Throws: OSStatus memFullErr memory allocation failure
Description: This method is used to clone an M3DObject, and all the data it contains.
Notes:
Note that M3DObject has no assignment operator and no copy-constructor. This Clone method is used instead, to remind you that this is a very expensive operation, and to prevent accidental copies.
The parameter is used by derived classes of M3DObject, which first create a new object of the derived type, then call the inherited method, passing this new object. Most users will generally omit the parameter, resulting in the creation of a new object.
Parameters:
| TriMesh | *meshToAdd | TriMesh object to add to this M3DObject |
Description: This method is used to add an existing TriMesh to the M3DObject, and is the primary way by which objects are built manually. The M3DObject takes ownership of the TriMesh; you must not delete it or add it to another M3DObject.
Notes:
There is no way to remove a TriMesh from an M3DObject once added.
See also AddFrom3DMF(), AddQD3DObject().
Parameters:
| const FSSpec | &filespec | FSSpec of a 3DMF file |
Return value: short qtyAdded number of TriMeshes added
Throws:
| OSStatus | memFullErr | memory allocation failure |
| OSStatus | -1 | QD3D error |
| OSStatus | (misc) | miscellaneous file errors |
Description: This method opens the 3DMF file with the given file specification, and searches it for any trimesh structures. These are added to the object, along with supported attributes such as shading information. The file is then closed. The return value is the number of TriMeshes which were added.
Notes:
In the future, other types of QD3D primitives may be supported by this method; but for now, only TriMeshes are read, and all others are ignored.
To make a FSSpec from a file name, use code like this:
FSSpec spec; OSErr err = FSMakeFSSpec(0,0,"\pYourFileName.3DMF",&spec);
Parameters:
| const TQ3Object | qd3dObj | QuickDraw 3D object to add |
Return value: short qtyAdded number of TriMeshes added
Throws: OSStatus memFullErr memory allocation failure
Description: This method examines the given QD3D object (which may be a complex object, containing several sub-objects), and copies any trimeshes it finds. The return value is the number of TriMeshes which were added.
Notes:
In the future, other types of QD3D primitives may be supported by this method; but for now, only TriMeshes are read, and all others are ignored.
Parameters:
| float | newRadius | new collision radius |
Description: Use this method to set the collision radius of the object. This radius defines a sphere around the object's position (see GetPosition()); collisions will only be considered when the spheres of the two objects intersect.
Notes:
To make an object which can never collide with anything, set its radius to zero.
The collision radius is initialized to zero; it is not automatically computed when trimeshes are added, for example. But see ResetRadius() for a way to easily compute an appropriate radius.
This radius is only used for collisions, not for object culling etc.; so you may safely set a radius which is bigger or smaller than the actual object.
See also: ResetRadius(), GetRadius().
Parameters: None
Description: This method sets the collision radius to the distance between the object's position (see GetPosition()) and its furthest vertex.
Notes:
You'll usually want to call this method after building your object with AddMesh(), AddFrom3DMF(), or AddQD3DObject(). It is not called automatically.
To make an object which a central, collidable core, and some extremeties which should not be considered in collisions, consider adding the core to the M3DObject first, then calling ResetRadius, and finally adding the extremeties.
See also: SetRadius(), GetRadius().
Parameters: None
Description: This method is called on every object in the scene, just before they are submitted for rendering with Submit()
. In M3DObject, PrepareToRender calls UpdateBounds() if necessary, and if the camera or the object has changed, it also recomputes whether the object is in the viewing frustum and sets an internal flag.Notes:
You'll probably never need to call this; it is called by the Scene class.
Parameters: None
Description: This method is called on every object in the scene, within the rendering loop, to give the object a change to submit its trimeshes to the renderer. In M3DObject, the trimeshes are submitted if the object was considered within the viewing frustum in PrepareToRender().
Notes:
You'll probably never need to call this; it is called by the Scene class.
Parameters: None
Return value: const Vec3D& pos object position
Description: This method returns the object position in 3D space. An object's position is the origin (i.e., Vec3D(0,0,0)) when the object is created, and is updated appropriately whenever the object is moved.
Notes:
This is merely a reference point, and in general has no relation to the object's centroid, center of mass, etc.
The position is used in collision calculations (see also GetRadius(), SetRadius(), and ResetRadius()). So colliding objects should generally be built centered on the origin.
Parameters: None
Return value: const Vec3D& orientation object orientation around x, y, and z axes
Description: This method returns the current orientation of the object, in terms of rotation about the x, y, and z axes. This is 0,0,0 when the object is constructed, and is updated whenever the object is rotated.
Notes:
See also: Orient()
Parameters: None
Return value: float radius object collision radius
Description: This method returns the radius of the collision sphere -- an imaginary sphere centered on the object's position, and within which collisions with other objects may happen.
Notes:
See also: SetRadius(), ResetRadius(), GetPosition().
Parameters:
| float | dx | displacement along the X axis |
| float | dy | displacement along the Y axis |
| float | dz | displacement along the Z axis |
Description: This method moves the object relative to its current position, given displacements in X, Y, and Z.
Parameters:
| const Vec3D& | delta | displacement in X, Y, and Z |
Description: This method moves the object relative to its current position, given a vector of displacements in X, Y, and Z.
Parameters:
| float | newX | new X position |
| float | newY | new Y position |
| float | newZ | new Z position |
Description: This method moves the object to a new absolute position in 3D space.
Parameters:
| const Vec3D& | newPosition | position to move to |
Description: This method moves the object to a new absolute position in 3D space.
Parameters:
| float | distance | amount to move forward |
Description: The MoveForward method moves the object relative to its current position and orientation. "Forward" means in the positive Z direction for an object that hasn't been rotated; for rotated objects, the direction is adjusted accordingly.
Notes:
If you model an object such that it's looking down the Z axis, then this method is a very convenient way to make it move in the direction it's facing.
Parameters:
| float | dXAng | amount to rotate around the X axis |
| float | dYAng | amount to rotate around the Y axis |
| float | dZAng | amount to rotate around the Z axis |
Description: This method rotates the object around its X, Y, and Z axes, relative to its current orientation.
Notes:
See also GetOrientation().
Parameters:
| const Vec3D& | dAng | amount to rotate around X, Y, and Z axes |
Description: This method rotates the object around its X, Y, and Z axes, relative to its current orientation.
Notes:
See also GetOrientation().
Parameters:
| float | xAng | new rotation around the X axis |
| float | yAng | new rotation around the Y axis |
| float | zAng | new rotation around the Z axis |
Description: This method sets the object to a new orientation about the X, Y, and Z axes.
Notes:
See also GetOrientation().
Parameters:
| const Vec3D& | newOrientation | new orientation about X, Y, and Z |
Description: This method sets the object to a new orientation about the X, Y, and Z axes.
Notes:
See also GetOrientation().
Parameters:
| float | radians | amount to turn, in radians |
| short | axis=1 | axis about which to turn (0==X, 1==Y, 2==Z) |
Description: This method provides a simplified way to rotate an object around one of the three canonical axes.
Notes:
This is mostly equivalent to using Orient() with two parameters set to zero, but it has one added feature: the object's orientation about the affected axis is kept in the range 0 to 2*PI. This doesn't matter to the engine, but may simplify your calculations after calling GetOrientation().
Parameters:
| float | scaleFactor | amount my which to multiply the size |
Description: This method uniformly scales the object. In principle, the distance between each point in the object and the object's position (see GetPosition()) is found, and this distance is multiplied by scaleFactor to get the point's new position.
Notes:
Of course, no distance computations are actually involved.
This method works properly on translated objects; there is no need to move an object back to the origin before scaling it. Scaling is done relative to the object's current position.
Parameters:
| float | scaleX | scale factor along the X axis |
| float | scaleY | scale factor along the Y axis |
| float | scaleZ | scale factor along the Z axis |
Description: This method is used to scale an object, with separate control over the X, Y, and Z scalings.
Notes:
For example, to double the height of an object without affecting its width or depth, you would call Scale(1,2,1).
This method works properly on translated objects; there is no need to move an object back to the origin before scaling it. Scaling is done relative to the object's current position.
Parameters:
| const Vec3D | scaleFactors | scale factor in X, Y, and Z |
Description: This method is used to scale an object, with separate control over the X, Y, and Z scalings.
Notes:
For example, to double the height of an object without affecting its width or depth, scaleFactors would be Vec3D(1,2,1).
This method works properly on translated objects; there is no need to move an object back to the origin before scaling it. Scaling is done relative to the object's current position.
Parameters: None
Description: This method turns the object inside-out; every triangle in the object is flipped. If you've set your rendering preferences to cull polygons seen from behind, then this will have a drastic effect on the appearance of your object.
Notes:
You'll probably never need this, but if you suspect an object has been modeled inside-out, this is a convenient way to flip the surfaces and see the effect.