Shadows and Environments

To make a shadow texture map, the -shadow option must be used, and the input depth image is read from a zfile that is produced by the zfile (4) display driver.

In order to make an environment texture, the -envlatl option may be used to convert a latitude-longitude image into a latlong environment texture, or the -envcube option can be used to convert a set of six cube face images into a cube face environment texture. In the cube face case, the -fov angle option can be used to specify a field-of-view angle in degrees, if the default field of view of 90 degrees was not used. The field of view may vary from 90 to 179 degrees.

In the case of a cube-face environment map, selected with the -envcube option, the input consists of a sequence of six image names corresponding to six cube face views in the order: px, nx, py, ny, pz, and nz. The option selects the cube-face environment case. In all other cases, the input consists of a single image name.

A new parameter -shbands can be used with envcube and envlatl textures to precompute a spherical harmonic representation of the reflection function of the given input image. This can then be used with txinfo() in a shader to perform very fast, low frequency environment lookups.

A ptexture envcube can be created with the -penvcube option. This option behaves exactly like the -envcube option, however it generates the environment cube as a ptexture file. The advantage of the ptexture file is that it provides significantly better filtering when the environment map is looked up with the environment() call using a large blur.

Formatting and Resolution

Standard TIFF black-and-white, grayscale, color-mapped, and RGB full-color images (TIFF B,G,P,R) are accepted, with the exception that only images with 1, 2, 4, or 8 bits per sample are accepted. In addition to the standard classes, 16 bit-per-sample RGB images and single-precision floating point images are accepted as are 4-channel images.

The -format option can be use to output files as Pixar texture files (txmake -format pixar), Pixar tiff textures (txmake -format tiff), or OpenEXR textures (txmake -format openexr). The default setting is tiff textures. The default behavior may be changed in the rendermn.ini file.

Textures are indexed using (s,t) coordinates ranging from 0 to 1. Note that the coordinates of a texture map are like the coordinates of a raster image: the pixel with texture coordinates (0,0) is at the upper left corner of the image. The s coordinate increases to the right and the t coordinate increases from top to bottom.

For reasons internal to the texture mapping software, texture files must be an even power of two in width and height. Any input image that is not already a power of two in both dimensions will be resized, as described below.

For shadow textures, the resolution of the texture file is derived from the height and width of the image file, each rounded up to the next larger power of two. For example, a 256x512 image file will generate a 256x512 texture, while a 250x84 image file will generate a 256x128 texture. Additional black (zero) pixels are added to the picture data as necessary to fill the texture file. The shadow operation may be incorrect for input images that are not sized to powers of two.

Resizing

For simple textures or environment textures the resolution of the texture file is determined from the height and width of the image file and the operation specified by the -resize option. If either the width or the height of the image is an exact power of two, that dimension is left unchanged. Any dimension that is not an exact power of two will be adjusted according to the -resize operation. The resize operation may be one of the following:

up

the image is resized up to the next higher power of two. Texture access will correct for the resize.

down

the image is resized down to the next lower power of two. Texture access will correct for the resize.

round

the image is resized to the nearest power of two. Texture access will correct for the resize.

up-

the image is resized up to the next higher power of two. Texture coordinates will be 0 to 1 across the resulting image.

down-

the image is resized down to the next lower power of two. Texture coordinates will be 0 to 1 across the resulting image.

round-

the image is resized to the nearest power of two. Texture coordinates will be 0 to 1 across the resulting image.

none

the image is not resized, the texture map size will be the next higher power of two. Texture file area not covered by the image will be set to black. Texture coordinates will be 0 to 1 across the resulting image. This is compatible with previous releases.

The default resize operation is up. When texture access corrects for the resize operation, as in up, down and round, the texture coordinates are 0 to 1 across the longest dimension and adjusted by the image aspect ratio across the shorter dimension so that image pixels will remain square if texture mapped onto a square patch.

The resize operation uses the filter specified by the -filter option. The recognized filters are the standard RenderMan filters: point, box, triangle, sinc, gaussian, gaussian-soft, catmull-rom, mitchell, cubic, lanczos, blackman-harris, and bessel. If no filter is specified catmull-rom is used. The amount of blur applied when filtering is determined by either the -blur option to specify the same amount in the s and t directions, or the -sblur and -tblur options to specify different amounts in the s and t directions. If no blur is specified, a default of 1.0 is used. (Which means no blurring is applied).

Wrap Modes

The -mode, -smode, and -tmode options can be used to specify the desired texture coordinate wrap modes that will be used to access the texture. -mode sets both s and t coordinate modes, while -smode sets only the s coordinate mode, and -tmode sets only the t coordinate mode. The legal modes are black, clamp, and periodic. The default mode for both s and t is black. The resize operation takes the wrap mode into account for the resize filtering at the texture edges.

