Texture Map Object

Introduction

Texture mapping is the technique of overlaying a raster image on top of another data type. Although all graphical objects are required to have a material, none are required to have a texture map. Texture mapping can be used for much more than just overlaying an image onto a surface. For more information look at the section Advanced Topics.

A texture map object is created using the function XintView3DCreateTextureMap.

XintView3DTextureMap *XintView3DCreateTextureMap(
	                              char	*name,
	                              int	type,
	                              int	format,
	                              int	blend,
	                              int	width,
	                              int	height,
	                              float	*image,
	                              float	**mipmaps,
	                              Boolean	build_mipmaps,
	                              int	mag_filter,
	                              int	min_filter,
	                              Boolean	clamp_s,
	                              Boolean	clamp_t,
	                              XintView3DAutoTexture *auto_data,
	                              Boolean	conserve_memory);

Formats

Arguments type, format and blend are used to define the style of texture map to generate.

The texture map type can be set to one of the following values:

XintTEXTURE_1D - Generate a 1D texture map. This can be useful for mapping elevation information onto an object. It defines a single row of data.
XintTEXTURE_2D - Generate a 2D texture map. This is the most commonly used texture map format. It defines an MxN image.
format defines the format of the data stored in the texture map image:
XintTFORMAT_RED - The texture map contains an array of floating point values. Each value represents an intensity of red. Blending operations will only affect the red component of the underlying color.
XintTFORMAT_GREEN - The texture map contains an array of floating point values. Each value represents an intensity of green. Blending operations will only affect the green component of the underlying color.
XintTFORMAT_BLUE - The texture map contains an array of floating point values. Each value represents an intensity of blue. Blending operations will only affect the blue component of the underlying color.
XintTFORMAT_LUMINANCE - The texture map contains an array of floating point values. Each value represents an intensity value. Blending operations will affect the red, green and blue components of the underlying color equally.
XintTFORMAT_LUMINANCE_ALPHA - The texture map contains an array of floating point pairs, luminance and alpha (transparency). The luminance component represents an intensity value, and the alpha component represents a transparency value. Blending operations will use the luminance component to adjust the red, green and blue components of the underlying color, and the alpha component to adjust the alpha value of the underlying color.
XintTFORMAT_RGB - The texture map contains an array of floating point triplets, red, green and blue. Blending operations will use the red component to adjust the underlying red value, the green component to adjust the underlying green value and the blue component to adjust the underlying blue value.
XintTFORMAT_RGBA - The texture map contains an array of floating point quadruplets, red, green, blue and alpha. This format behaves in the same manner as XintTFORMAT_RGB, except that the additional alpha component affects the underlying alpha component of the color during blending operations.

blend defines the method that the texture map is blended with the underlying color of the object:

XintTBLEND_DECAL - The underlying color is completely replaced with the texture maps color. This method will only function with a format of type XintTFORMAT_RGB or XintTFORMAT_RGBA. Because the underlying color is completely replaced, lighting affects will not be noticed.
XintTBLEND_MODULATE - Multiplies the underlying color with the texture map values. Use an underlying color of white (rgba = 1.0, 1.0, 1.0, 1.0) to use the texture map as a decal with lighting.
XintTBLEND_BLEND - The underlying color is blended with the texture map. This method will not work with format types of XintTFORMAT_RGB or XintTFORMAT_RGBA.

width and height define the dimensions of the texture map. Internally, the texture map must have dimensions that are a power of 2. You are not required to create a texture map with this limitation. View3D will convert the texture map internally. If you choose not to use dimensions of a power of 2, pay attention to the conserve_memory flag. If set to True, and the texture map dimensions are not a power of 2, then the next smaller image size will be used. This will cause a loss of some data, but will conserve_memory. If conserve_memory is set to False, and the texture map dimensions are not a power of 2, then the next larger image size will be used. This will preserve all of the original image data, but will require more memory.

For example:

