Primitive Lists

Primitive lists provide tessellated surface geometry in the form of triangles or quads which is close to the internal data layout in mental ray. The vertices of faces may be shared to form a mesh. Extra custom data can be attached per face.

There are two versions for the syntax of primitive lists, ascii or binary.

The ascii version syntax is as follows:

    trilist
        vertex nlines lineformat
        triangle ntriangles nborder
        [ vertex lines ]
        [ vertex reference indices ]
        [[ vertex reference indices for border triangles ]]
    end trilist

The vertex statement provides:

nlines

as the number of vertex lines.

lineformat

as a sequence of codes to describe the content and format of a vertex line in the following block. The supported codes are:

p: position, always present
n: normal
d: derivatives (two 3d vectors as x y z, respectively)
d2: second derivs (three 3d vectors as x y z, respectively)
b [ count ]: bump basis vectors (two 3d vectors as x y z, respectively),
with optional number of multiple sets of vectors
m [ count ]: motion vector (one 3d vector as x y z, respectively),
with optional number of multiple motion vectors
t dim [ dim ... ]: texture scalars, with dimension dim for each of multiple spaces
u dim [ dim ... ]: user scalars, with dimension dim for each of multiple spaces

If count is not given a value of 1 is assumed.

The vertex lines contains a list of entries each defining a vertex completely. The scalars need to be given in the format specified by lineformat. Here is an example:

    vertex 184 p n t 2 3

The following example will define a line in this format:

    [ 0.1 0.2 0.3   0 0 1   0.2 0.3     0.1 0.2 0.3]
    # position      normal  2d texture  3d texture

The triangle statement provides:

ntriangles: is the number of triangles.
nborder: optional number of border triangles.
vertex reference indices: For each triangle there are three integers, referencing the corresponding vertex lines. In tagged mode, there are four integers, the first specifying the material index.
vertex reference indices for border triangles: triangles in the border section define 1-rings of triangles at border faces of the regular region triangles. This is used to specify displacement-mapped multi-object placeholder input.

Here is a complete example for a primitive list:

    trilist
        vertex 4 p n t 2
        triangle 2
        # pos   normal  tex1 (2-dimensional)
        [
        0 0 0   0 0 1   0. 0.     # <-- line 0
        1 0 0   0 0 1   1. 0.     #
        1 1 0   0 0 1   1. 1.     #
        0 1 0   0 0 1   0. 1.     # <-- line 3
        ]
        # 2 triangles (non-tagged)
        [
        0 1 2
        2 3 0
        ]
    end trilist

The binary version of syntax for primitive lists is as follows:

    trilist
        vertex nlines lineformat
        triangle ntriangles nborder
        scalar  ` 32-bit float data: vertex lines `
        integer ` 32-bit integer data: triangle indices `
        integer ` 32-bit integer data: triangle material tags `
        # optional: border section
        integer ` 32-bit integer data: triangle indices `
        integer ` 32-bit integer data: triangle material tags `
    end trilist

Each material in the list corresponds to exactly one triangle. For non-tagged objects the triangle section is specified similar to the ascii version.

The 32-bit data is defined as a stream of network byte-order 32-bit words, interpreted either as scalars or integers.