QD3D

Metafile Header

Description:
The metafile header is the first object to appear in any metafile.
Metafile versions of 1.x are expected to maintain some degree of compatibility.
Flags indicate to a general degree of how the file is structured or should be read.

A database file indicates that the metafile is a library, and all objects that are shared appear in the table of contents.
A stream file indicates that no references exist in the metafile, so that a parsing program may discard encountered data when it is through with it.

If the toc location (Table of Contents location) is NULL, the entire file must be parsed to find a Table Of Contents.

Data structure:
Uns16 majorVersion
Uns16 minorVersion
MetafileFlags flags
FilePointer tocLocation

As of this release:

majorVersion = 0
minorVersion = 8

The final release of the metafile will be:

majorVersion = 1
minorVersion = 0

MetafileFlags bitfield is:

Binary Text
0x00000000 Normal
0x00000001 Stream
0x00000002 Database

Text samples:

3DMetafile (
  1 0 # version
  Normal
  toc>
)
...
toc: TableOfContents (
  ...
)

Begin Group

Description:
The begin group object is used similarly to the container object, except it is used as the starting delimiter for a group. This allows a naive parser to traverse a metafile without special casing the many types of groups that appear in the metafile spec. It also allows for a single mechanism that is used to declare a group.

Please note that all objects of type group MUST be contained in a begin group, to allow them to be identified as starting a group.

Data structure:

Text samples:

BeginGroup ( DisplayGroup ( ) )
  Triangle ( 0 0 1 0 0 0 0 1 0 )
  Translate ( 1 2 3 )
  Sphere ( )
EndGroup ( )

BeginGroup ( 
  OrderedDisplayGroup ( ) 
  DisplayGroupState ( DoNotDraw )
)
  Triangle ( 0 0 1 0 0 0 0 1 0 )
  Translate ( 1 2 3 )
  Sphere ( )
EndGroup ( )

BeginGroup ( InfoGroup ( ) )
  CString ( Copyright (c) 1995 )
EndGroup ( )

Container

Description:
Used to bind objects together to form a single object.
Container objects always contain other objects.
The first object in the container is called the root object, and sets the scope of the remaining objects in the container, called subobjects.
In general, the root object instantiates the object with its default values, and subobjects append information to the original root object.
There is one exception to these encapsulation rules, which is group objects. Although group objects contain a list of other objects, they are delimited with another 3DMF object, the end group object.

Data structure:

Text samples:

Container (
  Box ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 1 0 1 )
  )
)

End Group

Description:
This object is used as a delimiter for all group objects.

Data structure:
Groups should be arranged into non-overlapping pairs of BeginGroup ( group type/data ) and an EndGroup object.

All groups must be arranged into DAGs. (no cycles are permitted)

Text samples:

# Empty group
BeginGroup ( OrderedDisplayGroup ( ) )
EndGroup ( )

# Group containing 1 object
BeginGroup ( DisplayGroup ( ) )
  Translate ( 1 2 3 )
  Sphere ( )
EndGroup ( )

# Inline group referenced elsewhere

REDColor: 
BeginGroup (
  DisplayGroup ( )
  DisplayGroupState ( IsInline )
)
  Container (
    AttributeSet ( )
    DiffuseColor ( 1 0 0 )
  )
EndGroup ( )

BeginGroup ( DisplayGroup ( ) )
  Reference ( 1 ) # REDColor
  Cone () # Cone is RED
EndGroup ()
toc: TableOfContents (
  nextTOC> -1 2 0 12
  1
  1 REDColor>
)

Junk

Description:
The junk object contains garbage, and serves as a placeholder for deleted information in the metafile.
Junk objects should always be skipped and never parsed.

Data structure:

Text samples:

Container (
  Box ( )
  Junk (
    AttributeSet ( )
    DiffuseColor ( 1 0 1 )
  )
)

is equivalent to:

Box ()

Reference

Description:
The reference object is used to instantiate an object multiple times in a metafile.

It may be substituted anywhere in the metafile for another Shared object. Only shared objects may be referenced.

References are resolved in the Table Of Contents. If a Storage object is specified as a subobject, it is assumed that the reference is external to the current metafile, and should be resolved in that external storages table of contents.

Data structure:
Uns32 refID

if refID = 0, must contain subobjects

if refID > 0, a TOC must exist in current metafile that contains refIDs resolution

This refID is resolved in the current metafile unless a Storage subobject is found in the Reference

Text samples:

Reference ( 23 ) # internal reference
...
toc: TableOfContents (
  nextTOC> 35 -1 0 12
  ...
  20 CarFrame>
  21 Axle>
  23 WheelOfCar>
  ...
)

Container ( # external reference
  Reference ( 23 )
  UnixPath ( parts/car.eb )
)

Table Of Contents

Description:
The table of contents provides a means of resolving references within a file. The nextTOC file pointer points to the next table of contents in the file, or is NULL if no other table of contents exists.

The reference seed indicates the next available reference id available for reference objects. It is an unsigned positive number that is incremented with each addtional reference in a file. It is always one more than the maximum reference seed in a file.

The type seed indicates the next available type ID available for type objects. It is a negative number that is decremented with each additional type in a file. It is always one less than the minimum type seed in a file.

The tocEntryType and tocEntrySize are a set of paired values which indicate the size and type of information stored in a tocEntry.

The tocEntries are sorted by reference ID, in increasing order, to allow fast searching of the table of contents.

Data structure:
FilePointer nextTOC
Uns32 refSeed
Int32 typeSeed
Uns32 tocEntryType
Uns32 tocEntrySize
Uns32 nEntries
TOCEntry tocEntries

refSeed > 0
typeSeed < 0
tocEntryType = 0 or 1
tocEntrySize = 12 or 16, based upon tocEntryType
the TOCEntry structure is:
- tocEntryType 0, tocEntrySize 12 is:

Uns32 refID
FilePointer objLocation

- tocEntryType 1, tocEntrySize 16 is:

Uns32 refID
FilePointer objLocation
ObjectType objType

Text samples:

3DMetafile (
  1 0
  Normal
  toc>
)
box23:
Mesh (
  45 # nVertices
  ...
)
Reference ( 1 )
Arrows: 
BeginGroup ( DisplayGroup ( ) )
  Cone ( )
  Scale ( 0.2 0.1 0.2)
  Cylinder ( )
EndGroup ( )
Reference ( 2 )
Reference ( 4 )
...
Type ( -1 Joes Garage:RepairHistory )
...

-1 ( Jim Fixed lug nut 0.23 0.2 1.2 )

toc:
TableOfContents (
  nextTOC>
  5  # refSeed
  -2 # typeSeed
  0 12 # tocEntry Type/Size
  3 # nEntries
  1 box23>
  2 Arrows>
  4 Geom34>
)

Type

Description:
A type definition is used to declare a custom data type. A type definition may appear anywhere in a file, however, the custom type must be encountered before the custom object of that type is encountered..

All custom types in the metafile are negative numbers, and the typeID field begins at -1 and is decremented for each additional type. Only 2147483648 (or 2^31) custom types are permitted in a single metafile.

The owner string is an ISO 9070 registered owner string. Owner strings are unique globally for each type of custom data.

In the binary and text metafile, the typeID is used as the object type later in the file.

Data structure:
Int32 typeID
String owner

typeID < 0
owner string

Text samples:

Type (
  -1
  Joes Garage:BoltData
)

...

-1 (
   -2.3 34 # Stress (kPA/area)
)

Face Attribute Set List

Description:
The face attribute set list specifies a list of attributes to be attached to a set of faces determined by the parents topology.

nObjects indicates the total number of objects being mapped to.

packing indicates how AttributeSet objects are mapped to indices. Include packing lists the face indices, in sequential order, of those faces to be assigned face attribute sets. Exclude packing lists the face indices, in sequential order, of those faces to NOT be assigned face attribute sets.

So, for example, supposing nObjects was 5, Include packing with a list of 3 indices after it means that there are 3 subobjects, each assigned to the indices in their order. Exclude packing with a list of 3 indices after it means there are 2 attribute sets subobjects, assigned to the indices NOT in the exclude list, in order.

The face attribute set list is padded to the nearest long word.

The values in indices always appear in increasing order.

If a packing value other than Include or Exclude is found, this object and its subobjects should be ignored.

Data structure:
Uns32 nObjects
PackingEnum packing
Uns32 nIndices
Uns32 indices[nIndices]

nObjects must match parent values