Original Image Size conserve_memory
False conserve_memory
True
28x43 (1204 texels) 32x64 (2048 texels) 16x32 (512 texels)
1025x1025
(1,050,625 texels) 2048x2048 (4,194,304 texels) 1024x1024 (1,048,576 texels)
1023x1023
(1,046,529 texels) 1024x1024 (1,048,576 texels) 512x512 (262,144 texels)

Original Image Size	conserve_memory False	conserve_memory True
28x43 (1204 texels)	32x64 (2048 texels)	16x32 (512 texels)
1025x1025 (1,050,625 texels)	2048x2048 (4,194,304 texels)	1024x1024 (1,048,576 texels)
1023x1023 (1,046,529 texels)	1024x1024 (1,048,576 texels)	512x512 (262,144 texels)

Coordinates

Texture maps are "mapped" to another object by defining a texture coordinate for each coordinate of the object. Texture maps are defined with a local coordinate system whose elements are clamped to the range [0,1]. One dimensional texture maps only use a single coordinate S. Two dimensional texture maps use two coordinates S and T. Since it is possible to define texture coordinates outside of the range [0,1], a method is needed to define the behavior of the mapping. clamp_s and clamp_t do this.

clamp_s and clamp_t define the behavior of the texture map when the texture map is mapped to coordinates outside its range of [0,1]. If clamp_* is set to True, then any coordinate outside of the range will be clamped to the range. This can cause streaking effects on the object. If set to False, the texture map will be repeated across the object. Repeating a texture map is not always desirable. If a single image should be mapped to fit exactly onto another object, then clamp_* should be set to True, and any artifacts noticed will be attributed to an incorrect evaluation of the texture coordinates in the application.

The texture coordinates are defined during the call to XintView3DAssignTexture.

     void XintView3DAssignTexture(
	                          widget view3d,
	                          XintView3DObject *object,
	                          XintVector2f *tcoords,
	                          XintView3DTextureMap *front_texture,
	                          XintView3DTextureMap *back_texture);

The call requires a View3D widget, an object, an optional list of texture coordinates and at least one texture map. The second texture map is only useful for two-sided surfaces. The texture coordinates are required unless automatic texture coordinate generation has been enabled. See Advanced Topics.

Filtering

When a texture map is rendered into a screen space smaller or larger than the dimensions of the texture map, the texturing process must use filtering methods to determine which texels to render. The application developer has complete control over this feature by using the arguments min_filter, mag_filter. (See the discussion of mipmaps following this section.)

mag_filter defines the method that the texturing process uses when the texture map is smaller than the actual screen space (the texture map must be made larger):

XintTFILTER_NEAREST - The closest texel to the resultant location is chosen. This is the fastest operation, but will produce "blocky" looking textures when zoomed in close.
XintTFILTER_LINEAR - The closest texels are interpolated to determine the resultant output texel. This is the highest quality, but also the slowest operation.
min_filter defines the method that the texturing process uses when the texture map is larger than the actual screen space (the texture map must be made smaller):
XintTFILTER_NEAREST - The closest texel to the resultant location is chosen. This is the fastest operation, but can produce artifacts on the resultant image.
XintTFILTER_LINEAR - The closest texels are interpolated to determine the resultant output texel.
XintTFILTER_NEAREST_MIPMAP_NEAREST - Selects a texel from the mipmap that is closest in size to the screen space. No interpolation is performed.
XintTFILTER_LINEAR_MIPMAP_NEAREST - Linearly interpolates a texel from the mipmap that is closest in size to the screen space.
XintTFILTER_NEAREST_MIPMAP_LINEAR - Selects a texel from the linear interpolation of the two closest mipmaps to the screen space.
XintTFILTER_LINEAR_MIPMAP_LINEAR - Linearly interpolates a texel from the linear interpolation of the two closest mipmaps to the screen space. This is the highest quality minification filter, but is also the slowest.

MipMaps

A mipmap is a scaled down copy of the original image. Mipmaps can be used in the filtering operation to produce higher quality output images. For mipmaping to be used, mipmaps must be provided with dimensions of a power of 2 starting with the next smaller original image size down to a size of 1x1.

