This chapter discusses all of the basic types that are used in other Cosmo 3D classes. The basic class types fall into the following categories:
Array storage—stores data.
Vector classes—stores vectors.
Bounding shapes—creates a volume around a specified shape.
Field classes—specifies the classes for the node fields: single value.
Other math classes—miscellaneous math classes.
This chapter examines each of these class categories.
These are the sections in this chapter:
csData—stores raw data.
csArray—is a virtual array class.
Array-derived classes—are derivations of csArray.
The following sections describe each of these array classes.
The csData class is similar to malloc: it stores raw data. You can use the csData class directly, such as in storing data in arrays, but it is more common to derive your own class from it.
The methods in the class set and delete the amount of storage necessary for the data being stored:
void* getData () const; int getSize () const; void operator delete (void* ptr); void* operator new (size_t nbytes); |
getData() returns a pointer to the raw bytes of the csData.
getSize() returns the size of the data.
new() creates a new csData containing nbytes bytes.
delete() deallocates the object created by the new() method.
csArray is a virtual array class from which all other array classes are derived. Arrays are used as storage vehicles for a variety of types. Cosmo 3D provides a wealth of csArray-derived array classes for different types, including:
csPtrArray—An array of pointers often used to point to values in other arrays.
csFieldArray—An array of fields.
csByteArray—An array of bytes.
csIntArray—An array of integers.
csFloatArray—An array of floats.
csVec2fArray—An array of Vec2f classes.
csVec3fArray—An array of Vec3f classes.
csVec3sArray—An array of Vec3s classes.
csVec4fArray—An array of Vec4f classes.
csMatrix4fArray—An array of Matrix4f classes.
csRotationArray—An array of rotation vectors.
csStringArray—An array of strings.
csShortArray—An array of shorts.
csFieldInfoArray—An array of field descriptions.
csRefArray—An array of pointers to containers.
csEventArray—An array of events; an event is a user action, such as a mouse click.
The methods in all of the array classes are similar, as described in the following section.
The methods in csArray and all of the derived array classes are similar; the differences stem from the different types filling the arrays. The following example explains the methods in csIntArray but you can easily apply the same descriptions to all of the other array classes.
To fill an array, or to retrieve values from an array, use one of the set() or get() methods in the class, respectively, replacing <type> with the base type of the array.
void set(int i, csInt t); void get(int i, csInt& t) const; <type> get(int i) const; void set(const csIntArray &l); |
i is the position of the value in the array.
tis the value of that element in the array.
The second version of the set() method allows you to copy the contents of one array to another.
You can fill an array by setting groups of values using the following methods:
void setRange(int i, int count, csInt vals[]); void getRange(int i, int count, csInt vals[]); void fillRange(int i, int count, csInt vals[]); |
i is the position in the array where you want to begin setting values.
count is the number of array elements you want to set.
vals[] is an array of values that you want to enter into the array.
The fillRange() method sets all of the values in an array to the value passed in the argument.
The operator, [], assigns values.
<type> operator[](int i) const; |
The following methods manipulate the values in the array:
void append(<type> elt); void insert(int index, <type> elt); int replace(csInt old, <type> elt); int remove(<type> elt); void removeIndex(int i); int fastRemove(<type> elt); void fastRemoveIndex(int i); int find(<type> elt) const; void write(csOutput *out); |
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 index location.
Use the replace() method to replace one value with another.
Use the remove() method to remove the first value it finds that matches its argument.
Use the removeIndex() method to remove a specific value or a value located at a specific index.
You can also remove array elements more quickly: fastRemove() removes the array element, elt, and replaces it with the last element of the array, whereas remove() moves all the remaining elements down one. Also, you can remove the array element, elt, by passing in the index value, i, to fastRemoveIndex().
You can find the index of a specific value in an array using the find() method. You can also write the contents of the array to the csOutput passed using the write() method.
Cosmo 3D provides a wealth of vector math classes. Vectors of different dimensions allow for data categorization according to need, for example, a color value could include four component values. In this case, a four component vector would be used: csVec4f.
The following sections describe the vector classes and their transformation class.
Vectors are used in a variety of ways in Cosmo 3D. Commonly, they are used to define orientation, rotation, and transformations. Cosmo 3D provides the following multi-dimensional vectors.
csVec2f— represents a two-element floating point vector.
csVec3f— represents a three-element floating point vector.
csVec3s— represents a three-element short-integer vector.
csVec4f— represents a four-element floating point vector, often used as a homogenous space coordinate.
csVec4ub— represents a four-element unsigned byte vector, most often used as a color value. The elements range from 0 to 255, inclusive.
The methods in the csVec2f, csVec3f, csVec3s, csVec4f, classes are similar; the differences between them stem only from additional argument members that account for the different dimensions of the classes. The following discussion describes the csVec4f class, but can easily be extended to the other classes as well.
The classes use the following overridden get() and set() methods to return and define, respectively, the vectors.
void set(float a, float b, float c, float d); void get(float *a, float *b, float *c, float *d) const; void set(int i, float f); float get(int i) const; void set(const csVec4f &v); void get(csVec4f &v) const; |
For the csVec2f and csVec3f classes, only two or three arguments, respectively, are passed to the set and get methods.
The classes contain the following methods:
csBool equal(const csVec4f& v) const;
csBool almostEqual(const csVec4f& v, float tol) const;
void negate(const csVec4f& v);
float dot(const csVec4f& v) const;
void add(const csVec4f& v1, const csVec4f& v2);
void sub(const csVec4f& v1, const csVec4f& v2);
void scale(float s, const csVec4f& v);
void addScaled(const csVec4f& v1, float s, const csVec4f& v2);
void combine(float a, const csVec4f& v1, float b, const,
csVec4f& v2);
float sqrDistance(const csVec4f& v) const;
float normalize();
float length() const;
float distance(const csVec4f& v) const;
void xformPt(const csVec4f& v, const csMatrix4f& m);
void xformVec(const csVec4f& v, const csMatrix4f& m);
|
The methods have the following functionality:
almostEqual()—returns TRUE if the values are within tol of each other.
negate()—negates the vector, which, in effect, reverses its direction.
scale()—enlarges or reduces a vector by the multiplier passed in.
addScaled()—adds to a vector the scaled vector passed in.
combine()—performs the vector addition of two vectors.
sqrDistance()—provides the distance squared.
normalize()—makes the vector orthogonal to its original direction.
distance()—determines the distance between two vectors.
xformPt()—transforms the point by the matrix passed in.
xformVec()—transforms the vector by the matrix passed in.
The classes also provide the following write and operator methods:
void write(csOutput *out); csVec4f& operator=(const csVec4f &v); csVec4f& operator=(float v); float& operator[](int i); float operator[](int i) const; csBool operator==(const csVec4f &v) const; csBool operator!=(const csVec4f &v) const; |
The write() method prints the vector to the device or file defined by out.
The operator() method defines an operation that can be performed on two vectors. The first two operator methods are assignment operators, the second two are access operators, and the last two are equality operators. For example,
csVec2f *myVec = new csVec2f();
csVec2f *yourVec = new csVec2f();
...
if (myVec == yourVec) {...}
|
csVec3f vectors are commonly used to specify the placement and orientation of objects in world space. There are two ways to transform a csVec3f when passing a csMatrix4f into xform():
A csVec3f::xformPt(const csVec3f& v, const csMatrix4f& m) transform vector sets a csVec3f vector, v, to be the first three components of (v,1) * m where v is treated as a row vector.
A csVec3f::xformVec(const csVec3f& v, const csMatrix4f& m) transform point sets this vector to be v, thought of as a row vector, times the 3X3 submatrix formed by the first 3 rows and first three columns of m. This is most useful for non-projective transformations.
Bounding volumes provide an efficient means of determining which shapes are in and out of the view frustum. The bounding volume for all csNodes is a sphere, as shown in Figure A-1.
Cosmo 3D provides two bounding shapes as well as an abstract class from which you can derive your own bounding shapes.
csBound— is the abstract base class from which bounding objects are derived.
csBoxBound—prescribes the minimum-sized box that can enclose an object.
csSphereBound—prescribes the minimum-sized sphere that can enclose an object.
csBound provides methods to compute a bounding object around a group of points, boxes, or spheres, and to extend an existing bounding object by any of these. In addition, there are methods to determine if a point, bounding box, or bounding sphere is contained entirely within a bounding object. Methods are also provided to transform bounding objects using a matrix, test it for emptiness, or test it for intersection with a line segment.
csNodes use csSphereBound for efficient bounding updates and checking.
csGeoSets contain a csBoxBound because it provides a tighter bound around the vertices.
Together, fields and methods comprise a scene graph node. A field is a class with set() and get() methods that set and return the values of the field. Fields can also have other methods that perform other operations related to setting or returning the field value.
Cosmo 3D contains the following Field classes:
csField— represents a simple data type, such as float, csVec3f, and arrays of simple types.
csFieldInfo—maintains information about the fields of a class including string name, integer id, default value, and a pointer to a member in csContainer.
csMField— is an abstract class containing some of the functionality common to arrays.
csAtomField<Type>—is a single-valued atomic field type.
csArrayField<Type>—is a single-valued array field type.
You can substitute for <Type> any character type, such as Int, Short, or Field. The following sections describe each of these field classes.
csField is the abstract class from which all of the other field classes are derived. Because it does not have a constructor, you cannot use it directly. See “The csField Class” for additional information on csField.
csFieldInfo maintains information about the fields of a class, including the string name, integer id, default value, and storage offset from class instance, all of which you set in the constructor:
csFieldInfo(const char *name, short id, char csContainer::*offset); |
The class methods provide means of obtaining the argument values.
const char* getName(); short getId(); char csContainer::* getOffset(); |
csFieldInfo also provides methods that allow you to create an enumeration by pairing an integer with a string, and to create an alias for the field.
void addEnum(int e, const char *str); void addAlias(const char *alias); |
csMField is an abstract class containing some of the functionality common to arrays, including a container object, an index, and a storage value, as defined by the constructor:
csMField(csContainer *p, short i); |
The set and get methods in the class define array-type functionality, including returning an offset value in the array where Cosmo 3D starts reading the array. The stride function allows you to step through the values in the array at increments of two or more values at a time, for example, if the stride is two, Cosmo 3D uses every other value in the array.
The count and size methods set and return the number of elements in the object, such as the number of values in an array, and the total number of elements allocated for the object.
The editDone() method allows you to signal when you have finished manipulating the csMField object so that, for example, you can allow its values to take effect.
short getOffset() const; short getStride() const; void setCount(int n); int getCount(); void setSize(int n); int getSize(); void editDone(); |
csAtomField is a single-valued composite field type. A single value field can be something as simple as an integer or a csVec4f.
csAtomField<Val>(csContainer *p, short i, Val *stor); |
csArrayField is a multiple-valued array field type. It is commonly used as the type for array class fields.
csArrayField<ValType, ValRef>(csContainer *p, short i,
csGenArray<ValType, ValRef> *stor);
|
The class's set() and get() methods provide the means of setting and returning these values.
void set(int i, ValRef t); void get(int i, ValType& t); ValRef get(int i); void set(const csGenArray<ValType, ValRef> &l); void setRange(int i, int count, const ValType vals[]); void getRange(int i, int count, ValType vals[]); void fillRange(int i, int count, ValRef val); ValRef operator[](int i); |
You can fill an array by setting groups of values using the following methods:
void setRange(int i, int count, csInt vals[]); void getRange(int i, int count, csInt vals[]); void fillRange(int i, int count, csInt vals[]); |
i is the position in the array where you want to begin setting values.
count is the number of array elements you want to set.
vals[] is an array of values that you want to enter into the array.
The fillRange() method sets all of the values in an array to the value passed in the argument, vals[]
The operator, [], assigns values.
csInt operator[](int i) const; |
Cosmo 3D includes the following classes used for mathematical calculations.
csSeg— encapsulates a line segment.
csPlane—encapsulates a plane.
csFrustum— encapsulates a viewing frustum.
The following sections explain these classes.
csSeg encapsulates a line segment in 3-space as an origin, a normalized direction vector, and a length.
The methods in the class allow you to
Construct a line from a pair of points.
Create a vector given a point and polar coordinates.
Clip a segment out of a line.
csPlane represents a half space with a normal and an offset, which together form the parameters of the traditional Ax + By + Cz = D plane equation.
The methods in the class allow you to