PackingEnum is:

Binary Text
0x00000000 Include
0x00000001 Exclude

0 indices < nObjects

Text samples:

Container (
  Box ( )
  Container (
    FaceAttributeSetList ( 
      6 Include 2
      0 1 
    )
    Container ( # assigned to 0
      AttributeSet ( )
      DiffuseColor ( 1 0 0 )
    )
    Container ( # assigned to 1
      AttributeSet ( )
      DiffuseColor ( 0 0 1 )
    )
  )
)

Container (
  Box ( )
  Container (
    FaceAttributeSetList ( 
      6 Exclude 2
      2 4
    )
    Container ( # assigned to 0
      AttributeSet ( )
      DiffuseColor ( 1 0 0 )
    )
    Container ( # assigned to 1
      AttributeSet ( )
      DiffuseColor ( 1 1 0 )
    )
    Container ( # assigned to 3
      AttributeSet ( )
      DiffuseColor ( 1 0 1 )
    )
    Container ( # assigned to 5
      AttributeSet ( )
      DiffuseColor ( 0 0 1 )
    )
  )
)

Geometry Attribute Set List

Description:
The geometry attribute set list specifies a list of attributes to be attached to a set of geometric entities determined by the parents topology.

Currently, only the PolyLine primitive uses this object. Each attribute set is mapped to a line segment in the PolyLine.

Packing for this object is identical to the other attribute set lists.

Data structure:
Uns32 nObjects
PackingEnum packing
Uns32 nIndices
Uns32 indices[nIndices]

nObjects must match parent values

PackingEnum described in FaceAttributeSetList

Text samples:

Container (
  PolyLine (
   3
   10 2 3
   0 0 0
   2 8.5 3
  )
  Container (
    GeometryAttributeSetList ( 
      3 Exclude 1 1
    )
    Container ( # segment 0
      AttributeSet ( )
      DiffuseColor ( 1 0 0 )
    )
    Container ( # segment 2
      AttributeSet ( )
      DiffuseColor ( 0 0 1 )
    )
  )
)

Vertex Attribute Set List

Description:
The vertex attribute set list specifies a list of attributes to be attached to a set of vertices determined by the parents topology.

Packing for this object is identical to the other attribute set lists.

Data structure:
Uns32 nObjects
PackingEnum packing
Uns32 nIndices
Uns32 indices[nIndices]

nObjects must match parent values

PackingEnum described in FaceAttributeSetList

Text samples:

Container (
  Triangle (
    0 0 0 
    0 2 0
    0 0 2
  )
  Container (
    VertexAttributeSetList ( 
      3 Exclude 0
    )
    Container ( # vertex 0
      AttributeSet ( )
      DiffuseColor ( 0 0 0 )
    )
    Container ( # vertex 0
      AttributeSet ( )
      DiffuseColor ( 0 0 1 )
    )
    Container ( # vertex 0
      AttributeSet ( )
      DiffuseColor ( 0 1 0 )
    )
  )
)

Camera Placement

Description:
The camera placement specifies the location and orientation of the camera in space, by a camera location, a point of interest, and an up vector. This placement locates and orients the camera, and defines a space in which the rest of the parameters are interpreted.

If the up vector is not of unit length upon reading, it should be normalized by the reading program.

The camera placement is affected by the current transformation state in a hierarchy. The location and point of interest are multiplied by the current transformation directly, and the up vector is multiplied by the current transformation minus any translation component of the transform, and unitized.

The camera vector is defined as:
camera vector = (pointOfInterest - location)

Data structure:
Point3D location
Point3D pointOfInterest
Vector3D upVector

upVector ^ (pointOfInterest - location)

|upVector| = 1.0

Default Values:
0 0 1 # location
0 0 0 # pointOfInterest
0 1 0 # upVector

Text samples:

Container (
  OrthographicCamera (
    -1 -1 1 1
  )
  CameraPlacement (
     10 0 0 # located along X axis
      0 0 0 # point of interest is origin
      0 1 0 # Y is up
  )
)

Camera Range

Description:
The camera range affects the clipping of the viewing frustum.

This is used to bound the range of the set of objects of interest.

Hither is the frontmost clipping plane (sometimes referred to as near), yon is the backmost clipping plane (sometimes referred to as far).

Each of these distances is measured along the camera vector, described in the Camera Placement object.

Data structure:
Float32 hither
Float32 yon

0 < hither yon

default is:

hither e
yon

Text samples:

Container (
  OrthographicCamera (
    -1 -1 1 1
  )
  CameraRange (
     0.1 2 # hither, yon
  )
)

Camera ViewPort

Description:
The camera viewport specifies a rectangular region of the viewing frustum to which the image is clipped. Effectively the view port may be used to zoom in on a particular feature of an image.

The view port uses the cartesian coordinate system, with Y towards the top of the screen, X to the right, and Z coming towards the viewer, as shown in the diagram.

Data structure:
Point2D origin
Float32 width
Float32 height

-1 origin.x 1
-1 origin.y 1
0 < width 2
0 < height 2
Default is:
-1 1 # origin
2 # width
2 # height

Text samples:

Container (
  OrthographicCamera (
    -1 -1 1 1
  )
  CameraViewPort ( # zoom to 200%
    -0.5 0.5 1 1
  )
)

Bottom Cap Attribute Set

Description:
This object simply allows the attributes associated with the bottom cap of a Cone or Cylinder to be encapsulated.

Presence of a bottom cap attribute set does not neccessarily mean the bottom cap is drawn.

The Caps object determines whether the Cone and Cylinder caps are drawn or not.

Data structure:

Text samples:

3DMetafile ( 1 0 Normal toc> )
Container (
  Cone ( )
  Caps ( Bottom )
  Container (
    BottomCapAttributeSet ( )
    capColor: Container (
      AttributeSet ( )
      DiffuseColor ( 1 0 0 )
    )
  )
)
Container (
  Cone ( )
  Caps ( Bottom )
  Container (
    BottomCapAttributeSet ( )
    Reference (1)
  )
)
...
toc: TableOfContents (
   ...
   1 capColor>
)

Caps

Description:
In the binary file, the upper 28 bits of the caps bitfield should be ignored. In the text file, unknown bitfield strings should be skipped. The default caps value is 0, or None.

The Top cap bit (label) is ignored in the Cone.

Data structure:
CapsFlags caps

CapsFlags is defined as:

Binary Text
0x00000000 None
0x00000001 Bottom
0x00000002 Top

Default is:
None

Text samples:

Container (
  Cylinder ( )
  Caps ( Bottom | Top )
)

Container ( # Cone with a blue bottom
  Cone ( )
  Caps ( Bottom )
  Container (
    BottomCapAttributeSet ( )
    Container (
      AttributeSet ( )
      DiffuseColor ( 0 0 1 )
    )
  )
)

Face Cap Attribute Set

Description:
Attaches a set of attributes to the face cap of the cone and cylinder primitives. For the cone, its indicated in the diagram.

Data structure:

Text samples:

Container (
  Cone ( )
  Caps ( Bottom )
  Container (
    FaceCapAttributeSet ( )
    Container (
      AttributeSet ( )
      DiffuseColor ( 0.2 0.9 0.4 )
    )
  )
)

Top Cap Attribute Set

Description:
Attaches a set of attributes to the top cap of the cylinder primitive.

Presence of a top cap attribute set does not neccessarily mean the top cap is drawn.

The Caps object determines whether the Cylinder caps are drawn or not.

Data structure:

Text samples:

Container (
  Cylinder ( )
  Caps ( Top )
  Container (
    TopCapAttributeSet ( )
    Container (
      AttributeSet ( )
      DiffuseColor ( 0.2 0.9 0.4 )
    )
  )
)

Display Group State

Description:
This piece of data is a subobject only to objects of type display group. It affects how a display group is traversed. These flags allow any display group to have the following characteristics:

To have invisible objects in a scene which may act as user interface items, or may aid in bounding complex geometries
To have non-user interface items which may serve only as decoration and should not be picked.
To have a group of shaders/attributes which affects the state as an inline group so it may be instantiated and inherited in many parts of a hierarchy.

Data structure:
DisplayGroupStateFlags traversalFlags

DisplayGroupStateFlags is:

Binary Text
0x00000000 None
0x00000001 Inline
0x00000002 DoNotDraw
0x00000004 NoBoundingBox
0x00000008 NoBoundingSphere
0x00000010 DoNotPick

default is:

Binary Text
0x00000000 None

