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:

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

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.

Copyright © 1986-2008 by mental images GmbH