home << prev next >> contents  

Auxiliary Functions

    miBoolean mi_lookup_color_texture(
        miColor         *color,
        miState         *state,
        miTag           tag,
        miVector        *coord)

tag is assumed to be a texture as taken from a color texture parameter of a shader. This function checks whether the tag refers to a shader (procedural texture) or an image, depending on which type of color texture statement was used in the .mi file. If tag is a shader, coord is stored in state→tex, the referenced texture shader is called, and its return value is returned. If tag is an image, coord is brought into the range (0..1, 0..1) by removing the integer part, the image is looked up at the resulting 2D coordinate, and miTRUE is returned. If the texture is marked with the filter keyword, multi-level pyramid filtering is performed, a procedure related to classical mip-map textures. In both cases, the color resulting from the lookup is stored in * color.

    typedef struct {
        miScalar        eccmax;
        miScalar        max_minor;
        miScalar        circle_radius;
        miBoolean       bilinear;
        miScalar        spare[10];
    } miTexfilter;

    miBoolean mi_lookup_filter_color_texture(
        miColor         *color,
        miState         *state,
        miTag           tag,
        miTexfilter     *paras,
        miMatrix        ST)

This function provides higher quality filtering than the multi-level pyramid filtering of mi_lookup_color_texture described above using a transformation ST which transforms the coordinate system centered in the current raster position in screen space to texture space. The functions mi_texture_filter_project and mi_texture_filter_transform are provided for helping to calculate this transformation matrix.

This function expects that tag does not refer to a texture shader, that is, it works only on texture images. It will return miFALSE when used with incorrect parameters or if a projection failed.

In the filtering algorithm a circle around the current raster position is projected to an ellipse in texture space, and returns the average color of all texture pixels inside the ellipse. If the texture defined by tag is a pyramid texture, multi-level lookup of the texture pixels is performed to speed up the filtering. In the algorithm the level calculation is based on the minor radius of the ellipse.

The filtering can be controlled by choosing different values in paras. If paras is a null, default values for medium filter quality are used.

The eccmax field in miTexfilter specifies the maximum allowed eccentricity of the ellipse. It must be equal to or greater than 1.0. The eccentricity is defined by the ratio of the major and minor radius. Under severe projective distortion the ellipse can have a very large eccentricity and too many texture pixels would be covered by the elliptical area, resulting in long rendering times. In order to limit the filtering time in these cases, the eccentricity threshold can be specified. If the eccentricity is greater than this value, the minor radius of the ellipse is made larger allowing for a potentially higher level in the texture image pyramid since the level calculation is based on the minor radius.

In this calculation a level is selected where the minor radius of the ellipse has a maximum length of max_minor texture pixels. In each successive level in the image pyramid the radius is divided by two, and there are fewer pixels inside the elliptical area. The useful range for eccmax is approximately 10 to 30, higher values will result in better antialiasing. For max_minor the range should be 3 to 8. Higher values result in better antialiasing.

The size of the projected screen-space circle can be modified with the circle_radius parameter. Larger values will result in more blurring since the elliptical area is also made larger. Smaller values will increase the aliasing. The useful range for this field is 0.4 to 1.0.

When a magnification area is detected, that is, an area in which the pixels are not compressed (the elliptical area is smaller than a texture pixel), bilinear texture pixel interpolation can be switched on by setting the bilinear field to miTRUE, which results in a more blurry image.

See page elltexex for an example.

    miBoolean mi_lookup_scalar_texture(
        miScalar        *scalar,
        miState         *state,
        miTag           tag,
        miVector        *coord)

This function is equivalent to mi_lookup_color_texture, except that tag is assumed to refer to a scalar texture shader or scalar image, as defined in the .mi file with a scalar texture statement, and a scalar is looked up returned in * scalar. Note that filtering of scalar textures (enabled with filter scalar texture statements) is supported only in mental ray 3.1.2 and later.

    miBoolean mi_lookup_vector_texture(
        miVector        *vector,
        miState         *state,
        miTag           tag,
        miVector        *coord)

This function is also equivalent to mi_lookup_color_texture, except that tag is assumed to refer to a vector texture shader or vector image, as defined in the .mi file with a vector texture statement, and a vector is looked up returned in * vector. Vector textures cannot be filtered.

    miBoolean mi_texture_filter_project(
        miVector        p[3],
        miVector        t[3],
        miState *const  state,
        miScalar        disc_r,
        miUint          space)

This function helps in calculating the screen to texture space transformation matrix required by mi_lookup_filter_color_texture. It projects three points including the current raster position onto the current intersection primitive (statepri) plane and calculates the texture coordinates in the intersections. If statepri is null, or if the projection fails, miFALSE is returned.