Text samples:

# to pick a chess piece by a box around it

BeginGroup ( DisplayGroup ( ) )
  PickIDStyle ( 1 )
  BeginGroup (
    DisplayGroup ( )
    DisplayGroupState ( DoNotDraw )
  )
    Scale ( 2 4 2 )
    Box ( )
  EndGroup ( )

  Container (
    DisplayGroup ( )
    DisplayGroupState ( DoNotPick )
  )
  Mesh ( # chess piece
    56 # nVertices
    0.2 0.3 0.5
    ...
  )
  EndGroup ( )
EndGroup ( )

General Polygon Hint

Description:
The GeneralPolygonHint gives a reading application some hint of what shape a general polygon is.

A Complex general polygon may contain intersecting, concave, or convex polygons.

A Concave general polygon contains no intersecting polygons, but contains 1 or more concave polygons.

A Convex general polygon indicates that all contained polygons are convex and non-intersecting.

Data structure:
GeneralPolygonHintEnum shapeHint

GeneralPolygonHintEnum is:

Binary Text
0x00000000 Complex
0x00000001 Concave
0x00000002 Convex

default is:
Complex

Text samples:

Container (
  GeneralPolygon (
     1
     3
     0 2 3
     0 2 1
     2 0 0
  )
  GeneralPolygonHint ( Convex )
)

Light Data

Description:
The light data object affects information about a light that is common among all lights.

A light may be on or off, may vary in intensity, or may have different colors.

Data structure:
Boolean isOn
Float32 intensity
ColorRGB color

0 intensity 1

Default is:
True # isOn
1.0 # intensity
1 1 1 # color

Text samples:

Container (
  AmbientLight ( )
  LightData (
    True
    0.4
    1 0 0
  )
)

Mesh Corners

Description:
Mesh Corners allow you to attach AttributeSets to a mesh vertex, to allow for attributes to be associated with a particular face-vertex pair. This may be used to allow sharp corners in an object (diagram above), to set different shading parameters for adjacent faces, etc.

Mesh corners supplies a vertex index, a list of face indices, and a vertex attribute set for each corner.

The mesh corners object most often appears inside a container, and always has AttributeSet subobjects. The first corner in the mesh corners data is mapped to the first attribute set subobject, the second corner to the second attribute set, etc.

Data structure:
Uns32 nCorners
MeshCorner corners[nCorners]

0 < nCorners
where MeshCorner is:

Uns32 vertexIndex
Uns32 nFaces
Uns32 faces[nFaces]

0 < nFaces

Text samples:

Container (
  Mesh ( 
    ...
  )
  Container (
    MeshCorners (
      2 # numCorners
 
      # Corner 0
      5 # vertexIndex
      2 # faces
      25 26 # face indices
 
      # Corner 1
      5 # vertexIndex
      2 # faces
      23 24 # face indices
    )
    Container (
      AttributeSet ( )
      Normal ( -0.2 0.8 0.3 )
    )
    Container (
      AttributeSet ( )
      Normal ( -0.7 -0.1 0.4 )
    )
  )
)

Mesh Edges

Description:
Mesh Edges allow you to attach AttributeSets to a mesh edge.

You may attach mesh edges to any edge in the mesh that corresponds to a face edge. To specify and edge that should have an attribute set attached to it, include it as the nth edge the list of edges, and specify the attribute set as the nth attribute set subobject.

Data structure:
Uns32 nEdges
MeshEdge edges[nEdges]

0 < nEdges
where MeshEdge is:

Uns32 vertexIndex1
Uns32 vertexIndex2

Text samples:

Container (
  Mesh ( 
    ...
  )
  Container (
    MeshEdges (
      2 # numEdges
      0 1 # 1st edge vertexIndices
      1 2 # 2nd edge vertexIndices
    )
    Container ( /* 1st edge attribute set */
      AttributeSet ( )
      DiffuseColor ( 0.2 0.8 0.3 )
    )
    Container ( /* 2nd edge attribute set */
      AttributeSet ( )
      DiffuseColor ( 0.8 0.2 0.3 )
    )
  )
)

NURB Curve 2D

Description:
The NURB Curve 2D is a subobject of the TrimCurves object, and supplies a 2 dimensional curve to trim NURB Patches.

Data structure:
Uns32 order
Uns32 nPoints
RationalPoint3D points[nPoints]
Float32 knots[order + nPoints]

2 order
2 nPoints
0 < points[...].w (weights of points)

Text samples:

Shader Data

Description:
The shader data initializes boundary wrapping conditions for a shader.

Data structure:
ShaderUVBoundaryEnum uBounds
ShaderUVBoundaryEnum vBounds

ShaderUVBoundaryEnum is:

Binary Text
0x00000000 Wrap
0x00000001 Clamp

default is:
Wrap Wrap

Text samples:

Container (
  CustomShader ( ... )
  ShaderData ( Wrap Clamp )
)

Shader Transform

Description:
This transforms a shaded object into another world space coordinate system. It does not affect how the object is drawn, or the current state of the hierarchy.

Data structure:
Matrix4x4 shaderTransform

Text samples:

Container (
  3DMarbleShader ( )
  ShaderTransform (
    1 0 0 0
    0 1 0 0
    0 0 1 0
    2 3 4 1
  )
)
...
Type ( -3 Apple:ATG:3DMarbleShader )
Container (
  -3 ( 2.3 1.0 -10 )
  ShaderTransform (
    1 0 0 0
    0 1 0 0
    0 0 1 0
    2 3 4 1
  )
)

Shader UV Transform

Description:
The Shader UV transform allows the uvs on a geometric object to be transformed before shading occurs.

This allows you to rotate a texture map, for example.

Data structure:
Matrix3x3 matrix

Text samples:

Container (
  TextureShader ( )
  ShaderUVTransform (
    1 0 0
    0 1 0
    0.2 0.3 1
  )
  PixmapTexture (
    ...
  )
)

Trim Curves

Description:
The Trim Loop subobject allows users to attach trimming loops to a NURB Patch. The Trim Loop object contains no data, and serves only as an encapsulation of various 2-dimensional curves used for trimming.

The Trim loop object contains a sequence of 2 dimensional curves which are concatenated together to form a loop. The subobjects are order-dependent. Each trim loop subobject should contain loops that are geometrically continuous, meaning the first trim curves end point ends at the next trim curves starting point.

In the metafile version 1.0, the only 2-dimensional curve allowed is a NURBCurve2D.

In future releases of the metafile, we expect to add additional types of 2d trim curves for trimming NURBS.

Data structure:

Text samples:

Container ( 
 NURBPatch ( 
  4 4 4 4 # u,v order, num M,N points
  -2 2 0 1   -1 2 0 1   1 2 0 1   2 2 0 1
  -2 2 0 1   -1 2 0 1   1 0 5 1   2 2 0 1
  -2 -2 0 1  -1 -2 0 1  1 -2 0 1  2 -2 0 1
  -2 -2 0 1  -1 -2 0 1  1 -2 0 1  2 -2 0 1
   0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1 # knots
 )
 Container (
  TrimLoop ( )
  NURBCurve2D (
    ...
  )
  NURBCurve2D (
    ...
  )
 )
)

Image Clear Color

Description:
This specifies the preferred rgb color with should be used to clear the drawing areas background.

Data structure:
ColorRGB clearColor

Text samples:

3DMetafile ( 1 0 Normal toc> )
Container (
  ViewHints ( )
  ImageClearColor ( 1 1 1 ) # white 
)
Box ( )

Image Dimensions

Description:
The image dimensions specifies the preferred image width and height in bits. It is a subobject of the view hints, which aids an application in determining how to display an image.

Data structure:
Uns32 width
Uns32 height

0 < width
0 < height

Text samples:

3DMetafile ( 1 0 Normal toc> )
Container (
  ViewHints ( )
  ImageDimensions ( 32 32 )
  ImageClearColor ( 1 1 1 )
)
Rotate ( X 0.75 )
Rotate ( Y 0.75 )
Container (
  AttributeSet ( )
  DiffuseColor ( 1 0 0 )
)
Box ( )

Image Mask

Description:
The image mask is a bitmap that specifies how an images rendered pixels should be clipped. The origin of the bitmap (the upper-left) is aligned with the origin (upper left) of the drawing area. Generally, the image mask and the image dimensions are used simultaneously to specify an image which is partially clipped.

