Objects

Element type: miSCENE_OBJECT
Data type: miObject
Sizes: -
Defaults: as described below
enum miObject_type {
        miOBJECT_POLYGONS,
        miOBJECT_FACES,
        miOBJECT_BOXES,
        miOBJECT_SPACECURVES,
        miOBJECT_SUBDIVSURFS,
        miOBJECT_ALGEBRAICS,                    /* for future use */
        miOBJECT_PLACEHOLDER,                   /* read geometry on demand */
        miOBJECT_HAIR
};

typedef struct miObject {
        int                     spare_0[3];     /* not used */
        miUint                  volume_id;      /* autovolume identification */
        miTag                   finalgather_file; /* fgmap file name, if any */
        enum miObject_type      type;           /* which in union to use     */
        miUint1                 visible;        /* object visible?           */
        miUint1                 shadow;         /* cast a shadow?            */
        miUint1                 reflection;     /* bit0=cast, bit1=receive   */
        miUint1                 refraction;     /* bit0=cast, bit1=receive   */
        miUint1                 transparency;   /* bit0=cast, bit1=receive   */
        miUint1                 caustic;        /* bit0=cast, bit1=receive   */
        miUint1                 globillum;      /* bit0=cast, bit1=receive   */
        miUint1                 finalgather;    /* bit0=cast, bit1=receive   */
        miUint1                 select;         /* selectable when picking?  */
        char                    face;           /* a=all, f=front, b=back    */
        miUint1                 spare_1[5];     /* not used                  */
        miCBoolean              fine;           /* API: has "fine" miApprox  */
        miBoolean               view_dependent; /* miOBJECT_FACES only       */
        miBoolean               mtl_is_label;   /* poly/surf mtls are labels */
        miScalar                maxdisplace;    /* max return of displ shader*/
        miBoolean               hardware;       /* use hardware shading      */
        miTag                   userdata;       /* optional user data blocks */
        miUint                  label;          /* optional label            */
        miVector                bbox_min;       /* bounding box: low corner  */
        miVector                bbox_max;       /* bounding box: high corner */
        miVector                bbox_min_m;     /* bbox shift at T==1.0 (low)*/
        miVector                bbox_max_m;     /* bbox shift at T==1.0 (hi) */
        miTag                   functions;      /* SCENE: material req list  */
        unsigned int            n_functions;    /* SCENE: # tags in functions*/
        miCBoolean              mbox_explicit;  /* motion box given by user  */
        miSint1                 min_samples;    /* per-object oversampling,  */
        miSint1                 max_samples;    /* defaults -128 and 127     */
        miUchar                 spare_3[4];     /* not used                  */
        miUint1                 shadowmap;      /* casts shadowmap shadows?  */
        miScalar                ray_offset;     /* ray offset for the object */
        miTag                   approx_list;    /* list of miApproximations  */
        union {
            miPolygon_list      polygon_list;
            miFace_list         face_list;
            miTag               box_list;
            miSpacecurve_list   spacecurve_list;
            miSubdivsurf_list   subdivsurf_list;
            miPlaceholder_list  placeholder_list;
            miHair_list         hair_list;
        }                       geo;            /* geometry                  */
} miObject;

typedef struct miPolygon_list {
        miGeoIndex              no_polygons;
        miGeoIndex              no_indices;
        miGeoIndex              no_vertices;
        miGeoVector_list        vect_info;      /* contents of vector array */
        miVertex_content        vert_info;      /* vertex size & content */
        miTag                   polygons;       /* array of miPolygon */
        miTag                   indices;        /* array of miGeoIndex */
        miTag                   vertices;       /* see vert_info */
        miTag                   vectors;        /* array of miGeoVector */
        miApprox                approx;         /* poly approx technique */
} miPolygon_list;

typedef struct miFace_list {
        miGeoIndex      no_faces;
        miGeoIndex      no_surfaces;
        miGeoIndex      no_curves;
        miGeoIndex      no_specpnts;
        miGeoIndex      no_surf_scalars;
        miGeoIndex      no_curve_scalars;
        miTag           faces;                  /* array of miFace */
        miTag           surfaces;               /* array of miSurface */
        miTag           curves;                 /* array of miCurve */
        miTag           specpnts;               /* array of miCurve_point */
        miTag           surf_scalars;           /* array of miGeoScalar */
        miTag           curve_scalars;          /* array of miGeoScalar */
        miTag           basis_list;             /* miBasis_list */
} miFace_list;