Channels

By default, the number and order of channels in the texture file depends directly on the set of channels in the image file. This holds true for multi-channel OpenEXR files as well. An RGBA picture will generate a four-channel texture. An RGB picture will generate a three-channel texture. An R picture will generate a one-channel texture. The -ch option can be used to select and reorder the channels of the image file. The channel #'s are used to select the channels of the image file. Note that channels begin at channel 0 (zero) and if your image only has a single channel it is 0. For RGB -ch 1 selects only the green channel of the image file and puts it into channel 0 of the texture file. A list of numbers can be used to select multiple channels, for example, -ch 0,1,2 will select the RGB channels of the image file, and -ch 2,1,0 will select the RGB channels and put them into the texture channels in the order: blue, red, green.

By default, the precision of each texture channel is 8 bits per pixel. The -short option can be used to change the precision of each texture channel to 16 bits per pixel. The texture contents are signed 16 bit integers. When making short textures from TIFF images, txmake uses the appropriate TIFF tags to determine if the image data is signed or unsigned and properly converts to the signed texture data format. The -float option can be used to change the precision of each texture channel to 32 bits per pixel floating point. Floating point textures can be made from TIFF images with 32 bits per pixel and their sample format set to IEEE floating point. The -lossy option outputs the floating point textures in a format that provides better compression while still preserving much of their dynamic range.

Shadow maps are always 32 bits per pixel floating point.

Patterns

The -pattern option can be used to control the set of filtered texture resolutions that are generated by txmake and stored in the texture file. By default, the pattern is diagonal, which means that lower resolution textures are generated by successively reducing the texture image to one-half of its resolution in both the s and t directions. This results in a texture file which is approximately one-third larger than the original texture image.

Other patterns are:

single

Only a single texture image is stored in the texture file. This will result in very poor texturing performance for most applications.

all

A more complete set of texture images is stored in the texture file. This will make the texture file approximately four times as large as the original texture image (that is, four times as large as the single case). Texturing performance may be better than the default diagonal pattern for images in which the texture is applied to a severely foreshortened surface, or when the range of one texture coordinate is far different from the range of the other.

Shadow maps always use the single pattern.

The -mipfilter option can be used when creating textures with the diagonal or all pattern. This can reduce aliasing in certain conditions where the input image contains high frequency content. The same filters can be used as the resizing filters mentioned above.

Extra Args

Extra arguments can be passed to txmake to enable behavior for certain kinds of texture map creation. Currently a single -extraargs is supported and it is displaywindow. With this option, if an input image is OpenEXR with a display window, it will frame the resulting output texture at the resolution of the display window (the default is to frame using the data window).

User mipmaps

The -usermipmap option allows the specification of mipmap levels. Usage of this command is as follows:

txmake -usermipmap picnames txtname

The files in picnames correspond to the levels in the pyramid (first name in picnames = highest resolution level of the pyramid). Note that there are several rules for generating these "user mip-maps":

• The first image determines the transformation matrix to be put into the texture.
• The first image determines the texture's dimensions.
• All images listed in picnames must have the same number of channels.
• An image listed in picnames must be at least as large as the corresponding pyramid level (i.e. a 4x4 image can't go into an 8x8 image).
• Images in picnames must all be the same relative dimensions (i.e., a 4x2 image and a 4x4 image are not compatible, but 4x4 and 8x8 are compatible as are a 4x2 and a 8x4.)
• Unless the format is tiff, no image listed in picnames can be larger than the first image.
• Unless "singl" is chosen, then the last image listed in picnames will be filtered up the rest of the pyramid.

Diffuse Convolution

txmake can produce side-band data for use in the control variates method of Monte Carlo integration. The side-bands are the convolution of a diffuse BRDF with an environment map. Only lat-long maps are supported. OpenEXR and TIFF files are supported. The command line option is:

txmake -diffconv brdf,xres,mip

Where:

brdf is one of {Lambert, KajiyaKay}. This is required.

xres is the image width in a mip-map pyramid at which the convolution will be computed. This is optional and defaults to 256.

"mip" is optional and literal. If added, the convolution image will be mip-mapped, otherwise not (the other mip levels will contain black).

More than one convolution can be specified for a single image. So, for example,

txmake -format openexr -envlatl -diffconv Lambert,mip -diffconv KajiyaKay,128,mip in.exr out.env

will produce an image with 6 extra channels named: diffuseConvolutionLambert.{R,G,B} and diffuseConvolutionKajiyaKay.{R,G,B}. The Lambert channels will be black until the mip level whose width is less than or equal to 256. From there on down they will be populated. The KajiyaKay channels will be black until width less than or equal to 128, and black below there.