This function assumes that the current intersected object has a texture space associated and uses space as an index into the texture space. The three screen space points are returned in p, the corresponding two dimensional texture space points are put into t. The first point in the array is always the central raster position (0,0), the others are inside a disc with radius of disc_r from this central position. Note that the points are relative to the central position, absolute screen space coordinates are not used. The value of disc_r should be set to 0.5 in most cases, since the full pixel is projected to texture space. However, when there are highly curved objects in the scene, a smaller value can effectively remove projection problems where the projected points are far outside the hit triangle primitive.

    miBoolean mi_texture_filter_transform(
        miMatrix        ST,
        miVector        p[3],
        miVector        t[3])

This function helps in calculating the screen to texture space transformation matrix required by mi_lookup_filter_color_texture. The three two dimensional screen space points in p and the corresponding three two dimensional texture space points form a linear equation which is solved for the transformation matrix. See page elltexex for an example. This function returns miFALSE if the linear equation mentioned above has no solution.

    miScalar mi_luminance(
        miState         *state,
        miColor         *color);

Return the luminance of color, by multiplying each RGB component by a factor (default ) and adding the results. The factors can be changed with the luminance weight statement, or the luminance_weight field in the miOptions structure. The purpose of having a single function to do this calculation is to make luminance calculations in shaders consistent across all shaders, and making the weight easily changeable in one central place. This is for shaders only; mental ray does not calculate luminances or use the weights in any way.

    miBoolean mi_tri_vectors(
        miState         *state,
        int             which,
        int             ntex,
        miVector        **a,
        miVector        **b,
        miVector        **c)

All the information in the state pertains to the interpolated intersection point in a triangle. This function can be used to obtain information about the uninterpolated triangle vertices. Together with the barycentric coordinates in the state, parameters retrieved with mi_tri_vectors may be interpolated differently by the shader. The which argument is a character that controls which triple of vectors is to be retrieved:

which vector
'p' the points in space
'n' the normal vectors
'm' the motion vectors
't' the texture coordinates of texture space ntex
'u' the U bump basis vectors
'v' the V bump basis vectors
'U' the first surface derivative in U (d P du)
'V' the first surface derivative in U (d P dv)
'X' the second surface derivative d^2 P du^2
'Y' the second surface derivative d^2 P dv^2
'Z' the second surface derivative d^2 P du dv
'*' the user vectors

A pointer to the vectors is stored in * a, * b, and * c. The shader may not modify these vectors. They are stored in the space used when the scene was created (either object space or camera space depending on ); the original data is accessed without implicit transformation to internal space. If the requested triple is not available, miFALSE is returned. This function relies on ; it only works if the shader has not modified this variable, as some ray-marching volume shaders do.

This function may not be called in displacement shaders because triangles do not yet exist at that stage. Displacement displaces vertices, not triangles; triangles are built from final vertices later. It also may not be called for hair objects, because hair is not based on triangles. (mental ray 3.2 and later detect this case and return miFALSE for hair objects.)

    miBoolean mi_texture_interpolate(
        miState         *state,
        miUint          space,
        miScalar        *result)

3.4 This function interpolates the current intersection texture coordinates, using the barycentric coordinates from the state. The texture space index is given with space. The coordinates are written to the array result which must be allocated large enough according to the dimension of the texture space. This function is needed only for geometry with texture coordinates that have more or fewer than three dimensions. Standard 3D texture coordinates should be read from . Non-3D texture coordinates are supported only for subdivision surfaces and raw primitive lists. Use the miQ_TEXTURE_DIM mode of mi_query to find the dimension of a texture coordinate.

    miBoolean mi_raster_unit(
        miState         *state,
        miVector        *x,
        miVector        *y)

