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 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 is returned; the caller may modify the structure.
miTag mi_api_material_end(void)
Complete the definition of a material 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) /* bit0=local, 1=filter, 2=writable */
Begin the definition of a texture with the specified name. 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 a filter. This flag is ignored for procedural (function) textures.
Bit 1 of the flags, if set, enables pyramid filtering, an algorithm comparable to mip-map textures. mental ray will convert the texture to pyramid format, which takes about 30% more memory but allows filtered lookups. This avoids texture aliasing, which is a problem for point-sampled non-filter textures that are far away so that each point sample hits widely spaced pixels in the texture.
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.
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.
void mi_api_texture_set_colorprofile(
char *cprof_name)
remembers the name of the color profile describing the color space of the texture. If a rendering profile has also been provided, then the texture will be transformed from this color profile to the rendering color profile while it is read. The routine has to be called before mi_api_texture_file_def is invoked.
miTag mi_api_texture_file_def(
char *file) /* file name to open */
The new texture is defined as a file texture, using the path 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 */
The new 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 or 2 */
The final method of defining a texture is verbatim. It is equivalent to a file texture except that the pixel data is not read from a file on disk but is stored by the API caller using the texture copy calls below. This kind of texture cannot be flagged local. The texture resolution is set with the xres and yres arguments. The number of bytes per component is set with the zres argument. The number of components per pixel is determined by the type argument of the preceding call to mi_api_texture_begin: 4 for color textures, 1 for scalar textures, and 2 for vector textures. Vector textures always assume 4 bytes per component (one float) regardless of whether zres is 1 or 2. If the verbatim texture is filtered, only the highest resolution is given with 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 */
After the texture was defined, the contents of the texture must be copied. A total of xres · yres · zres · nc bytes must be copied, with zres being 4 for vector textures and nc being the number of components (1 for 8 bits, 2 for 16 bits, or 4 for floating point). The copy function can be called multiple times to collect the required number of bytes, the sum of all len arguments must be the total required number of bytes. The byte order is big-endian (MSB first) if zres is greater or equal to 1. Pixels are stored in pixel 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)
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.
miTag 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 */
If the color texture is writable, mental ray needs to know the size ( xres and yres) and the number of bytes per component ( zres, 1 for 8 bits, 2 for 16 bits, and 4 for 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 */
This function sets the filter constant of the texture. It must be set with this function instead of writing the filter value into the texture structure directly, as was done in mental ray 2.1, because the texture is created 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 .format, the filter value must be specified when the map file is created, using imf_copy's -f option.
void mi_api_texture_end()
ends the definition of a texture.
Copyright © 1986-2008 by mental images GmbH