| 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:
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.
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:
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