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 or 2, default is 1; mental ray 3.0 also supports 4 for floating-point textures with four bytes per component). For verbatim textures, a list of 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 file, while the skinny brackets around depth denote that the depth is optional and not part of the .mi file. 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. For a list of allowed file formats, see page picformats. 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; this requires the file exists locally on all slave hosts but reduces network transfer times drastically if many texture files or very large texture files are used. Filename rewriting is available for interpreting the remote filename locally, for example to translate between Unix and Windows NT 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 physical disks and not on NFS-mounted file systems (NFS stands for Network File System, distinguishable by the nfs type in the output of the Unix df command).

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, 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 explicitely 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 texture pyramids, a technique comparable to mip-map textures. during rendering. 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 color profile. 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, it is checked whether the texture is memory-mappable. This is the case if the texture file has the special uncompressed .map format. If this is the case, the texture is not loaded into memory but mapped into virtual memory. Memory-mapped textures use far less physical RAM and no swap space, but they use virtual memory. Memory mapping is especially 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), but is recommended for all nontrivial texture images. Memory-mapped textures are implicitly also local textures. Memory-map textures should be created with the imf_copy utility, with the -p option to create pyramids. 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.