JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
com.jogamp.opengl.util.texture.TextureSequence Interface Reference

Protocol for texture sequences, like animations, movies, etc. More...

Inheritance diagram for com.jogamp.opengl.util.texture.TextureSequence:
Collaboration diagram for com.jogamp.opengl.util.texture.TextureSequence:

Classes

interface  TexSeqEventListener
 Event listener to notify users of updates regarding the TextureSequence. More...
 
class  TextureFrame
 Texture holder interface, maybe specialized by implementation to associated related data. More...
 

Public Member Functions

int getTextureTarget ()
 Returns the texture target used by implementation. More...
 
int getTextureUnit ()
 Return the texture unit used to render the current frame. More...
 
int[] getTextureMinMagFilter ()
 
int[] getTextureWrapST ()
 
boolean useARatioAdjustment ()
 Returning true indicates texture correction for aspect-ratio in the shader. More...
 
void setARatioAdjustment (final boolean v)
 Toggles useARatioLetterbox(). More...
 
boolean useARatioLetterbox ()
 Returns whether useARatioAdjustment() shall add letter-box space to match aspect-ratio, otherwise it will be zoomed in. More...
 
Vec4f getARatioLetterboxBackColor ()
 Returns useARatioLetterbox() background color for added letter-box space, defaults to transparent zero. More...
 
void setARatioLetterbox (final boolean v, Vec4f backColor)
 Toggles useARatioLetterbox(). More...
 
boolean isTextureAvailable ()
 Returns true if texture source is ready and a texture is available via getNextTexture(GL) and getLastTexture(). More...
 
TextureFrame getLastTexture () throws IllegalStateException
 Returns the last updated texture. More...
 
TextureFrame getNextTexture (GL gl) throws IllegalStateException
 Returns the next texture to be rendered. More...
 
String getRequiredExtensionsShaderStub () throws IllegalStateException
 In case a shader extension is required, based on the implementation and the runtime GL profile, this method returns the preprocessor macros, e.g. More...
 
String getTextureSampler2DType () throws IllegalStateException
 Returns either sampler2D or samplerExternalOES depending on getLastTexture(). More...
 
String setTextureLookupFunctionName (String texLookupFuncName) throws IllegalStateException
 Set the desired shader code's texture lookup function name. More...
 
String getTextureLookupFunctionName () throws IllegalStateException
 Returns the chosen lookup function name, which can be set via setTextureLookupFunctionName(String). More...
 
String getTextureLookupFragmentShaderImpl () throws IllegalStateException
 Returns the complete texture2D lookup function code of type. More...
 
String getTextureFragmentShaderHashID ()
 Returns the concatenated string representing the following values utilized for getTextureFragmentShaderHashCode(). More...
 
int getTextureFragmentShaderHashCode ()
 Returns the hash code of the string getTextureFragmentShaderHashID(). More...
 

Static Public Member Functions

static void setTexCoordBBoxSimple (final Texture tex, final AABBox box, final float[] colorTexBBox, final boolean verbose)
 Calculates the texture coordinates bounding box w/o correcting aspect-ratio. More...
 
static void setTexCoordBBox (final Texture tex, final AABBox box, final boolean letterBox, final float[] colorTexBBox, final boolean verbose)
 Calculates the texture coordinates bounding box while correcting for aspect-ratio. More...
 

Static Public Attributes

static final String samplerExternalOES = "samplerExternalOES"
 
static final String sampler2D = "sampler2D"
 

Detailed Description

Protocol for texture sequences, like animations, movies, etc.

Ensure to respect the texture coordinates provided by TextureFrame.getTexture().getImageTexCoords().

