Appendix A. Cosmo Basic Types

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:

This chapter examines each of these class categories.

These are the sections in this chapter:

Array Storage Class Types

The array classes store data.

  • 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.

Data Class

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.

Array Classes

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.

Array Methods

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.

Returning Array Data

To return a pointer directly to the array data, use the following method:

<type>* getArray() const;

Vector Classes

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.

Vector Math

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.

Vector Methods

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) {...}


The methods in csVec3s are the same as those in the csVec3f class.

csVec4ub Methods

The csVec4ub class contains a subset of the above methods, including the set(), get(), equal(), write(), and operator() methods for two-, three-, and four-dimensional ubyte quantities. For example, the four-dimensional definition is

csVec4ub(ubyte a, ubyte b, ubyte c, ubyte d);

Transforming csVec3f Vectors

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

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.

Figure A-1. Bounding Sphere

Figure A-1 Bounding Sphere

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.

Field Classes

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;

Other Math Classes

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

  • Determine the closest point on the plane to a point in space.

  • Determine whether or not it intersects with a csSeg.

  • Construct a plane from three points.

  • Construct a plane from a point and the plane normal at a point.

  • Transform the orientation of the plane.


csFrustum is a truncated, possibly asymmetric pyramid for the purposes of testing objects against view volumes.

The methods in the class allow you to

  • Determine if a point or shape is in the frustum.

  • Copy the contents of the frustum.

  • Set and return the near and far clipping planes of the frustum.

  • Create an orthogonal frustum.

  • Transform the frustum.

  • Return the aspect of the frustum and the position of the camera.