JOGL 2.3.2 · com.jogamp.opengl.util.texture.Texture

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.

Order of Texture Commands

Due to many confusions w/ texture usage, following list described the order and semantics of texture unit selection, binding and enabling.

Optional: Set active textureUnit via gl.glActiveTexture(GL.GL_TEXTURE0 + textureUnit), 0 is default.
Bind textureId -> active textureUnit's textureTarget via gl.glBindTexture(textureTarget, textureId)
Compatible Context Only: Enable active textureUnit's textureTarget via glEnable(textureTarget).
Optional: Fiddle with the texture parameters and/or environment settings.
GLSL: Use textureUnit in your shader program, enable shader program.
Issue draw commands

Non-power-of-two restrictions
When creating an OpenGL texture object, the Texture class will attempt to use non-power-of-two textures (NPOT) if available, see GL#isNPOTTextureAvailable(). Further more, GL_ARB_texture_rectangle (RECT) will be attempted on OSX w/ ATI drivers. If NPOT is not available or RECT not chosen, the Texture class will simply upload a non-pow2-sized image into a standard pow2-sized texture (without any special scaling). Since the choice of extension (or whether one is used at all) depends on the user's machine configuration, developers are recommended to use getImageTexCoords and getSubImageTexCoords, as those methods will calculate the appropriate texture coordinates for the situation.

One caveat in this approach is that certain texture wrap modes (e.g. GL_REPEAT) are not legal when the GL_ARB_texture_rectangle extension is in use. Another issue to be aware of is that in the default pow2 scenario, if the original image does not have pow2 dimensions, then wrapping may not work as one might expect since the image does not extend to the edges of the pow2 texture. If texture wrapping is important, it is recommended to use only pow2-sized images with the Texture class.

Performance Tips
For best performance, try to avoid calling enable / bind / disable any more than necessary. For example, applications using many Texture objects in the same scene may want to reduce the number of calls to both enable and disable. To do this it is necessary to call getTarget to make sure the OpenGL texture target is the same for all of the Texture objects in use; non-power-of-two textures using the GL_ARB_texture_rectangle extension use a different target than power-of-two textures using the GL_TEXTURE_2D target. Note that when switching between textures it is necessary to call bind, but when drawing many triangles all using the same texture, for best performance only one call to bind should be made. User may also utilize multiple texture units, see order of texture commands above.

Alpha premultiplication and blending

Disclaimer: Consider performing alpha premultiplication in shader code, if really desired! Otherwise use RGBA.

The Texture class does not convert RGBA image data into premultiplied data when storing it into an OpenGL texture.

The mathematically correct way to perform blending in OpenGL with the SrcOver "source over destination" mode, or any other Porter-Duff rule, is to use premultiplied color components, which means the R/G/ B color components must have been multiplied by the alpha value. If using premultiplied color components it is important to use the correct blending function; for example, the SrcOver rule is expressed as:

    gl.glBlendFunc(GL.GL_ONE, GL.GL_ONE_MINUS_SRC_ALPHA);

Also, when using a texture function like GL_MODULATE where the current color plays a role, it is important to remember to make sure that the color is specified in a premultiplied form, for example:

    float a = ...;
    float r = r * a;
    float g = g * a;
    float b = b * a;
    gl.glColor4f(r, g, b, a);

For reference, here is a list of the Porter-Duff compositing rules and the associated OpenGL blend functions (source and destination factors) to use in the face of premultiplied alpha:

Rule	Source	Dest
Clear	GL_ZERO	GL_ZERO
Src	GL_ONE	GL_ZERO
SrcOver	GL_ONE	GL_ONE_MINUS_SRC_ALPHA
DstOver	GL_ONE_MINUS_DST_ALPHA	GL_ONE
SrcIn	GL_DST_ALPHA	GL_ZERO
DstIn	GL_ZERO	GL_SRC_ALPHA
SrcOut	GL_ONE_MINUS_DST_ALPHA	GL_ZERO
DstOut	GL_ZERO	GL_ONE_MINUS_SRC_ALPHA
Dst	GL_ZERO	GL_ONE
SrcAtop	GL_DST_ALPHA	GL_ONE_MINUS_SRC_ALPHA
DstAtop	GL_ONE_MINUS_DST_ALPHA	GL_SRC_ALPHA
AlphaXor	GL_ONE_MINUS_DST_ALPHA	GL_ONE_MINUS_SRC_ALPHA

Field Summary

Modifier and Type	Field and Description
private float	aspectRatio The original aspect ratio of the image, before any rescaling that might have occurred due to using the GLU mipmap routines.
private TextureCoords	coords The texture coordinates corresponding to the entire image.
private static final boolean	DEBUG
private static final boolean	disableNPOT
private static final boolean	disableTexRect
private int	estimatedMemorySize An estimate of the amount of texture memory this texture consumes.
private int	imageTarget The image GL target type for this texture, or its sub-components if cubemap.
private int	imgHeight The height of the image.
private int	imgWidth The width of the image.
private boolean	mustFlipVertically Indicates whether the TextureData requires a vertical flip of the texture coords.
private int	target The GL target type for this texture.
private int	texHeight The height of the texture.
private int	texID The GL texture ID.
private int	texWidth The width of the texture.
private boolean	usingAutoMipmapGeneration Indicates whether we're using automatic mipmap generation support (GL_GENERATE_MIPMAP).
private static final boolean	VERBOSE

Constructor Summary

Access	Constructor and Description
public	Texture(final GL gl, final TextureData data)
public	Texture(final int the OpenGL texture target, eg GL.GL_TEXTURE_2D, GL2.GL_TEXTURE_RECTANGLE target) Constructor for use when creating e.g. cube maps, where there is no initial texture data
public	Texture(final int the OpenGL texture object to wrap textureID, final int the OpenGL texture target, eg GL.GL_TEXTURE_2D, GL2.GL_TEXTURE_RECTANGLE target, final int the width of the texture in pixels texWidth, final int the height of the texture in pixels texHeight, final int the width of the image within the texture in pixels (if the content is a sub-rectangle in the upper left corner); otherwise, pass in texWidth imgWidth, final int the height of the image within the texture in pixels (if the content is a sub-rectangle in the upper left corner); otherwise, pass in texHeight imgHeight, final boolean indicates whether the texture coordinates must be flipped vertically in order to properly display the texture mustFlipVertically) Constructor to wrap an OpenGL texture ID from an external library and allows some of the base methods from the Texture class, such as binding and querying of texture coordinates, to be used with it.

Method Summary