3.2 Transforms a pair of X and Y unit vectors in raster space to the current object space. In other words, the returned x and y vectors specify the size of a pixel in object space. This information is useful for selecting filter parameters in the shader, such as bump map precisions or texture lookups. This function assumes a pinhole camera. The orientation of the surface at the current shading point is not taken into account.

    miBoolean mi_query(
        const miQ_type  query,
        miState *const  state,
        miTag           tag,
        void * const    result,

Return various pieces of information about the current state of mental ray. query is the request code specifying what piece of information to query; state is the shader state, tag is the tag of the DB element to query, if any, and result is a pointer to the variable to store the results in. Some queries do not require a tag; in this case miNULLTAG must be passed as tag. Some queries require extra arguments in addition to the four standard arguments. mi_query returns miFALSE if the queried value is not available or an unknown type code is used. The following query codes are available:

query code state tag result purpose
miQ_DATA_DECL N Y miTag user data declaration if any, or 0
miQ_DATA_LABEL N Y miUint translator-defined user data label
miQ_DATA_NEEDSWAP N Y miBoolean requires byte-swapping by shader
miQ_DATA_NEXT N Y miTag next user data block in chain, or 0
miQ_DATA_PARAM N Y char * user data contents
miQ_DATA_PARAM_SIZE N Y int size of user data block in bytes
miQ_DATE N N char * mental ray compilation date
miQ_DECL_LOCK N Y miLock * shared by all shader instances
miQ_DECL_NAME N Y char * shader name
miQ_DECL_PARAM N Y char * ascii-encoded parameter declaration
miQ_DECL_RESULT_SIZE N Y int result size, 4 unless struct
miQ_DECL_TYPE N Y int miTYPE_* result type
miQ_DECL_VERSION N Y int shader declaration version
miQ_FINALGATHER_STATE3.2 Y N int 0=not a finalgather ray (grand)child, 1=finalgather ray (grand)child in a tile rendering, 2=finalgather ray (grand)child in finalgather precomputing
miQ_SAMPLE_MOVING3.5 Y N int Not zero if mental ray has detected geometry motion for the current raster sample.
miQ_FUNC_CALLTYPE Y N int one of miSHADER_*, as specified by the calling mi_call_shader
miQ_FUNC_DECL N Y miTag tag of shader declaration
miQ_FUNC_INDIRECT N Y miTag take params from this shader
miQ_FUNC_LOCK N Y miLock * local shader instance lock
miQ_FUNC_NEXT N Y miTag next shader in shader list
miQ_FUNC_PARAM N Y void * shader parameters
miQ_FUNC_PARAM_SIZE N Y int size of shader parameters in bytes
miQ_FUNC_RESULT_SIZE N Y int shader result size in bytes
miQ_FUNC_TAG3.2 Y N miTag tag of the currently running shader
miQ_FUNC_TLS_GET Y N void * retrieve thread-local shader data pointer
miQ_FUNC_TLS_GETALL Y N void *, int get list of all valid thread-local shader data pointers, and the list size
miQ_FUNC_TLS_SET Y N void * set thread-local shader data pointer (see page querytls)
miQ_FUNC_TYPE N Y int 0=C/C++, 1=phen., 2=output file
miQ_FUNC_USERPTR N Y void ** user pointer in shader instance
miQ_GEO_DATA N N miTag user data block of current object
miQ_GEO_HAS_DERIVS3.2 Y N miBoolean * validity of state derivatives
miQ_GEO_HAS_DERIVS23.2 Y N miBoolean * validity of state second derivatives
miQ_GEO_LABEL N N miUint translator-defined triangle label
miQ_GLOBAL_LIGHTS N N miTag * array with global light tags
miQ_GROUP_DATA N Y miTag user data block
miQ_GROUP_KID N Y miTag nth child (n is fifth argument)
miQ_GROUP_LABEL N Y miUint translator-defined group label
miQ_GROUP_MERGE_GROUP N Y miBoolean miTRUE if connected
miQ_GROUP_NKIDS N Y int number of child instances
miQ_IMAGE_BITS N Y int num of bits per component (8,16,32)
miQ_IMAGE_COLORCLIP N N miBoolean color frame buffer color clipping mode
miQ_IMAGE_COMP N Y int num of components (1,2,3,4)
miQ_IMAGE_DESATURATE N N miBoolean color frame buffer desaturation mode
miQ_IMAGE_DITHER N N miBoolean color frame buffer dithering mode
miQ_IMAGE_FILTER N Y miBoolean image allows filtering
miQ_IMAGE_GAMMA N N double color frame buffer gamma factor
miQ_IMAGE_HEIGHT N Y int height of image in pixels
miQ_IMAGE_NOPREMULT N N miBoolean color frame buffer premultiplication mode
miQ_IMAGE_WIDTH N Y int width of image in pixels
miQ_INST_AREA N Y miScalar light instances only: area of area light
miQ_INST_CAUSTIC N Y miUint bitmap: 1=enable casting, 2=enable receiving, 3=disable casting, 4=disable receiving
miQ_INST_DATA N Y miTag user data block
miQ_INST_DECL N Y miTag inherited parameter declaration
miQ_INST_FUNCTION N Y miTag optional procedural transformation
miQ_INST_GLOBAL_TO_LOCAL N Y miMatrix * instance transformation
miQ_INST_GLOBILLUM N Y miUint bitmap: 1=enable casting, 2=enable receiving, 3=disable casting, 4=disable receiving
miQ_INST_HIDE N Y miBoolean instance is inactive
miQ_INST_IDENTITY N Y miBoolean miTRUE if identity transformation
miQ_INST_ITEM N Y miTag instanced scene element
miQ_INST_LABEL N Y miUint translator-defined instance label
miQ_INST_LOCAL_TO_GLOBAL N Y miMatrix * inverse instance transformation
miQ_INST_MATERIAL N Y miTag inherited material
miQ_INST_PARAM N Y void * inherited parameters
miQ_INST_PARAM_SIZE N Y int inherited parameter size
miQ_INST_PARENT N Y miTag leaf instance parent (0 otherwise)
miQ_INST_PLACEHOLDER_ITEM N Y miTag content of placeholder instances
miQ_INST_SHADOW N Y miUint invisible to shadow rays
miQ_INST_TRACE N Y miUint visible to secondary rays
miQ_INST_VISIBLE N Y miUint visible to primary rays
miQ_LIGHT_AREA N Y int 0=none, 1=rectangle, 2=disc, 3=sphere
miQ_LIGHT_AREA_C_AXIS N Y miVector axis of cylinder area light
miQ_LIGHT_AREA_C_RADIUS N Y miScalar radius of cylinder area light
miQ_LIGHT_AREA_R_EDGE_U N Y miVector U size of rectangular area light
miQ_LIGHT_AREA_R_EDGE_V N Y miVector V size of rectangular area light
miQ_LIGHT_AREA_D_NORMAL N Y miVector normal vector of disc area light
miQ_LIGHT_AREA_D_RADIUS N Y miScalar radius of disc area light
miQ_LIGHT_AREA_S_RADIUS N Y miScalar radius of spherical area light
miQ_LIGHT_AREA_SAMPLES_U N Y int number of samples in U direction
miQ_LIGHT_AREA_SAMPLES_V N Y int number of samples in V direction
miQ_LIGHT_CAUSTIC_PHOTONS N Y int number of caustic photons to store
miQ_LIGHT_CAUSTIC_PHOTONS_EMIT N Y int number of caustic photons to emit
miQ_LIGHT_DATA N Y miTag user data block
miQ_LIGHT_DIRECTION Y Y miVector light direction
miQ_LIGHT_EMITTER N Y miVector tag of light photon emitter shader
miQ_LIGHT_ENERGY N Y miTag energy for caustics and globillum
miQ_LIGHT_EXPONENT N Y miScalar distance falloff, n in 1 / r^n
miQ_LIGHT_GLOBAL_PHOTONS N Y miColor number of globillum photons to store
miQ_LIGHT_GLOBAL_PHOTONS_EMIT N Y miColor number of globillum photons to emit
miQ_LIGHT_LABEL N Y int light label
miQ_LIGHT_NORMAL Y N miVector normal vector at light surface in world coordinates
miQ_LIGHT_ORIGIN Y Y miVector light position
miQ_LIGHT_SHADER N Y miTag tag of light shader
miQ_LIGHT_SPREAD N Y miScalar outer cone angle of spot light
miQ_LIGHT_TANGENT_SPACE Y N miVector[3] tangent, bi-tangent and normal vector at light surface in world coordinates
miQ_LIGHT_TYPE N Y int 0=point, 1=directional, 2=spot
miQ_LIGHT_USE_SHADOWMAP N Y miBoolean light has a shadow map
miQ_LIGHTPROFILE_COSTHETA_MAX N Y miScalar largest possible value of the cosine of the profile vertical angle
miQ_LIGHTPROFILE_COSTHETA_MIN N Y miScalar smallest value of the cosine of the profile vertical angle.
miQ_LIGHTPROFILE_INTENSITY_MAX N Y miScalar largest intensity value of the profile
miQ_LIGHTPROFILE_PHI_MAX N Y miScalar horizontal angle where the light profile ends
miQ_LIGHTPROFILE_PHI_MIN N Y miScalar horizontal angle where the light profile starts
miQ_LIGHTPROFILE_PHI_RES N Y int number of interpolation points in the horizontal direction
miQ_LIGHTPROFILE_THETA_RES N Y int number of interpolation points in the vertical direction
miQ_MTL_CONTOUR N Y miTag contour shader
miQ_MTL_DISPLACE N Y miTag displacement shader
miQ_MTL_ENVIRONMENT N Y miTag environment shader
miQ_MTL_OPAQUE N Y miBoolean material is opaque to shadow rays
miQ_MTL_PHOTON N Y miTag photon shader
miQ_MTL_PHOTONVOL N Y miTag photon volume shader
miQ_MTL_SHADER N Y miTag material shader
miQ_MTL_SHADOW N Y miTag shadow shader
miQ_MTL_VOLUME N Y miTag volume shader
miQ_NUM_BUMPS3.2 Y N int * number of bumps in state x, y bump lists
miQ_NUM_GLOBAL_LIGHTS N N int number of global lights
miQ_NUM_TEXTURES Y N int * number of textures in state->tex_list
miQ_OBJ_CAUSTIC N Y miUint 0=none, 1=casts, 2=receives, 3=both
miQ_OBJ_DATA N Y miTag user data block
miQ_OBJ_GLOBILLUM N Y miUint 0=none, 1=casts, 2=receives, 3=both
miQ_OBJ_LABEL N Y miUint translator-defined object label
miQ_OBJ_SHADOW N Y miBoolean invisible to shadow rays
miQ_OBJ_TRACE N Y miBoolean visible to secondary rays
miQ_OBJ_TYPE N Y int 0=polygonal, 1=surfaces
miQ_OBJ_VIEW_DEPENDENT N Y miBoolean contains view-dependent surfaces
miQ_OBJ_VISIBLE N Y miBoolean visible to primary rays
miQ_PIXEL_SAMPLE3.2 Y N miScalar[2] set up QMC sequences for sampling, and return a jitter value for lightmap shaders. See page miqpixelsample for an example.
miQ_PRI_BBOX_MAX Y N miVector object-space bounding box of intersected primitive
miQ_PRI_BBOX_MIN Y N miVector object-space bounding box of intersected primitive
miQ_RAY_INTERFACE Y N MI::RAY:Interface* pointer to C++ interface class
miQ_SCENE_BBOX_ALL Y N miVector[2] world-space bounding box of all geometry
miQ_SCENE_BBOX_CAUSTIC_G Y N miVector[2] bounding box of all caustic-casting geometry
miQ_SCENE_BBOX_CAUSTIC_R Y N miVector[2] bounding box of all caustic-receiving geometry
miQ_SCENE_BBOX_GLOBILLUM_G Y N miVector[2] bounding box of all globillum-casting geometry
miQ_SCENE_BBOX_GLOBILLUM_R Y N miVector[2] bounding box of all globillum-receiving geometry
miQ_SCENE_BBOX_SHADOW Y N miVector[2] bounding box of all shadow-casting geometry
miQ_SCENE_ROOT_GROUP Y N miTag the root group of the scene from the render statement; useful for custom scene traversals
miQ_TEXTURE_DIM N Y miUint dimension of nth texture space of intersected primitive (n is fifth argument)
miQ_TILE_PIXELS Y N int[4] lower left and upper right tile pixel coord
miQ_TILE_SAMPLES Y N int[4] same but including filter source margin
miQ_TRANS_CAMERA_TO_INTERNAL Y N miMatrix * camera to internal space transformation
miQ_TRANS_CAMERA_TO_WORLD Y N miMatrix * camera to world space transformation
miQ_TRANS_INTERNAL_TO_CAMERA Y N miMatrix * internal to camera space transformation
miQ_TRANS_INTERNAL_TO_OBJECT Y N miMatrix * internal to object space transformation
miQ_TRANS_INTERNAL_TO_WORLD Y N miMatrix * internal to world space transformation
miQ_TRANS_OBJECT_TO_INTERNAL Y N miMatrix * object to internal space transformation
miQ_TRANS_OBJECT_TO_WORLD Y N miMatrix * object to world space transformation
miQ_TRANS_WORLD_TO_CAMERA Y N miMatrix * world to camera space transformation
miQ_TRANS_WORLD_TO_INTERNAL Y N miMatrix * world to internal space transformation
miQ_TRANS_WORLD_TO_OBJECT Y N miMatrix * internal to world space transformation
miQ_PRI_DATA Y N miPri_data the per-primitive data of the current primitive in the state
miQ_VERSION N N char * mental ray version string

The "N" symbol in the state column indicates that the state is not used. The "N" symbol in the tag column means that miNULLTAG must be passed. Some queries can specify a state instead of a tag. Their query codes are indicated with a *, which stands for any of the preceding codes whose names begin with the same prefix; in this case mi_query will take the current shader ( ) instead of an arbitrary tag. This is slightly faster than passing a tag.

The result type in the table indicates the type of the variable that mi_query accepts a pointer to: to obtain an integer result from mi_query (the table lists an "int"), a pointer to an integer must be passed as the fourth argument ("int *"). For mi_query, "function" is synonymous with "shader".

The result of the miQ_INST_VISIBLE, miQ_INST_SHADOW, miQ_INST_TRACE, and miQ_INST_CAUSTIC queries depend on whether a scene DAG or leaf instance tag is passed. A scene DAG instance contains the flags specified by the scene description language when the instance was created. A leaf instance contains the effective instance flags for rendering, that is, with instance inheritance and object flags taken into account.

Note: for a scene DAG instance, the visibility etc. flags should be interpreted as: unset (0), off (1), on (2); for a leaf instance, the flags should be interpreted as: off (0), on (1); see also the description for the instance data structure.

The miQ_INST_VISIBLE etc. modes should be used instead of the miQ_OBJ_VISIBLE etc. modes because they return the same modes that mental ray uses when rendering.

The result vectors of the miQ_LIGHT_ORIGIN and miQ_LIGHT_DIRECTION queries are defined in internal space if the light instance tag is passed, otherwise the vectors are defined in local space.

The miQ_TILE_* codes are supported by mental ray or later. They describe the location and size of the currently rendered image tile. The returned values are in the order xlow xhigh ylow yhigh. The sampled area may be larger than the tile due to filtering and jittering. These codes may be used to detect if a shader is called in the finalgather precomputing stage: for finalgather precomputing the return value is miFALSE as no tile exist.

The miQ_SAMPLE_MOVING3.5 mode can be used by an environment shader to detect if taking several samples of a moving environment texture at different shutter times would be advantageous. If the queried value is not zero, mental ray does such oversampling automatically.

The query codes miQ_NUM_TEXTURES and miQ_GEO_LABEL may only be used if has not been modified by the shader or calling shader. Ray-marching volume shaders sometimes clear this state variable. Both are not supported in displacement shaders. miQ_GEO_LABEL also returns miFALSE if the object is not marked tagged and no polygon/surface labels exist. In mental ray 3.3, the miQ_GEO_LABEL mode may be used from displacement shaders; this did not work in earlier versions.

Note that a return type of miMatrix * means that the address of a pointer must be passed, not the address of a matrix. This reduces the number of bytes that mi_query has to copy from 64 (sixteen floats) to only four (or eight, on some CPU architectures).

The query mode miQ_PRI_DATA returns an miPri_data structure which is defined as follows:

    typedef struct miPri_data {
        miUint          info_size;      /* size of info */
        const miUint    *info;          /* info: data layout */
        miUint          data_size;      /* size of triangle data */
        const miUint    *data;          /* primitive (triangle) data */
    } miPri_data;

All fields in this structure are specific to the current intersected object. The field info_size specifies the size of the per-face userdata information block for the current intersection, in multiples of 32 bit. The address of this block is given in info if info_size is not zero. The per-face data of the hit primitive is returned in data, the length of the data block in multiples of 32 bit is given in data_size. Per face data can be present even if the information block is not specified. The caller must pass a pointer to such a structure which is then filled out by mi_query.

    miBoolean mi_shaderstate_set(
        miState         *state,
        const char      *key,
        void            *value,
        int             valsize,
        int             lifetime)

3.2 Store a data block * value under the name key (which has become const in mental ray 3.3). The data block can be retrieved by key with mi_shaderstate_get later. Shorter keys are slightly faster to hash and compare. valsize is the size of the value block to store. A copy of * value is made. If a data item with the same key exists, it is replaced with the new one. If value or valsize are null, an existing data item with the same key is deleted and none is created. The lifetime controls when the data item is deleted: at the end of the current eye ray if lifetime is miSS_LIFETIME_EYERAY, or at some later point, but no later than the end of the rectangle, if it is miSS_LIFETIME_RECT. The latter is slightly faster. In any case, data items are separate for each host, thread, and rectangle.

Data items stored with this mechanisms are intended for communication between shaders called during evaluation of a single eye ray, both upstream and downstream. For example, a material shader may set a data item to be picked up by any later light shader, or by the root lens shader. It is a replacement for , which works only downstream and causes conflicts if more than one data item is needed. The mechanism is only available in eye ray context during rendering, but not in geometry, output, displacement, or other shaders that do not get called as a consequence of an eye ray. As a special case, use in lightmap shaders is supported.

Note that transparency in rasterizer mode (formerly called Rapid Motion) is not performed by casting rays that could carry shader state, but by compositing at a later stage. For this reason it is not possible to transport shader state through a call to mi_trace_transparency In rasterizer mode.

    void *mi_shaderstate_get(
        struct miState  *state,
        const char      *key,
        int             *valsize)

3.2 Look up a data element previously stored with mi_shaderstate_set, under the same key, and return a pointer to the stored value. Also return the size of the stored value in *valsize, unless valsize is a null pointer. If no data element is found, a null pointer is returned and valsize is undefined.

    void mi_shaderstate_enumerate(
        miState         *state,
        miBoolean       (*cb)(void *arg, char *key, void *val, int vsz, int l),
        void            *arg)

3.2 The callback cb is called for each known item, with the opaque arg pointer, key, value, value size, and lifetime. If cb is a null pointer, the list is printed using mi_info. This function is intended for debugging only; the implied linear search is inefficient. Callback mode is useful to interpret the contents of the value pointer; mi_info merely prints an address.

    miBoolean mi_fb_put(
        miState         *state,
        int             fb,
        void            *data)

Store data into the sample so that it gets filtered and stored in user frame buffer fb later. The type of the data to copy from * data is determined by the frame buffer type as defined in the options block. The frame buffer number fb must be a number equal to or greater than 0, corresponding to the fb n number in the frame buffer statements. (mental ray 3.3 and earlier only supported the range 0..7.) If this frame buffer was not defined, this function has no effect and returns miFALSE. The data is stored in the current sample (i.e., the current location for which the primary ray was cast), and is filtered to create frame buffer pixels after all samples in the region have been taken. There is no way to store user frame buffer data in arbitrary locations with this function. It should be called for all samples and all defined user frame buffers to avoid leaving holes; if user frame buffer data is left undefined in a sample because mi_fb_put was not called, the data defaults to zero and is filtered as such.

Output shaders may not use this function because there is no notion of "samples" during output shading; instead, they must use the standard mi_img_put_* functions with an offset of miRC_IMAGE_USER + fb. Shaders may get the data type of a frame buffer n by inspecting . Similarly, final gathering, light mapping, displacement, and geometry shaders may not use mi_fb_put and mi_fb_get because the frame buffers are only available during frame rendering. 3.4 The data type of a frame buffer is stored in .

    miBoolean mi_fb_get(
        miState         *state,
        int             fb,
        void            *data)

Retrieve data from user frame buffer fb. The type of the data copied to * data is determined by the frame buffer type as defined in the options block. It will never be larger than 16 bytes (the size of a miColor). The frame buffer number fb must be in the range 0...7. If this frame buffer was not defined, this function returns miFALSE, and no data is stored. This function is intended to let shaders retrieve data that may have been stored by shaders called in later ray generations, but like mi_fb_put it is limited to the current sample. Again, output shaders may not use this function because there is no notion of "samples" during output shading; instead, they must use the standard mi_img_get_* functions with an offset of miRC_IMAGE_USER + fb.

    miImg_image *mi_output_image_open(
        miState         *state,
        miUint          idx)

3.4 Returns an image pointer for a frame buffer index. idx is one of the miRC_IMAGE_RGBA, miRC_IMAGE_USER etc. constants. May only be called from output shaders. Versions prior to 3.4 could obtain the output image from a static array in the state, but this array is no longer available in mental ray 3.4. This means that all output shaders need to be rewritten for mental ray 3.4.

    void mi_output_image_close(
        miState         *state,
        miUint          idx)

3.4 Closes an opened frame buffer image that has been opened with mi_output_image_open. idx is one of the miRC_IMAGE_RGBA, miRC_IMAGE_USER etc constants. May only be called from output shaders.

    miBoolean mi_geoshader_add_result(
        miTag           *result,
        const miTag     item)

This function should be called from geometry shaders for adding a scene element to the result. If result or item are null, miFALSE is returned. If result refers to a null tag, an instance group is created and returned in result. If result is non-null but does not refer to an instance group, an instance group is created, the result element is put into this group and the group is returned in result. Now that this function has enforced that an instance group element is always returned, the item element is put into the returned group. See page geoshaderex for an example.

    miBoolean mi_geoshader_tesselate(
        miState         *state,
        miTag           *leaves,
        miTag           source)

This function should be called from geometry shaders only. It builds a list of instances that describes the object, instance group, or instance source. If source contains more than one object, there will be multiple instances in the leaves list. The leaves argument is set to the tag of the first instance; the others are chained to one another with the next field in each instance. The last instance in the list has a null next field.

The tessellation function also tessellates the geometry described by each instance, and attaches the triangles resulting from the tessellation to the boxes field of the instance. Triangles are stored in boxes, which are data structures consisting of a header, a vector list, a vertex list, and a triangle list. In mental ray 2.x, boxes have a maximum size; if an object does not fit into one box, more are generated and chained using the next_box tag in each box.

    miBoolean mi_geoshader_tesselate_end(
        miTag           leaves)

Release all memory allocated by mi_geoshader_tesselate. This function releases all instances and boxes attached to the instance chain leaves, which was created by mi_geoshader_tesselate. Multiple instance lists can exist at the same time; it is not necessary to release one before creating the next but since memory demands may be substantial if the tessellated geometry is large, it is recommended to not keep instance lists longer than necessary.

    typedef struct {
        miBoolean       prefer_approx_polygons; /* triangles from polygons */
        miBoolean       prefer_approx_faces;    /* triangles from surfaces */
        miBoolean       ascii_output;           /* non-binary output */
        miBoolean       verbatim_textures;      /* dump textures verbatim ? */
        miBoolean       norendercommand;        /* disable rendercmd echo? */
        miUint          explode_objects;        /* write objects to subfiles */
        miTag           leaf_insts;             /* for prefer_approx_* lookup*/
        miBoolean       nolinkcommand;          /* don't echo link statements*/
        miUint          dont_echo;              /* EO_* bitmap: omit these */
        miUint          dont_recurse;           /* EO_* bitmap: no prereqs */
    } miEchoOptions;

    miBoolean mi_geoshader_echo_tag(
        FILE            *fp,
        miTag           tag,
        miEchoOptions   *eopt)

This function exists for debugging geometry shaders. It echos a .mi scene fragment, anchored at tag, to the stdio file fp. The options should be cleared with memset or similar, and then initialized (the structure occasionally grows; this way recompilation will suffice). The prefer_approx_polygons, prefer_approx_faces, norendercommand, and nolinkcommand must be miFALSE (0). ascii_output prints geometry vectors as ASCII numbers instead of the default binary vectors. verbatim_textures includes texture files in the echoed scene, instead of referencing them by file name. explode_objects, if nonzero, causes all objects with more than the given number of vectors to be echoed to independent subfiles; this is not generally useful for debugging. The dont_echo and dont_recurse bitmaps of miEO_ bits allow excluding certain scene element types. In a geometry shader it may be useful to set dont_recurse to to suppress echo of all tags that tag is referencing. See the command-line option -echo (appendix A) for more details.

    char *mi_string_substitute(
        char            *newname,
        char            *name,
        long            size)

This function [18] performs substitutions on the file path name, and returns the substituted path in newname, which must point to a char buffer of sufficient size ( miPATHSIZE is recommended). The size of the buffer must be passed as size to prevent buffer overruns. Substitutions are taken from the MI_RAY_SUBSTITUTE environment variable, the mental ray registry mechanism, and the (obsolete) Softimage Linktab mechanism. For details on the first two refer to [Driemeyer 01]. The value of newname is returned.

    miInteger mi_volume_num_shaders(
        miState         *state)

In autovolume mode, volume shaders can use this function to determine the number of overlapping volumes whose volume shaders have the same (highest) volume level as the current volume shader. This is the length of the list of volume shaders to call. Refer to the autovolume section on page autovolshd for more information on autovolumes. mental ray 3.2 also supports autovolume mode for photon emitters, so photon shaders can determine which photonvolumes a photon passes through.

    miInteger mi_volume_cur_shader(
        miState         *state)

In autovolume mode, volume shaders can use this function to determine their own position in the list of volume shaders to call. The first volume shader gets number 0.

    miTag *mi_volume_tags(
        miState         *state)

In autovolume mode, volume shaders can use this function to retrieve the list of volume shader tags scheduled for being called for this ray segment. The length of the list can be obtained by calling mi_volume_num_shaders.

    miTag *mi_volume_instances(
        miState         *state)

This function is a companion function to mi_volume_tags. It returns a constant pointer to the leaf instances through which the current ray is traveling. The n-th instance tag in the returned array corresponds to the n-th volume shader tag in the array returned by mi_volume_tags. A volume shader could use this function to store the instance it is associated with to (which otherwise holds the instance of the hit primitive) to enable correct object transformations from the vector_to_object and point_from_object family. The instance tag can also be used to obtain instance-specific user data.

    void mi_opacity_set(
        miState         *state,
        miColor         *color)

3.2 This function has an effect in the rasterizer rendering mode (formerly called Rapid Motion) only. Since the rasterizer handles transparency in a separate shading sample combination pass and not inside the material shader, the shader cannot normally create matte objects by returning a transparent color regardless of other objects behind the shaded surface. The shading sample combination phase would fill in the obscured objects. In this case, the shader may use mi_opacity_set to explicitly set the opacity to be used for combining instead oif the result alpha. As a bonus, the opacity may be set for R, G, B, and A separately, instead of using the result alpha for all components. The color is saved along with the result color returned by the shader until the combination phase.

    miBoolean mi_opacity_get(
        miState         *state,
        miColor         *color)

3.2 After mi_opacity_set has been called at any point for the current surface shading point and all its secondary rays, it remains in effect until the rasterizer (formerly called Rapid Motion) shades the next surface point. It is saved along with the returned color until shading sample combination. Since any of the shaders of a Phenomenon can call mi_opacity_set, the companion function mi_opacity_get can be used to retrieve the opacity color last set. This is also useful in volume shaders that need to control matte opacity. The function returns miFALSE if mi_opacity_set has not been called for the current shading point yet; in this case color is undefined.

    miColor *mi_volume_user_color(
        miState         *state)

In autovolume mode, volume shaders can use this function to store an arbitrary color value. This is useful for communication between different volume shaders in the list. For example, the first volume shader can initialize this value, and the last can return it.

[18] This function was introduced in mental ray 2.1.36.

home << prev next >> contents  

Copyright © 1986-2007 by mental images GmbH