BRL-CAD Database Format

The length of an object or sub-element in the database is recorded using an unsigned integer. These are variable-width fields based on the magnitude of the maximum number needed. The Wid bits specify the size of the unsigned integer employed in each instance. There are four 2-bit width (Wid) flags: Object_Wid (OWid) and Name_Wid (NWid) (stored in HFlags), Attribute_Wid (AWid) (stored in AFlags), and Body_Wid (BWid) (stored in BFlags). The Wid fields are interpreted in this manner:

The OWid flag, at the high end of HFlags, encodes the width of the Object_Length field. The NWid flag, in bits 3 and 4 of HFlags, encodes the width of the Name_Length field (when the name element is present; see the N bit, shown later). AWid (or BWid, as the case may be) encodes the width of the Attribute_Length field (when the Object_Attributes or Object_Body element is present; see the AP and BP bits below).

(See the original draft at [http://ftp.arl.mil/~mike/papers/brlcad5.0/newdb.html].)

The rationale for allowing the width of the Object_Length field to be specified independently of the other widths is to save space on objects in which the values in many of the length fields nearly overflow the specified field width, so that their sum requires a wider field. For example, for four 255-byte interior fields, the corresponding length fields need be no more than 8 bits wide, so the choice Interior_Wid=00 suffices, but their combined length of 1020 bytes would require Object_Wid=01. Because all of the length fields besides Object_Length must have the same width (FIXME: is that true?), the largest of the values stored in these length fields determines the value of Interior_Wid required. Both Object_Wid and Interior_Wid may vary from object to object. It is expected that the routines that write an object to the disk will use the narrowest width possible for each object.

The bits labeled as "r" in all three flags are reserved for future design work assigning additional optional fields in the object.

The DLI flag is a 2-bit flag that indicates whether the object is an Application Data Object or a Database Layer Internal Object. The bits are interpreted as follows:

The DLI flag is not available to the higher database access layers.

The "NP" bit indicates whether the Name element (consisting of Name_Length and Object_Name fields) is present (1) or absent (0) in the noncompressible basic header immediately following the Object_Length field. The width of the Name_Length field is specified by the Name_Wid field.

The "(A|B)P" bit indicates whether the Attributes (or, alternatively, Body) element consisting of Attribute_Length and Attribute_Data (or Body_Length and Body_Data) fields, is present (1) or absent (0) in the Object_Interior.

The 3-bit "(A|B)Z" flag indicates the compression, if any, of the object Attributes (or Body):

Major Type 0 is illegal. The rationale is to provide the library an opportunity to detect incompletely filled in data structures.

This class of objects is private to librt and concerns all nongeometric objects needed by the library. For this Major_Type, the following Minor_Type values are defined:

All other values reserved for future expansion.

?????Should "Grip" and "Joint" objects be of this type, or Major_Type = 2?

This class of objects is private to librt and concerns all geometric objects needed by the library. Typically, there will be one xxx/xxx.c module in librt for each minor type. For this Major_Type, the following Minor_Type values are defined:

The details of these Minor_Types are provided in Section IV.

This type of object stores only attributes in the object interior section; it has no object body elements.

For example, if several objects need to have the same shader parameters, it would be possible to create one attribute-only object to hold these common attributes and serve as a simple form of "macro". Objects that needed to share these attributes could all reference the same attribute object. If the attribute object is altered, then all of the objects that reference it would be updated together. Without this capability, the user would have to update each element individually to alter the attributes.

Conventions will have to be established regarding which attributes of an attribute-only object will be used when a macro reference is performed. For example, rt shaders will only be interested in the value of the "oshader=" attribute, while librt’s tree-walker might also be interested in the "rgb=", "giftmater=", "nsn=", "material=", and "los=" attributes (assuming that a convention was developed so that a combination could macro-reference an attribute-only object too).

An attribute-only object may not have an object body; thus, flag bit B must always be zero for this type of object.

As used by the rt family of applications codes, these attribute-only objects will contain "macros" for shaders. The shader name and its parameters shall be encoded as a single ASCII string, which is the value of the "oshader=" attribute. An rt shader named "macro" (or equivalent) would take a single parameter "obj=", which would specify the name of the attribute-only object in the database from which the actual shader and shader parameter information would be extracted.

There will be one attribute-only object with a reserved object name of "_GLOBAL" that will be used to contain various kinds of states that are global to the entire ".g" database and that had previously been found in the database header itself. There will be the following BRL-CAD-specific attributes whose meaning is predefined for the _GLOBAL object:

In addition, the "comment=" attribute of the "_GLOBAL" object may be used to store human-readable remarks about the database that are not more properly associated with a specific database item. These might include remarks about data sources, model evolution, security classification, and release restrictions. In the absence of some outboard revision-control system, this might also be a place to record modification history, although such use is discouraged.

This class of objects contains various "bulk" binary data that might otherwise have been placed in auxiliary files.

MGED and stand-alone commands must be built to store/extract these opaque binary objects between a ".g" file and other files. A user might want to use those same MGED commands to store or extract the binary object body of any object for external processing. An easy example to imagine is the importing and exporting of texture maps for external processing, but the same commands could be used for importing and exporting solid parameters in their external binary form.

These objects may be referenced in combination nodes, for organizational purposes, but they cannot be drawn in MGED or raytraced, and doing so would result in a warning message being printed by the tree walker as that arc is traversed. This class may be used by all applications and layers.

The data’s purpose may be placed in the "purpose=" attribute. (????????Need a table/registry of presently known values for this attribute.)

Routines that retrieve bulk binary objects should check the minor type and the "purpose=" attribute and send a warning message in the event of a mismatch, but best-effort processing of the object should continue. This will permit some degree of error checking, which should benefit novice users without standing in the way of "creatively" reusing one set of data, (e.g., using one array of values as both a height field and a bwtexture). This allows common data perversion practices, such as interpreting an array of floats as an array of bytes, to continue.

Each application will need to have its own syntax for the user to specify whether the data source is an outboard file or a raw-binary object. For example, the current RT sh_texture module uses the keyword file="name" to indicate an outboard file; that might be supplemented with an additional obj="name" possibility for retrieving from an inboard raw-binary object.

A Minor_Type of 1 indicates that this is a contiguous block of free storage.

A Minor_Type of 2 indicates that this is a database header.