Dore Raster File Format

Also Known As: Dore, RFF


Type Bitmap
Colors Unlimited
Compression None
Maximum Image Size Unlimited
Multiple Images Per File No
Numerical Format Any
Originator Kubota Pacific Computers
Platform UNIX
Supporting Applications AVS visualization package, many others
See Also None

Usage
Storage and interchange of 2D and 3D image data.

Comments
The Dore Raster File Format is one of the rare formats that combines both ASCII and binary information within the same image file. Dore lacks a native method of data compression, but does support the storage of voxel data.

Vendor specifications are available for this format.


The Dore Raster File Format (Dore RFF) is used by the Dore graphics library for storing 2D and 3D image data. Once stored, the data may be retrieved or the RFF files may be used to interchange the image information with other software packages.

Contents:
File Organization
File Details
For Further Information

Dore itself is an object-oriented 3D graphics library used for rendering 2D and 3D near-photographic quality images and scenes. Dore supports features such as texture and environment mapping, 2D and 3D filtering, and storage of 3D raster data.

Most raster (bitmap) file formats are only capable of storing 2D pixels (picture elements). Dore RFF is capable of storing 3D pixels called voxels (volume elements). A voxel contains standard pixel information, such as color and alpha channel values, plus Z-depth information, which describes the relative distance of the voxel from a point of reference. The Dore RFF format defines Z-depth data as a 32-bit integer value in the range of 00h to FFFFFFFFh (2^32 - 1). A value of 00h places a voxel at the farthest possible point from the point of reference, and a value of FFFFFFFFh places a voxel at the closest possible point.

The Dore Raster File Format is the underlying API for the AVS visualization package.

File Organization

Dore RFF is a rather simple, straightforward format that contains primarily byte-oriented data. All Dore RFF files contain an ASCII header, followed by binary image data.

Following is an example of a Dore RFF file. The position of the binary image data is indicated by the label in brackets. The <FF> symbols are formfeed (ASCII 0Ch) characters:

# # Dore Raster File Example
#
  rastertype = image
  width = 1280
  height = 1024
  depth = 2
  pixel = r8g8b8a8z32
  wordbyteorder = big-endian
<FF><FF>
[Binary Image Data]
<EOF>

The header may contain up to six fields. Each field has the format keyword = value and is composed entirely of ASCII characters. There is typically one field per line, although multiple fields may appear on a single line if they are separated by one or more white-space characters. Comments begin with the # character and continue to the end of the line.

The header fields are summarized below:

rastertype

Type of raster image contained in the file. The only supported value for this keyword is image. This field must appear first in all RFF headers and has no default value.

width

2-byte WORD value that indicates the width of the image in pixels or voxels. The width field must appear in all RFF headers and has no default value.

height

2-byte WORD value that indicates the height of the image in pixels or voxels. The height field must appear in all RFF headers and has no default value.

depth

2-byte WORD value that indicates the depth of the raster. 2D raster images always contain pixels, and therefore the depth value is 1. 3D raster images always contain voxels, and therefore the depth value is always greater than 1. The depth field is optional and has a default value of 1.

pixel

String indicating the data format of each pixel or voxel. The pixel field has no default value and must appear in all RFF headers. The possible values for this field are as follows:

r8g8b8

Pixels are three bytes in size and stored as three separate 8-bit RGB values.

r8g8b8a8

Pixels are four bytes in size and stored as three separate 8-bit RGB values and a single 8-bit alpha channel value in RGBA order.

a8b8g8r8

Pixels are four bytes in size and stored as three separate 8-bit RGB values and a single 8-bit alpha channel value in ABGR order.

a8g8b8a8z32

Voxels are eight bytes in size and stored as three separate 8-bit RGB values, a single 8-bit alpha channel value, and a single 32-bit DWORD containing the Z-depth value in RGBAZ order.

a8

Pixels or voxels are a single byte in size and only contain a single 8-bit alpha channel value.

z32

Voxels are a single byte in size and only contain a single 32-bit Z-depth value.

wordbyteorder

Indicates the byte-order of the Z-depth values in the binary image data. The value of this field may be either the string big-endian or little-endian. The appearance of the wordbyteorder field in the header is optional, and the value defaults to big-endian.

The order of the fields within the header is not significant, except for the rastertype field. rastertype must always appear in every RFF header and must always be the first field. The width, height, and pixel fields must appear in every header as well. All other fields are optional; if not present, their default values are assumed.

The End Of Header marker is two formfeed characters. If it is necessary to pad out the header to end on a particular byte boundary, you can place any number of ASCII characters, except formfeeds, between these two formfeed characters. See the example below:

# # Example of using the End Of Header marker to pad out the header
# # to a byte boundary
#
  rastertype = image
  width = 64
  height = 64
  depth = 1
  pixel = r8g8b8
  wordbyteorder = little-endian
<FF>
ASCII data used to extend the length of the header
<FF>
Binary Image Data
<EOF>

File Details

The image data immediately follows the End OF Header maker and is always stored in an uncompressed binary form. The format of the image data depends upon the format of the pixel (or voxel) data indicated by the value of the pixel field in the header.

The image data is always stored as contiguous pixels or voxels organized within scan lines. All RGB and alpha channel values are stored as bytes. Z-depth values are stored as 32-bit DWORDs, with the byte-order of the Z-depth values being indicated by the value of the wordbyteorder field in the header. Any pixel containing a Z-depth value is regarded as a voxel.

The format of each possible type of pixel or voxel is illustrated using C language structures as follows:

/* Pixel - Simple RGB triple */
typedef struct _r8g8b8
{
  BYTE red;
  BYTE green;
  BYTE blue;
} R8G8B8;
/* Pixel - RGB triple with alpha channel value */
typedef struct _r8g8b8a8
{
  BYTE red;
  BYTE green;
  BYTE blue;
  BYTE alpha;
} R8G8B8A8;
/* Pixel - RGB triple with alpha in reverse order */
typedef struct _a8b8g8r8
{
  BYTE alpha;
  BYTE blue;
  BYTE green;
  BYTE red;
} A8B8G8R8;
/* Voxel - RGB triple, alpha, and Z-depth */
typedef struct _a8g8b8a8z32
{
  BYTE red;
  BYTE green;
  BYTE blue;
  BYTE alpha
  DWORD zdepth;
} R8G8B8A8Z32;
/* Pixel or voxel mask - Only an alpha channel value */
typedef struct _a8 {
	BYTE alpha;
} A8;
/* Voxel mask - Only a Z-depth value */
typedef struct _z32
{
  DWORD zdepth;
} Z32;

For Further Information

For further information about the Dore Raster File Format, see the specification included on the CD-ROM that accompanies this book. You can also contact:

Kubota Pacific Computer, Inc.
Attn: Steve Hollasch
2630 Walsh Avenue
Santa Clara, CA 95051
Voice: 408-727-8100
Email: hollasch@kpc.com

You can also contact:

Lori Whippler
Email: loriw@kpc.com



Copyright © 1996, 1994 O'Reilly & Associates, Inc. All Rights Reserved.