javax.media.j3d
Class Texture

java.lang.Object
  |
  +--javax.media.j3d.SceneGraphObject
        |
        +--javax.media.j3d.NodeComponent
              |
              +--javax.media.j3d.Texture

Direct Known Subclasses:

Texture2D, Texture3D

public abstract class Texture

extends NodeComponent

The Texture object is a component object of an Appearance object that defines the texture properties used when texture mapping is enabled. The Texture object is an abstract class and all texture objects must be created as either a Texture2D object or a Texture3D object.

Each Texture object has the following properties:

• Boundary color - the texture boundary color. The texture boundary color is used when the boundaryModeS and boundaryModeT parameters are set to CLAMP. The magnification filter affects the boundary color as follows: For BASE_LEVEL_POINT, the boundary color is ignored since the filter size is 1 and the border is unused. For BASE_LEVEL_LINEAR, the boundary color is used.
• Boundary ModeS and Boundary ModeT - the boundary mode for the S and T coordinates, respectively. The boundary modes are as follows:
• CLAMP - clamps texture coordinates to be in the range [0,1]. A constant boundary color is used for U,V values that fall outside this range.
• WRAP - repeats the texture by wrapping texture coordinates that are outside the range [0,1]. Only the fractional portion of the texture coordinates is used. The integer portion is discarded

• Image - an image or an array of images for all the mipmap levels. If only one image is provided, the MIPmap mode must be set to BASE_LEVEL.
• Magnification filter - the magnification filter function. Used when the pixel being rendered maps to an area less than or equal to one texel. The magnification filter functions are as follows:
• FASTEST - uses the fastest available method for processing geometry.
• NICEST - uses the nicest available method for processing geometry.
• BASE_LEVEL_POINT - selects the nearest level in the level 0 texture map.
• BASE_LEVEL_LINEAR - performs a bilinear interpolation on the four nearest texels in the level 0 texture map.

• Minification filter - the minification filter function. Used when the pixel being rendered maps to an area greater than one texel. The minifaction filter functions are as follows:
• FASTEST - uses the fastest available method for processing geometry.
• NICEST - uses the nicest available method for processing geometry.
• BASE_LEVEL_POINT - selects the nearest level in the level 0 texture map.
• BASE_LEVEL_LINEAR - performs a bilinear interpolation on the four nearest texels in the level 0 texture map.
• MULTI_LEVEL_POINT - selects the nearest texel in the nearest mipmap.
• MULTI_LEVEL_LINEAR - performs trilinear interpolation of texels between four texels each from the two nearest mipmap levels.

• MIPmap mode - the mode used for texture mapping for this object. The mode is one of the following:
• BASE_LEVEL - indicates that this Texture object only has a base-level image. If multiple levels are needed, they will be implicitly computed.
• MULTI_LEVEL_MIPMAP - indicates that this Texture object has multiple images - one for each mipmap level (that is, log2(max(W,H)) + 1 separate images). If MIPmap mode is set to MULTI_LEVEL_MIPMAP, images for all levels must be set.

• Format - the data format. The format is one of the following:
• INTENSITY - the texture image contains only texture values.
• LUMINANCE - the texture image contains only luminance values.
• ALPHA - the texture image contains only alpha values.
• LUMINANCE_ALPHA - the texture image contains both luminance and alpha values.
• RGB - the texture image contains red, green, and blue values.
• RGBA - the texture image contains red, green, blue, and alpha values.

Field Summary

static int	ALLOW_BOUNDARY_COLOR_READ Specifies that this Texture object allows reading its boundary color information.
static int	ALLOW_BOUNDARY_MODE_READ Specifies that this Texture object allows reading its boundary mode information.
static int	ALLOW_ENABLE_READ Specifies that this Texture object allows reading its enable flag.
static int	ALLOW_ENABLE_WRITE Specifies that this Texture object allows writing its enable flag.
static int	ALLOW_FILTER_READ Specifies that this Texture object allows reading its filter information.
static int	ALLOW_FORMAT_READ Specifies that this Texture object allows reading its format information.
static int	ALLOW_IMAGE_READ Specifies that this Texture object allows reading its image component information.
static int	ALLOW_IMAGE_WRITE Specifies that this Texture object allows writing its image component information.
static int	ALLOW_MIPMAP_MODE_READ Specifies that this Texture object allows reading its mipmap mode information.
static int	ALLOW_SIZE_READ Specifies that this Texture object allows reading its size information (e.g., width, height, number of mipmap levels).
static int	ALPHA Specifies Texture contains only Alpha values.
static int	BASE_LEVEL Indicates that Texture object only has one level.
static int	BASE_LEVEL_LINEAR Performs bilinear interpolation on the four nearest texels in level 0 texture map.
static int	BASE_LEVEL_POINT Select the nearest texel in level 0 texture map.
static int	CLAMP Clamps texture coordinates to be in the range [0, 1].
static int	FASTEST Uses the fastest available method for processing geometry.
static int	INTENSITY Specifies Texture contains only Intensity values.
static int	LUMINANCE Specifies Texture contains only luminance values.
static int	LUMINANCE_ALPHA Specifies Texture contains Luminance and Alpha values.
static int	MULTI_LEVEL_LINEAR Performs tri-linear interpolation of texels between four texels each from two nearest mipmap levels.
static int	MULTI_LEVEL_MIPMAP Indicates that this Texture object has multiple images, one for each mipmap level.
static int	MULTI_LEVEL_POINT Selects the nearest texel in the nearest mipmap.
static int	NICEST Uses the nicest available method for processing geometry.
static int	RGB Specifies Texture contains Red, Green and Blue color values.
static int	RGBA Specifies Texture contains Red, Green, Blue color values and Alpha value.
static int	WRAP Repeats the texture by wrapping texture coordinates that are outside the range [0,1].

