• 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. 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 (state→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 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_MOVING 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 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.

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.

• home
• « prev
• next »
• index

Copyright © 1986-2008 by mental images GmbH