void Define_Texture (const char *texture_name, const char *definition)
 Assigns a name to a set of texture mapping options. More...
void UnDefine_Texture (const char *texture_name)
 Removes all settings established by a previous call to Define_Texture(). More...

Detailed Description

Function Documentation

◆ Define_Texture()

void Define_Texture ( const char *  texture_name,
const char *  definition 

Assigns a name to a set of texture mapping options.

texture_name- The name this texture definition will be assigned to.
definition- A quoted string or a string variable containing a list of desired options for this specific texture.
Supported Options:
caching, camera, decal, down sampling, layout, modulate, parameter offset, parameterization source, transform, transform override, tiling, source, source callback, source callback data, interpolation filter, decimation filter, red channel mapping, green channel mapping, blue channel mapping, alpha channel mapping, value scale,


Texture mapping is a method of giving rendered surfaces high detail at minimal computational cost. For example, rather than inserting thousands of individually colored faces to simulate a wood-grain surface, a texture map could be used to "paint" an image of wood-grain onto a set of shell faces.

Texture mapping works by linking every pixel of a face to a corresponding "texel" (texture element) of a HOOPS image (one of many possible texture sources). As a textured face is drawn, the referenced image texels are used to modulate one (or more) of the surface's material properties. Defined texture names are used with the Set_Color() routine to assign textures to specific material properties.

The most common method of defining the connection between shell or mesh surface pixels and image texels is with a texture coordinate at each vertex (set by MSet_Vertex_Parameters() ). Other methods are described below.

The following diagram illustrates the stages involved when texturing, where each stage is a settable option of the texture definition.

FIGURE 0.1 The texturing pipeline, defined by Define_Texture

The definition parameter to Define_Texture() is a comma-separated list of options which can include the following:

[no] caching

When set, 3dGS will do its best to reduce the memory impact of using textures. This may be of use for developers who are using large textures extensively.

default value: "no caching"

[no] camera = segment

This option allows you to specify which segment's camera should be used for rendering a "skybox". You can make a skybox by creating a cube texture and setting that as your window color via Set_Color as described in the HOOPS/3dGS Programming Guide entry on skyboxes and cube maps.

default value: "no camera"

[no] decal

This setting is only relevant when the texture is applied to diffuse channel 0. When set, any transparent portions of the texture show the underlying diffuse color, rather than making the entire material transparent.

default value: "no decal"

[no] down-sampling

Instructs HOOPS not to down-sample images that exceed 512x512 pixels, but instead to try and create a texture as close as possible to the original size of the image, without exceeding the texture size limit on the graphics card. For textures, many graphics cards have a limit of between 512x512 and 4096x4096 pixels.

default value: "no downsampling"

layout = (unknown | rectilinear | spherical) [unknown]

Normal texturing assumes "rectilinear", a simple0->1 mapping in x & y. Environment mapping assumes "spherical", a sort of distorted polar coordinates, as defined by OpenGL for environment mapping. The default value, "unknown", means the code can assume the layout is whatever is appropriate for the usage.

default value: "unknown"

[no] modulate

This setting is only relevant for diffuse channels. When set, the texture will modulate, rather than replace, materials that came before it (for diffuse channel n, this would be first the underlying surface color then all diffuse channels i < n.
Note that this explicit modulate setting is distinct from the implicit modulation set as part of the color, e.g. Set_Color ("red brick"), where "brick" is a previously defined texture. If "brick" were defined with modulation turned on, then Set_Color ("diffuse color = red, diffuse texture = brick") would have the same visual effect.

default value: "no modulate"

parameter offset = x

Specifies how far into each vertex parameter list to skip before coming to the texture parameters for this specific texture. If the offset exceeds the number of parameters at each vertex, then 0 is assumed.

default value: "0"

parameterization source = source

In order to apply a texture to a surface, each pixel of the rendered surface must be "mapped" to a texel in the texture source. The "parameterization source" option allows you to specify which of the surface's parameters will be used for the surface-pixel to image-texel mapping. Currently, the only valid choices for source are the following:

  • cylinder
    Automatically creates the texture map based on a cylindrical mapping.

  • natural uv
    Stretches the texture along meshes and NURBS surfaces according to their natural internal parameterization. For meshes this is range [0..1]. For NURBS surfaces this is range [0..(control point count - degree)]. Shells do not have a natural parameterization, so the [u,v] coordinates are generated according to the following formula: [u=x+z, v=x+y], where x, y, and z are object space coordinates.
  • object
    The XYZ coordinates of the local geometry. Identical to world space (see below) except that this coordinate system is before modelling matrices are applied.
  • physical reflection
    An alternative setting for environment mapping. When set, this calculates the environment coordinates as a reflection between the normal (to the item being textured) and the view vector. The result is that the environment map is not held at a fixed position.
  • reflection vector
    This is the recommended setting for an environment map. It matches the behaviour of OpenGL environment mapping, in that the environment is held at a fixed position along the view vector.
  • surface normal
    The surface normal computed for the local screen pixel.
  • sphere
    Automatically creates the texture map based on a spherical mapping.
  • uv
    Used for traditional image based texture maps. The parameterization source comes from a user supplied (u,v) coordinate set with the MSet_Vertex_Parameters() routine.
  • world
    A three-valued parameter (XYZ) corresponding to the surface pixel's 3D world coordinate position (the coordinate system of geometry after modelling matrices have been applied, but before projecting through a camera into a window). The Z value is ignored unless there is a texture matrix that has set.

Although these parameters are defined only at shell or mesh vertices, values are interpolated for all interior pixels.
For all parameterization sources, a 4 component vector is generated. Sources with fewer than 4 components are padded as follows:

  one parameter (i)       [i, 0, 0, 1]
  two parameter (i,j)     [i, j, 0, 1]
  three parameter (i,j,k) [i, j, k, 1]
default value: "uv"

[no] transform = segment

Once a parameter has been selected (or perhaps generated if there was a parameterization source), the resultant four component vector can be further transformed with a "transform" 4-by-4 matrix. The result is a [u/h, v/h, w/h] texture coordinate (where "h" is the resultant homogeneous coordinate, and is normally 1.0).
Texture matrices (e.g. from Translate_Texture() or Rotate_Texture()) are inherited and concatonated just like modelling matrices (e.g. from Translate_Object() or Rotate_Object()). The "transform" texture definition option allows the user to specify a source for an additional texture matrix to be concatonated. This works in a manner similar to the Style_Segment() routine. If no texture matrix is present at the specified segment, this setting has no effect. Changes to the texture matrix at the specified segment will be respected.

default value: "no transform"

[no] transform override

When set, the only transforms which are applied to the texture are the ones which are specified explicitly in the texture definition. All transforms defined via Rotate_Texture() or Translate_Texture() are ignored.

default value: "no transform override"

[no] tiling = style

With the texture coordinate resulting from the above definitions, it is possible for some screen pixels to have texture coordinates outside the texture's legal range (from 0 to 1). The "tiling" option controls how parameters outside the legal range are remapped to legal range. Legal choices include the following:

  • clamp
    Any "U,V,W" surface coordinate components outside the [0.0, 1.0] range are clamped to either 0.0 or 1.0, whichever is closer.
  • drop
    Same as clamp, but the outer texels of the image will be treated as if they were transparent (i.e. outside of the [0.0, 1.0] range it will show the previous texture, the underlying face's diffuse color or nothing at all depending on whether it is multitextured, decal or neither).
  • repeat
    A modulo operation is performed on any "U,V,W" surface coordinate components outside the legal range. This is useful when you want a pattern to repeat without visible "seams".
  • mirror
    Similar to "repeat", but every other modulo is inverted (see diagram below).
  • off
    Identical to "clamp".
  • on
    Identical to "repeat".

FIGURE 0.2 Effect of tiling method when texturing a surface

default value: "tiling=repeat"

source = (name1 | name1, name2, name3, name4, name5, name6)

The name of the texture data source. The name is provided to HOOPS through a named HOOPS image (see Insert_Image() ). If a single name is provided, then the newly created texture can be applied to any shell-based geometry in the scene. If a list of six names is provided then a cube map texture is created. This texture can then be used to create a skybox via Set_Color("window= texturename") or be used as an environment map which is available of the dx11, and opengl2 drivers. The order the images are placed in the list controls the plane on which the image is placed such that the order is negative Z-plane, positive Z-plane, negative X-plane, positive X-plane, negative Y-plane, positive Y-plane.

Please note that the output from any texture source is a four component color vector (red, green, blue, alpha). Texture sources with fewer components are padded as follows:

  one component (a)         [a, a, a, 1.0]
  two component (a,b)       [a, a, a, b]
  three component (a,b,c)   [a, b, c, 1.0]
default value: <none> (if a value is not provided, HOOPS will issue a warning)

source callback

Textures may be defined with an image as the source data or with a callback which provides the image data. The callback is invoked at draw time and has the prototype:

void foo(
int width, // width HOOPS says the image is
int height, // height HOOPS says the image is
int row, // row HOOPS wants
int * rwidth, // output - how wide the callback says the image is
int * rheight, // output - how tall the callback says the image is
int * count, // output - how many rows we're returning in data right now
char ** data, // output - return the row pointer to HOOPS
int counter,
void * callback_data, // source callback data

Any of the output pointer parameters call be NULL, so the callback MUST check for NULL pointers. See "source callback data", below.

source callback data This is a pointer which is passed to the callback in the "callback data" parameter.

static void imageCallback(
int width,
int height,
int currentrow,
int * rwidth,
int * totalheight,
int * rheight,
char ** data,
int counter,
void * callback_data)
/* Do something interesting */

Example usage:

HC_Define_Callback_Name("the_callback", HIM_FUNCTION(imageCallback));
HC_Define_Texture("btexture", H_FORMAT_TEXT("source callback = the_callback, source callback data = %s", kto0xa(p2)));

[no] interpolation filter = filter_type

The interpolation filter affects how HOOPS retrieves data from texture sources composed of a grid of texels. When the texture coordinate samples a location between four neighboring texels, the following filter_types can be used to retrieve data from the texture:

  • bilinear
    The texture data from the four closest texels to the texture coordinate are blended using a weighted average (bilinear interpolation).
  • stochastic
    A form of interpolation that adds "noise" to the texture coordinates in order to simulate bilinear interpolation.
  • off
    The data from the texel closest to the texture coordinate is returned.
  • on
    Identical to "bilinear".

On systems that implement texture mapping in hardware, the interpolation filters available might not match the filter requested. In this case, the device driver is free to substitute an implemented filter for the purpose of performance. If this substitution is not desired, the driver can be forced to use the HOOPS built-in renderer with the rendering option "lighting interpolation=phong".

FIGURE 0.3 Effect of interpolation filter when texturing a surface

default value: "no interpolation filter"

[no] decimation filter = filter_type

This option is only supported in our hardware-accelerated 3d drivers (opengl_Deprecated, dx11, and opengl2).
When the area of a screen pixel maps to several texels, undesired aliasing can result. "Decimation" is a method of prefiltering texture images to prevent such aliasing by producing lower resolution versions of the image. Using a decimation filter generally doubles the amount of memory required to perform texture mapping. Legal values for filter_type include

  • anisotropic
    Advanced downsampling algorithm that generates better quality textures, particularly when viewed from non-orthogonal directions.
  • mipmap
    Basic downsampling technique that ensures that the downsampled image maintains a power of two.
  • off
    No decimation is performed, and data is retrieved from the textures using the selected "interpolation filter" method.
  • on
    Identical to "mipmap".

default value: "no decimation filter"

[no] red channel mapping = source
[no] green channel mapping = source
[no] blue channel mapping = source
[no] alpha channel mapping = source

For each of the four color channels (red, green, blue, and alpha), you can define the source of the channel. This is useful, for example, when you want to swap the red and blue channels for a special effect. For each color channel, the output can be selected from the following source inputs:

  • red
    The output of the color channel will be from the red channel input.
  • green
    The output of the color channel will be from the green channel input.
  • blue
    The output of the color channel will be from the blue channel input.
  • alpha
    The output of the color channel will be from the alpha channel input.
  • zero
    The output of the color channel will be equal to zero, regardless of what the input channels are.
  • one
    The output of the color channel will be equal to 1, regardless of what the input channels are.
  • luminance
    The output of the color channel will be equal to the luminance value of the red, green, and blue input channels combined. This is useful when your texture source is full color, but you desire a grayscale texture.

The defaults are "no red channel mapping, no green channel mapping, no blue channel mapping, and no alpha channel mapping". (Therefore, no channels are remapped.)

value scale = (scale_min, scale_max)

Once the color intensities have been retrieved from the texture source, you may wish to rescale them in order to brighten or dim the overall texture. Incoming samples from the texture source are in the range 0.0 to 1.0. They are scaled to the range scale_min to scale_max.

default value: "no red channel mapping, no green channel mapping, no blue channel mapping, no alpha channel mapping" (no channels are remapped)


The "texture interpolation" rendering option needs to be enabled if you wish to see textures in your scene. (see Set_Rendering_Options() ).

Texture mapping both edges and faces simultaneously (with both visible) does not make sense (texture mapping just faces renders the same image) and will perform slowly. Normally, you should turn off edge visibility (with Set_Visibility() ) when texture mapping faces.

Here is an example (in pseudo-C) showing the steps used to perform texture mapping:

        Insert_Image(0., 0., 0., "RGB, name=brick_image",128,64, brick data);
        Define_Texture("brick_texture","source = brick_image");
        key = Insert_Mesh(2, 2, mesh_points);
        MSet_Vertex_Parameters(key, 0, 4, 3, UVW_vtx_coords);
        Set_Color("faces=(diffuse = red brick_texture)");


Texture names may be guarded with regular quotes, single quotes, or back quotes ( ", ', or ` ). If guarded, the quotes must come at the beginning and end of the texture name. In between, any character other than the null-terminator or carriage return may appear ('\0' or '\n'). Interior quotes of a different type may be used as-is (e.g. "elmo's world"). Interior quotes of the same type must be escaped by doubling them (e.g. 'elmo''s world').

Enclosing texture names in quotes (any one of the three quote styles are ok) is recommended, but not required. If unguarded, the texture name must not contain any of the following characters: '\0', '\n', '\'', '"', '‘’, ' ', '/', '?', '^', ',', '{', '}', '<', '>', '[', ']', '!', '(', ')', '=', '@', '&', '#', ';', '|' or any unprintable characters (outside of the range 0x20 to 0x7F). Unguarded texture names are automatically converted to lower case.

The restriction against '\0' and '\n' mean that even guarded strings may not contain wide character data (e.g. unicode) as-is. To use wide characters as texture names, we recommend that the user encode either as uuencode or utf-8.

See also
Begin_Texture_Search, Insert_Image, MSet_Vertex_Parameters, Set_Color, Set_Texture_Matrix, Set_Parameter, Set_Rendering_Options, Show_Texture, UnDefine_Texture.

◆ UnDefine_Texture()

void UnDefine_Texture ( const char *  texture_name)

Removes all settings established by a previous call to Define_Texture().

texture_name- The name this texture definition will be assigned to.


No additional details. See Define_Texture()