The example to the right specifies a mask to clip a 32x32 image. The application using this data uses this clip mask to only render to a clipped portion of a custom document icon in this case, the bitmap will only draw inside of a document icon, providing a small preview in the Finder with a black document icon. The image mask to the right was used to render the example above.

Data structure:
Uns32 width
Uns32 height
Uns32 rowBytes
EndianEnum bitOrder
RawData image[rowBytes * height]

width, height in bits
0 < width
0 < height
((width >> 3) + ((width & 0x7) ? 1 : 0)) rowBytes
EndianEnum is:

Binary Text
0x00000000 BigEndian
0x00000001 LittleEndian

Text samples:

3DMetafile ( 1 0 Normal toc> )
Container (
  ViewHints ( )
  ImageDimensions ( 32 32 )
  ImageClearColor ( 1 1 1 )
  ImageMask (
    32 32 # width, height
    4 # rowBytes
    BigEndian # bitOrder
    0x000000000FFFF8000FFFF8000FFFF800
    0x0FFFF8000FFFF8000FFFF8000FFFFFE0
    0x0FFFFFE00FFFFFE00FFFFFE00FFFFFE0
    0x0FFFFFE00FFFFFE00FFFFFE00FFFFFE0
    0x0FFFFFE00FFFFFE00FFFFFE00FFFFFE0
    0x0FFFFFE00FFFFFE00FFFFFE00FFFFFE0
    0x0C61FFE00F24FFE00E64FFE00F24FFE0
    0x0F24FFE00C61FFE00FFFFFE000000000
  )
)
Rotate ( X 0.25 )
Rotate ( Y 0.23 )
Container (
  Torus ( 0 0.7 0 0 0 1 1 0 0 0 0 0 0.7 )
  Container (
    AttributeSet ( )
    DiffuseColor ( 0.2 0.9 0.9 )
  )
)

Ambient Coefficient

Description:
The ambient coefficient describes the intensity of the ambient light that is reflected by a surface.

Data structure:
Float32 ambientCoefficent

0 ambientCoefficient 1.0

Text samples:

Container (
  AttributeSet ( )
  AmbientCoefficient ( 0.7 )
)

Diffuse Color

Description:
The diffuse color indicates the amount of diffuse light reflected by a surface.

Data structure:
ColorRGB diffuseColor

Text samples:

Container (
  AttributeSet ( )
  DiffuseColor ( 1 0 0 ) # red
)

Highlight State

Description:
The highlight state attribute, when true, indicates that the current attribute state is overridden with the current highlight styles attribute set. The highlight state attribute allows various portions of a geometry object to be highlighted for user interface, etc. while retaining the integrity of a geometrys attribute set.

Data structure:
Boolean highlighted

Text samples:

Container (
  HighlightStyle ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 1 0 0 ) # RED
  )
)
...
Container (
  Polygon (
    3
    0 1 2
    0 0 0
    0 -1 2
  )
  Container (
    AttributeSet ( )
    DiffuseColor ( 0 1 2 )
    HighlightState ( True ) 
    # polygon is drawn RED
  )
)
 

Normal

Description:
If normal is not of unit length upon reading, it should be normalized. (npi)

The normal indicates the surface normal at a vertex.

Data structure:
Vector3D normal

|normal| = 1

Text samples:

Container (
  Polygon (
     5
     0.23423 0.56434 0.2312
     ...
  )
  Container (
    VertexAttributeSetList ( 5 Exclude 0 )
    Container ( 
      AttributeSet ( ) 
      Normal ( 0.8 -0.1 -0.1 )
    ) 
  )
)

Shading UV

Description:
The shading UV indicates an alternate UV to the Surface UV for shading purposes.

Shading UVs are generally used by shaders that affect appearance information, such as texture maps, which alter the color on a geometric surface.

Surface UVs are generally used for trimming.

Data structure:
Param2D shadingUV

Any UV parametrization is allowed, however, shading generally occurs with the following values.

0 shadingUV.u 1
0 shadingUV.v 1

Text samples:

Container (
  AttributeSet ( )
  ShadingUV ( 0 0 )
)

Specular Color

Description:
The specular color indicates the color of specular highlights on a surface.

Data structure:
ColorRGB specularColor

Text samples:

Container (
  AttributeSet ( )
  DiffuseColor ( 0.1 0.1 0.1 ) # near-black
  SpecularColor ( 1 1 1 ) # white
)
Sphere (
  0 0 0
  0 1 0
  1 0 0
  0 0 1
)

Specular Control

Description:
The specular control attribute indicates the power to which the specular component of lighting computations is raised.

Data structure:
Float32 specularControl

0 specularControl

Text samples:

Container (
  AttributeSet ( )
  DiffuseColor ( 0.5 0.5 0.5 ) # near-black
  SpecularColor ( 0.5 ) # white highlights
  SpecularControl ( 1 ) # larger highlight area
)
Sphere ( )

Surface Tangent

Description:
The surface tangent attribute indicates the direction of changing U and V on a surface.

Data structure:
Vector3D paramU
Vector3D paramV

Text samples:

Container (
  Mesh (
    ...
  )
  Container (
    VertexAttributeSetList (
      ...
    )
    Container (
      AttributeSet ( )
      SurfaceUV ( 0.1 0.293 )
      SurfaceTangent ( 
        1 0 0
        0 1 0
      ) 
    )
  )
)

Surface UV

Description:
The surface UV indicates an alternate UV to the shading UV for shading purposes.

Surface UVs are generally used for trim shaders.

Shading UVs are generally used by shaders that affect appearance information, such as texture maps, which alter the color on a geometric surface.

Data structure:
Param2D surfaceUV

Any UV parametrization is allowed, however, shading generally occurs with the following values.

0 surfaceUV 1
0 surfaceUV 1

Text samples:

Container (
  Mesh (
    ...
  )
  Container (
    VertexAttributeSetList (
      200 Include 4 10 21 22 11
    )
    Container (
      AttributeSet ( )
      SurfaceUV ( 0 0 )
    )
    Container (
      AttributeSet ( )
      SurfaceUV ( 0 1 )
    )
    Container (
      AttributeSet ( )
      SurfaceUV ( 1 1 )
    )
    Container (
      AttributeSet ( )
      SurfaceUV ( 1 0 )
    )
  )
)

Transparency Color

Description:
The transparency color indicates the degree of light allowed to pass though the various channels (r,g,b) of a surface.

A color of (1, 1, 1) indicates complete transparency (meaning 100% of the light behind an object is allowed to pass through), a color of (0, 0, 0) indicates complete opacity (meaning no light passes through an object.)

Data structure:
ColorRGB transparency

Text samples:

Container (
  Polygon (
    ...
  )
  Container (
    AttributeSet ( )
    TransparencyColor ( 1 0 0 )
  )
)

Generic Renderer

Description:
A renderer that doesnt do anything, but may be used to accumulate state or for picking.

Data structure:

Text samples:

Container (
  ViewHints ( )
  GenericRenderer ( )
  ViewAngleAspectCamera (
    ...
  )
  AmbientLight ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 0.2 0.2 0.2 )
  )
)

Interactive Renderer

Description:
The interactive renderer.

This will be renamed later when the corresponding product is named.

Data structure:

Text samples:

Container (
  ViewHints ( )
  InteractiveRenderer ( )
  ViewAngleAspectCamera (
    ...
  )
  AmbientLight ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 0.2 0.2 0.2 )
  )
)

Wire Frame Renderer

Description:
A wireframe renderer.

Data structure:

Text samples:

Container (
  ViewHints ( )
  Wireframe ( )
  ViewAngleAspectCamera (
    ...
  )
  AmbientLight ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 0.2 0.2 0.2 )
  )
)

Attribute Set

Description:
A attribute set groups sets of unique attributes together and is associated with a vertex, face, or an entire geometry. Any object that is an Element may be placed in an attribute set.

An attribute set also may be placed in a group. The various attributes in an attribute set are inherited to nodes lower than it in a hierarchy.

Data structure:

Text samples:

Container (
  Mesh (
    ...
  )
  Container (
    VertexAttributeSetList (
      30 Exclude 2
      29 30
    )
    ...
    Container (
      AttributeSet ( )
      DiffuseColor ( 0 1 0 )
      SurfaceUV ( 0.87 0.57 )
    )
    ...
  )
)

Orthographic Camera

Description:
The lens characteristics are set with the dimensions of a rectangular view port in the frame of the camera.

Data structure:
Float32 left
Float32 top
Float32 right
Float32 bottom

left < right
bottom < top

