libgfx: Packed Integer Vectors

Packed Integer Vectors

The vector package provides the standard way to represent and manipulate vector quantities. These vectors are primarily designed to represent real-valued vectors using floating point numbers. However, there are times when it is more convenient to use a packed integer vector format. That is the purpose of this package, which you can use by including the header file

    #include <intvec.h>

A packed integer vector is an n element vector, each of whose elements are k-bit integers. These k-bit integers are interpreted as representing the range [0, 1] for unsigned types and [-1, 1] for signed types. For example, suppose we have a vector whose elements are unsigned 8-bit quantities (e.g., of type unsigned char). Each value would have an integral value in the range [0, 255], but these values would always be interpreted as real values ranging between [0, 1].

class IntVec

Packed integer vectors are declared using the following template class

    template<class T, int T_MAX, int N>  class IntVec;

The type T is the type of the constituent elements (e.g., unsigned char) and T_MAX is the maxium representable value for this type (e.g., UCHAR_MAX). The number of elements in the vector is determined by N. Note that ANSI C defines appropriate maximum values of integer types in <limits.h>.

Classes created from the IntVec template provide a small set of fundamental public methods:

A default constructor that initializes all elements of the vector to 0.
A C-style [] bracket accessor which returns, as a double the appropriate element of the vector.
A vector assignment operator (v = w).
A scalar assignment operator (v = 3.14).

class IntVec3

Because 3-D vectors are particularly common in graphics applications, this package provides explicit support for them.

    template <class T, int T_MAX>  class IntVec3;

In addition to the standard IntVec methods, IntVec3 provides the following additional constructors, all of which allow the values of the vector to be explicitly initialized.

    IntVec3(double x, double y, double z);
    IntVec3(const Vec3& v);
    IntVec3(const float  v[3]);
    IntVec3(const double v[3]);

It also provides the following methods for manipulating the elements of the vector:

    Vec3 unpack() const;                      // Return vector as Vec3
    void pack(const Vec3& v);                 // Set vector from v
    void pack(double x, double y, double z);  // Set vector from x,y,z

A typical use of this class would be in defining a type for RGB colors represented with 8 bits per channel. Such a type could be declared as follows:

    typedef IntVec3 byteColor;