TriMesh

Requires: library QD3D

Base class: none

Description: This class wraps the "trimesh" geometry of QuickDraw 3D. This is the fundamental datatype for efficient rendering: a set of triangles with shared vertices and common properties. This wrapper class gives you a (mostly) uniform data structure, and utilities to simplify transformation and computation of bounding boxes.

Notes:
Notice that this class does not use any other Magdef files. You can use this in your own projects, all by itself, without needing anything else from the library.

Methods

[Add Note] [Top]


TriMesh ( qtyVertices, qtyTriangles, textured=false, smooth=true )

Parameters:
short qtyVertices number of vertices in the trimesh
short qtyTriangles number of triangles in the trimesh
Boolean textured=false if true, keep UV coordinates for applying a texture map; if false, no UV coordinates
Boolean smooth=true if true, keep vertex normals for smooth shading; if false, no vertex normals

Throws: OSStatus memFullErr memory allocation failure

Description: This is the standard TriMesh constructor. You must pass the size of the mesh, in terms of the number of triangles and vertices, and also choose whether to keep UV parameters (for texture mapping) and vertex normals (for smooth shading). These parameters cannot be changed once the TriMesh is created.

Notes:
These constructors are not yet exception-safe; if a memory allocation fails mid-construction, some allocations may not be freed.

This constructor merely allocates space for the data; to define the actual geometry of the TriMesh, call the BuildMesh() method.

[Add Note] [Top]


TriMesh ( srcTriMesh )

Parameters:
const TriMesh& srcTriMesh TriMesh to copy

Throws: OSStatus memFullErr memory allocation failure

Description: This copy-constructor copies all data from the source TriMesh. No data is shared; either may be destroyed without affecting the other.

Notes:
This is a very expensive operation; use only when necessary. Consider using (possibly reference-counted) pointers to common TriMeshes instead.

[Add Note] [Top]


TriMesh ( srcGeom )

Parameters:
TQ3GeometryObject srcGeom QD3D trimesh to copy

Throws: OSStatus memFullErr memory allocation failure

Description: This constructor builds the TriMesh object by copying a QuickDraw 3D object of type kQ3GeometryTypeTriMesh. The QD3D data is copied in its entirety, and may be disposed of after calling this constructor.

Notes:
This method is useful for building TriMesh objects out of QD3D objects read from 3DMF files.

All non-trimesh data in the passed QD3D geometry is ignored. Color and texture maps are copied, as are surface normals if any. Any other attributes are ignored.

[Add Note] [Top]


~TriMesh ( )

Parameters: None

Description: TriMesh destructor. All internal data is freed.

[Add Note] [Top]


virtual void BuildMesh ( )

Parameters: None

Description: This method is used to fill in the data structures allocated by the first constructor above. In this class, it does nothing; derived classes may override it to set up a mesh structure.

Notes:
If you use either of the other constructors -- those which copy data from another TriMesh or a TQ3GeometryObject -- then this method is probably not needed, since the trimesh geometry will already be defined.

[Add Note] [Top]


void ComputeNormals ( )

Parameters: None

Description: This method (re)computes the normals of all triangles in the TriMesh, and if it has vertex normals, those are recomputed as well.

Notes:
This function should be called whenever you manually change the positions of the vertices (unless you translate all vertices equally, which does not affect the normals).

[Add Note] [Top]


void FlipSurface ( )

Parameters: None

Description: This method flips every triangle in the mesh, turning it inside-out.

Notes:
This is a utility function, rarely needed if your modeler produces correct output.

[Add Note] [Top]


void Submit ( view )

Parameters:
TQ3ViewObject& view QD3D view object to which to submit

Throws: OSStatus -1 QD3D error

Description: This method submits the TriMesh for rendering in the given view. The DoneWithChanges() method is first called, if PrepareForChanges() or one of the transformation methods (Scale(), etc.) has been called since the last Submit.

[Add Note] [Top]


virtual void PrepareForChanges ( )

Parameters: None

Description: Call this method whenever you're going to be making any direct changes to the TriMesh data (e.g., by using Points() to directly modify the vertex positions).

Notes:
You do not need to call this method before using the built-in transformation methods Scale(), Move(), or Transform().

[Add Note] [Top]


virtual void DoneWithChanges ( )

Parameters: None

Description: Call this method after you've made direct changes to the TriMesh data (having first called PrepareForChanges(), of course), or after calling one of the built-in transformation methods such as Move() or Transform(). This method updates the bounding box and any internal data structures which might be affected.

Notes:
Technically, you don't have to call this method before calling Submit(), as Submit() will call it when needed.

You do, however, need to call this after making changes and before using Bounds().

[Add Note] [Top]


virtual void Move ( dx, dy, dz )

Parameters:
float dx amount to increase X position
float dy amount to increase Y position
float dz amount to increase Z position

Description: This method moves the TriMesh relative to its current position, by translating each vertex accordingly.

Notes:
A TriMesh object does not have an absolute position -- if you want to treat it as if it does, you'll have to keep track of it yourself. Thus, there is no "MoveTo" method which would move to an absolute position, but only this relative-displacement method.

[Add Note] [Top]


virtual void Scale ( scaleFactor )

Parameters:
float scaleFactor factor by which to scale the vertex positions

Description: Use this method to uniformly scale a TriMesh. In effect, the distance of each vertex to the origin is computed, and this distance is multiplied by the given scaleFactor to find the new vertex position.

Notes:
No actual distance computations are involved; rather, each vertex coordinate is simply multiplied by scaleFactor.

This method assumes that the TriMesh has not been displaced; if it has, warping will result. Thus, you'll generally want to scale a TriMesh before you Move() it. Or if you've already moved it, first move it back to its original location, then Scale, then return it to its displaced location.

