Obsolete Auxiliary Functions

These functions are obsolete; use mi_query for future implementations.

mi_light_info
    void mi_light_info(
        miTag           tag,
        miVector        *org,
        miVector        *dir,
        void            **paras)

tag is assumed to be a light source instance as found in a light parameter of a shader, or returned by mi_query. It is looked up, and its origin (location in internal space) is stored in * org, and its direction (also in internal space) is stored in * dir. If tag refers to a light source instead of the instance, both vectors are defined in local space. Since light sources can only have one or the other but not both, the unused vector is set to a null vector. This can be used to distinguish directional (infinite) light sources; their org vector is set to (0, 0, 0). The paras pointer is set to the shader parameters of the referenced light shader; if properly cast by the caller, it can extract information such as whether a non-directional light source is a point or a spot light, and its color and attenuation parameters. (mental ray considers a spot light to be a point light with directional attenuation.) Any of the three pointers org, dir, and paras can be a null pointer.

mi_global_lights_info
    int mi_global_lights_info(
        miTag           **tag)

Returns the address of an array containing all global light leaf instances. The tags in this array can be used like light shader parameters for calls to mi_sample_light and mi_light_info. One important difference between shader light parameters and global lights is that global lights are the result of instancing, so if a light is transformed and/or multiply instanced it will appear transformed and/or more than once in the global light list, while shader parameters will be accessed as stored in the scene with no instancing applied. It is recommended that translators that support multiple light instancing use material shaders that use the global light list instead of a light array in the shader parameter list (which, however, may still be useful as an argument for mi_inclusive_lightlist and mi_exclusive_lightlist).

mi_texture_info
    void mi_texture_info(
        miTag           tag,
        int             *xres,
        int             *yres,
        void            **paras)

tag is assumed to be a texture as found in a texture parameter of a shader. If tag refers to a procedural texture shader, * xres and * yres are set to 0 and * paras is set to the shader parameters of the texture shader. If tag is an image texture, * xres and * yres are set to the image resolution in pixels, and * paras is set to 0. Any of the three pointers can be a null pointer.

mi_shader_info
    void *mi_shader_info(
        miState         *state)

Returns a pointer to the user pointer of the current shader in the state, state→shader. This is useful for shaders that allocate memory during startup (in the instance init shader) and need a place to store the pointer to the initialized data in a place where shader instances can pick it up. A unique user pointer is returned for each shader instance (each unique function/parameters pair).

mi_instance_info
    int mi_instance_info(
        miState         *state,
        void ** const   paraspp,
        void ** const   spare1,
        void ** const   spare2,
        void ** const   spare3)

Returns the size of and a pointer to the inherited instance parameters. Instance parameters are attached to the instances of the scene DAG, and are combined in a scene DAG traversal step during scene preprocessing, before rendering begins. The structure of the inherited data is determined by the inheritance function or traversal function, not by the shader, and is generally under control of the translator that generated the scene. Typically, all instances contain either no parameters at all (size 0), or they all use the same data structure. The instance being checked is state→instance. The spare pointers must be passed as 0.

Copyright © 1986-2010 by mental images GmbH