typedef struct miSpacecurve_list {
        miGeoIndex      no_spacecurves;
        miGeoIndex      no_curves;
        miGeoIndex      no_specpnts;
        miGeoIndex      no_curve_scalars;
        miTag           spacecurves;            /* array of miSpacecurve */
        miTag           curves;                 /* array of miCurve */
        miTag           specpnts;               /* array of miCurve_point */
        miTag           curve_scalars;          /* array of miGeoScalar */
        miTag           basis_list;             /* miBasis_list */
        miBoolean       pad;                    /* not used */
} miSpacecurve_list;

typedef struct miSubdivsurf_list {
        miGeoIndex      no_subdivsurfs;
        miTag           subdivsurfs;
} miSubdivsurf_list;

typedef struct miPlaceholder_list {
        miTag           object;                 /* the real object with geom.*/
        miTag           filename;               /* file name to read */
        enum miObject_type      type;           /* type of object created */
} miPlaceholder_list;

typedef struct miHair_list {
        miGeoIndex      no_hairs;               /* number of hairs */
        miGeoIndex      no_scalars;             /* number of vectors */
        miHair_content  hair_info;              /* data attached to hairs */
        miHair_content  vert_info;              /* data attached to vertices,*/
                                                /* bump vars used for radius */
        miTag           hairs;                  /* 1st hair vec: miInteger[] */
        miTag           scalars;                /* control points: miScalar[]*/
        miInteger       approx;                 /* quality control of approx */
        miTag           material;               /* material for all hairs */
        miScalar        radius;                 /* hair radius, default 1 */
        int             degree;                 /* Bezier degree 1..3, def. 1*/
        int             space_max_size;         /* space subdiv. leaf size */
        int             space_max_depth;        /* space subdiv. tree depth */
} miHair_list;

A translator must provide: type, fine, geo.

volume_id assigns a volume identification to the object. It allows combining separate objects into a logical group which is treated as a single object for inside-outside computation in autovolume.

finalgather_file 3.4 file (list) argument allows a file name or a list of file names with finalgather map(s) to be specified to be used for the object. If identical file names or file name lists are used for several objects, only one copy of finalgather map will be kept in memory.

type (default miOBJECT_POLYGONS) specifies the type of the geometry attached to this object. It may be one of miOBJECT_POLYGONS, miOBJECT_FACES, miOBJECT_BOXES, miOBJECT_SUBDIVSURF, miOBJECT_PLACEHOLDER, or miOBJECT_HAIR3.1. This field determines which member of the union is used. Algebraics are not supported.

visible is, as of mental ray 3.4, a bitmap flag. Bit 0 controls whether the object is visible. The remaining bits are unused.

shadow flag is a bitmap that controls casting and receiving of shadows separately. Bit 0 enables shadows cast from this surface, and bit 1 allow shadows to be received by (fall onto) this object. By default, bit 0 is 0 and bit 1 is 1 ( mode 2).

reflection3.4, refraction3.4, and finalgather3.4 flags replace the trace flag. Code that writes to the trace field must now write to these three flag bitmaps instead. Again, bit 0 enables casting and bit 1 enables receiving, and the defaults are 0 and 1, respectively ( mode 2).

transparency3.4 flag that enables visibility of the surface to transparency rays, again separately for casting (bit 0) and receiving (bit 1). Unlike the other flags, both bits are on (mode 3) by default to ensure backwards compatibility.

caustic is a bitmap with three valid bits. Bit 0, if set, enables generation of caustics cast by this object. Bit 1, if set, enables receiving caustics. Bit 4, if set, makes this object invisible to caustic photons.

globillum is a bitmap with three valid bits. Bit 0, if set, enables generation of global illumination from this object. Bit 1, if set, enables receiving of global illumination by this object. Bit 4, if set, makes this object invisible to global illumination photons.

select (default miFALSE) makes the object subject to select tracing.

visible, shadow, caustic, globillum, and select flags are inherited in the scene DAG. See page instance_inh for an explanation of the inheritance.

face3.4 controls face culling. The possible values are 'f' (front), 'b' (back), and 'a' (all). If not specified, the culling flag given in the options or in the state is used.

fine3.1 must be set if the object contains any approximation with the fine3.1 flag set. It is set automatically by API. This field is redundant but allows mental ray to detect very quickly whether the object needs special treatment without scanning its contents.