Modifier and Type	Method and Description
public void	bind(final GL the current GL context gl) Binds this texture to the given GL context.
private void	checkCompressedTextureExtensions(final GL gl, final TextureData data)
public void	destroy(final GL gl) Destroys the native resources used by this texture object.
public void	disable(final GL the current GL object gl) Disables this texture's target (e.g., GL_TEXTURE_2D) in the given GL state.
public void	enable(final GL the current GL object gl) Enables this texture's target (e.g., GL_TEXTURE_2D) in the given GL context's state.
public float	getAspectRatio() Returns the original aspect ratio of the image, defined as (image width) / (image height), before any scaling that might have occurred as a result of using the GLU mipmap routines.
public int	getEstimatedMemorySize() Returns an estimate of the amount of texture memory in bytes this Texture consumes.
public int	Returns: the height of the texture getHeight() Returns the height of the allocated OpenGL texture in pixels.
public int	Returns: the height of the image getImageHeight() Returns the height of the image contained within this texture.
public int	getImageTarget() Returns the image OpenGL "target" of this texture, or its sub-components if cubemap.
public TextureCoords	Returns: the texture coordinates corresponding to the entire image getImageTexCoords() Returns the set of texture coordinates corresponding to the entire image.
public int	Returns: the width of the image getImageWidth() Returns the width of the image contained within this texture.
public boolean	getMustFlipVertically() Indicates whether this texture's texture coordinates must be flipped vertically in order to properly display the texture.
public TextureCoords	Returns: the texture coordinates corresponding to the specified sub-image getSubImageTexCoords(final int x1, final int y1, final int x2, final int y2) Returns the set of texture coordinates corresponding to the specified sub-image.
public int	getTarget() Returns the OpenGL "target" of this texture.
public int	getTextureObject(final GL required to be valid and current in case the texture object has not been generated yet, otherwise it may be `null`. gl) Returns the underlying OpenGL texture object for this texture and generates it if not done yet.
public int	getTextureObject() Returns the underlying OpenGL texture object for this texture, maybe `0` if not yet generated.
public int	Returns: the width of the texture getWidth() Returns the width of the allocated OpenGL texture in pixels.
private static boolean	haveNPOT(final GL gl)
private static boolean	haveTexRect(final GL gl)
private static boolean	Returns: true if the given value is a power of two, false otherwise isPowerOfTwo(final int val) Returns true if the given value is a power of two.
public boolean	isUsingAutoMipmapGeneration() Indicates whether this Texture is using automatic mipmap generation (via the OpenGL texture parameter GL_GENERATE_MIPMAP).
private static int	Returns: the next power of two nextPowerOfTwo(final int the value val) Returns the nearest power of two that is larger than the given value.
private static boolean	preferTexRect(final GL gl)
public void	setMustFlipVertically(final boolean v) Change whether the TextureData requires a vertical flip of the texture coords.
public void	setTexParameterf(final GL gl, final int parameterName, final float value) Sets the OpenGL floating-point texture parameter for the texture's target.
public void	setTexParameterfv(final GL gl, final int parameterName, final FloatBuffer params) Sets the OpenGL multi-floating-point texture parameter for the texture's target.
public void	setTexParameterfv(final GL gl, final int parameterName, final float[] params, final int params_offset) Sets the OpenGL multi-floating-point texture parameter for the texture's target.
public void	setTexParameteri(final GL gl, final int parameterName, final int value) Sets the OpenGL integer texture parameter for the texture's target.
public void	setTexParameteriv(final GL gl, final int parameterName, final IntBuffer params) Sets the OpenGL multi-integer texture parameter for the texture's target.
public void	setTexParameteriv(final GL gl, final int parameterName, final int[] params, final int params_offset) Sets the OpenGL multi-integer texture parameter for the texture's target.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public void	updateImage(final GL gl, final TextureData data) Updates the entire content area incl.
public void	updateImage(final GL gl, final TextureData data, final int targetOverride) Updates the content area incl.
public void	updateSubImage(final GL gl, final TextureData the image data to be uploaded to this texture data, final int 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. mipmapLevel, final int the x offset (in pixels) relative to the lower-left corner of this texture x, final int the y offset (in pixels) relative to the lower-left corner of this texture y) Updates a subregion of the content area of this texture using the given data.
public void	updateSubImage(final GL gl, final TextureData the image data to be uploaded to this texture data, final int 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. mipmapLevel, final int the x offset (in pixels) relative to the lower-left corner of this texture where the update will be applied dstx, final int the y offset (in pixels) relative to the lower-left corner of this texture where the update will be applied dsty, final int the x offset (in pixels) relative to the lower-left corner of the supplied TextureData from which to fetch the update rectangle srcx, final int the y offset (in pixels) relative to the lower-left corner of the supplied TextureData from which to fetch the update rectangle srcy, final int the width (in pixels) of the rectangle to be updated width, final int the height (in pixels) of the rectangle to be updated height) Updates a subregion of the content area of this texture using the specified sub-region of the given data.
private void	updateSubImageImpl(final GL gl, final TextureData data, final int newTarget, final int mipmapLevel, int dstx, int dsty, int srcx, int srcy, int width, int height)
private void	updateTexCoords()
private boolean	validateTexID(final GL gl, final boolean throwException)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

aspectRatio	back to summary
private float aspectRatio The original aspect ratio of the image, before any rescaling that might have occurred due to using the GLU mipmap routines.

coords	back to summary
private TextureCoords coords The texture coordinates corresponding to the entire image.

DEBUG	back to summary
private static final boolean DEBUG

disableNPOT	back to summary
private static final boolean disableNPOT

disableTexRect	back to summary
private static final boolean disableTexRect

estimatedMemorySize	back to summary
private int estimatedMemorySize An estimate of the amount of texture memory this texture consumes.

imageTarget	back to summary
private int imageTarget The image GL target type for this texture, or its sub-components if cubemap.

imgHeight	back to summary
private int imgHeight The height of the image.

imgWidth	back to summary
private int imgWidth The width of the image.

mustFlipVertically	back to summary
private boolean mustFlipVertically Indicates whether the TextureData requires a vertical flip of the texture coords.

target	back to summary
private int target The GL target type for this texture.

texHeight	back to summary
private int texHeight The height of the texture.

texID	back to summary
private int texID The GL texture ID.

texWidth	back to summary
private int texWidth The width of the texture.

usingAutoMipmapGeneration	back to summary
private boolean usingAutoMipmapGeneration Indicates whether we're using automatic mipmap generation support (GL_GENERATE_MIPMAP).

VERBOSE	back to summary
private static final boolean VERBOSE

Constructor Detail

Texture	back to summary
public Texture(final GL gl, final TextureData data) throws GLException

Texture	back to summary
public Texture(final int target) Constructor for use when creating e.g. cube maps, where there is no initial texture data Parameters target:int the OpenGL texture target, eg GL.GL_TEXTURE_2D, GL2.GL_TEXTURE_RECTANGLE

Texture