Text samples:

OrthographicCamera (
  -1 -1 1 1
)

Container (
  OrthographicCamera (
    -1 -1 1 1
  )
  CameraPlacement (
    0 0 20
    0 0 0
    1 0 0
  )
  CameraRange (
    1 25
  )
)

View Angle Aspect Camera

Description:
A perspective camera specified in terms of the minimum view angle and the aspect ratio of X to Y.

Data structure:
Float32 fieldOfView
Float32 aspectRatioXtoY

0 < fieldOfView
0 < aspectRatioXtoY

Text samples:

ViewAngleAspectCamera (
  1.7 1.0
)

Container (
  ViewAngleAspectCamera (
    1.7 1.0
  )
  CameraPlacement (
    0 0 20
    0 0 0
    1 0 0
  )
  CameraRange (
    1 25
  )
)

View Plane Camera

Description:
A view plane camera is a view angle aspect camera specified in terms of an arbitrary view plane. This is most useful when setting the camera to look at a particular object.

The viewPlane is set to distance from the camera to the object.

The halfWidth is set to half the width of the cross section of the object, and the halfHeight equal to the halfWidth divided by the aspect ratio of the viewPort.

This is the only perspective camera with specifications for off-axis viewing, which is desirable for scrolling.

Data structure:
Float32 viewPlane
Float32 halfWidthAtViewPlane
Float32 halfHeightAtViewPlane
Float32 centerXOnViewPlane
Float32 centerYOnViewPlane

0 < viewPlane
0 < halfWidthAtViewPlane
0 < halfHeightAtViewPlane
centerXOnViewPlane, centerYOnViewPlane may be any value

Text samples:

ViewPlaneCamera (
  ...
)

Container (
  ViewPlaneCamera (
    20
    15.0 15.0
    18 29
  )
  CameraPlacement (
    0 0 20
    0 0 0
    1 0 0
  )
  CameraRange (
    1 25
  )
)

Box

Description:
This is a rectangular parallelepiped

A size of zero indicates the default values, helpful in instantiating a unit-cube.

The Face Attribute Set List subobject assigns color to the following faces:

Face ^ orientation at origin + orientation
Face ^ orientation at origin
Face ^ majorAxis at origin + majorAxis
Face ^ majorAxis at origin
Face ^ minorAxis at origin + minorAxis
Face ^ minorAxis at origin

Basically, the faces perpendicular to the orientation direction are assigned first, then the majorAxis, then the minorAxis.

Data structure:
Vector3D orientation
Vector3D majorAxis
Vector3D minorAxis
Point3D origin

For 0-sized objects, default is:

1 0 0 # orientation
0 1 0 # majorAxis
0 0 1 # minorAxis
0 0 0 # origin

Text samples:

Box ( )

Box (
  2 0 0
  0 1 1 
  2 3 0
  0 0 0
)

Container (
  Box ( )
  Container (
    FaceAttributeSetList (
      6 Exclude 0
    )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 1 0 0 )
    )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 0 1 1 )
    )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 0 1 0 )
    )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 1 0 1 )
    )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 0 0 1 )
    )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 1 1 0 )
    )
  )
)

Cone

Description:
A cone may have a cap, and may have attributes assigned to the entire geometry, to the face cap, or to the bottom cap.

The default parametrization is shown in the diagram.

Data structure:
Vector3D orientation
Vector3D majorAxis
Vector3D minorAxis
Point3D origin

For 0-sized objects, default is:

1 0 0 # orientation
0 1 0 # majorAxis
0 0 1 # minorAxis
0 0 0 # origin

Text samples:

Cone ( )

Cone (
  2 0 0
  0 1 1 
  2 3 0
  0 0 0
)

Container (
  Cone ( )
  Caps ( Bottom )
  Container (
    BottomCapAttributeSet ( )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 1 0 0 )
    )
  )
  Container (
    FaceCapAttributeSet ( )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 1 1 0 )
    )
  )
)

Cylinder

Description:
A cylinder may have either top or bottom caps, and may have attributes assigned to the entire geometry, to the face cap, the bottom cap, or the top cap.

The default parametrization is shown in the diagram.

Data structure:
Vector3D orientation
Vector3D majorRadius
Vector3D minorRadius
Point3D origin

For 0-sized objects, default is:

1 0 0 # orientation
0 1 0 # majorAxis
0 0 1 # minorAxis
0 0 0 # origin

Text samples:

Cylinder ( )

Cylinder (
  2 0 0
  0 1 1 
  2 3 0
  0 0 0
)

Container (
  Cylinder ( )
  Caps ( Bottom | Top )
  Container (
    BottomCapAttributeSet ( )
    Container (
      AttributeSet ( )
      DiffuseColor ( 0 1 0 )
    )
  )
  Container (
    FaceCapAttributeSet ( )
    Container (
      AttributeSet ( )
      DiffuseColor ( 1 0 1 )
    )
  )
  Container (
    TopCapAttributeSet ( )
    Container (
      AttributeSet ( )
      DiffuseColor ( 1 1 0 )
    )
  )
)

Disk

Description:
This is an elliptical disk at the given origin with two vectors specifying the dimensions.

The default parametrization is shown in the diagram.

Data structure:
Vector3D majorRadius
Vector3D minorRadius
Point3D origin

For 0-sized objects, default is:

1 0 0 # majorRadius
0 1 0 # minorRadius
0 0 0 # origin

Text samples:

Disk ( )

Disk (
  2 0 0
  0 1 1 
  0 0 0
)

Container (
  Cylinder ( )
  Caps ( Bottom | Top )
  Container (
    BottomCapAttributeSet ( )
    Container (
      AttributeSet ( )
      DiffuseColor ( 1 0 1 )
    )
  )
  Container (
    FaceCapAttributeSet ( )
    Container (
      AttributeSet ( )
      DiffuseColor ( 1 1 0 )
    )
  )
  Container (
    AttributeSet ( )
    DiffuseColor ( 1 1 0 )
  )
)

Ellipse

Description:
This is an ellipse at the given origin with two vectors specifying its dimensions.

There is no default parametrization for an ellipse.

Data structure:
Vector3D majorAxis
Vector3D minorAxis
Point3D origin

For 0-sized objects, default is:

1 0 0 # majorAxis
0 1 0 # minorAxis
0 0 0 # origin

Text samples:

Ellipse ( )

Ellipse (
  2 0 0
  0 1 1 
  0 0 0
)

Container (
  Ellipse ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 1 1 0 )
  )
)

Ellipsoid

Description:
An ellipsoid may have an attribute set attached to it.

The default parametrization is shown in the diagram. V is zero to the left of majorRadius, and is 1 to the right. U is zero at the orientation vector, and 0 at the bottom.

Data structure:
Vector3D orientation
Vector3D majorRadius
Vector3D minorRadius
Point3D origin

For 0-sized objects, default is:

1 0 0 # orientation
0 1 0 # majorRadius
0 0 1 # minorRadius
0 0 0 # origin

Text samples:

Sphere ( )

Sphere (
  2 0 0
  0 1 1 
  2 3 0
  0 0 0
)

Container (
  Sphere ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 1 1 0 )
  )
)

General Polygon

Description:
A general polygon is a polygon that may be convex or may contain holes. A general polygon also assumes that all faces are planar within floating point tolerances.

Holes are indicated by specifying a contour of the generalPolygon in clockwise order.

Polygons that cross use the even-odd rule to specify holes (see diagram).

You may specify the complexity of a GeneralPolygon by adding a viewHints object.

Data structure:
Uns32 nContours
PolygonData polygons[nContours]

where PolygonData is:

Uns32 nVertices
Point3D vertices[nVertices]

0 < nContours
2 < nVertices

Text samples:

Container ( 
 GeneralPolygon ( 
  2 # nContours
  3 # nVertices 
  -1 0 0
  1 0 0
  0 1.7 0
  3 # nVertices
  -1 0.4 0
  1 0.4 0
  0 2.1 0 
 )
 Container ( 
  VertexAttributeSetList ( 6 Exclude 2 0 4 )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 0 0 1 )
  )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 0 1 1 )
  )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 1 0 1 )
  )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 1 1 0 )
  )
 )
 Container ( 
  AttributeSet ( )
  DiffuseColor ( 1 1 1 )
 )
)

Line

Description:
Our basic line primitive is a line segment, a simple line drawn between two vertices.

Optional vertex attributes may be attached using a VertexAttributeSetList.

