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.
miBoolean mi_api_light_end(void)Complete the definition of a light.
This function should be called after all parameters have been set.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
void mi_api_texture_end()
Completes the definition of a texture.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.