[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Utility Classes

IMG_TextureMap Class

Description of classes

The purpose of IMG_TextureMap is to provide a mechanism for loading up texture maps and accessing them in an efficient manner. There are two classes of interest: IMG_TextureCache and IMG_TextureMap. The texture cache class is basically a verb class which is used to tune the configuration of the texture cache. You can specify the size of the cache (in images), the maximum resolution of each texture map, etc.

The texture cache contains a list of IMG_TextureMap classes. Each texture map is a reference to an actual image. When you have a texture map, you can specify specific lookup functions (for bump mapping, color lookup or depth map lookup). There are anti-aliasing versions (which do sub-sampling on the texture). The texture map handles 8 and 16 bit textures correctly (i.e. you don't have to worry what the bit-depth of the raster is set to).

The IMG_TextureMap class is primarily used in creation of TOP (Texture Operators). However, it also has uses for other operator types or even as a stand alone utility class (i.e. an expression function to evaluate a pixel of an image using interpolation of colors).


IMG_TextureCache

Usually, the application will control the cache parameters. However, it is possible to change these configuration parameters from within your code.

Method Description
setMaxSize This method sets the maximum size of a raster that can be loaded into the texture cache. If a map is too large, it will be filter scaled an loaded at the maximum resolution specified. Used in conjunction with the cache size, this can give you an upper bound on memory usage for the cache.
setCacheSize This method sets the maximum number of images that can be in the cache at one time.
setAutoFlush The texture cache is reasonably smart. Reference counts are kept for each image. If the auto-flush flag is set, then as images get dereferenced, the raster data will automatically be flushed out of the cache.
clearCache This will flush all the textures out of the cache. All the IMG_TextureMap references will have to re-load their images the next time that they are referenced.
setAllocator This method is a back-door to allow you to allocate raster memory using your own allocation mechanism. For example, this has been used in the past to allocate shared memory for the raster data so that the same raster data is shared across multiple processes.
setRenderAllocator This method is used to build an allocator for a specific hardware renderer.

IMG_TextureMap

A IMG_TextureMap is a reference to a texture map. The cache maintains an internal list of the actual raster data for the textures, while the texture maps are the mechanism for accessing the raster data.

When a IMG_TextureMap is created, no actual raster data is loaded into memory. Only when the map is actually accessed does the raster data get allocated. As well, it is possible that the raster data will get flushed out of the cache, only to be loaded next time the raster is accessed. This is all done automatically.

When looking up values, the u/v parameters should be in the range of 0 to 1 (not based on the resolution of the map). If the parameters go outside the range, they will be folded into a valid range for lookup. The anti-aliased color lookup works correctly over the boundaries of maps.

Method Description
getRaster This method will get a IMG_Raster pointer from the cache. loaded into the texture cache. If a map is too large, it will be filter scaled an loaded at the maximum resolution specified. Used in conjunction with the cache size, this can give you an upper bound on memory usage for the cache.
setColorLookup When looking up a pixel value as a color, this method sets the parameters for evaluation.
  • interp - specifies whether interpolation will be done for evaluation. If no interpolation is done, then the raw pixel value will be used, otherwise, bi-linear interpolation of pixel corners will be done.
  • alpha - specifies whether the fourth component of the color needs to be computed. Color lookup will be slightly faster if no alpha is needed.
  • setBumpLookup When evaluating a map as a bump map, you can compute the gradient (i.e. delta U/V) in one of several different ways (see IMG_BUMP_COMPUTE_TYPE). As well, the pixel values can be interpolated or set to the raw pixel values.
    getIdealSamples When looking up anti-aliased textures, this method will compute the "ideal" number of samples. That is, the number of samples required to get good quality sampling of the map.
    colorLookup There are two versions of this method. The first version will does point sampling of the texture map, while the second version will do anti-aliased sampling over a region of the map. Both methods return the color in a UT_Vector4. Please see the comment in the header file describing the correct order for specifying the u/v pairs when doing anti-aliased lookup. The color returned will be in a 0-1 scale.
    bumpLookup This method computes the gradient of a texture map. The values are returned in the du/dv pointers passed in. The maximum range for du/dv will be -1 to 1.
    depthLookup This method evaluates the picture as if it were rendered as a depth map. A depth map is stored as a single IEEE floating point number per pixel. Since the sizeof(float) == sizeof(rgba), we simply overload the color values with the floating point depth. This method allows you to query the depth of a map at a specific u/v value.

    Table of Contents
    Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
    Material & Texture | Objects | Command and Expression | Render Output |
    Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
    Customizing UI | Questions & Answers

    Copyright © 2004 Side Effects Software Inc.
    477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7