A set of attributes may be applied to the entire line segment by attaching an attribute set.

Data structure:
Point3D start
Point3D end

Text samples:

Line ( 0 0 0 1 0 0 )

Container (
  Line (
    0 0 0
    1 0 0
  )
  Container (
    VertexAttributeSetList ( 2 Exclude 0 )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 1 0 0 )
    )
    Container ( 
      AttributeSet ( )
      DiffuseColor ( 0 0 1 )
    )
  )
)

Marker

Description:
The marker is used to rasterize bitmaps parallel to the viewing plane. They are used for annotation of an image.

Data structure:
Point3D location
Int32 xOffset
Int32 yOffset
Uns32 width
Uns32 height
Uns32 rowBytes
EndianEnum bitEndian
RawData data[height * rowBytes]

0 < width
0 < height
(((width / 8) + ((width & 7) > 0)) rowBytes
EndianEnum is:

Binary Text
0x00000000 BigEndian
0x00000001 LittleEndian

Text samples:

 Container ( 
  Marker ( 
   0.5 0.5 0.5 # origin
   -28 # xOffset
   -3 # yOffset
   56 # width
   6 # height
   7 # rowBytes
   BigEndian # bitOrder
   0x7E3C3C667E7C18606066666066187C3C
   0x607E7C661860066066607C1860066666
   0x6066007E3C3C667E6618
  )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 0.8 0.2 0.6 )
  )
 )

Mesh

Description:
The mesh is used for representing complex topological objects. It contains enough information to determine which polygonal faces are adjacent to each other without numerical ambiguity. This metafile object contains topological as well as geometrical information.

A contour (hole) in a face is indicated by supplying a negative number for the number of vertices, and adds a hole to the previous face that was not a contour.

The size of nFaceVertexIndices and faceVertexIndices is based on the value of nVertices.

We introduce a special subobject used only with the mesh, called MeshCorners. This object allows multiple attribute sets to be attached to a single vertex, where each attribute set is bound to a set of vertex-face pairs. It can be used to place a sharp edge in the mesh (if the attribute set contains a normal, for instance).

Data structure:
Uns32 nVertices
Point3D vertices[nVertices]
Uns32 nFaces
Uns32 nContours
MeshFace faces[nFaces + nContours]

where MeshFace is:

Int32 nFaceVertexIndices
Uns32 faceVertexIndices[nFaceVertexIndices]

3 nVertices
3 nFaceVertexIndices

Text samples:

 Mesh ( 
  10 # nVertices
  -1 1 1  
  -1 1 -1  
  1 1 -1
  1 -1 -1  
  1 -1 1  
  0 -1 1  
  -1 -1 0  
  -1 -1 -1  
  1 1 1  
  -1 0 1 
  7 # nFaces
  0 # nContours
  3 6 5 9  
  5 7 6 9 0 1  
  4 2 3 7 1  
  4 2 8 4 3  
  4 1 0 8 2  
  5 4 8 0 9 5  
  5 3 4 5 6 7  
 )

NURB Curve

Description:
NURB curves are Non-Uniform Rational B-spline curves. A rational B-spline curve is a curve in 4D space, which has been projected down to 3D space. Thus, the control points for a 3D rational curve have four components - x, y, z, and w (usually known as the weight). For such a point, the corresponding point in 3D space is (x/w, y/w, z/w)

Weights (w) are always positive.

Data structure:
Uns32 order
Uns32 nPoints
RationalPoint4D points[nPoints]
Float32 knots[order + nPoints]

2 order
2 nPoints
0 < points[...].w (weights of points)

Text samples:

 NURBCurve ( 
  4 7 # order, nPoints
  0 0 0 1 # points
  1 1 0 1
  2 0 0 1
  3 1 0 1
  4 0 0 1
  5 1 0 1
  6 0 0 1
  0 0 0 0 0.25 0.5 0.75 1 1 1 1 # knots
 )

NURB Patch

Description:
Non-Uniform Rational B-Spline (NURB) Patches are closed under projective transformations, can represent quadrics exactly, and can be refined locally to allow additional detail.

The default parametrization is given by the knot vectors.

Weights (w) are always positive.

Data structure:
Uns32 uOrder
Uns32 vOrder
Uns32 numColumns
Uns32 numRows
RationalPoint4D points[numMPoints*numNPoints]
Float32 uKnots[uOrder + numColumns]
Float32 vKnots[vOrder + numRows]

2 numColumns
2 numRows
2 uOrder
2 vOrder
0 < points[...].w (weights of points)

Text samples:

 NURBPatch ( 
  4 4 4 4 # u,v order, num M,N points
  -2 2 0 1   -1 2 0 1   1 2 0 1   2 2 0 1
  -2 2 0 1   -1 2 0 1   1 0 5 1   2 2 0 1
  -2 -2 0 1  -1 -2 0 1  1 -2 0 1  2 -2 0 1
  -2 -2 0 1  -1 -2 0 1  1 -2 0 1  2 -2 0 1
   0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1 # knots
 )

Point

Description:
The basic point primitive is an infinitesimally small point in space. It is specified as a 3D point plus an optional attribute set.

A 3D point has no default parametrization.

Data structure:
Point3D point

Text samples:

Point ( 0 1 2 )

Polygon

Description:
The polygon is convex with no holes. To describe concave polygons or polygons with holes, use the general polygon primitive.

The points that make up a polygons face are assumed to be planar within floating point tolerances.

Data structure:
Uns32 nVertices
Point3D vertices[nVertices]

2 nVertices

Text samples:

Polygon (
  4
  0 1 1 
  0 -1 1
  0 -1 -1
  0 1 -1
)

Poly Line

Description:
An extension of the basic line primitive is a polyline, where simple lines are drawn between adjacent points in a point list

A polyline is NOT closed, and the last point is never connected to the first point.

A polyline has no default parametrization.

Data structure:
Uns32 nVertices
Point3D vertices[nVertices]

2 nVertices

Text samples:

Container ( 
  PolyLine ( 
    4
    -1 -0.5 -0.25
    -0.5 1.5 0.45
    0 0 0
    1.5 1.5 1 
  )
  Container ( 
    AttributeSet ( )
    DiffuseColor ( 0.4 0.2 0.9 )
  )
)

Torus

Description:
The orientation length specifies the radius of the circular along the orientation vector of the torus cross-section.

The major and minor axes are vectors to the center of the torus cross-section (as in the diagram).

The ratio is the change in the orientation length in the axial direction. A ratio of 2, for example, creates a fatter torus cross-section along the major and minor axes, a ratio of 0.5 creates a fatter cross-section along the orientation.

As far as anyone knows, the torus is useful for drawing donuts and bagels, and makes a great demo.

The default parametrization is shown in the diagram.

Data structure:
Vector3D orientation
Vector3D majorAxis
Vector3D minorAxis
Point3D origin
Float32 ratio


For 0-sized objects, default is:

1 0 0 # orientation
0 1 0 # majorAxis
0 0 1 # minorAxis
0 0 0 # origin
1 # ratio

Text samples:

Torus ( )

Torus (
  2 0 0
  0 1 1 
  2 3 0
  0 0 0
  1
)

Container (
  Torus ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 1 1 0 )
  )
)

Triangle

Description:
The most basic polygon is a triangle, which contains 3 points.

A VertexAttributeSetList may be used to attach attribute sets to the vertices (containing three vertex attribute sets) or an optional AttributeSet may be added to attach to the face.

There is no default parametrization for a triangle.

Data structure:
Point3D vertices[3]

Text samples:

Container (
 Triangle ( 
  -1 -0.5 -0.25
  0 0 0
  -0.5 1.5 0.45 
 )
 Container ( 
  VertexAttributeSetList ( 3 Exclude 0 )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 1 0 0 )
  )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 0 1 0 )
  )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 0 0 1 )
  )
 )
 Container ( 
  AttributeSet ( )
  DiffuseColor ( 0.8 0.5 0.2 )
 )
)

Tri Grid

Description:
Points specified are given in row major order.

You may add a FaceAttributeSetList to attach a set of attributes for each of the triangles generated by this primitive.

You may also add a VertexAttributeSetList to attach attributes to each vertex.

Data structure:
Uns32 nColumns
Uns32 nRows
Point3D points[numMVertices * numNVertices]

2 nColumns
2 nRows

Text samples:

