Textures

[local] [filter [scale_const]] scalar texture "texture_name" "filename"
scalar texture "texture_name" [ width_int height_int [depth_int] ] bytes ...
writable scalar texture "texture_name" [ width_int height_int [depth_int] ]
writable scalar texture "texture_name" "filename" "filetype" ["fileformat"] [ width_int height_int ]
scalar texture "texture_name"shader_list

[local] [filter [scale_const]] color texture "texture_name" [colorprofile "profile_name"] "filename"
color texture "texture_name" [colorprofile "profile_name"] [ width_int height_int [depth_int] ] bytes ...
writable color texture "texture_name" [colorprofile "profile_name"] [ width_int height_int [depth_int] ]
writable color texture "texture_name" [colorprofile "profile_name"] "filename" "filetype" ["fileformat"] [ width_int height_int ]
color texture "texture_name"shader_list

[local] vector texture "texture_name" "filename"
vector texture "texture_name" [ width_int height_int ] bytes ...
writable vector texture "texture_name" [ width_int height_int ]
writable vector texture "texture_name" "filename" "filetype" ["fileformat"] [ width_int height_int ]
vector texture "texture_name"shader_list

Textures are lookup functions. They come in two flavors: lookups of two-dimensional texture or picture files or literal bytes, and procedural lookups. File textures require a file name parameter or a byte list; procedural textures require a shading function parameter. There are three types of texture functions: textures computing scalars, colors, and vectors. Which one is chosen depends on what the texture is used for. Textures are used as parameters to other shaders, typically material shaders. A material shader could, for example, use a color texture to wrap a picture around an object, or a scalar texture as a transparency or displacement map, or a vector texture as a bump map. The actual use of the texture result is entirely up to the shader that uses the texture.

All of the above syntax variations define a texture texture_name. The texture_name should be quoted to avoid reserved words and to allow non-alphabetic characters. This is the name that the texture will later be referenced as.

Verbatim or writable non-procedural textures can be defined by specifying the width and height of the texture and an optional depth (bytes per component, 1, 2, or 4, default is 1). For verbatim textures, a list of width × height × depth hexadecimal two-digit bytes follows, most significant digit first if depth is 2 or 4, in RGBA order for colors and UV order for vectors. Note, that the brackets around the sizes are literally part of the .mi syntax, while the skinny brackets around depth denote that the depth is optional and not part of the .mi syntax. These textures are called verbatim textures, and should be used with care because they can increase the scene file size enormously. Writable textures are primarily useful as the output of light mapping.

Non-procedural textures can also be defined by naming a texture or picture file; see file formats for the supported types. In this case, the sizes (width, height, and depth) are read from the file. If the local keyword is not present, the file is read once on the master host and then transmitted over the network to all slave hosts that participate in the rendering. With the local keyword, only the file name is transmitted to the slave hosts; the file is expected to exists locally on slave hosts. This allows to distribute the texture files to all the remote machines once by manual copying, thus reducing network transfer times during mental ray rendering drastically. Filename rewriting is available for interpreting the remote filename locally, for example to translate between Unix and Windows file paths. Maximum speed improvements are achieved if local files are memory-mapped pyramids (see the -p option of the imf_copy tool), and reside on local disks and not on network-mounted file systems. Most efficient memory usage together with reasonable performance, on the other hand, is achieved by using tiled texture formats which benefit from texture caching.

If the writable keyword is present, the texture is written to a file after it was written by a shader. This kind of texture is used by lightmap shaders to write back the light mapping result. Light mapping involves scanning the surface of an object, and collecting data for each point. This data is later written to a texture file. A typical example is "baking" indirect illumination into a texture that can then be simply texture-mapped at a later render pass, instead of computing the information at rendering time. If writable is specified then local should be specified as well because the file should be written to disk on the master host only. Writable textures always have to give the texture height and width in pixels. The depth may be given explicitly or be inferred from the file type. The file format of the file is usually derived from the file extension, but it is possible to provide an explicit file format.

The filter keyword, if present, enables texture filtering based on texture pyramids, a technique comparable to mip-map textures. Filtered textures are preprocessed before rendering begins and use approximately 30% more memory. Filtering should be used when the texture is large and seen at a distance, such that every sample covers many texture pixels. Without filtering, widely spaced samples "overlook" the areas between the samples; filtered textures perform a filter operation to take the skipped areas into account. The compression of the texture on the viewing plane can be scaled by the optional scale value if necessary.

Color textures may be flagged with an optional colorprofile. The texture is then assumed to be given in the color space described by this profile. The color values of the texture will be transformed to render color space before they are used.

When loading a texture image from a file, mental ray checks whether the texture is memory-mappable. This is the case if the texture file is stored in the special uncompressed .map format. In this case, the texture is not loaded into memory but mapped into virtual memory. Memory-mapped textures use far less physical memory and no swap space, they use virtual memory only (practically reducing available memory on computers with limited address range, like 32bit machines). Memory mapping might especially be useful for large textures that are not used often (i.e., many or most of its pixels are not sampled or the textured object is small or far away from the camera). Memory-mapped textures are implicitly also local textures. In addition, they always need to fit the byte order of the CPU on the local machine, otherwise they are read as regular files because they can not be memory mapped. Memory-map textures should be created with the imf_copy utility, with the -p option to create pyramids. Note, that the filter scale value is stored in the texture file as well, any other scale constant specified in the scene texture definition referencing such files is ignored. Note also, that color profiles should not be applied to memory mapped textures, since the resulting color space transformations would attempt to overwrite the original texture files with the color transformed textures.

Procedural textures are defined by naming a shading function with parameters; the shading function can either be one of the built-in functions or an external function from a code or link command.

When a shader evaluates a texture by calling a texture evaluation function, the program either looks up non-procedural shaders by looking up the texture in the range [0, 1) in each dimension, or it calls the named shader in the procedural case. The shader is free to interpret the point for which it evaluates the texture in any way it wants, two-dimensional or three-dimensional.