Vertex and triangle normals are properly updated; there is no need to call ComputeNormals() afterwards.

This method sets an internal flag which causes the bounding box to be recomputed when DoneWithChanges() or Submit() is called.

[Add Note] [Top]


virtual void Scale ( scaleX, scaleY, scaleZ )

Parameters:
float scaleX factor by which to multiply each vertex X coordinate
float scaleY factor by which to multiply each vertex Y coordinate
float scaleZ factor by which to multiply each vertex Z coordinate

Description: Use this method to scale a TriMesh non-uniformly. Each coordinate of each vertex is multiplied by the corresponding scale factor.

Notes:
This method assumes that the TriMesh has not been displaced; if it has, warping will result. Thus, you'll generally want to scale a TriMesh before you
Move() it. Or if you've already moved it, first move it back to its original location, then Scale, then return it to its displaced location.

Vertex and triangle normals are properly updated; there is no need to call ComputeNormals() afterwards.

This method sets an internal flag which causes the bounding box to be recomputed when DoneWithChanges() or Submit() is called.

[Add Note] [Top]


virtual void Transform ( transform )

Parameters:
const TQ3Matrix4x4& transform transformation matrix to apply

Description: This method can apply any transformation to the TriMesh. The parameter is a QD3D 4-by-4 transformation matrix; QD3D's math routines include functions to construct such a matrix for any type of transformation.

Notes:
This method assumes that the TriMesh has not been displaced; if it has, warping will result. Thus, you'll generally want to transform a TriMesh before you
Move() it. Or if you've already moved it, first move it back to its original location, then Transform, then return it to its displaced location.

Vertex and triangle normals are properly updated; there is no need to call ComputeNormals() afterwards.

This method sets an internal flag which causes the bounding box to be recomputed when DoneWithChanges() or Submit() is called.

[Add Note] [Top]


short QtyPoints ( ) const

Parameters: None

Return value: short qtyPoints quantity of vertices in the TriMesh

Description: This method returns the number of vertices (points) in the TriMesh.

Notes:
This value is the bounding value for the arrays returned by
Points(), VertexNormals(), and VertexUVs().

[Add Note] [Top]


TQ3Point3D* Points ( )

Parameters: None

Return value: TQ3Point3D* pointArray array of vertex positions

Description: This method gives you direct access to the position of each vertex in the TriMesh. The return value is an array of TQ3Point3D data structures, each of which has members x, y, and z specifying the position of a point in 3D space.

Notes:
This can be used to "manually" modify the vertex positions.

Be sure to call PrepareForChanges() before modifying these points.

After modifying vertex positions, you will need to call ComputeNormals(), and may want to call DoneWithChanges() (though the latter will be called automatically by Submit() if you don't do it first).

[Add Note] [Top]


TQ3Vector3D* VertexNormals ( )

Parameters: None

Return value: TQ3Vector3D* normArray array of vertex normals, if any

Description: This method gives you direct access to the normal of each vertex, for a TriMesh which keeps such data for smooth shading. The return value is an array of TQ3Vector3D data structures, each of which has members x, y, and z, specifying a vector perpendicular to the surface at each vertex. If the TriMesh is not smoothed (i.e., does not keep vertex normals), then the return value is 0.

[Add Note] [Top]


TQ3Param2D* VertexUVs ( )

Parameters: None

Return value: TQ3Param2D* uvArray array of vertex UV coordinates, if any

Description: This method gives you direct access to the UV coordinate (i.e., the attachment point in the texture map) of each vertex, for a TriMesh which keeps such data for texture mapping. The return value is an array of TQ3Param2D data structures, each of which has members u and v, specifying the position of each vertex in the texture map. If the TriMesh is not textured (i.e., does not keep UV coordinates), then the return value is 0.

[Add Note] [Top]


short QtyTriangles ( ) const

Parameters: None

Return value: short qtyTriangles number of triangles in the TriMesh

Description: This method returns the number of triangles (faces) in the TriMesh.

Notes:
This value is the bounding value for the arrays returned by
Triangles() and FaceNormals().

[Add Note] [Top]


TQ3TriMeshTriangleData* Triangles ( )

Parameters: None

Return value: TQ3TriMeshTriangleData* triArray array of triangle vertices

Description: This method gives you direct access to the definition of each triangle in the mesh. The return value is an array of TQ3TriMeshTriangleData data structures, each of which contains a 3-element pointIndices array. The values of this array indicate the numbers of the vertices making up the triangle.

[Add Note] [Top]


TQ3Vector3D* FaceNormals ( )

Parameters: None

Return value: TQ3Vector3D* normArray array of triangle normals

Description: This method gives you direct access to the normal of each triangle face in the mesh. The return value is an array of TQ3Vector3D data structures, each of which has members x, y, and z, specifying a vector perpendicular to the surface at each face.

[Add Note] [Top]


TQ3AttributeSet Attributes ( )

Parameters: None

Return value: TQ3AttributeSet attributes QD3D attribute set for the TriMesh

Description: This method gives you access to the TriMesh QD3D attributes. Standard QD3D methods can be used to inspect or modify this data, e.g., to add a color or texture map.

[Add Note] [Top]


TQ3BoundingBox& Bounds ( )

Parameters: None

Return value: TQ3BoundingBox& bbox box just enclosing the TriMesh points

Description: This method returns a reference to the bounding box for the TriMesh vertices, using the QD3D TQ3BoundingBox data structure.

Notes:
This method could be useful for object culling (removing meshes not in the viewing frustum), or for collision detection.

Note that this method does not call DoneWithChanges(); for the sake of speed, it assumes that the bounding box is up-to-date. If you've done any transformations to the object since the last Submit(), you'd better call DoneWithChanges() before calling Bounds.

[Add Note] [Top]