Container ( 
 TriGrid ( 
  3 4 # nUVertices nVVertices
  -1 1 1      -0.5 1 0  0 1 0
   0.7 1 0.5  -1 0 0    -0.5 0 0.3
   0 0.2 0    0.5 0 0   -1 -1 0
   -0.5 -1 0  0 -1 0.1  0.2 -1.3 0.2 
 )
 Container ( 
  FaceAttributeSetList ( 12 Include 1 5 )
  Container ( 
   AttributeSet ( )
   DiffuseColor ( 1 0 0.5 )
  )
 )
 Container ( 
  AttributeSet ( )
  DiffuseColor ( 0.8 0.7 0.3 )
 )
)

Group

Description:
The group is useful for grouping any type of shared objects together.

It is delimited by an end group object.

Data structure:

Text samples:

BeginGroup ( Group ( ) )
  CString ( This is the first day of the rest of your life. )
  Torus ( )
EndGroup ( )

Display Group

Description:
A display group contains only objects that are drawable.

A display group adds the ability to be traversed for various operations via the DisplayGroupState subobject.

It is delimited by an end group object.

Data structure:

Text samples:

IO Proxy Display Group

Description:
The IO proxy display group contains drawable objects that are similar representations of the same object in different formats. For example, if it is known that a particular application does not understand NURBPatchs, the writing application may write the NURBPatch in an IO proxy group along with a mesh which is the tesselated NURBPatch.

The objects in a IO proxy display group appear in their preferencial order. The first object is the most preferred representation, the last object the least. The first object that is understood by a reading application should be used.

You may specify a group of objects inside a IOProxyDisplayGroup, as a group (up to its EndGroup) delimiter is a single object.

It is understood that ONLY the first understood object in an IO proxy display group is traversed while drawing, bounding, or picking.

In other words, if an IO proxy display group contains many objects, only one of them will be drawn when it comes time to render an image, etc.

Data structure:

Text samples:

BeginGroup ( IOProxyDisplayGroup ( ) )
  Mesh (
    8
    0 0 0
    0 0 1
    0 1 0
    1 0 0
    1 1 0
    0 1 1
    1 0 1
    1 1 1
    ... etc.
  )
  Box ( )
EndGroup ( )

BeginGroup ( IOProxyDisplayGroup ( ) )
  NURBPatch (       # preferred object
    ...
  ) 
  DisplayGroup ( )  # 2nd choice object 
    Translate ( 1 2 3 )
    Box ( )
  EndGroup ( )
EndGroup ( )

Ordered Display Group

Description:
The ordered display group is simply a display group except that objects are sorted by type. Objects always appear in an ordered group in the following order:

Transforms
Styles
AttributeSets
Shaders
Geometries
DisplayGroups

It is delimited by an end group object.

Data structure:

Text samples:

Info Group

Description:
An info group contains nothing but String objects. It is used to add human-readable information pertaining to a files origin or history. A use that comes to mind is copyright notices.

The info group object should be preserved by a reading application, and appended with additional information if a file is re-written.

It is delimited by an end group object.

Data structure:

Text samples:

BeginGroup ( InfoGroup ( ) )
  CString (
    Copyright  1995 Apple Computer, Inc. )
  CString (
    Author: Bonanza Jellybean )
EndGroup ( )

Light Group

Description:
A light group contains nothing but lights.

It is delimited by an end group object.

Data structure:

Text samples:

BeginGroup ( LightGroup ( ) )
  AmbientLight ( )
  DirectionalLight ( 1 0 0 False )
EndGroup ( )

Ambient Light

Description:
An ambient light supplies light that comes from secondary reflections.

In lieu of other light sources, the ambient light illuminates the scene with a flat, uniform light.

Data structure:

Text samples:

AmbientLight ( )

Container (
  AmbientLight ( )
  LightData (
    EcTrue # isOn
    1.0 # intensity
    1 0 0 # red color
  )
)

Directional Light

Description:
A directional light is far enough away from the scene that we may treat it as though it were infinitely far away. This produces shading results faster than any other type of light (except ambient).

It is specified with a vector pointing in the same direction as the light rays, an attenuation and a boolean value indicating whether this light casts shadows or not.

Data structure:
Vector3D direction
Boolean castsShadows

|direction| = 1.0

Text samples:

DirectionalLight ( 1 0 0 True )

Container (
  DirectionalLight ( 1 0 0 True )
  LightData (
    True
    0.4
    1 0 0
  )
)

Point Light

Description:
A point light is a light at an infinitesimally small point in space. It may be attenuated or it may cast shadows.

Data structure:
Point3D location
Attenuation attenuation
Boolean castsShadows

where Attenuation is the structure:

Float32 c0
Float32 c1
Float32 c2

attenuation is computed, using d as the distance from location:

1
c0 + c1*d + c2 * d^2

0 < c0
0 < c1
0 < c2

attenuation is not clamped to [0,1] to allow for lighting washout (such as in a nuclear explosion)

Text samples:

PointLight (
  12 23 2
  0 0 1 # InverseDistanceSquared
  True
)

Container (
  PointLight (
    12 23 2
    0 0 1 # InverseDistanceSquared
    True
  )
  LightData (
    True
    0.4
    1 0 0
  )
)

Spot Light

Description:
A spot light radiates with a circular cone of light that tapers toward the edge of the cone.

The hotSpotAngle is the angle (in radians) from the axis of the spot light for which the spot light has maximum, constant intensity. The outer angle is the angle for which the light falls to zero. Between these two, the light intensity tapers to zero according to the FallOff enumerated type.

Data structure:
Point3D location
Vector3D orientation
Boolean castsShadows
Attenuation attenuation
Float32 hotAngle
Float32 outerAngle
FallOffEnum fallOff

|orientation| = 1

Attenuation is described in the Point Light

0 < hotAngle outerAngle

FallOffEnum is:

Binary Text
0x00000000 None
0x00000001 Linear
0x00000002 Exponential
0x00000003 Cosine

Text samples:

SpotLight (
  12 0 0
  0 1 0
  True
  0 0 1 # InverseDistanceSquared
  0.7 # hotAngle
  0.8 # outerAngle
  Cosine
)

Container (
  SpotLight (
    12 0 0
    0 1 0
    True
    0 0 1 # InverseDistanceSquared
    0.7 # hotAngle
    0.8 # outerAngle
   Cosine
  ) 
  LightData (
    True
    0.4
    1 0 1
  )
)

Lambert Illumination

Description:
The lambertian illumination model.

Data structure:

Text samples:

LambertIllumination ( )

Phong Illumination

Description:
The phong illumination model.

Data structure:

Text samples:

PhongIllumination ( )

Texture Shader

Description:
The texture shader is used to perform shading using a texture (in this case, a PixmapTexture).

Data structure:

Text samples:

Container (
  TextureShader ( )
  PixmapTexture (
    ...
  )
)

Backfacing Style

Description:
The backfacing style tells a renderer how to clip backfacing polygons while rendering.

Data structure:
BackfacingEnum backfacing

where BackfacingEnum is:

Text Binary
0x00000000 Both
0x00000001 Culled
0x00000002 Flipped

Text samples:

BackfacingStyle ( Culled )

Fill Style

Description:
The fill style tells a renderer what parts of a polygon to draw.

Data structure:
FillStyleEnum fillStyle

where FillStyleEnum is:

Text Binary
0x00000000 Filled
0x00000001 Edges
0x00000002 Points
0x00000003 Empty

Text samples:

FillStyle ( Edges )

Highlight Style

Description:
The highlight style sets the binding for highlighting features of a geometry via the HighlightState attribute. The attribute set subobject sets the highlight attribute set.

Data structure:

Text samples:

Container (
  HighlightStyle ( )
  Container (
    AttributeSet ( )
    DiffuseColor ( 0 0 1 )
  )
)

Interpolation Style

Description:
The interpolation style tells a renderer how to interpolate shading values on a polygon.

Data structure:
InterpolationStyleEnum interpolationStyle

where InterpolationStyleEnum is:

Binary Text
0x00000000 None
0x00000001 Vertex
0x00000002 Pixel

Text samples:

InterpolationStyle ( Vertex )

Orientation Style

Description:
The Orientation style is used to change the orientation of polygons.

Data structure:
OrientationEnum orientation

where OrientationEnum is:

Binary Text
0x00000000 CounterClockwise
0x00000001 Clockwise

Text samples:

OrientationStyle ( Clockwise )

Pick ID Style

Description:
The pick ID style is used to allow the user to insert ids within a hierarchy to aid in picking a hierarchy.