view_dependent (default miFALSE) enables view-dependent tessellation if the object has type miOBJECT_FACES. It should be set to miTRUE iff any of the surfaces in the object references a view-dependent approximation. It should not be changed between preprocessing and postprocessing.

mtl_is_label is a flag that informs the renderer that the material field in the polygons or surfaces does not hold a material but an integer label. The renderer must ignore the material in this case and use the inherited material. This flag is set for tagged objects in the mi2 language.

maxdisplace specifies the maximum allowed displacement applied to object control points in local object space in normal direction.

userdata allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders can retrieve the data with mi_query.

label is a 32-bit integer that may be used to identify the object in shaders. mental ray does not use it in any way.

bbox_min and bbox_max are a bounding box that encloses all triangles resulting from tessellating this object, without taking motion blur or displacement into account. For polygons this is the convex hull of all point-in-space vectors, but for other object types better bounding boxes should be found to make rendering more efficient.

bbox_min_m and bbox_max_m are a bounding box of all motion vectors, if there are any. bbox_min_m is composed of all the smallest X, Y, and Z components of all motion vectors, and bbox_max_m is composed of all the greatest components. If setting these fields, set mbox_explicit3.1 to miTRUE.

functions if this is not a null tag, it points to a list of material tags. This list represents the required materials for the object.

n_functions the number of tags in the functions taglist.

mbox_explicit3.1 specifies that the bbox_min_m and bbox_max_m were specified by the user, and do not represent defaults computed by mental ray.

min_samples3.1 specifies that this object should be oversampled no less than this value. The default is -128, which makes the object default to the minimum sampling value in the options.

max_samples3.1 specifies that this object should be oversampled no more than this value. The default is 127, which makes the object default to the maximum sampling value in the options.

Note that neither of the previous two options are used by the rasterizer.

shadowmap specifies that the object casts shadows into shadowmaps, if the shadow flag is enabled as well.

ray_offset specifies the distance from the surface where secondary rays start. Effectively, no intersections closer than this distance will be found. This is useful to prevent rays leaving a visible-only high-resolution surface hitting the low-resolution trace-only version of the same surface. Different versions can be constructed with object or instance flags, or with flagged approximations.

approx_list is the list with ten approximations inherited from the instance.

geo is a union containing type-specific data. The suffix "_list" indicates that several types store the actual geometry in one or more lists of specific types; these lists are anchored here. The box_list case is a tag of a database element of type miSCENE_BOX. The box data type has been described above. Polygonal geometry is stored in four lists, all anchored in the geo.polygon_list structure.

The following diagram shows the connections between the four lists:

Polygonal Geometry Storage

Arrows indicate indices into the pointed-to data structure. All four grey boxes are separate Scene database element types, refer to the sections for miSCENE_POLYGON, miSCENE_GEOINDEX, and miSCENE_GEOVECTOR, respectively. The data structures are similar to the box data structure, except that the lists are stored in separate database elements, and that an index list is inserted that allows storing polygons with different numbers of vertices in a miPolygon data structure that has a constant size. The polygon points to the first vertex index in the index list and gives the number of vertices, as opposed to triangles in boxes that contain the three vertex indices directly.

geo.polygon_list.no_polygons is the number of polygons in the polygons list.

geo.polygon_list.no_indices is the number of indices in the indices list.

geo.polygon_list.no_vertices is the number of vertices in the vertices list. Each vertex consists of vert_info.sizeof_vertex indices.

geo.polygon_list.vect_info describes the sections of the vector list. For details, see the section for boxes above.

geo.polygon_list.vert_info describes the layout of the indices in the vertex list. For details, see the section for boxes above.

geo.polygon_list.polygons is the tag of the polygon list.

geo.polygon_list.indices is the tag of the index list.

geo.polygon_list.vertices is the tag of the vertex list.

geo.polygon_list.vectors is the tag of the vector list.

geo.polygon_list.approx is the approximation technique for displacement-mapped polygons. (It does not apply to polygons whose material does not specify displacement maps.)

Surface geometry is more complex. It is stored in up to seven different database elements, all of which are anchored in geo.face_list. The term face describes one complete visible free-form surface, which is built from one geometry surface and multiple optional texture surfaces, bump surfaces, and/or motion surfaces that provide certain types of mappings on the surface.

For details on texture surfaces, refer to the mental ray User Manual.