Constructor Summary

Texture()
Constructs a Texture object with default parameters.

Texture(int mipMapMode, int format, int width, int height)
Constructs an empty Texture object with specified mipMapMode format, width and height.

Method Summary

void	getBoundaryColor(Color4f boundaryColor) Retrieves the texture boundary color for this texture object.
int	getBoundaryModeS() Retrieves the boundary mode for the S coordinate.
int	getBoundaryModeT() Retrieves the boundary mode for the T coordinate.
boolean	getEnable() Retrieves the state of the texture enable flag.
int	getFormat() Retrieves the format of this Texture object.
int	getHeight() Retrieves the height of this Texture object.
ImageComponent	getImage(int level) Retrieves the image for a specified mipmap level.
ImageComponent[]	getImages() Retrieves the array of images for all mipmap levels.
int	getMagFilter() Retrieves the magnification filter.
int	getMinFilter() Retrieves the minification filter.
int	getMipMapMode() Retrieves current mipmap mode.
int	getWidth() Retrieves the width of this Texture object.
int	numMipMapLevels() Retrieves the number of mipmap levels needed for this Texture object.
void	setBoundaryColor(Color4f boundaryColor) Sets the texture boundary color for this texture object.
void	setBoundaryColor(float r, float g, float b, float a) Sets the texture boundary color for this texture object.
void	setBoundaryModeS(int boundaryModeS) Sets the boundary mode for the S coordinate in this texture object.
void	setBoundaryModeT(int boundaryModeT) Sets the boundary mode for the T coordinate in this texture object.
void	setEnable(boolean state) Enables or disables texture mapping for this appearance component object.
void	setImage(int level, ImageComponent image) Sets the image for a specified mipmap level.
void	setImages(ImageComponent[] images) Sets the array of images for all mipmap levels.
void	setMagFilter(int magFilter) Sets the magnification filter function.
void	setMinFilter(int minFilter) Sets the minification filter function.
void	setMipMapMode(int mipMapMode) Sets mipmap mode for texture mapping for this texture object.

Methods inherited from class javax.media.j3d.NodeComponent

cloneNodeComponent, cloneNodeComponent, duplicateNodeComponent, duplicateNodeComponent, getDuplicateOnCloneTree, setDuplicateOnCloneTree

Methods inherited from class javax.media.j3d.SceneGraphObject

clearCapability, duplicateSceneGraphObject, getCapability, getUserData, isCompiled, isLive, setCapability, setUserData, updateNodeReferences

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALLOW_ENABLE_READ

public static final int ALLOW_ENABLE_READ

Specifies that this Texture object allows reading its enable flag.

ALLOW_ENABLE_WRITE

public static final int ALLOW_ENABLE_WRITE

Specifies that this Texture object allows writing its enable flag.

ALLOW_BOUNDARY_MODE_READ

public static final int ALLOW_BOUNDARY_MODE_READ

Specifies that this Texture object allows reading its boundary mode information.

ALLOW_FILTER_READ

public static final int ALLOW_FILTER_READ

Specifies that this Texture object allows reading its filter information.

ALLOW_IMAGE_READ

public static final int ALLOW_IMAGE_READ

Specifies that this Texture object allows reading its image component information.

ALLOW_IMAGE_WRITE

public static final int ALLOW_IMAGE_WRITE

Specifies that this Texture object allows writing its image component information.

Since:

Java 3D 1.2

ALLOW_FORMAT_READ

public static final int ALLOW_FORMAT_READ

Specifies that this Texture object allows reading its format information.

Since:

Java 3D 1.2

ALLOW_SIZE_READ

public static final int ALLOW_SIZE_READ

Specifies that this Texture object allows reading its size information (e.g., width, height, number of mipmap levels).

Since:

Java 3D 1.2

