DORE.TXT
Remove Frame
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
<ff><ff>
.
.
(binary data)
.
.
<EOF>
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
<ff><ff>
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,
<Z1> is the most significant byte. For little-endian, <Z1> is the least
significant byte.
r8g8b8
<red><green><blue>
r8g8b8a8
<red><green><blue><alpha>
a8b8g8r8
<alpha><blue><green><red>
r8g8b8a8z32
<red><green><blue><alpha><Z1><Z2><Z3><Z4>
r8g8b8z32
<red><green><blue><Z1><Z2><Z3><Z4>
a8
<alpha>
z32
<Z1><Z2><Z3><Z4>
______________________________________________________________________________
Steve Hollasch Kubota Pacific Computer, Inc.
[email protected] Santa Clara, California