Unlike polygons, surfaces store their parameter lists and vectors in large miGeoScalar lists. This simplifies storing one, two, three, and four dimensional data in the same list. Trimming, hole, and special curves can optionally be attached to faces; they have their own scalar lists. Both surfaces and curves may reference optional special points. Every surface references two bases, and every curve references one base. Again, all lines in the following diagram indicate indices.


Free-form Surface Geometry Storage

geo.face_list.no_faces is the number of faces in the geo.face_list.faces list.

geo.face_list.no_surfaces is the number of surfaces in the geo.face_list.surfaces list.

geo.face_list.no_curves is the number of curves in the geo.face_list.curves list.

geo.face_list.no_specpnts is the number of special points in the geo.face_list.specpnts list.

geo.face_list.no_surf_scalars is the number of surface scalars in the geo.face_list.surf_scalars list.

geo.face_list.no_curve_scalars is the number of curve scalars in the geo.face_list.curve_scalars list.

geo.face_list.faces is the tag of the list of faces.

geo.face_list.surfaces is the tag of the list of surfaces.

geo.face_list.curves is the tag of the list of curve.

geo.face_list.specpnts is the tag of the list of special points.

geo.face_list.surf_scalars is the tag of the list of surface scalars, which are used for parameter vectors, control points, weights etc. that define all surfaces in this object.

geo.face_list.curve_scalars is the tag of the list of curve scalars, which are used for parameter vectors, control points, weights etc. that define all curves in this object.

geo.face_list.basis_list is the tag of the list of all bases.

An object of type miOBJECT_SPACECURVE contains a list of space curves. A single space curve consists of curve segments which are approximated as a single three dimensional curve. The approximation result is stored in a miLinebox.

geo.spacecurve_list.no_spacecurves is the number of space curves in the geo.spacecurve_list.spacecurves list.

geo.spacecurve_list.no_curves is the number of curves in the geo.spacecurve_list.curves list.

geo.spacecurve_list.no_specpnts is the number of special points in the geo.spacecurve_list.specpnts list.

geo.spacecurve_list.no_curve_scalars is the number of curve scalars in the geo.spacecurve_list.curve_scalars list.

geo.spacecurve_list.spacecurves is the tag of the list of spacecurves.

geo.spacecurve_list.curves is the tag of the list of curves.

geo.spacecurve_list.specpnts is the tag of the list of curve special points.

geo.spacecurve_list.curve_scalars is the tag of the list of curve scalars.

geo.spacecurve_list.basis_list is the tag of the list of all bases used by the curves.

An object of type miOBJECT_PLACEHOLDER contains a reference to the actual object containing the geometry, which is created on demand. A placeholder object must have a bounding box, and motion bounding box and maximum displacement fields if applicable, and may contain only a single object group.

geo.placeholder_list.object is the tag of the object that holds the actual geometry. This must be a demand-loaded tag, not a regular tag. The only way to construct such a tag is the mi_api_object_file function. Do not assign or access this field directly.

geo.placeholder_list.filename is the tag of a string containing the .mi scene file name that defines the object. This is only used for placeholder objects defined with mi_api_object_file.

geo.placeholder_list.type3.4 is the myObject_type of the object whose place is being held.

An object of type miOBJECT_HAIR3.1 defines an object with a different type of geometry that is not based on triangles but hairs. Since there is typically a very large number of hairs, this is far more efficient in terms of both memory usage and rendering performance. The description is very compact:


Hair Geometry Storage

Hairs are stored in a scalar list. Each hair has some data that is shared by all points of that hair, and some data that is separate for each point of the hair. All hairs share the exact same layout, except that they may have different numbers of points. In this example, each hair has two texel scalars (U and V) and a radius; and each point has a coordinate (X, Y, and Z; mandatory), one motion vector (X, Y, Z), and one texel scalar (T). The hairs list contains indices into the scalar list where the corresponding hair begins, plus one extra hair end marker at the end. Here there are two hairs, one with two points and one with three.

geo.hair_list.no_hairs3.1 is the number of hairs, 2 in the example. There is always one more index in the hairs list for the end marker. Each index must be greater than the previous by i + j · n, where i is the size of the header (3 in the example), j is the size of a point (7 in the example), and n is the number of points for this hair (2 and 3 in the example). API verifies this.

geo.hair_list.no_scalars3.1 is the number of scalars in the scalar list.

