This summary of the Dore file format was compiled by Steve Hollasch of Kubota Pacific and is included with permission. ============================== DORE' RASTER FILE FORMAT ============================== Dore' is an object oriented 3D graphics library that enables the user to produce both dynamic image sequences and near-photographic quality images. Dore' is device independent and supports multiple output devices and renderers. It provides a rich set of graphics attributes, including features such as 2D and 3D texture mapping and filtering. The Dore' raster file format was developed in order to store and retrieve information for texture mapping, environment mapping, bump mapping, voxel fields and so on. It provides for the representation of two- and three- dimensional rasters of a variety of different data types, including color, transparency, and depth information. This document describes the file format used by Dore' for raster data. Raster File Data Interpretation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A pixel (picture element) is the set of information associated with a specific point in a two-dimensional raster image. A voxel (volume element) is the three-dimensional analog of a pixel, and is used when referring to three-dimensional rasters. In Dore', a pixel or voxel consists of certain combinations of red, green, blue, alpha, and Z image data. This section describes the meaning of the values of these pixel and voxel components. RGB Data: RGB color information describes the color of each pixel/voxel, and is represented by three 8-bit unsigned integer byte values. Each value represents the intensity of light for that color channel. A value of 0 means no light, and a value of 255 means full intensity light. Alpha Data: Alpha information describes the transparency of the pixel/voxel, and is represented as a single 8-bit unsigned integer byte value. A value of 0 means the pixel/voxel is opaque, and a value of 255 means it is completely transparent. Alpha information is used in image compositing. Z Data: The Z information describes the relative distance of the pixel/voxel from a point of reference, and is stored as a 32-bit unsigned integer. A value of 0 represents a distance as far away as possible, and a value of 4,294,967,295 (or 2^32 - 1) represents a distance as close as possible. For example, if the image is a two-dimensional rendering of a three-dimensional scene, then the Z data could be the distance of the visible surface from the eye. Raster File Format ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Raster files are used to store Dore' image data in computer file systems and to allow other programs to communicate image data to Dore'. Dore' raster files consist of an ASCII header section followed by a binary data section. An example of a raster file (with the binary data shown only as an annotation) is given below: # brick texture raster - Dore' Rasterfile rastertype = image width = 128 height = 128 depth = 1 pixel = r8g8b8z32 wordbyteorder = big-endian . . (binary data) . . The sections below describe the formats of the header and binary data sections of raster files in more detail. Raster File Header ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ASCII header of a Dore' raster file consists of several attribute- value pairs followed by an end-of-header marker. An attribute-value pair is an attribute name followed by an equal sign (=), followed by a numeric value or an identifier name value. Optional white space characters (spaces, tabs, newlines/linefeeds, or carriage returns) may precede or follow the = character. Attribute-value pairs must be separated by white space characters. The convention is to have one attribute-value pair per line. Unknown attribute-value pairs are ignored. An attribute may have multiple values, separated by commas, even though this feature is not currently used by Dore'. The end-of-header marker is a formfeed character (ASCII character 0x0c) followed by zero or more nonformfeed characters followed by a formfeed character. The double formfeed end-of-header marker allows the header section to be expanded to fall at the end of a disk block boundary. This improves efficiency on some machines. Comments consist of the pound sign (#) and any number of characters to the end of the line. The attributes rastertype, width, height, and pixel are mandatory. The rastertype attribute is required to be the first attribute in the header. The order of all attributes other than rastertype is not restricted. Attribute names and value strings are case sensitive. Mandatory and optional attributes are listed below with their permissible values. rastertype (mandatory; must be first attribute) A character string indicating the type of raster. Must have the value "image" to indicate that this is a Dore' raster image file. width (mandatory) An unsigned integer value indicating the width of the raster image in pixels (or voxels). height (mandatory) An unsigned integer value indicating the height of the raster image in pixels (or voxels). depth (optional - defaults to 1) An unsigned integer value indicating the depth of the raster image. For 2-D rasters, the picture elements are pixels and depth is 1. For 3-D rasters, the picture elements are voxels and depth is greater than 1. wordbyteorder (optional - defaults to big-endian) A character string indicating the byte order of large unsigned integer binary numbers stored in the file (used for Z values). It has one of two values: big-endian Meaning the machine represents words in the order of most significant byte to least significant byte. little-endian Meaning the machine represents words in the order of least significant byte to most significant byte. pixel (mandatory) A character string indicating the content of each pixel in the raster image. It has one of the following values: r8g8b8 Indicates that each pixel in the image consists of three 8-bit values, representing the RGB color components of the pixel. r8g8b8a8 Indicates that each pixel in the image consists of four 8-bit values, representing the RGB color components and the alpha component of the pixel. a8b8g8r8 Indicates that each pixel in the image consists of four 8-bit values, the alpha component of the pixel, and the color components in BGR order. r8g8b8a8z32 Indicates that each pixel in the image consists of four 8-bit values and one 32-bit value, representing the RGB color components, the alpha component, and the Z depth component of the pixel. r8g8b8z32 Indicates that each pixel in the image consists of three 8-bit values and one 32-bit value, representing the RGB color components, and the Z depth component of the pixel. a8 Indicates that each pixel in the image consists of one 8-bit value representing the alpha component of the pixel. z32 Indicates that each pixel in the image consists of one 32-bit value representing the Z depth component of the pixel. The following example shows sample values for the minimal header attributes acceptable. # mountain background raster - Dore' Rasterfile rastertype = image width = 1280 height = 1024 pixel = r8g8b8 Raster File Binary Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Raster image binary data for Dore' has seven basic formats depending on which of the r8g8b8, r8g8b8a8, a8b8g8r8, r8g8b8a8z32, r8g8b8z32, a8, or z32 types were specified for the pixels or voxels in the raster. For file based images, the binary data is logically read from and written to the files in a byte-by-byte fashion. Since RGB and alpha information is represented as byte values, their representation and order in the file is the same for all machines. Z information, however, consists of an unsigned 32-bit integer. While the position of the 32-bit value is the same in the file for all machines, the order of the bytes in the value is machine dependent. If the word byte order on the machine writing the file goes from the most significant byte first down to the least significant byte, the order is called `big-endian'. The ordering may then be optionally indicated in the file header with the "wordbyteorder = big-endian" attribute-value pair. If the word byte order on the machine writing the file goes from the least significant byte first up to the most significant byte, the order is called `little-endian'. In that case, the ordering must be indicated in the file header with the "wordbyteorder = little-endian" attribute-value pair. Binary data in Dore' raster files are stored in pixel interleaved fashion, meaning that the data is stored pixel by pixel (voxel by voxel). All the information related to a pixel (voxel) is stored consecutively in the file. The order of pixels (voxels) in the binary data section is in width, then height, and then depth order. The data starts with the upper left hand front corner of the image data and scans out in a left to right, top to bottom, front to back order. The index related to width varies the fastest, the index related to height varies the second fastest, and the index related to depth varies the slowest. The following shows the order of the data for a single pixel (voxel) for each of the seven formats. Each <..> denotes one byte. For big-endian, is the most significant byte. For little-endian, is the least significant byte. r8g8b8 r8g8b8a8 a8b8g8r8 r8g8b8a8z32 r8g8b8z32 a8 z32 ______________________________________________________________________________ Steve Hollasch Kubota Pacific Computer, Inc. hollasch@kpc.com Santa Clara, California