Data structure:
Uns32 id

Text samples:

PickIDStyle ( 23 )

Pick Parts Style

Description:
The pick parts style determines the level of granularity for picking.

Data structure:
PickPartsFlags pickParts

where PickPartsFlags is:

Text Binary
0x00000000 Object
0x00000001 Face
0x00000002 Edge
0x00000004 Vertex

default is:
Object

Text samples:

PickPartsStyle ( Object | Vertex )

Receive Shadows Style

Description:
The receive shadows style determines whether a geometry receives shadows when rendering. It is coupled with the casts shadows field in all lights, excluding the ambient light.

Data structure:
Boolean receiveShadows

Text samples:

ReceiveShadowsStyle ( True )

Subdivision Style

Description:
The subdivision style tells a geometric decomposition the courseness of a geometric primitive tesselation. There are three methods of subdivision: constant, world space, and screen space subdivision.

Constant subdivision supplies 2 integral values, which indicate the number of sections the u and v axes of a decomposition should be divided into.

The Screen Space value indicates average size of a single polygon in a tesselation in screen space.

The world space value indicates the average size of a single polygon in a tesselation in world space.

Data structure:
This object has two forms, based on the subdivison method field:

for subdivisionMethod == WorldSpace or ScreenSpace the structure is:

SubdivisionMethodEnum subdivisionMethod
Float32 value1

for subdivisionMethod == Constant, the values are integral:

SubdivisionMethodEnum subdivisionMethod
Uns32 value1
Uns32 value2

where SubdivisionMethodEnum is:

Binary Text
0x00000000 Constant
0x00000001 WorldSpace
0x00000002 ScreenSpace

Text samples:

SubdivisionStyle (
   Constant 12 12
)

SubdivisionStyle (
   WorldSpace 50
)

SubdivisionStyle (
   ScreenSpace 50
)

Matrix Transform

Description:
A custom, invertible matrix transform.

Data structure:
Matrix4x4 matrix

matrix is invertible

Text samples:

Quaternion Transform

Description:
The quaternion specifies three axes of rotation and a twist value.

Useful for user interface.

Data structure:
Float32 w
Float32 x
Float32 y
Float32 z

Text samples:

Quaternion ( 0.2 0.7 0.2 1.57 )

Rotate Transform

Description:
Rotate about the X, Y, or Z axes.

Data structure:
AxisEnum axis
Float32 radians

AxisEnum is:

Binary Text
0x00000000 X
0x00000001 Y
0x00000002 Z

Text samples:

Rotate ( X 1.57 )

Rotate About Axis Transform

Description:
Rotate about an arbitrary axis in space.

Data structure:
Point3D origin
Vector3D orientation
Float32 radians

|orientation| = 1

Text samples:

RotateAboutAxis (
  20 0 0 # origin
  0  1 0 # orientation
  1.57 # radians
)

Rotate About Point Transform

Description:
To rotate about the X, Y, or Z axes at an arbitrary point in space.

Data structure:
AxisEnum axis
Float32 radians
Point3D origin

AxisEnum is:

Binary Text
0x00000000 X
0x00000001 Y
0x00000002 Z

Text samples:

Scale Transform

Description:
A scale transform.

Data structure:
Vector3D scale

scale.x 0.0
scale.y 0.0
scale.z 0.0

Text samples:

Scale ( 1 1 2 )

Translate Transform

Description:
A translate transfrom.

Data structure:
Vector3D translate

Text samples:

Translate ( 1 2 100 )

Unknown Binary

Description:
The unknown binary object is a way of transporting unknown data found in a binary file. It is an encapsulated replica of the original data found in a binary metafile, containing the object type (an Int32), the object size (in bytes), the byte order of the original file, and the data itself. The byte order is needed if unknown data is transported across different processors, and allows for parsing endian-specific primitives within the raw data block.

Unknown binary objects may be written in either the text or binary files.

When an unknown binary object is encountered in a metafile, it is up to the reading program to either:
transport the data around
validate it and convert it to a known object
discard the data

Unknown objects are inherently dirty, meaning you may assume the unknown binary object may contain out-of-sync (bogus) information, as the original object may have been removed from its original context.

Data structure:
Int32 objectType
Uns32 objectSize
EndianEnum byteOrder
RawData objectData[objectSize]

Text samples:

UnknownBinary (
  1701605476
  4
  BigEndian
  0x0AB2
)

Unknown Text

Description:
The unknown text object is a way of transporting unknown data found in a text file. It is an encapsulated replica of the original data found in a text metafile, containing the object type (a String), and a text string containing the original data. In some cases, white space and comments may have been stripped from the contents field.

Unknown text objects may be written in either the text or binary files.

When an unknown text object is encountered in a metafile, it is up to the reading program to either:
transport the data around
validate it and convert it to a known object
discard the data

Unknown objects are inherently dirty, meaning you may assume the unknown text object may contain out-of-sync (bogus) information, as the original object may have been removed from its original context.

Data structure:
String asciiName
String contents

Text samples:

UnknownText (
  Ellipsoid
  
)

Macintosh Path

Description:
The Macintosh path specifies the pathname of an external file reference using the pathname specification found in the Inside Macintosh volumes. (essentially, a colon-based separator)

Data structure:
String pathName

Text samples:

Container (
  Reference ( 43 )
  MacintoshPath ( :::Foo:Bar:Models:Cheryl )
)

Unix Path

Description:
The unix path object serves as a way to reference files on a unix file system.

The path should obey naming standards for unix operating systems.

Data structure:
String unixPath

Text samples:

Container (
  Reference ( 23 )
  UnixPath ( ./shaders.eb )
)

C String

Description:
The CString is a way of embedding text in a metafile.

Other string types allow for internationalization.

The only allowable characters in a CString are 7-bit ASCII numbers.

The following characters may be escaped with the \ character:

'\a', '\b', '\f', '\n', '\r', '\t', '\v', '\', '\\'

Data structure:
String cString

Text samples:

CString (
  Copyright (c) 1994 Apple Computer, Inc.
)

Unicode

Description:
The unicode object is another way of embedding text in a metafile.

See UNICODE reference for details.

Data structure:
Uns32 length
RawData unicode[length * 2]

Text samples:

Unicode (
  6
  0x457363686572
)

Pixmap Texture

Description:
A generic means of transferring pixmap data. Used in the Texture Shader.

Data structure:
Uns32 width
Uns32 height
Uns32 rowBytes
Uns32 pixelSize
PixelTypeEnum pixelType
EndianEnum bitOrder
EndianEnum byteOrder
RawData image[rowBytes * height]

0 < width
0 < height
0 < pixelSize < 32
width * pixelSize rowBytes
PixelTypeEnum is:

Binary Text
0x00000000 RGB8
0x00000001 RGB16
0x00000002 RGB24
0x00000003 RGB32

EndianEnum is:

Binary Text
0x00000000 BigEndian
0x00000001 LittleEndian

Text samples:

PixmapTexture (
   256 256 # width/height
   128 # rowBytes
   32 # pixelSize
   RGB24
   BigEndian BigEndian
   0x00123232...
   0x...
)

View Hints

Description:
The subobjects of the view hints object specifies the preferences supplied by a writing application when rendering a scene.

The semantic to be followed when a view hints object is encountered in the metafile is that the view hints is specified previous to a list of objects to be rendered to that particular view hints preference. The subobjects of the view hints object are inherited from the previous view hints in a metafile.

For example, if a modelling application contains 10 camera locations for viewing various portions of a scene, it would first store the default view as the first object in a metafile, then the group representing the scene, then a view containing the second camera position, then a reference to the scene, etc.

Data structure:

Text samples:

3DMetafile ( 1 0 Normal toc> )
Container (
  ViewHints ( )
  Container (
    ViewAngleAspect ( 0.73 1.0 )
    CameraPlacement (
      0 0 30
      0 0 0
      0 1 0
    )
  )
  DirectionalLight ( -0.7 -0.7 -0.65 )
  Container (
    AttributeSet ( )
    DiffuseColor ( 0.2 0.2 0.2 )
    SpecularControl ( 3 )
  )
  ImageDimensions ( 200 200 )
)
ref1:
BeginGroup ( DisplayGroup ( ) )
...
EndGroup ( )
Container (
  ViewHints ( )
  Container (
    ViewAngleAspect ( 0.73 1.0 )
    CameraPlacement (
      0 10 0
      0 0 0
      0 1 0
    )
  )
)
Reference ( 1 )