ALLOW_MIPMAP_MODE_READ

public static final int ALLOW_MIPMAP_MODE_READ

Specifies that this Texture object allows reading its mipmap mode information.

ALLOW_BOUNDARY_COLOR_READ

public static final int ALLOW_BOUNDARY_COLOR_READ

Specifies that this Texture object allows reading its boundary color information.

FASTEST

public static final int FASTEST

Uses the fastest available method for processing geometry. This value can be used as a parameter to setMinFilter and setMagFilter.

NICEST

public static final int NICEST

Uses the nicest available method for processing geometry. This value can be used as a parameter to setMinFilter and setMagFilter.

BASE_LEVEL_POINT

public static final int BASE_LEVEL_POINT

Select the nearest texel in level 0 texture map. Maps to NEAREST.

BASE_LEVEL_LINEAR

public static final int BASE_LEVEL_LINEAR

Performs bilinear interpolation on the four nearest texels in level 0 texture map. Maps to LINEAR.

MULTI_LEVEL_POINT

public static final int MULTI_LEVEL_POINT

Selects the nearest texel in the nearest mipmap. Maps to NEAREST_MIPMAP_NEAREST.

MULTI_LEVEL_LINEAR

public static final int MULTI_LEVEL_LINEAR

Performs tri-linear interpolation of texels between four texels each from two nearest mipmap levels. Maps to LINEAR_MIPMAP_LINEAR, but an implementation can fall back to LINEAR_MIPMAP_NEAREST or NEAREST_MIPMAP_LINEAR.

CLAMP

public static final int CLAMP

Clamps texture coordinates to be in the range [0, 1]. A constant boundary color is used for U,V values that fall outside this range.

WRAP

public static final int WRAP

Repeats the texture by wrapping texture coordinates that are outside the range [0,1]. Only the fractional portion of the texture coordinates is used; the integer portion is discarded.

BASE_LEVEL

public static final int BASE_LEVEL

Indicates that Texture object only has one level. If multiple levels are needed, they will be implicitly computed.

MULTI_LEVEL_MIPMAP

public static final int MULTI_LEVEL_MIPMAP

Indicates that this Texture object has multiple images, one for each mipmap level. In this mode, there are log2(max(width,height))+1 separate images.

INTENSITY

public static final int INTENSITY

Specifies Texture contains only Intensity values.

LUMINANCE

public static final int LUMINANCE

Specifies Texture contains only luminance values.

ALPHA

public static final int ALPHA

Specifies Texture contains only Alpha values.

LUMINANCE_ALPHA

public static final int LUMINANCE_ALPHA

Specifies Texture contains Luminance and Alpha values.

RGB

public static final int RGB

Specifies Texture contains Red, Green and Blue color values.

RGBA

public static final int RGBA

Specifies Texture contains Red, Green, Blue color values and Alpha value.

Constructor Detail

Texture

public Texture()

Constructs a Texture object with default parameters. The default values are as follows:

enable flag : true
width : 0
height : 0
mipmap mode : BASE_LEVEL
format : RGB
boundary mode S : WRAP
boundary mode T : WRAP
min filter : BASE_LEVEL_POINT
mag filter : BASE_LEVEL_POINT
boundary color : black (0,0,0,0)
array of images : null

Note that the default constructor creates a texture object with a width and height of 0 and is, therefore, not useful.

Texture

public Texture(int mipMapMode,
               int format,
               int width,
               int height)

Constructs an empty Texture object with specified mipMapMode format, width and height. Defaults are used for all other parameters. If mipMapMode is set to BASE_LEVEL, then the image at level 0 must be set by the application (using either the setImage or setImages method). If mipMapMode is set to MULTI_LEVEL_MIPMAP, then images for all levels must be set.

Parameters:

mipMapMode - type of mipmap for this Texture: one of BASE_LEVEL, MULTI_LEVEL_MIPMAP

format - data format of Textures saved in this object. One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA

width - width of image at level 0. Must be power of 2.

height - height of image at level 0. Must be power of 2.

Throws:

java.lang.IllegalArgumentException - if width or height are not a power of 2, or if an invalid format or mipMapMode is specified.

Method Detail

setBoundaryModeS

public void setBoundaryModeS(int boundaryModeS)

Sets the boundary mode for the S coordinate in this texture object.

Parameters:

boundaryModeS - the boundary mode for the S coordinate. One of: CLAMP or WRAP.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

getBoundaryModeS

public int getBoundaryModeS()

Retrieves the boundary mode for the S coordinate.

Returns:

the current boundary mode for the S coordinate.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setBoundaryModeT

public void setBoundaryModeT(int boundaryModeT)

Sets the boundary mode for the T coordinate in this texture object.

Parameters:

boundaryModeT - the boundary mode for the T coordinate. One of: CLAMP or WRAP.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

getBoundaryModeT