The user's shader shall be fitted for this implementation. Assuming we use a base shader code w/o headers using ShaderCode. (Code copied from unit test / demo TexCubeES2)


 static final String[] es2_prelude = { "#version 100\n", "precision mediump float;\n" };
 static final String gl2_prelude = "#version 110\n";
 static final String shaderBasename = "texsequence_xxx";  // the base shader code w/o headers
 static final String myTextureLookupName = "myTexture2D"; // the desired texture lookup function

 private void initShader(GL2ES2 gl, TextureSequence texSeq) {
     // Create & Compile the shader objects
     ShaderCode rsVp = ShaderCode.create(gl, GL2ES2.GL_VERTEX_SHADER, TexCubeES2.class,
                                         "shader", "shader/bin", shaderBasename, true);
     ShaderCode rsFp = ShaderCode.create(gl, GL2ES2.GL_FRAGMENT_SHADER, TexCubeES2.class,
                                         "shader", "shader/bin", shaderBasename, true);

     // Prelude shader code w/ GLSL profile specifics [ 1. pre-proc, 2. other ]
     int rsFpPos;
     if(gl.isGLES2()) {
         // insert ES2 version string in beginning
         rsVp.insertShaderSource(0, 0, es2_prelude[0]);
         rsFpPos = rsFp.insertShaderSource(0, 0, es2_prelude[0]);
     } else {
         // insert GL2 version string in beginning
         rsVp.insertShaderSource(0, 0, gl2_prelude);
         rsFpPos = rsFp.insertShaderSource(0, 0, gl2_prelude);
     }
     // insert required extensions as determined by TextureSequence implementation.
     rsFpPos = rsFp.insertShaderSource(0, rsFpPos, texSeq.getRequiredExtensionsShaderStub());
     if(gl.isGLES2()) {
         // insert ES2 default precision declaration
         rsFpPos = rsFp.insertShaderSource(0, rsFpPos, es2_prelude[1]);
     }
     // negotiate the texture lookup function name
     final String texLookupFuncName = texSeq.getTextureLookupFunctionName(myTextureLookupName);

     // in case a fixed lookup function is being chosen, replace the name in our code
     rsFp.replaceInShaderSource(myTextureLookupName, texLookupFuncName);

     // Cache the TextureSequence shader details in StringBuilder:
     final StringBuilder sFpIns = new StringBuilder();

     // .. declaration of the texture sampler using the implementation specific type
     sFpIns.append("uniform ").append(texSeq.getTextureSampler2DType()).append(" mgl_ActiveTexture;\n");

     // .. the actual texture lookup function, maybe null in case a built-in function is being used
     sFpIns.append(texSeq.getTextureLookupFragmentShaderImpl());

     // Now insert the TextureShader details in our shader after the given tag:
     rsFp.insertShaderSource(0, "TEXTURE-SEQUENCE-CODE-BEGIN", 0, sFpIns);

     // Create & Link the shader program
     ShaderProgram sp = new ShaderProgram();
     sp.add(rsVp);
     sp.add(rsFp);
     if(!sp.link(gl, System.err)) {
         throw new GLException("Couldn't link program: "+sp);
     }
     ...

The above procedure might look complicated, however, it allows most flexibility and workarounds to also deal with GLSL bugs.

Definition at line 111 of file TextureSequence.java.

Member Function Documentation

◆ getARatioLetterboxBackColor()

Vec4f com.jogamp.opengl.util.texture.TextureSequence.getARatioLetterboxBackColor ( )

Returns useARatioLetterbox() background color for added letter-box space, defaults to transparent zero.

Implemented in com.jogamp.opengl.util.av.GLMediaPlayer, and com.jogamp.opengl.util.texture.ImageSequence.

Here is the caller graph for this function:

◆ getLastTexture()

TextureFrame com.jogamp.opengl.util.texture.TextureSequence.getLastTexture ( ) throws IllegalStateException

Returns the last updated texture.

In case the instance is just initialized, it shall return a TextureFrame object with valid attributes. The texture content may be undefined until the first call of getNextTexture(GL).

Not blocking.

Exceptions
IllegalStateExceptionif instance is not initialized

Implemented in com.jogamp.opengl.util.av.GLMediaPlayer, and com.jogamp.opengl.util.texture.ImageSequence.

Here is the caller graph for this function:

◆ getNextTexture()

TextureFrame com.jogamp.opengl.util.texture.TextureSequence.getNextTexture ( GL  gl) throws IllegalStateException

Returns the next texture to be rendered.

Implementation shall return the next frame if available, may block if a next frame may arrive soon. Otherwise implementation shall return the last frame.

Shall return null in case no next or last frame is available.

Exceptions
IllegalStateExceptionif instance is not initialized

Implemented in com.jogamp.opengl.util.texture.ImageSequence, and com.jogamp.opengl.util.av.GLMediaPlayer.

Here is the caller graph for this function:

◆ getRequiredExtensionsShaderStub()

String com.jogamp.opengl.util.texture.TextureSequence.getRequiredExtensionsShaderStub ( ) throws IllegalStateException

In case a shader extension is required, based on the implementation and the runtime GL profile, this method returns the preprocessor macros, e.g.

:

#extension GL_OES_EGL_image_external : enable
Exceptions
IllegalStateExceptionif instance is not initialized

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

◆ getTextureFragmentShaderHashCode()

int com.jogamp.opengl.util.texture.TextureSequence.getTextureFragmentShaderHashCode ( )

Returns the hash code of the string getTextureFragmentShaderHashID().

User shall call setTextureLookupFunctionName(String) first if intended.

Returns zero if texture is not available.

The returned hash code allows selection of a matching shader program for this TextureSequence instance.

Implementation caches the resulting hash code, which is reset by setTextureLookupFunctionName(String) and this method if texture is not available.

See also
setTextureLookupFunctionName(String)
getTextureLookupFunctionName()
getTextureLookupFragmentShaderImpl()
getTextureFragmentShaderHashID()

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

Here is the caller graph for this function:

◆ getTextureFragmentShaderHashID()

String com.jogamp.opengl.util.texture.TextureSequence.getTextureFragmentShaderHashID ( )

Returns the concatenated string representing the following values utilized for getTextureFragmentShaderHashCode().

To reduce string concatenating, implementation may simply return getTextureLookupFragmentShaderImpl(), if it covers getTextureSampler2DType() and getTextureLookupFunctionName().

See also
getTextureFragmentShaderHashCode()

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

◆ getTextureLookupFragmentShaderImpl()

String com.jogamp.opengl.util.texture.TextureSequence.getTextureLookupFragmentShaderImpl ( ) throws IllegalStateException

Returns the complete texture2D lookup function code of type.

  vec4 funcName(in getTextureSampler2DType() image, in vec2 texCoord) {
     vec4 texColor = do_something_with(image, texCoord);
     return texColor;
  }

<p<blockquote>‍

funcName is set via setTextureLookupFunctionName(String) and queried via getTextureLookupFunctionName().

User shall call setTextureLookupFunctionName(String) first if intended.

Note: This function may return an empty string in case a build-in lookup function is being chosen. If the implementation desires so, getTextureLookupFunctionName() will ignore the desired function name and returns the build-in lookup function name.

Exceptions
IllegalStateExceptionif instance is not initialized
See also
getTextureLookupFunctionName()
setTextureLookupFunctionName(String)
getTextureFragmentShaderHashID()
getTextureFragmentShaderHashCode()
getTextureSampler2DType()

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

◆ getTextureLookupFunctionName()

String com.jogamp.opengl.util.texture.TextureSequence.getTextureLookupFunctionName ( ) throws IllegalStateException

Returns the chosen lookup function name, which can be set via setTextureLookupFunctionName(String).

Exceptions
IllegalStateExceptionif instance is not initialized
See also
setTextureLookupFunctionName(String)
getTextureFragmentShaderHashCode()
getTextureLookupFragmentShaderImpl()

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

◆ getTextureMinMagFilter()

int[] com.jogamp.opengl.util.texture.TextureSequence.getTextureMinMagFilter ( )

◆ getTextureSampler2DType()

String com.jogamp.opengl.util.texture.TextureSequence.getTextureSampler2DType ( ) throws IllegalStateException

Returns either sampler2D or samplerExternalOES depending on getLastTexture().

getTexture().getTarget().

Exceptions
IllegalStateExceptionif instance is not initialized

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

◆ getTextureTarget()

int com.jogamp.opengl.util.texture.TextureSequence.getTextureTarget ( )

Returns the texture target used by implementation.

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

◆ getTextureUnit()

int com.jogamp.opengl.util.texture.TextureSequence.getTextureUnit ( )

Return the texture unit used to render the current frame.

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

Here is the caller graph for this function:

◆ getTextureWrapST()

int[] com.jogamp.opengl.util.texture.TextureSequence.getTextureWrapST ( )

◆ isTextureAvailable()

boolean com.jogamp.opengl.util.texture.TextureSequence.isTextureAvailable ( )

Returns true if texture source is ready and a texture is available via getNextTexture(GL) and getLastTexture().

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

◆ setARatioAdjustment()

void com.jogamp.opengl.util.texture.TextureSequence.setARatioAdjustment ( final boolean  v)

Toggles useARatioLetterbox().

Default value is implementation specific and toggling is optional.

See also
useARatioLetterbox()
useARatioAdjustment()

Implemented in com.jogamp.opengl.util.av.GLMediaPlayer, and com.jogamp.opengl.util.texture.ImageSequence.

Here is the caller graph for this function:

◆ setARatioLetterbox()

void com.jogamp.opengl.util.texture.TextureSequence.setARatioLetterbox ( final boolean  v,
Vec4f  backColor 
)

Toggles useARatioLetterbox().

Default value is implementation specific and toggling is optional.

Impacts only if useARatioAdjustment() returns true.

Parameters
vnew value for useARatioLetterbox()
backColoroptional background color for added letter-box space, defaults to transparent zero
See also
useARatioLetterbox()
useARatioAdjustment()

Implemented in com.jogamp.opengl.util.texture.ImageSequence, and com.jogamp.opengl.util.av.GLMediaPlayer.

Here is the caller graph for this function:

◆ setTexCoordBBox()

static void com.jogamp.opengl.util.texture.TextureSequence.setTexCoordBBox ( final Texture  tex,
final AABBox  box,
final boolean  letterBox,
final float[]  colorTexBBox,
final boolean  verbose 
)
static

Calculates the texture coordinates bounding box while correcting for aspect-ratio.

Parameters
texthe Texture
boxthe {@Link AABBox} of the destination
letterBoxtrue to produce letter-box space to match aspect-ratio, otherwise will zoom in
colorTexBBoxdestination float[6] array for the following three texture-coordinate tuples: minX/minY, maxX/maxY, texW/texH
verboseTODO
See also
useARatioAdjustment()

Definition at line 429 of file TextureSequence.java.

Here is the call graph for this function:

◆ setTexCoordBBoxSimple()

static void com.jogamp.opengl.util.texture.TextureSequence.setTexCoordBBoxSimple ( final Texture  tex,
final AABBox  box,
final float[]  colorTexBBox,
final boolean  verbose 
)
static

Calculates the texture coordinates bounding box w/o correcting aspect-ratio.

Parameters
texthe Texture
boxthe {@Link AABBox} of the destination
colorTexBBoxdestination float[6] array for the following three texture-coordinate tuples: minX/minY, maxX/maxY, texW/texH
verboseTODO
See also
useARatioAdjustment()

Definition at line 391 of file TextureSequence.java.

◆ setTextureLookupFunctionName()

String com.jogamp.opengl.util.texture.TextureSequence.setTextureLookupFunctionName ( String  texLookupFuncName) throws IllegalStateException

Set the desired shader code's texture lookup function name.

Parameters
texLookupFuncNamedesired lookup function name. If null or ignored by the implementation, a build-in name is returned.
Returns
the chosen lookup function name
Exceptions
IllegalStateExceptionif instance is not initialized
See also
getTextureLookupFunctionName()
getTextureFragmentShaderHashCode()
getTextureLookupFragmentShaderImpl()

Implemented in com.jogamp.opengl.util.texture.ImageSequence.

Here is the caller graph for this function:

◆ useARatioAdjustment()

boolean com.jogamp.opengl.util.texture.TextureSequence.useARatioAdjustment ( )

Returning true indicates texture correction for aspect-ratio in the shader.

Graph's Region shader will utilize setTexCoordBBox(Texture, AABBox, boolean, float[], boolean) for texture-coordinate bounding-box calculation.

Returning false indicates no correction for aspect-ratio in the shader. Graph's Region shader will utilize setTexCoordBBoxSimple(Texture, AABBox, float[], boolean) for texture-coordinate bounding-box calculation.

Default value is implementation specific and toggling is optional.

See also
setTexCoordBBox(Texture, AABBox, boolean, float[], boolean)
setTexCoordBBoxSimple(Texture, AABBox, float[], boolean)
useARatioLetterbox()

Implemented in com.jogamp.opengl.util.av.GLMediaPlayer, and com.jogamp.opengl.util.texture.ImageSequence.

Here is the caller graph for this function:

◆ useARatioLetterbox()

boolean com.jogamp.opengl.util.texture.TextureSequence.useARatioLetterbox ( )

Returns whether useARatioAdjustment() shall add letter-box space to match aspect-ratio, otherwise it will be zoomed in.

Default value is implementation specific and toggling is optional.

See also
useARatioAdjustment()
setARatioLetterbox(boolean, Vec4f)

Implemented in com.jogamp.opengl.util.av.GLMediaPlayer, and com.jogamp.opengl.util.texture.ImageSequence.

Here is the caller graph for this function:

Member Data Documentation

◆ sampler2D

final String com.jogamp.opengl.util.texture.TextureSequence.sampler2D = "sampler2D"
static

Definition at line 113 of file TextureSequence.java.

◆ samplerExternalOES

final String com.jogamp.opengl.util.texture.TextureSequence.samplerExternalOES = "samplerExternalOES"
static

Definition at line 112 of file TextureSequence.java.


The documentation for this interface was generated from the following file: