com.sun.opengl.util.texture
Class Texture

java.lang.Object
  com.sun.opengl.util.texture.Texture

public class Texture

extends Object

Represents an OpenGL texture object. Contains convenience routines for enabling/disabling OpenGL texture state, binding this texture, and computing texture coordinates for both the entire image as well as a sub-image.
REMIND: document GL_TEXTURE_2D/GL_TEXTURE_RECTANGLE_ARB issues...
REMIND: translucent images will have premultiplied comps by default...

Author:

Chris Campbell, Kenneth Russell

Method Summary

void	bind() Binds this texture to the current GL context.
void	disable() Disables this texture's target (e.g., GL_TEXTURE_2D) in the current GL context's state.
void	dispose() Disposes the native resources used by this texture object.
void	enable() Enables this texture's target (e.g., GL_TEXTURE_2D) in the current GL context's state.
int	getEstimatedMemorySize() Returns an estimate of the amount of texture memory in bytes this Texture consumes.
int	getHeight() Returns the height of the texture.
int	getImageHeight() Returns the height of the image contained within this texture.
TextureCoords	getImageTexCoords() Returns the set of texture coordinates corresponding to the entire image.
int	getImageWidth() Returns the width of the image contained within this texture.
boolean	getMustFlipVertically() Indicates whether this texture's texture coordinates must be flipped vertically in order to properly display the texture.
TextureCoords	getSubImageTexCoords(int x1, int y1, int x2, int y2) Returns the set of texture coordinates corresponding to the specified sub-image.
int	getTarget() Returns the OpenGL "target" of this texture.
int	getTextureObject() Returns the underlying OpenGL texture object for this texture.
int	getWidth() Returns the width of the texture.
void	setTexParameterf(int parameterName, float value) Sets the OpenGL floating-point texture parameter for the texture's target.
void	setTexParameterfv(int parameterName, float[] params, int params_offset) Sets the OpenGL multi-floating-point texture parameter for the texture's target.
void	setTexParameterfv(int parameterName, FloatBuffer params) Sets the OpenGL multi-floating-point texture parameter for the texture's target.
void	setTexParameteri(int parameterName, int value) Sets the OpenGL integer texture parameter for the texture's target.
void	setTexParameteriv(int parameterName, int[] params, int params_offset) Sets the OpenGL multi-integer texture parameter for the texture's target.
void	setTexParameteriv(int parameterName, IntBuffer params) Sets the OpenGL multi-integer texture parameter for the texture's target.
void	updateImage(TextureData data) Updates the entire content area of this texture using the data in the given image.
void	updateImage(TextureData data, int target) Updates the content area of the specified target of this texture using the data in the given image.
void	updateSubImage(TextureData data, int mipmapLevel, int x, int y) Updates a subregion of the content area of this texture using the data in the given image.

Methods inherited from class java.lang.Object

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

Method Detail

enable

public void enable()
            throws GLException

Enables this texture's target (e.g., GL_TEXTURE_2D) in the current GL context's state.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

disable

public void disable()
             throws GLException

Disables this texture's target (e.g., GL_TEXTURE_2D) in the current GL context's state.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

bind

public void bind()
          throws GLException

Binds this texture to the current GL context.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

dispose

public void dispose()
             throws GLException

Disposes the native resources used by this texture object.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

getTarget

public int getTarget()

Returns the OpenGL "target" of this texture.

Returns:

the OpenGL target of this texture

See Also:

GL.GL_TEXTURE_2D, GL.GL_TEXTURE_RECTANGLE_ARB

getWidth

public int getWidth()

Returns the width of the texture. Note that the texture width will be greater than or equal to the width of the image contained within.

Returns:

the width of the texture

getHeight

public int getHeight()

Returns the height of the texture. Note that the texture height will be greater than or equal to the height of the image contained within.

Returns:

the height of the texture

getImageWidth

public int getImageWidth()

Returns the width of the image contained within this texture.

Returns:

the width of the image

getImageHeight

public int getImageHeight()

Returns the height of the image contained within this texture.

Returns:

the height of the image

getImageTexCoords

public TextureCoords getImageTexCoords()

