Bitmap Storage

From K-3D

Bitmap data is handled in K-3D using the basic_bitmap<> class defined in k3dsdk/bitmap.h, which acts as a two-dimensional array of "pixels", and is parameterized by the type of "pixels" it contains.

There are a number of auxiliary classes that define common pixel types in k3dsdk/color.h, including basic_rgb<>, basic_rgba<>, basic_luma<>, and basic_hsv. With the exception of basic_hsv, these types are parameterized by the type of data used to store color samples.

Thus, you can combine these objects in various ways to store any reasonable bitmap data you might imagine; here are just a few examples:

basic_bitmap<basic_luma<float> > a; // Stores a grayscale image with floating-point values.
basic_bitmap<basic_hsv> b; // Stores an image containing color HSV data.
basic_bitmap<basic_rgb<boost::int8_t> > c; Stores a color RGB image with 8-bit signed-integer values.

You are also free to define a bitmap containing other, less-traditional types:

basic_bitmap<normal3> d; // A normal map for doing cartoon rendering, perhaps?

basic_bitmap<> supports value-semantics, including copying and pass-by-value. Bitmaps of dissimilar types may be copied as well, as long as there are implicit conversions between the types they contain. Implicit conversions are defined for all of the types in k3dsdk/color.h - for example:

basic_bitmap<basic_rgba<float> > e = /* initialized elsewhere */;
basic_bitmap<basic_hsv> f = e; /* Implicit conversion of RGB to HSV data */

With this in mind, there are "standard" pixel and bitmap types defined for K-3D:

typedef basic_rgba<half> pixel;
typedef basic_bitmap<pixel> bitmap;

This standard "bitmap" type is the type used for all bitmap plugins, including import/export plugins and filters, and can thus be considered the "native" bitmap format for K-3D.

Note that a "half" is a 16-bit floating-point type that is comparable to an IEEE float, albeit with reduced precision. Storing bitmaps using the "half" datatype allows K-3D to interoperate with high-definition file formats such as OpenEXR and produce images and textures of the highest possible fidelity.

Developers accustomed to working with the 8-bits-per-channel integer color data typical of todays computers should be aware that "full intensity" pixels with a value of 255 will have a value of 1.0 when stored using the "half" datatype. Further, you should be aware that values greater-than 1.0 are explicitly allowed (to handle highlights, overexposure, etc.), but will be clamped to 255 when converted to an 8-bits-per-channel type.