Lights, Materials, Textures

mi_api_light_begin
miLight *mi_api_light_begin(
    char            *name)      /* light name */

Begin the definition of a light with the specified name.

A pointer to the light is returned; the caller may modify the structure.

mi_api_light_end
miBoolean mi_api_light_end(void)

Complete the definition of a light.

This function should be called after all parameters have been set.

mi_api_material_begin
miMaterial *mi_api_material_begin(
    char            *name)     /* material name */

Begin the definition of a material with the specified name.

A pointer to the material data structure is returned; the caller may modify its values.

mi_api_material_end
miTag mi_api_material_end(void)

Complete the definition of a material.

This function should be called after all parameters have been set. If an error occurs, a null tag is returned; otherwise the tag of the new material element is returned. The type of the returned element is miSCENE_MATERIAL.

mi_api_texture_begin
miTag mi_api_texture_begin(
    char            *name,     /* texture name */
    int             type,      /* 0=color, 1=scalar, 2=vector */
    int             flags)     /* bits: 0=local, 1=filter, 2=writable */

Begin the definition of a texture with the specified name.

This call is always the first stage of creating a texture, and must be followed by one of the next three def calls, which complete the texture definition. In incremental mode, the tag of the existing texture to be changed is returned; otherwise a null tag is returned. The tag is useful mainly to determine whether the previous texture was an image or a shader, using the mi_db_type function. The type of the texture and a flags bitmap must also be specified.

Bit 0 of the flags, if set, specifies that the texture is local. This is meaningful for image textures only, it specifies that each host on the network should read the image from its local file system instead of fetching the texture across the network. Memory-mapped textures are not flagged explicitly; they are recognized automatically at load time.

Bit 1 of the flags, if set, specifies that the texture image is looked up using pyramid filtering, an algorithm similar to mip-map textures. mental ray will compute the texture pyramid automatically if necessary, like when the input texture does not provide pre-filtered images. The pyramid takes about 30% more texture memory to accelerate filtered lookups. This avoids texture aliasing, a visual artifact typically appearing for point-sampled textures that are far away so that a single sample hits widely spaced pixels in the texture. This flag is ignored for procedural (function) textures.

Bit 2 of the flags, if set, specifies that the texture is writable. This flag should be set if the texture is attached to a lightmap shader that stores its data into the texture.

mi_api_texture_set_colorprofile
void mi_api_texture_set_colorprofile(
    char            *cprof_name)

Assign a colorprofile to the texture.

Set the name of the color profile describing the color space of the current texture. If a rendering profile has also been provided, then the texture color values will be transformed from this color profile to the rendering color profile upon reading.

Note This function needs to be called before calling mi_api_texture_file_def.

mi_api_texture_file_def
miTag mi_api_texture_file_def(
    char            *file)     /* file name to open */

Define the texture content to be read from file.

The path must be valid on the local host and, if the texture is local, on all other hosts on the network. If an error occurs, a null tag is returned; otherwise the tag of the new texture element is returned. The type of the returned element is miSCENE_IMAGE.

mi_api_texture_function_def
miTag mi_api_texture_function_def(
    miTag           function)   /* function with args */

Define the texture content to be computed by function.

The current texture is defined as a procedural texture, using the texture shader function. Function tags are created when defining functions, and are returned by mi_api_function_call_end. The local flag is ignored for procedural textures. If an error occurs, a null tag is returned; otherwise the tag of the new texture element is returned. The type of the returned element is miSCENE_FUNCTION.

mi_api_texture_array_def_begin
miBoolean mi_api_texture_array_def_begin(
    int             xres,       /* width in pixels */
    int             yres,       /* height in pixels */
    int             zres)       /* bytes/comp, 1, 2 or 4 */

Define the texture content verbatim as a byte stream.

This is similar to a file texture except that the pixel data are provided directly using the texture copy calls below. This kind of texture cannot be flagged local. The texture resolution is given with the xres and yres arguments. The number of bytes per component is set with the zres argument, like 1 for 8 bit, 2 for 16 bit, and 4 for 32 bit data. mental ray determines the number of components per pixel from the type argument of the preceding call to mi_api_texture_begin (1 for scalar, 2 for vector, and 4 for color textures). Vector textures always assume 4 bytes per component (one 32 bit float) regardless of the given zres value. If the verbatim texture should be filtered, only the highest resolution needs to be provided using the function mi_api_texture_byte_copy; the lower resolutions of the pyramid are built automatically by mental ray.

mi_api_texture_byte_copy
miBoolean mi_api_texture_byte_copy(
    int             len,       /* number of bytes */
    miUchar         *bytes)    /* from the mi file */

Copy the byte data to a verbatim texture.

After a verbatim texture was defined, its content needs to be provided. A total of xres · yres · zres · nc bytes will be copied, with zres being 1, 2, or 4 for 8 bit, 16 bit, or 32 bit data, respectively (and always 4 for vector textures), and nc being the number of components (1 for scalar, 2 for vector, and 4 for color textures). The copy function can be called multiple times to collect the total number of bytes, the sum of all len arguments must match the total byte count. The byte order is big-endian (MSB first) if zres is greater 1. Pixel values are stored in scanline order: first the bottom scanline is copied in RGBARGBA... order, then the next scanline, up to the top scanline. Scalar textures have only one component, vector texture pixels are stored U first, then V.

mi_api_texture_array_def_end
miTag mi_api_texture_array_def_end(void)

Complete the content of a verbatim texture.

After all texture bytes have been copied, the texture must be completed with this call. If an error occurs, a null tag is returned; otherwise the tag of the new texture element is returned. The type of the returned element is miSCENE_IMAGE.

mi_api_texture_file_size
miBoolean mi_api_texture_file_size(
    int             xres,           /* width in pixels */
    int             yres,           /* height in pixels */
    int             zres,           /* # of bytes per component */
    int             unused)         /* reserved, must be 0 */

Determine the file size of a writable texture with given resolution.

If the color texture is writable, mental ray needs to know the size of the file on disk. This function computes this value from the given input xres and yres and the number of bytes per component zres, 1 for 8 bits, 2 for 16 bits, and 4 for 32 bits floating point. The unused argument is reserved for future extensions to data types other then RGBA, and must always be set to 0.

mi_api_texture_set_filter
miTag mi_api_texture_set_filter(
    miScalar        filter)         /* value for filter scaling */

Set the filter scale of the texture.

The filter scale value must be set with this function instead of writing it into the texture structure directly, as done in older versions of mental ray, because the texture will be created only on demand. This function only works if the texture lives in memory. If it is a memory-mapped texture created with imf_copy using the .map format, the filter value must be specified when the map file is created, using imf_copy's -f option.

mi_api_texture_end
void mi_api_texture_end()

Completes the definition of a texture.

Copyright © 1986, 2013 NVIDIA Corporation