DORE.TXT

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