* Due to many confusions w/ texture usage, following list described the order * and semantics of texture unit selection, binding and enabling. *
gl.glActiveTexture(GL.GL_TEXTURE0 + textureUnit), 0 is default.textureId -> active textureUnit's textureTarget via gl.glBindTexture(textureTarget, textureId)textureUnit's textureTarget via glEnable(textureTarget).
* textureUnit in your shader program, enable shader program.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 {@link 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 {@link #getImageTexCoords} and {@link
* #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 {@link #enable} /
* {@link #bind} / {@link #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 {@link #enable} and
* {@link #disable}. To do this it is necessary to call {@link
* #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 {@link
* #bind}, but when drawing many triangles all using the same texture,
* for best performance only one call to {@link #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 |
* gl.glEnable(texture.getTarget());
*
* * Call is ignored if the {@link GL} object's context * is using a core profile, see {@link GL#isGLcore()}, * or if {@link #getTarget()} is {@link GLES2#GL_TEXTURE_EXTERNAL_OES}. *
** See the performance tips above for hints * on how to maximize performance when using many Texture objects. *
* @param gl the current GL object * * @throws GLException if no OpenGL context was current or if any * OpenGL-related errors occurred */ public void enable(final GL gl) throws GLException { if( !gl.isGLcore() && GLES2.GL_TEXTURE_EXTERNAL_OES != target) { gl.glEnable(target); } } /** * 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 {@link GL} object's context * is using a core profile, see {@link GL#isGLcore()}, * or if {@link #getTarget()} is {@link GLES2#GL_TEXTURE_EXTERNAL_OES}. *
** See the performance tips above for hints * on how to maximize performance when using many Texture objects. *
* @param gl the current GL object * * @throws GLException if no OpenGL context was current or if any * OpenGL-related errors occurred */ public void disable(final GL gl) throws GLException { if( !gl.isGLcore() && GLES2.GL_TEXTURE_EXTERNAL_OES != target ) { gl.glDisable(target); } } /** * 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.
*
* @param gl the current GL context
* @throws GLException if no OpenGL context was current or if any
* OpenGL-related errors occurred
*/
public void bind(final GL gl) throws GLException {
validateTexID(gl, true);
gl.glBindTexture(target, texID);
}
/**
* Destroys and {@code null}s the {@link #getTextureObject() underlying native texture} used by this {@link Texture} instance
* if {@link #ownsTexture() owned}, otherwise just {@code null}s the {@link #getTextureObject() underlying native texture}.
*
* @throws GLException if any OpenGL-related errors occurred
*/
public void destroy(final GL gl) throws GLException {
if( 0 != texID && ownsTextureID ) {
gl.glDeleteTextures(1, new int[] {texID}, 0);
}
texID = 0;
}
/**
* Returns the OpenGL "target" of this texture.
* @see com.jogamp.opengl.GL#GL_TEXTURE_2D
* @see com.jogamp.opengl.GL2#GL_TEXTURE_RECTANGLE_ARB
*/
public int getTarget() {
return target;
}
/**
* Returns the image OpenGL "target" of this texture, or its sub-components if cubemap.
* @see com.jogamp.opengl.GL#GL_TEXTURE_2D
* @see com.jogamp.opengl.GL2#GL_TEXTURE_RECTANGLE_ARB
*/
public int getImageTarget() {
return imageTarget;
}
/**
* 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.
*
* @return the width of the texture
*/
public int getWidth() {
return texWidth;
}
/**
* 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.
*
* @return the height of the texture
*/
public int getHeight() {
return texHeight;
}
/**
* 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 of {@link #getWidth}. It is
* recommended that applications call {@link #getImageTexCoords} and
* {@link #getSubImageTexCoords} rather than using this API
* directly.
*
* @return the width of the image
*/
public int getImageWidth() {
return imgWidth;
}
/**
* 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 of {@link #getHeight}. It is
* recommended that applications call {@link #getImageTexCoords} and
* {@link #getSubImageTexCoords} rather than using this API
* directly.
*
* @return the height of the image
*/
public int getImageHeight() {
return imgHeight;
}
/**
* 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 float getAspectRatio() {
return aspectRatio;
}
/**
* 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.
*
* @return the texture coordinates corresponding to the entire image
*/
public TextureCoords getImageTexCoords() {
return coords;
}
/**
* 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.
*
* @return the texture coordinates corresponding to the specified sub-image
*/
public TextureCoords getSubImageTexCoords(final int x1, final int y1, final int x2, final int y2) {
if (GL2.GL_TEXTURE_RECTANGLE_ARB == imageTarget) {
if (mustFlipVertically) {
return new TextureCoords(x1, texHeight - y1, x2, texHeight - y2);
} else {
return new TextureCoords(x1, y1, x2, y2);
}
} else {
final float tx1 = (float)x1 / (float)texWidth;
final float ty1 = (float)y1 / (float)texHeight;
final float tx2 = (float)x2 / (float)texWidth;
final float ty2 = (float)y2 / (float)texHeight;
if (mustFlipVertically) {
final float yMax = (float) imgHeight / (float) texHeight;
return new TextureCoords(tx1, yMax - ty1, tx2, yMax - ty2);
} else {
return new TextureCoords(tx1, ty1, tx2, ty2);
}
}
}
/**
* Updates the entire content area incl. {@link TextureCoords}
* of this texture using the data in the given image.
*
* @throws GLException if any OpenGL-related errors occurred
*/
public void updateImage(final GL gl, final TextureData data) throws GLException {
updateImage(gl, data, 0);
}
/**
* Indicates whether this texture's texture coordinates must be
* flipped vertically in order to properly display the texture. This
* is handled automatically by {@link #getImageTexCoords
* getImageTexCoords} and {@link #getSubImageTexCoords
* getSubImageTexCoords}, but applications may generate or otherwise
* produce texture coordinates which must be corrected.
*/
public boolean getMustFlipVertically() {
return mustFlipVertically;
}
/**
* Change whether the TextureData requires a vertical flip of
* the texture coords.
* * No-op if no change, otherwise generates new {@link TextureCoords}. *
*/ public void setMustFlipVertically(final boolean v) { if( v != mustFlipVertically ) { mustFlipVertically = v; updateTexCoords(); } } /** * Updates the content area incl. {@link 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 */ public void updateImage(final GL gl, final TextureData data, final int targetOverride) throws GLException { validateTexID(gl, true); imgWidth = data.getWidth(); imgHeight = data.getHeight(); aspectRatio = (float) imgWidth / (float) imgHeight; mustFlipVertically = data.getMustFlipVertically(); int texTarget = 0; int texParamTarget = this.target; // See whether we have automatic mipmap generation support boolean haveAutoMipmapGeneration = (gl.isExtensionAvailable(GLExtensions.VERSION_1_4) || gl.isExtensionAvailable(GLExtensions.SGIS_generate_mipmap)); // Indicate to the TextureData what functionality is available data.setHaveEXTABGR(gl.isExtensionAvailable(GLExtensions.EXT_abgr)); data.setHaveGL12(gl.isExtensionAvailable(GLExtensions.VERSION_1_2)); // Indicates whether both width and height are power of two final boolean isPOT = Bitfield.Util.isPowerOf2(imgWidth) && Bitfield.Util.isPowerOf2(imgHeight); // Note that automatic mipmap generation doesn't work for // GL_ARB_texture_rectangle if (!isPOT && !haveNPOT(gl)) { haveAutoMipmapGeneration = false; } boolean expandingCompressedTexture = false; boolean done = false; if (data.getMipmap() && !haveAutoMipmapGeneration) { // GLU always scales the texture's dimensions to be powers of // two. It also doesn't really matter exactly what the texture // width and height are because the texture coords are always // between 0.0 and 1.0. imgWidth = Bitfield.Util.roundToPowerOf2(imgWidth); imgHeight = Bitfield.Util.roundToPowerOf2(imgHeight); texWidth = imgWidth; texHeight = imgHeight; texTarget = GL.GL_TEXTURE_2D; done = true; } if (!done && preferTexRect(gl) && !isPOT && haveTexRect(gl) && !data.isDataCompressed() && !gl.isGL3() && !gl.isGLES()) { // GL_ARB_texture_rectangle does not work for compressed textures if (DEBUG) { System.err.println("Using GL_ARB_texture_rectangle preferentially on this hardware"); } texWidth = imgWidth; texHeight = imgHeight; texTarget = GL2.GL_TEXTURE_RECTANGLE_ARB; done = true; } if (!done && (isPOT || haveNPOT(gl))) { if (DEBUG) { if (isPOT) { System.err.println("Power-of-two texture"); } else { System.err.println("Using GL_ARB_texture_non_power_of_two"); } } texWidth = imgWidth; texHeight = imgHeight; texTarget = GL.GL_TEXTURE_2D; done = true; } if (!done && haveTexRect(gl) && !data.isDataCompressed() && !gl.isGL3() && !gl.isGLES()) { // GL_ARB_texture_rectangle does not work for compressed textures if (DEBUG) { System.err.println("Using GL_ARB_texture_rectangle"); } texWidth = imgWidth; texHeight = imgHeight; texTarget = GL2.GL_TEXTURE_RECTANGLE_ARB; done = true; } if (!done) { // If we receive non-power-of-two compressed texture data and // don't have true hardware support for compressed textures, we // can fake this support by producing an empty "compressed" // texture image, using glCompressedTexImage2D with that to // allocate the texture, and glCompressedTexSubImage2D with the // incoming data. if (data.isDataCompressed()) { if (data.getMipmapData() != null) { // We don't currently support expanding of compressed, // mipmapped non-power-of-two textures to the nearest power // of two; the obvious port of the non-mipmapped code didn't // work throw new GLException("Mipmapped non-power-of-two compressed textures only supported on OpenGL 2.0 hardware (GL_ARB_texture_non_power_of_two)"); } expandingCompressedTexture = true; } if (DEBUG) { System.err.println("Expanding texture to power-of-two dimensions"); } if (data.getBorder() != 0) { throw new RuntimeException("Scaling up a non-power-of-two texture which has a border won't work"); } texWidth = Bitfield.Util.roundToPowerOf2(imgWidth); texHeight = Bitfield.Util.roundToPowerOf2(imgHeight); texTarget = GL.GL_TEXTURE_2D; } texParamTarget = texTarget; imageTarget = texTarget; updateTexCoords(); if (targetOverride != 0) { // Allow user to override auto detection and skip bind step (for // cubemap construction) if (this.target == 0) { throw new GLException("Override of target failed; no target specified yet"); } texTarget = targetOverride; texParamTarget = this.target; gl.glBindTexture(texParamTarget, texID); } else { gl.glBindTexture(texTarget, texID); } if (data.getMipmap() && !haveAutoMipmapGeneration) { final int[] align = new int[1]; gl.glGetIntegerv(GL.GL_UNPACK_ALIGNMENT, align, 0); // save alignment gl.glPixelStorei(GL.GL_UNPACK_ALIGNMENT, data.getAlignment()); if (data.isDataCompressed()) { throw new GLException("May not request mipmap generation for compressed textures"); } try { // FIXME: may need check for GLUnsupportedException final GLU glu = GLU.createGLU(gl); glu.gluBuild2DMipmaps(texTarget, data.getInternalFormat(), data.getWidth(), data.getHeight(), data.getPixelFormat(), data.getPixelType(), data.getBuffer()); } finally { gl.glPixelStorei(GL.GL_UNPACK_ALIGNMENT, align[0]); // restore alignment } } else { checkCompressedTextureExtensions(gl, data); final Buffer[] mipmapData = data.getMipmapData(); if (mipmapData != null) { int width = texWidth; int height = texHeight; for (int i = 0; i < mipmapData.length; i++) { if (data.isDataCompressed()) { // Need to use glCompressedTexImage2D directly to allocate and fill this image // Avoid spurious memory allocation when possible gl.glCompressedTexImage2D(texTarget, i, data.getInternalFormat(), width, height, data.getBorder(), mipmapData[i].remaining(), mipmapData[i]); } else { // Allocate texture image at this level gl.glTexImage2D(texTarget, i, data.getInternalFormat(), width, height, data.getBorder(), data.getPixelFormat(), data.getPixelType(), null); updateSubImageImpl(gl, data, texTarget, i, 0, 0, 0, 0, data.getWidth(), data.getHeight()); } width = Math.max(width / 2, 1); height = Math.max(height / 2, 1); } } else { if (data.isDataCompressed()) { if (!expandingCompressedTexture) { // Need to use glCompressedTexImage2D directly to allocate and fill this image // Avoid spurious memory allocation when possible gl.glCompressedTexImage2D(texTarget, 0, data.getInternalFormat(), texWidth, texHeight, data.getBorder(), data.getBuffer().capacity(), data.getBuffer()); } else { final ByteBuffer buf = DDSImage.allocateBlankBuffer(texWidth, texHeight, data.getInternalFormat()); gl.glCompressedTexImage2D(texTarget, 0, data.getInternalFormat(), texWidth, texHeight, data.getBorder(), buf.capacity(), buf); updateSubImageImpl(gl, data, texTarget, 0, 0, 0, 0, 0, data.getWidth(), data.getHeight()); } } else { if (data.getMipmap() && haveAutoMipmapGeneration && gl.isGL2ES1()) { // For now, only use hardware mipmapping for uncompressed 2D // textures where the user hasn't explicitly specified // mipmap data; don't know about interactions between // GL_GENERATE_MIPMAP and glCompressedTexImage2D gl.glTexParameteri(texParamTarget, GL2ES1.GL_GENERATE_MIPMAP, GL.GL_TRUE); usingAutoMipmapGeneration = true; } gl.glTexImage2D(texTarget, 0, data.getInternalFormat(), texWidth, texHeight, data.getBorder(), data.getPixelFormat(), data.getPixelType(), null); updateSubImageImpl(gl, data, texTarget, 0, 0, 0, 0, 0, data.getWidth(), data.getHeight()); } } } final int minFilter = (data.getMipmap() ? GL.GL_LINEAR_MIPMAP_LINEAR : GL.GL_LINEAR); final int magFilter = GL.GL_LINEAR; final int wrapMode = (gl.isExtensionAvailable(GLExtensions.VERSION_1_2) || !gl.isGL2()) ? GL.GL_CLAMP_TO_EDGE : GL2.GL_CLAMP; // REMIND: figure out what to do for GL_TEXTURE_RECTANGLE_ARB if (texTarget != GL2.GL_TEXTURE_RECTANGLE_ARB) { gl.glTexParameteri(texParamTarget, GL.GL_TEXTURE_MIN_FILTER, minFilter); gl.glTexParameteri(texParamTarget, GL.GL_TEXTURE_MAG_FILTER, magFilter); gl.glTexParameteri(texParamTarget, GL.GL_TEXTURE_WRAP_S, wrapMode); gl.glTexParameteri(texParamTarget, GL.GL_TEXTURE_WRAP_T, wrapMode); if (this.target == GL.GL_TEXTURE_CUBE_MAP) { gl.glTexParameteri(texParamTarget, GL2ES2.GL_TEXTURE_WRAP_R, wrapMode); } } // Don't overwrite target if we're loading e.g. faces of a cube // map if ((this.target == 0) || (this.target == GL.GL_TEXTURE_2D) || (this.target == GL2.GL_TEXTURE_RECTANGLE_ARB)) { this.target = texTarget; } // This estimate will be wrong for cube maps estimatedMemorySize = data.getEstimatedMemorySize(); } /** * Updates a subregion of the content area of this texture using the * given data. If automatic mipmap generation is in use (see {@link * #isUsingAutoMipmapGeneration isUsingAutoMipmapGeneration}), * 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. * * @param data the image data to be uploaded to this texture * @param 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. * @param x the x offset (in pixels) relative to the lower-left corner * of this texture * @param y the y offset (in pixels) relative to the lower-left corner * of this texture * * @throws GLException if any OpenGL-related errors occurred */ public void updateSubImage(final GL gl, final TextureData data, final int mipmapLevel, final int x, final int y) throws GLException { if (usingAutoMipmapGeneration && mipmapLevel != 0) { // When we're using mipmap generation via GL_GENERATE_MIPMAP, we // don't need to update other mipmap levels return; } bind(gl); updateSubImageImpl(gl, data, target, mipmapLevel, x, y, 0, 0, data.getWidth(), data.getHeight()); } /** * 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 (see {@link #isUsingAutoMipmapGeneration * isUsingAutoMipmapGeneration}), 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. * * @param data the image data to be uploaded to this texture * @param 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. * @param dstx the x offset (in pixels) relative to the lower-left corner * of this texture where the update will be applied * @param dsty the y offset (in pixels) relative to the lower-left corner * of this texture where the update will be applied * @param srcx the x offset (in pixels) relative to the lower-left corner * of the supplied TextureData from which to fetch the update rectangle * @param srcy the y offset (in pixels) relative to the lower-left corner * of the supplied TextureData from which to fetch the update rectangle * @param width the width (in pixels) of the rectangle to be updated * @param height 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 */ public void updateSubImage(final GL gl, final TextureData data, final int mipmapLevel, final int dstx, final int dsty, final int srcx, final int srcy, final int width, final int height) throws GLException { if (data.isDataCompressed()) { throw new GLException("updateSubImage specifying a sub-rectangle is not supported for compressed TextureData"); } if (usingAutoMipmapGeneration && mipmapLevel != 0) { // When we're using mipmap generation via GL_GENERATE_MIPMAP, we // don't need to update other mipmap levels return; } bind(gl); updateSubImageImpl(gl, data, target, mipmapLevel, dstx, dsty, srcx, srcy, width, height); } /** * 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 */ public void setTexParameterf(final GL gl, final int parameterName, final float value) { bind(gl); gl.glTexParameterf(target, parameterName, value); } /** * 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 */ public void setTexParameterfv(final GL gl, final int parameterName, final FloatBuffer params) { bind(gl); gl.glTexParameterfv(target, parameterName, 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 */ public void setTexParameterfv(final GL gl, final int parameterName, final float[] params, final int params_offset) { bind(gl); gl.glTexParameterfv(target, parameterName, params, params_offset); } /** * 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 */ public void setTexParameteri(final GL gl, final int parameterName, final int value) { bind(gl); gl.glTexParameteri(target, parameterName, value); } /** * 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 */ public void setTexParameteriv(final GL gl, final int parameterName, final IntBuffer params) { bind(gl); gl.glTexParameteriv(target, parameterName, 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 */ public void setTexParameteriv(final GL gl, final int parameterName, final int[] params, final int params_offset) { bind(gl); gl.glTexParameteriv(target, parameterName, params, params_offset); } /** * 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. *
* @param gl required to be valid and current in case the texture object has not been generated yet, * otherwise it may benull.
* @see #getTextureObject()
*/
public int getTextureObject(final GL gl) {
validateTexID(gl, false);
return texID;
}
/**
* Returns the underlying OpenGL texture object for this texture,
* maybe 0 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 #getTextureObject(GL) */ public int getTextureObject() { return texID; } /** Returns whether {@link #getTextureObject()} is owned by this {@link Texture} instance. */ public final boolean ownsTexture() { return ownsTextureID; } /** 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. */ public int getEstimatedMemorySize() { return estimatedMemorySize; } /** 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. */ public boolean isUsingAutoMipmapGeneration() { return usingAutoMipmapGeneration; } //---------------------------------------------------------------------- // Internals only below this point // private void updateTexCoords() { if ( GL2.GL_TEXTURE_RECTANGLE_ARB == imageTarget ) { if (mustFlipVertically) { coords = new TextureCoords(0, imgHeight, imgWidth, 0); } else { coords = new TextureCoords(0, 0, imgWidth, imgHeight); } } else { if (mustFlipVertically) { coords = new TextureCoords(0, // l (float) imgHeight / (float) texHeight, // b (float) imgWidth / (float) texWidth, // r 0 // t ); } else { coords = new TextureCoords(0, // l 0, // b (float) imgWidth / (float) texWidth, // r (float) imgHeight / (float) texHeight // t ); } } } 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) throws GLException { data.setHaveEXTABGR(gl.isExtensionAvailable(GLExtensions.EXT_abgr)); data.setHaveGL12(gl.isExtensionAvailable(GLExtensions.VERSION_1_2)); Buffer buffer = data.getBuffer(); if (buffer == null && data.getMipmapData() == null) { // Assume user just wanted to get the Texture object allocated return; } int rowlen = data.getRowLength(); int dataWidth = data.getWidth(); int dataHeight = data.getHeight(); if (data.getMipmapData() != null) { // Compute the width, height and row length at the specified mipmap level // Note we do not support specification of the row length for // mipmapped textures at this point for (int i = 0; i < mipmapLevel; i++) { width = Math.max(width / 2, 1); height = Math.max(height / 2, 1); dataWidth = Math.max(dataWidth / 2, 1); dataHeight = Math.max(dataHeight / 2, 1); } rowlen = 0; buffer = data.getMipmapData()[mipmapLevel]; } // Clip incoming rectangles to what is available both on this // texture and in the incoming TextureData if (srcx < 0) { width += srcx; srcx = 0; } if (srcy < 0) { height += srcy; srcy = 0; } // NOTE: not sure whether the following two are the correct thing to do if (dstx < 0) { width += dstx; dstx = 0; } if (dsty < 0) { height += dsty; dsty = 0; } if (srcx + width > dataWidth) { width = dataWidth - srcx; } if (srcy + height > dataHeight) { height = dataHeight - srcy; } if (dstx + width > texWidth) { width = texWidth - dstx; } if (dsty + height > texHeight) { height = texHeight - dsty; } checkCompressedTextureExtensions(gl, data); if (data.isDataCompressed()) { gl.glCompressedTexSubImage2D(newTarget, mipmapLevel, dstx, dsty, width, height, data.getInternalFormat(), buffer.remaining(), buffer); } else { final int[] align = { 0 }; final int[] rowLength = { 0 }; final int[] skipRows = { 0 }; final int[] skipPixels = { 0 }; gl.glGetIntegerv(GL.GL_UNPACK_ALIGNMENT, align, 0); // save alignment if(gl.isGL2GL3()) { gl.glGetIntegerv(GL2ES2.GL_UNPACK_ROW_LENGTH, rowLength, 0); // save row length gl.glGetIntegerv(GL2ES2.GL_UNPACK_SKIP_ROWS, skipRows, 0); // save skipped rows gl.glGetIntegerv(GL2ES2.GL_UNPACK_SKIP_PIXELS, skipPixels, 0); // save skipped pixels } gl.glPixelStorei(GL.GL_UNPACK_ALIGNMENT, data.getAlignment()); if (DEBUG && VERBOSE) { System.out.println("Row length = " + rowlen); System.out.println("skip pixels = " + srcx); System.out.println("skip rows = " + srcy); System.out.println("dstx = " + dstx); System.out.println("dsty = " + dsty); System.out.println("width = " + width); System.out.println("height = " + height); } if(gl.isGL2GL3()) { gl.glPixelStorei(GL2ES2.GL_UNPACK_ROW_LENGTH, rowlen); gl.glPixelStorei(GL2ES2.GL_UNPACK_SKIP_ROWS, srcy); gl.glPixelStorei(GL2ES2.GL_UNPACK_SKIP_PIXELS, srcx); } else { if ( rowlen!=0 && rowlen!=width && srcy!=0 && srcx!=0 ) { throw new GLException("rowlen and/or x/y offset only available for GL2"); } } gl.glTexSubImage2D(newTarget, mipmapLevel, dstx, dsty, width, height, data.getPixelFormat(), data.getPixelType(), buffer); gl.glPixelStorei(GL.GL_UNPACK_ALIGNMENT, align[0]); // restore alignment if(gl.isGL2GL3()) { gl.glPixelStorei(GL2ES2.GL_UNPACK_ROW_LENGTH, rowLength[0]); // restore row length gl.glPixelStorei(GL2ES2.GL_UNPACK_SKIP_ROWS, skipRows[0]); // restore skipped rows gl.glPixelStorei(GL2ES2.GL_UNPACK_SKIP_PIXELS, skipPixels[0]); // restore skipped pixels } } } private void checkCompressedTextureExtensions(final GL gl, final TextureData data) { if (data.isDataCompressed()) { switch (data.getInternalFormat()) { case GL.GL_COMPRESSED_RGB_S3TC_DXT1_EXT: case GL.GL_COMPRESSED_RGBA_S3TC_DXT1_EXT: case GL.GL_COMPRESSED_RGBA_S3TC_DXT3_EXT: case GL.GL_COMPRESSED_RGBA_S3TC_DXT5_EXT: if (!gl.isExtensionAvailable(GLExtensions.EXT_texture_compression_s3tc) && !gl.isExtensionAvailable(GLExtensions.NV_texture_compression_vtc)) { throw new GLException("DXTn compressed textures not supported by this graphics card"); } break; default: // FI1027GXME: should test availability of more texture // compression extensions here break; } } } private boolean validateTexID(final GL gl, final boolean throwException) { if( 0 == texID ) { if( null != gl && ownsTextureID ) { final int[] tmp = new int[1]; gl.glGenTextures(1, tmp, 0); texID = tmp[0]; if ( 0 == texID && throwException ) { throw new GLException("Create texture ID invalid: texID "+texID+", glerr 0x"+Integer.toHexString(gl.glGetError())); } } else if ( throwException ) { if( !ownsTextureID ) { throw new GLException("Invalid external texture ID"); } else { throw new GLException("No GL context given, can't create texture ID"); } } } return 0 != texID; } // Helper routines for disabling certain codepaths private static boolean haveNPOT(final GL gl) { return !disableNPOT && gl.isNPOTTextureAvailable(); } private static boolean haveTexRect(final GL gl) { return (!disableTexRect && TextureIO.isTexRectEnabled() && gl.isExtensionAvailable(GLExtensions.ARB_texture_rectangle)); } private static boolean preferTexRect(final GL gl) { // Prefer GL_ARB_texture_rectangle on ATI hardware on Mac OS X // due to software fallbacks if (NativeWindowFactory.TYPE_MACOSX == NativeWindowFactory.getNativeWindowType(false)) { final String vendor = gl.glGetString(GL.GL_VENDOR); if (vendor != null && vendor.startsWith("ATI")) { return true; } } return false; } }