geo.hair_list.hair_info3.1 describes the size and layout of the hair headers in the scalar list. This structure and vert_info work like in objects and boxes (see page vertinfo), but count scalars, not vectors.

geo.hair_list.vert_info3.1 describes the size and layout of the points in the scalar list.

geo.hair_list.hairs3.1 is the tag of a database element containing the index integers.

geo.hair_list.scalars3.1 is the tag of a database element containing the scalars.

geo.hair_list.approx3.1 specifies the number of linear segments used to approximate a curve segment.

geo.hair_list.material3.1 is the material shader shared by all hairs. If this is a null tag, the material is inherited from the instance.

geo.hair_list.radius3.1 specifies the radius of all hairs, if neither hair_info nor vert_info specify radius values.

geo.hair_list.degree3.1 is the degree of the Bézier curves that approximate the hair. It must be 1, 2, or 3. Each hair is defined by degree · n + 1 points, for some integer n > 0 . The approximation will result in n · approx linear segments.

geo.hair_list.space_max_size3.1 specifies the maximum leaf size of the hair BSP tree that is used for intersection testing. If left at 0, mental ray chooses a default.

geo.hair_list.space_max_depth3.1 specifies the maximum depth of the hair BSP tree that is used for intersection testing. If left at 0, mental ray chooses a default.

There are two data structures that are used to describe the format of vertices and vectors:

typedef struct miVertex_content {
        miUchar         sizeof_vertex;  /* size of a vertex */
        miUchar         normal_offset;  /* when 0, not present */
        miUchar         motion_offset;  /* when 0, not present */
        miUchar         derivs_offset;  /* surf derivs, when 0, not present */
        miUchar         derivs2_offset; /* 2nd derivs, when 0, not present */
        miUchar         motion_offset;  /* when 0, not present */
        miUchar         no_motions;     /* number of motion vectors */
        miUchar         texture_offset; /* when 0, not present */
        miUchar         no_textures;    /* number of textures */
        miUchar         bump_offset;    /* when 0, not present */
        miUchar         no_bumps;       /* number of bumps */
        miUchar         user_offset;    /* when 0, not present */
        miUchar         no_users;       /* number of user vectors */
} miVertex_content;

A translator must provide: all fields.

This structure is used to describe which information is stored with each vertex. It is also used to inform the tessellator what information to create vertices with. Vertices always consist of at least one vector reference for the point in space. The normal, the motion vectors, the surface derivative pair, the list of textures, the list of bump basis vectors, and the list of user vectors are all optional. Multiple motion vectors (up to 15 per vertex) are supported only in mental ray 3.1; mental ray 3.0 has the no_motions field but ignores it when rendering; mental ray 2.1 lacks this field.

A vertex is a list of indices into the actual vector table. Each such list begins with the index for the point in space, said to be at offset 0 in the list. The miVertex_content structure describes at which offset in the list other vector indices can be found. For example, if there is an index for a normal in the list directly after the index for the point in space, normal_offset would be 1.

If some vertices have a certain type type of index and others do not (like some vertices have normals and others do not), the offset in the miVertex_content structure is nonzero but the index is set to miNULL_GEOINDEX in those vertices that do not need it. Using 0 for nonexistent offset members is ok because the first index in a vertex (which has offset 0) is the point in space, which must always exist. Do not confuse null offsets with null indices, which must use miNULL_GEOINDEX instead of 0 because the first vector in a polygon vector list can be something other than a point in space. Polygon lists mirror the order in the .mi file.

The second recurring structure is the vector list header:

typedef struct miGeoVector_list {
        miGeoIndex      no_vectors;     /* total number of input vectors */
        miGeoIndex      no_points;      /* number of points in space */
        miGeoIndex      no_normals;     /* number of normals */
        miGeoIndex      no_derivs;      /* number of 1st/2nd surface derivs */
        miGeoIndex      no_motions;     /* number of motion vectors */
        miGeoIndex      no_textures;    /* number of texture coordinates */
        miGeoIndex      no_bumps;       /* number of bump basis vectors */
        miGeoIndex      no_users;       /* number of user-defined vectors */
} miGeoVector_list;

A translator must provide: all fields.

All the vertex indices described by the miVertex_content structure are indices into the actual vector list. The vector list itself is partitioned in the eight "sections": one for points in space, one for normals, one for surface derivatives, and so on.

Copyright © 1986-2008 by mental images GmbH