For example: An original image size of 32x32 will require 5 mipmaps of size 16x16, 8x8, 4x4, 2x2 and 1x1. An original image size of 64x32 will also require only 5 mipmaps of size 32x16, 16x8, 8x4, 4x2, and 2x1.

mipmaps is an array of images (float **). In the example above, memory would be allocated as such:

     mipmaps = (float **)malloc(5*sizeof(float *));
     mipmaps[0]=(float *)malloc(16*16*num_components*sizeof(float));
     mipmaps[1]=(float *)malloc(8*8*num_components*sizeof(float));
     mipmaps[2]=(float *)malloc(4*4*num_components*sizeof(float));
     mipmaps[3]=(float *)malloc(2*2*num_components*sizeof(float));
     mipmaps[4]=(float *)malloc(1*1*num_components*sizeof(float));

where num_components is based on the format of the data and will either be 1 (XintTFORMAT_RED, XintTFORMAT_GREEN, XintTFORMAT_BLUE or XintTFORMAT_LUMINANCE), 2 (XintTFORMAT_LUMINANCE_ALPHA), 3 (XintTFORMAT_RGB) or 4 (XintTFORMAT_RGBA).

If you want to use mipmaps, but do not want to take the time to generate them yourself, you can use the flag build_mipmaps. This will generate all the required mipmaps.

Mipmaps do require significantly more memory than a single texture image. In most cases, using a mag_filter = XintTFILTER_LINEAR and a min_filter = XintTFILTER_LINEAR will produce a high enough quality image.

Advanced Topics

View3D can automatically generate the texture coordinates for an object. This is accomplished by using the argument auto_data.

auto_data is a data structure that is used for the automatic generation of texture coordinates of type XintView3DAutoTexture defined below:

     typedef struct {
                      int mode[2];
                      float parameters[2][4];
     } XintView3DAutoTexture;

Each element of this structure contains 2 elements. The first "[0]" is for 1D textures, or the S coordinate of a 2D texture. The second element "[1]" is only used for 2D textures, and represents the T coordinate. mode must be:

Defined Constant Description
XintTGEN_OBJECT_LINEAR Linear mapping across the object. The texture map is fixed to the object.
XintTGEN_EYE_LINEAR Mapping relative to eye coordinates. The texture map is fixed relative to the eye. The object will move through the texture.
XintTGEN_SPHERE Spherical mapping. Useful for environment mapping.

Defined Constant	Description
XintTGEN_OBJECT_LINEAR	Linear mapping across the object. The texture map is fixed to the object.
XintTGEN_EYE_LINEAR	Mapping relative to eye coordinates. The texture map is fixed relative to the eye. The object will move through the texture.
XintTGEN_SPHERE	Spherical mapping. Useful for environment mapping.

If mode is set to XintTGEN_OBJECT_LINEAR then parameters specifies a linear mapping using the function:

If mode is set to XintTGEN_EYE_LINEAR then parameters specifies a linear mapping in eye coordinates using the function:

Where M is the viewing transformation matrix.

If mode is set to XintTGEN_SPHERE, then parameters does not need to be defined.

Automatic generation of texture coordinates can be very useful. Here are two suggested uses:

Color Coding Elevations: Create a 1D texture map with the colors ranging from low elevation to high. Enable automatic texture generation with the following values in auto_data:

	auto_data.mode[0] = XintTGEN_OBJECT_LINEAR;
	auto_data.parameters[0][0] = 0.0;
	auto_data.parameters[0][1] = 0.0;
	auto_data.parameters[0][2] = 1.0;
	auto_data.parameters[0][3] = 0.0;

Environment Mapping: This technique will produce object with a mirrored finish. The texture map image needs to be a "fish eye" or "wide-angle" picture within a circle:

Enable automatic texture generation with the following values in auto_data:

	auto_data.mode[0] = XintTGEN_SPHERE;
	auto_data.mode[1] = XintTGEN_SPHERE;