Functions | |
void | Define_Texture (const char *texture_name, const char *definition) |
void | UnDefine_Texture (const char *texture_name) |
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. |
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
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"
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"
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"
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"
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"
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:
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"
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"
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"
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:
FIGURE 0.2 Effect of tiling method when texturing a surface
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 dx9 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)
[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:
FIGURE 0.3 Effect of interpolation filter when texturing a surface
[no] decimation filter = filter_type
This option is only supported in our hardware-accelerated 3d drivers (opengl, dx9 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
[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:
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)
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)"); Update_Display();
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.
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. |