• home
• « prev
• next »
• index

• mi_query

Queries with mi_query

mi_query

    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:

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, 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).

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 for 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 retreive 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_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.

• home
• « prev
• next »
• index

Copyright © 1986-2009 by mental images GmbH