public int getBoundaryModeT()

Retrieves the boundary mode for the T coordinate.

Returns:

the current boundary mode for the T coordinate.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setMinFilter

public void setMinFilter(int minFilter)

Sets the minification filter function. This function is used when the pixel being rendered maps to an area greater than one texel.

Parameters:

minFilter - the minification filter. One of: FASTEST, NICEST, BASE_LEVEL_POINT, BASE_LEVEL_LINEAR, MULTI_LEVEL_POINT, MULTI_LEVEL_LINEAR.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

getMinFilter

public int getMinFilter()

Retrieves the minification filter.

Returns:

the current minification filter function.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setMagFilter

public void setMagFilter(int magFilter)

Sets the magnification filter function. This function is used when the pixel being rendered maps to an area less than or equal to one texel.

Parameters:

magFilter - the magnification filter, one of: FASTEST, NICEST, BASE_LEVEL_POINT, or BASE_LEVEL_LINEAR.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

getMagFilter

public int getMagFilter()

Retrieves the magnification filter.

Returns:

the current magnification filter function.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setImage

public void setImage(int level,
                     ImageComponent image)

Sets the image for a specified mipmap level.

Parameters:

level - mipmap level to set: 0 is the base level

image - ImageComponent object containing the texture image for the specified mipmap level

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

java.lang.IllegalArgumentException - if an ImageComponent3D is used in a Texture2D object; if an ImageComponent2D is used in a Texture3D object; or if this object is part of a live scene graph and the image being set at this level is not the same size (width, height, depth) as the old image at this level.

getImage

public ImageComponent getImage(int level)

Retrieves the image for a specified mipmap level.

Parameters:

level - mipmap level to get: 0 is the base level

Returns:

the ImageComponent object containing the texture image at the specified mipmap level.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setImages

public void setImages(ImageComponent[] images)

Sets the array of images for all mipmap levels.

Parameters:

images - array of ImageComponent objects containing the texture images for all mipmap levels

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

java.lang.IllegalArgumentException - if an ImageComponent3D is used in a Texture2D object; if an ImageComponent2D is used in a Texture3D object; if images.length is not equal to the total number of mipmap levels; or if this object is part of a live scene graph and the size of each dimension (width, height, depth) of the image at a given level in the images array is not half the dimension of the previous level.

Since:

Java 3D 1.2

getImages

public ImageComponent[] getImages()

Retrieves the array of images for all mipmap levels.

Returns:

the array of ImageComponent objects for this Texture.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

Since:

Java 3D 1.2

getFormat

public int getFormat()

Retrieves the format of this Texture object.

Returns:

the format of this Texture object.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

Since:

Java 3D 1.2

getWidth

public int getWidth()

Retrieves the width of this Texture object.

Returns:

the width of this Texture object.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

Since:

Java 3D 1.2

getHeight

public int getHeight()

Retrieves the height of this Texture object.

Returns:

the height of this Texture object.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

Since:

Java 3D 1.2

numMipMapLevels

public int numMipMapLevels()

Retrieves the number of mipmap levels needed for this Texture object.

Returns:

log2(max(width,height))+1 if mipMapMode is MULTI_LEVEL_MIPMAP; otherwise it returns 1.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

Since:

Java 3D 1.2

setMipMapMode

public void setMipMapMode(int mipMapMode)

Sets mipmap mode for texture mapping for this texture object.

Parameters:

mipMapMode - the new mipmap mode for this object. One of: BASE_LEVEL or MULTI_LEVEL_MIPMAP.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

getMipMapMode

public int getMipMapMode()

Retrieves current mipmap mode.

Returns:

current mipmap mode of this texture object.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setEnable

public void setEnable(boolean state)

Enables or disables texture mapping for this appearance component object.

Parameters:

state - true or false to enable or disable texture mapping

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

getEnable

public boolean getEnable()

Retrieves the state of the texture enable flag.

Returns:

true if texture mapping is enabled, false if texture mapping is disabled

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

setBoundaryColor

public void setBoundaryColor(Color4f boundaryColor)

Sets the texture boundary color for this texture object. The texture boundary color is used when boundaryModeS or boundaryModeT is set to CLAMP.

Parameters:

boundaryColor - the new texture boundary color.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

setBoundaryColor

public void setBoundaryColor(float r,
                             float g,
                             float b,
                             float a)

Sets the texture boundary color for this texture object. The texture boundary color is used when boundaryModeS or boundaryModeT is set to CLAMP.

Parameters:

r - the red component of the color.

g - the green component of the color.

b - the blue component of the color.

a - the alpha component of the color.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

getBoundaryColor

public void getBoundaryColor(Color4f boundaryColor)

Retrieves the texture boundary color for this texture object.

Parameters:

boundaryColor - the vector that will receive the current texture boundary color.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph