Previous: Appearances, Up: Conventions

#### 4.1.11 Texture Mapping

Some rendering back-ends support texture-mapped objects, actually only the OpenGL and the RenderMan interface at the time of this writing. There are also some issues with the RMan interface when using an alpha-channel in the texture image. Those rendering back-ends which don't support texturing silently ignore attempts to use texture mapping. A texture is specified as part of an appearance structure (see Appearances). Briefly, one provides a texture image (see Image objects), which is considered to lie in a square in `(s,t)` parameter space in the range 0 <= s <= 1, 0 <= t <= 1. Then one provides a geometric primitive, with each vertex tagged with `(s,t)` texture coordinates. If texturing is enabled, the appropriate portion of the texture image is pasted onto each face of the textured object.

There is (currently) no provision for inheritance of part of a texture structure; if the `texture` keyword is mentioned in an appearance, it supplants any other texture specification.

The appearance attribute `texturing` controls whether textures are used; there's no performance penalty for having texture { ... } fields defined when texturing is off.

The available fields are:

         clamp   none  -or-  s  -or-  t  -or-  st
           Determines the meaning of texture coordinates outside the range 0..1.
           With clamp none, the default, coordinates are interpreted
           modulo 1, so (s,t) = (1.25,0), (.25,0), and (-.75,0) all refer to
           the same point in texture space.  With s or t or
           st, either or both of s- or t-coordinates less than 0 or
           greater than 1 are clamped to 1 or 0, respectively.

         image { <image specification> (see Image objects) }
           Specify the actual texture image. Images can have 1, 2, 3 or 4 channels:
             1 channel:  luminance
             2 channels: luminance and alpha
             3 channels: RGB data
             4 channels: RGBA data

           See Image objects, for the actual definition of image
           objects. The alpha-channel is only interpreted as mask: where the mask
           is zero, pixels are simply not drawn. An exception is the case where
           apply is equal to modulate and translucency is enabled:
           in this case the resulting alpha value is the result of the
           multiplication of the surface color with the alpha value of the
           texture's alpha channel.

         file      filename
         alphafile filename
           This is considered obsolete, and only kept for compatibility,
           the modern way is to use the new OOGL image object. See Image objects.
           The stuff documented here should still work, though

           Specifies image file(s) containing the texture.

           The file keyword specifies a file with color or lightness information;
           alphafile if present, specifies a transparency ("alpha") mask;
           where the mask is zero, pixels are simply not drawn.
           Several image file formats are available; the file type must be
           indicated by the last few characters of the file name:
             .ppm or .ppm.Z or .ppm.gz  24-bit 3-color image in PPM format
             .pgm or .pgm.Z or .pgm.gz  8-bit grayscale image in PGM format
             .sgi or .sgi.Z or .sgi.gz  8-bit, 24-bit, or 32-bit SGI image
             .tiff                      8-bit or 24-bit TIFF image
             .gif                       GIF image
           For this feature to work, some programs must be available in
           geomview's search path:
             zcat  for .Z files
             gzip  for .gz files
             tifftopnm for .tiff files
             giftoppm for .gif files

           If an alphafile image is supplied, it must be the same size
           as the file image.

           Image objects provide a more flexible way to specify texture
           data. See Image objects.

         apply   modulate  -or-  blend  -or-  decal
           Indicates how the texture image is applied to the surface.
           Here the "surface color" means the color the surface would have
           in the absence of texture mapping.

           With modulate, the default, the texture color (or lightness,
           if textured by a gray-scale image) is multiplied by the surface color.

           With blend, texture blends between the background color
           and the surface color.  The file parameter must specify a
           gray-scale image.  Where the texture image is 0, the surface color is
           unaffected; where it's 1, the surface is painted in the color given
           by background; and color is interpolated for intermediate values.

           With decal, the file parameter must specify a
           3-color image.  If an alphafile parameter is present,
           its value interpolates between the surface color (where alpha=0)
           and the texture color (where alpha=1).  Lighting does not affect the
           texture color in decal mode; effectively the texture is
           constant-shaded.

         background  R G B A
           Specifies a 4-component color, with R, G, B, and A floating-point
           numbers normally in the range 0..1, used when apply blend
           is selected.

         transform transformation-matrix
           Expects a list of 16 numbers, or one of the other ways of representing
           a transformation (: handlename or < filename).
           The 4x4 transformation matrix is applied to texture coordinates,
           in the sense of a 4-component row vector (s,t,0,1) multiplied on
           the left of the matrix, to produce new coordinates (s',t')
           which actually index the texture.