Class Texture
- java.lang.Object
-
- com.jogamp.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.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
-> activetextureUnit
'stextureTarget
viagl.glBindTexture(textureTarget, textureId)
- Compatible Context Only: Enable active
textureUnit
'stextureTarget
viaglEnable(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, seeGLBase.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 usegetImageTexCoords()
andgetSubImageTexCoords(int, int, int, int)
, 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 callingenable(com.jogamp.opengl.GL)
/bind(com.jogamp.opengl.GL)
/disable(com.jogamp.opengl.GL)
any more than necessary. For example, applications using many Texture objects in the same scene may want to reduce the number of calls to bothenable(com.jogamp.opengl.GL)
anddisable(com.jogamp.opengl.GL)
. To do this it is necessary to callgetTarget()
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 callbind(com.jogamp.opengl.GL)
, but when drawing many triangles all using the same texture, for best performance only one call tobind(com.jogamp.opengl.GL)
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 likeGL_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 - Author:
- Chris Campbell, Kenneth Russell, et.al.
- Optional: Set active textureUnit via
-
-
Constructor Summary
Constructors Constructor Description Texture(int target)
Constructor for use when creating e.g.Texture(int textureID, int target, int texWidth, int texHeight, int imgWidth, int imgHeight, boolean 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.Texture(GL gl, TextureData data)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
bind(GL gl)
Binds this texture to the given GL context.void
destroy(GL gl)
Destroys the native resources used by this texture object.void
disable(GL gl)
Disables this texture's target (e.g., GL_TEXTURE_2D) in the given GL state.void
enable(GL gl)
Enables this texture's target (e.g., GL_TEXTURE_2D) in the given GL context's state.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.int
getEstimatedMemorySize()
Returns an estimate of the amount of texture memory in bytes this Texture consumes.int
getHeight()
Returns the height of the allocated OpenGL texture in pixels.int
getImageHeight()
Returns the height of the image contained within this texture.int
getImageTarget()
Returns the image OpenGL "target" of this texture, or its sub-components if cubemap.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, maybe0
if not yet generated.int
getTextureObject(GL gl)
Returns the underlying OpenGL texture object for this texture and generates it if not done yet.int
getWidth()
Returns the width of the allocated OpenGL texture in pixels.boolean
isUsingAutoMipmapGeneration()
Indicates whether this Texture is using automatic mipmap generation (via the OpenGL texture parameter GL_GENERATE_MIPMAP).void
setMustFlipVertically(boolean v)
Change whether the TextureData requires a vertical flip of the texture coords.void
setTexParameterf(GL gl, int parameterName, float value)
Sets the OpenGL floating-point texture parameter for the texture's target.void
setTexParameterfv(GL gl, int parameterName, float[] params, int params_offset)
Sets the OpenGL multi-floating-point texture parameter for the texture's target.void
setTexParameterfv(GL gl, int parameterName, FloatBuffer params)
Sets the OpenGL multi-floating-point texture parameter for the texture's target.void
setTexParameteri(GL gl, int parameterName, int value)
Sets the OpenGL integer texture parameter for the texture's target.void
setTexParameteriv(GL gl, int parameterName, int[] params, int params_offset)
Sets the OpenGL multi-integer texture parameter for the texture's target.void
setTexParameteriv(GL gl, int parameterName, IntBuffer params)
Sets the OpenGL multi-integer texture parameter for the texture's target.String
toString()
void
updateImage(GL gl, TextureData data)
Updates the entire content area incl.void
updateImage(GL gl, TextureData data, int targetOverride)
Updates the content area incl.void
updateSubImage(GL gl, TextureData data, int mipmapLevel, int x, int y)
Updates a subregion of the content area of this texture using the given data.void
updateSubImage(GL gl, TextureData data, int mipmapLevel, int dstx, int dsty, int srcx, int srcy, int width, int height)
Updates a subregion of the content area of this texture using the specified sub-region of the given data.
-
-
-
Constructor Detail
-
Texture
public Texture(GL gl, TextureData data) throws GLException
- Throws:
GLException
-
Texture
public Texture(int target)
Constructor for use when creating e.g. cube maps, where there is no initial texture data- Parameters:
target
- the OpenGL texture target, eg GL.GL_TEXTURE_2D, GL2.GL_TEXTURE_RECTANGLE
-
Texture
public Texture(int textureID, int target, int texWidth, int texHeight, int imgWidth, int imgHeight, boolean 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. Attempts to update such textures' contents will yield undefined results.- Parameters:
textureID
- the OpenGL texture object to wraptarget
- the OpenGL texture target, eg GL.GL_TEXTURE_2D, GL2.GL_TEXTURE_RECTANGLEtexWidth
- the width of the texture in pixelstexHeight
- the height of the texture in pixelsimgWidth
- 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 texWidthimgHeight
- 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 texHeightmustFlipVertically
- indicates whether the texture coordinates must be flipped vertically in order to properly display the texture
-
-
Method Detail
-
enable
public void enable(GL gl) throws GLException
Enables this texture's target (e.g., GL_TEXTURE_2D) in the given GL context's state. This method is a shorthand equivalent of the following OpenGL code:gl.glEnable(texture.getTarget());
Call is ignored if the
GL
object's context is using a core profile, seeGLBase.isGLcore()
, or ifgetTarget()
isGLES2.GL_TEXTURE_EXTERNAL_OES
.See the performance tips above for hints on how to maximize performance when using many Texture objects.
- Parameters:
gl
- the current GL object- Throws:
GLException
- if no OpenGL context was current or if any OpenGL-related errors occurred
-
disable
public void disable(GL gl) throws GLException
Disables this texture's target (e.g., GL_TEXTURE_2D) in the given GL state. This method is a shorthand equivalent of the following OpenGL code:gl.glDisable(texture.getTarget());
Call is ignored if the
GL
object's context is using a core profile, seeGLBase.isGLcore()
, or ifgetTarget()
isGLES2.GL_TEXTURE_EXTERNAL_OES
.See the performance tips above for hints on how to maximize performance when using many Texture objects.
- Parameters:
gl
- the current GL object- Throws:
GLException
- if no OpenGL context was current or if any OpenGL-related errors occurred
-
bind
public void bind(GL gl) throws GLException
Binds this texture to the given GL context. This method is a shorthand equivalent of the following OpenGL code:gl.glBindTexture(texture.getTarget(), texture.getTextureObject());
See the performance tips above for hints on how to maximize performance when using many Texture objects.- Parameters:
gl
- the current GL context- Throws:
GLException
- if no OpenGL context was current or if any OpenGL-related errors occurred
-
destroy
public void destroy(GL gl) throws GLException
Destroys the native resources used by this texture object.- Throws:
GLException
- if any OpenGL-related errors occurred
-
getTarget
public int getTarget()
Returns the OpenGL "target" of this texture.- See Also:
GL.GL_TEXTURE_2D
,GL2.GL_TEXTURE_RECTANGLE_ARB
-
getImageTarget
public int getImageTarget()
Returns the image OpenGL "target" of this texture, or its sub-components if cubemap.- See Also:
GL.GL_TEXTURE_2D
,GL2.GL_TEXTURE_RECTANGLE_ARB
-
getWidth
public int getWidth()
Returns the width of the allocated OpenGL texture in pixels. 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 allocated OpenGL texture in pixels. 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. Note that for non-power-of-two textures in particular this may not be equal to the result ofgetWidth()
. It is recommended that applications callgetImageTexCoords()
andgetSubImageTexCoords(int, int, int, int)
rather than using this API directly.- Returns:
- the width of the image
-
getImageHeight
public int getImageHeight()
Returns the height of the image contained within this texture. Note that for non-power-of-two textures in particular this may not be equal to the result ofgetHeight()
. It is recommended that applications callgetImageTexCoords()
andgetSubImageTexCoords(int, int, int, int)
rather than using this API directly.- Returns:
- the height of the image
-
getAspectRatio
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.
-
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(GL gl, TextureData data) throws GLException
Updates the entire content area incl.TextureCoords
of this texture using the data in the given image.- Throws:
GLException
- 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 bygetImageTexCoords
andgetSubImageTexCoords
, but applications may generate or otherwise produce texture coordinates which must be corrected.
-
setMustFlipVertically
public void setMustFlipVertically(boolean v)
Change whether the TextureData requires a vertical flip of the texture coords.No-op if no change, otherwise generates new
TextureCoords
.
-
updateImage
public void updateImage(GL gl, TextureData data, int targetOverride) throws GLException
Updates the content area incl.TextureCoords
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 any OpenGL-related errors occurred
-
updateSubImage
public void updateSubImage(GL gl, TextureData data, int mipmapLevel, int x, int y) throws GLException
Updates a subregion of the content area of this texture using the given data. If automatic mipmap generation is in use (seeisUsingAutoMipmapGeneration
), updates to the base (level 0) mipmap will cause the lower-level mipmaps to be regenerated, and updates to other mipmap levels will be ignored. Otherwise, if automatic mipmap generation is not in use, 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 texturemipmapLevel
- 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 texturey
- the y offset (in pixels) relative to the lower-left corner of this texture- Throws:
GLException
- if any OpenGL-related errors occurred
-
updateSubImage
public void updateSubImage(GL gl, TextureData data, int mipmapLevel, int dstx, int dsty, int srcx, int srcy, int width, int height) throws GLException
Updates a subregion of the content area of this texture using the specified sub-region of the given data. If automatic mipmap generation is in use (seeisUsingAutoMipmapGeneration
), updates to the base (level 0) mipmap will cause the lower-level mipmaps to be regenerated, and updates to other mipmap levels will be ignored. Otherwise, if automatic mipmap generation is not in use, only updates the specified mipmap level and does not re-generate mipmaps if they were originally produced or loaded. This method is only supported for uncompressed TextureData sources.- Parameters:
data
- the image data to be uploaded to this texturemipmapLevel
- 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.dstx
- the x offset (in pixels) relative to the lower-left corner of this texture where the update will be applieddsty
- the y offset (in pixels) relative to the lower-left corner of this texture where the update will be appliedsrcx
- the x offset (in pixels) relative to the lower-left corner of the supplied TextureData from which to fetch the update rectanglesrcy
- the y offset (in pixels) relative to the lower-left corner of the supplied TextureData from which to fetch the update rectanglewidth
- the width (in pixels) of the rectangle to be updatedheight
- the height (in pixels) of the rectangle to be updated- Throws:
GLException
- if no OpenGL context was current or if any OpenGL-related errors occurred
-
setTexParameterf
public void setTexParameterf(GL gl, 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(GL gl, 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 any OpenGL-related errors occurred
-
setTexParameterfv
public void setTexParameterfv(GL gl, 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 any OpenGL-related errors occurred
-
setTexParameteri
public void setTexParameteri(GL gl, 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 if OpenGL 1.2 is supported on the current platform and GL_CLAMP if not. Causes this texture to be bound to the current texture state.- Throws:
GLException
- if any OpenGL-related errors occurred
-
setTexParameteriv
public void setTexParameteriv(GL gl, 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 any OpenGL-related errors occurred
-
setTexParameteriv
public void setTexParameteriv(GL gl, 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 any OpenGL-related errors occurred
-
getTextureObject
public int getTextureObject(GL gl)
Returns the underlying OpenGL texture object for this texture and generates it if not done yet.Most applications will not need to access this, since it is handled automatically by the bind(GL) and destroy(GL) APIs.
- Parameters:
gl
- required to be valid and current in case the texture object has not been generated yet, otherwise it may benull
.- See Also:
getTextureObject()
-
getTextureObject
public int getTextureObject()
Returns the underlying OpenGL texture object for this texture, maybe0
if not yet generated.Most applications will not need to access this, since it is handled automatically by the bind(GL) and destroy(GL) APIs.
- See Also:
getTextureObject(GL)
-
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.
-
isUsingAutoMipmapGeneration
public boolean isUsingAutoMipmapGeneration()
Indicates whether this Texture is using automatic mipmap generation (via the OpenGL texture parameter GL_GENERATE_MIPMAP). This will automatically be used when mipmapping is requested via the TextureData and either OpenGL 1.4 or the GL_SGIS_generate_mipmap extension is available. If so, updates to the base image (mipmap level 0) will automatically propagate down to the lower mipmap levels. Manual updates of the mipmap data at these lower levels will be ignored.
-
-