Returns the set of texture coordinates corresponding to the entire image. If the TextureData indicated that the texture coordinates must be flipped vertically, the returned TextureCoords will take that into account.

Returns:

the texture coordinates corresponding to the entire image

getSubImageTexCoords

public TextureCoords getSubImageTexCoords(int x1,
                                          int y1,
                                          int x2,
                                          int y2)

Returns the set of texture coordinates corresponding to the specified sub-image. The (x1, y1) and (x2, y2) points are specified in terms of pixels starting from the lower-left of the image. (x1, y1) should specify the lower-left corner of the sub-image and (x2, y2) the upper-right corner of the sub-image. If the TextureData indicated that the texture coordinates must be flipped vertically, the returned TextureCoords will take that into account; this should not be handled by the end user in the specification of the y1 and y2 coordinates.

Returns:

the texture coordinates corresponding to the specified sub-image

updateImage

public void updateImage(TextureData data)
                 throws GLException

Updates the entire content area of this texture using the data in the given image.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

getMustFlipVertically

public boolean getMustFlipVertically()

Indicates whether this texture's texture coordinates must be flipped vertically in order to properly display the texture. This is handled automatically by getImageTexCoords() and getSubImageTexCoords(int, int, int, int), but applications may generate or otherwise produce texture coordinates which must be corrected.

updateImage

public void updateImage(TextureData data,
                        int target)
                 throws GLException

Updates the content area of the specified target of this texture using the data in the given image. In general this is intended for construction of cube maps.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

updateSubImage

public void updateSubImage(TextureData data,
                           int mipmapLevel,
                           int x,
                           int y)
                    throws GLException

Updates a subregion of the content area of this texture using the data in the given image. Only updates the specified mipmap level and does not re-generate mipmaps if they were originally produced or loaded.

Parameters:

data - the image data to be uploaded to this texture

mipmapLevel - the mipmap level of the texture to set. If this is non-zero and the TextureData contains mipmap data, the appropriate mipmap level will be selected.

x - the x offset (in pixels) relative to the lower-left corner of this texture

y - the y offset (in pixels) relative to the lower-left corner of this texture

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

setTexParameterf

public void setTexParameterf(int parameterName,
                             float value)

Sets the OpenGL floating-point texture parameter for the texture's target. This gives control over parameters such as GL_TEXTURE_MAX_ANISOTROPY_EXT. Causes this texture to be bound to the current texture state.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

setTexParameterfv

public void setTexParameterfv(int parameterName,
                              FloatBuffer params)

Sets the OpenGL multi-floating-point texture parameter for the texture's target. Causes this texture to be bound to the current texture state.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

setTexParameterfv

public void setTexParameterfv(int parameterName,
                              float[] params,
                              int params_offset)

Sets the OpenGL multi-floating-point texture parameter for the texture's target. Causes this texture to be bound to the current texture state.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

setTexParameteri

public void setTexParameteri(int parameterName,
                             int value)

Sets the OpenGL integer texture parameter for the texture's target. This gives control over parameters such as GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T, which by default are set to GL_CLAMP_TO_EDGE. Causes this texture to be bound to the current texture state.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

setTexParameteriv

public void setTexParameteriv(int parameterName,
                              IntBuffer params)

Sets the OpenGL multi-integer texture parameter for the texture's target. Causes this texture to be bound to the current texture state.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

setTexParameteriv

public void setTexParameteriv(int parameterName,
                              int[] params,
                              int params_offset)

Sets the OpenGL multi-integer texture parameter for the texture's target. Causes this texture to be bound to the current texture state.

Throws:

GLException - if no OpenGL context was current or if any OpenGL-related errors occurred

getTextureObject

public int getTextureObject()

Returns the underlying OpenGL texture object for this texture. Most applications will not need to access this, since it is handled automatically by the bind() and dispose() APIs.

getEstimatedMemorySize

public int getEstimatedMemorySize()

Returns an estimate of the amount of texture memory in bytes this Texture consumes. It should only be treated as an estimate; most applications should not need to query this but instead let the OpenGL implementation page textures in and out as necessary.