• home
• « prev
• next »
• index

• mi_query

Queries with mi_query

mi_query

miBoolean mi_query(
    miQ_type    query,
    miState *   state,
    miTag       tag,
    void *      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:

The  ◊  symbol in the state column indicates that the state is not used. The  ◊  symbol in the tag column means that miNULLTAG must be passed.

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

Note The 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).

miQ_FUNC_PARAM_VALUE

This query can be used to retrieve the value of a shader input parameter that is not connected. The result should point to a variable of sufficient size to hold a value of the specified parameter type. Here is an example which retrieves an "intensity" parameter value of a shader:

miScalar    intensity = 0.0;
if (mi_query(miQ_FUNC_PARAM_VALUE, 0, tag,
             &intensity, "intensity", miTYPE_SCALAR) == miTRUE) {
    ... /* use valid intensity value */
    }

The query will fail by returning miFALSE under the following conditions:

• the given tag doesn't refer to a shader,
• the parameter is not an input parameter,
• the parameter is an array or struct,
• the requested parameter type doesn't match the actual type of the parameter with the given name.

miQ_INST_VISIBLE
miQ_INST_SHADOW
miQ_INST_TRACE
miQ_INST_CAUSTIC
miQ_INST_GLOBILLUM

The result of these 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 of the instance data structure.

The miQ_INST_ modes should be used instead of the miQ_OBJ_ modes because they return the same modes that mental ray uses when rendering.

miQ_LIGHT_ORIGIN
miQ_LIGHT_DIRECTION

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

miQ_TILE_PIXELS
miQ_TILE_SAMPLES

These codes retrieve the location and size of the currently rendered image tile. The returned values are in the order x_low x_high y_low y_high. 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 pre-computing stage: for finalgather pre-computing the return value is miFALSE since no tile exist.

miQ_SAMPLE_MOVING

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

miQ_NUM_TEXTURES
miQ_GEO_LABEL

These query codes may only be used if state→pri has not been modified by the shader or calling shader. Ray-marching volume shaders sometimes clear this state variable. The miQ_GEO_LABEL query also returns miFALSE if the object is not marked tagged and no polygon/surface labels exist.

miQ_PRI_ASSEMBLY_INST_TAG

For a valid intersection state, the assembly leaf instance for the hit primitive is returned. If the geometry does not belong to an assembly, the miNULLTAG is returned. This query mode may be used by shaders to implement custom attribute inheritance from the main scene file.

miQ_PRI_DATA

This query mode 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.

miQ_PRI_NUM_VERTICES
miQ_PRI_VERTICES_POINTS
miQ_PRI_VERTICES_NORMALS
miQ_PRI_VERTICES_MOTION
miQ_PRI_VERTICES_TEX
miQ_PRI_VERTICES_USER
miQ_PRI_VERTICES_BUMPS_*
miQ_PRI_VERTICES_DERIVS_*

These query modes return per-vertex data of the current primitive, as delivered with the source geometry, or computed by mental ray during approximation and tessellation. It is the callers responsibility to pass sufficiently large memory which will be filled by the function. The query code miQ_PRI_NUM_VERTICES allows to determine how many vertices the current primitive has. For a tessellated surface, this number will be 3 for the vertices of the currently rendered triangle. Other primitives like hair may return an arbitrary number of values. Here is an example how to retrieve the normals and the texture vectors of the second texture space for a triangle :

miUint  num = 0;
/* we like to deal with triangles only, like in mi_tri_vectors() */
if (mi_query(miQ_PRI_NUM_VERTICES, state, 0, &num) && num == 3) {
    miVector    n[3], t[3];
    miUint      tex_space = 2;

    if (mi_query(miQ_PRI_VERTICES_NORMALS, state, 0, &n)
    &&  mi_query(miQ_PRI_VERTICES_TEX, state, 0, &t, tex_space) {

        /* use the values */
    }
}

This functionality is the recommended replacement for the function mi_tri_vectors.

miQ_PRI_PARTICLE_INDEX
miQ_PRI_PARTICLE_TYPE
miQ_PRI_PARTICLE_UV

These query modes return data of the currently hit particle of a particle object. The function call returns miFALSE if no particle was hit. The intersection coordinates returned for the particles shapes are as follows:

Spheres

the first value U is the azimuth angle in the range [0,1] around the Z axis, and the second value V is the elevation angle in the range [-1,1] from the XZ plane (in object space).

Tubes

the first value U is the azimuth in the range [0,1] around the tube axis (in object space), and the second value V is a number in the range [0,1] representing the position of the intersection point along the tube axis relative to the base, with 0.0 at the base and 1.0 at the tip.

• home
• « prev
• next »
• index

Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.