TextureSequence (JOGL API -- 2.3 Specification)

All Known Subinterfaces:: GLMediaPlayer

All Known Implementing Classes:: ImageSequence

public interface TextureSequence

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

Ensure to respect the texture coordinates provided by TextureSequence.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.

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`TextureSequence.TexSeqEventListener<T extends TextureSequence>` Event listener to notify users of updates regarding the `TextureSequence`.
`static class`	`TextureSequence.TextureFrame` Texture holder interface, maybe specialized by implementation to associated related data.

Field Summary

Fields
Modifier and Type Field and Description

static String sampler2D

static String samplerExternalOES

Fields
Modifier and Type	Field and Description
`static String`	`sampler2D`
`static String`	`samplerExternalOES`

Method Summary

Methods
Modifier and Type	Method and Description
`TextureSequence.TextureFrame`	`getLastTexture()` Returns the last updated texture.
`TextureSequence.TextureFrame`	`getNextTexture(GL gl)` Returns the next texture to be rendered.
`String`	`getRequiredExtensionsShaderStub()` In case a shader extension is required, based on the implementation and the runtime GL profile, this method returns the preprocessor macros, e.g.:
`int`	`getTextureFragmentShaderHashCode()` Returns the hash code of the strings: `getTextureLookupFragmentShaderImpl()` `getTextureSampler2DType()`
`String`	`getTextureLookupFragmentShaderImpl()` Returns the complete texture2D lookup function code of type
`String`	`getTextureLookupFunctionName(String desiredFuncName)`
`int[]`	`getTextureMinMagFilter()`
`String`	`getTextureSampler2DType()` Returns either `sampler2D` or `samplerExternalOES` depending on `getLastTexture()`.`getTexture()`.`getTarget()`.
`int`	`getTextureTarget()` Returns the texture target used by implementation.
`int`	`getTextureUnit()` Return the texture unit used to render the current frame.
`int[]`	`getTextureWrapST()`
`boolean`	`isTextureAvailable()` Returns true if texture source is ready and a texture is available via `getNextTexture(GL)` and `getLastTexture()`.

- Field Detail
  - samplerExternalOES
```
static final String samplerExternalOES
```
    See Also:
    Constant Field Values
  - sampler2D
```
static final String sampler2D
```
    See Also:
    Constant Field Values
- Method Detail
  - getTextureTarget
```
int getTextureTarget()
```
    Returns the texture target used by implementation.
  - getTextureUnit
```
int getTextureUnit()
```
    Return the texture unit used to render the current frame.
  - getTextureMinMagFilter
```
int[] getTextureMinMagFilter()
```
  - getTextureWrapST
```
int[] getTextureWrapST()
```
  - isTextureAvailable
```
boolean isTextureAvailable()
```
    Returns true if texture source is ready and a texture is available via getNextTexture(GL) and getLastTexture().
  - getLastTexture
```
TextureSequence.TextureFrame 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.
    
    Throws:
    
    IllegalStateException - if instance is not initialized
  - getNextTexture
```
TextureSequence.TextureFrame 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.
    
    Throws:
    
    IllegalStateException - if instance is not initialized
  - getRequiredExtensionsShaderStub
```
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.:
```
 #extension GL_OES_EGL_image_external : enable
 
```
    Throws:
    
    IllegalStateException - if instance is not initialized
  - getTextureSampler2DType
```
String getTextureSampler2DType()
                               throws IllegalStateException
```
    Returns either sampler2D or samplerExternalOES depending on getLastTexture().getTexture().getTarget().
    
    Throws:
    
    IllegalStateException - if instance is not initialized
  - getTextureLookupFunctionName
```
String getTextureLookupFunctionName(String desiredFuncName)
                                    throws IllegalStateException
```
    Parameters:
    desiredFuncName - desired lookup function name. If null or ignored by the implementation, a build-in name is returned.
    
    Returns:
    the final lookup function name
    
    Throws:
    
    IllegalStateException - if instance is not initialized
    See Also:
    #getTextureLookupFragmentShaderImpl()}
  - getTextureLookupFragmentShaderImpl
```
String 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;
   }
 
```
    funcName can be negotiated and queried via getTextureLookupFunctionName(String).
    Note: This function may return an empty string in case a build-in lookup function is being chosen. If the implementation desires so, getTextureLookupFunctionName(String) will ignore the desired function name and returns the build-in lookup function name.
    Throws:
    
    IllegalStateException - if instance is not initialized
    See Also:
    getTextureLookupFunctionName(String), getTextureSampler2DType()
  - getTextureFragmentShaderHashCode
```
int getTextureFragmentShaderHashCode()
```
    Returns the hash code of the strings:
    - getTextureLookupFragmentShaderImpl()
    - getTextureSampler2DType()
    Returns zero if texture is not available.
    The returned hash code allows selection of a matching shader program for this TextureSequence instance.
    
    Implementation shall cache the resulting hash code, which must be reset to zero if texture is not available.

Interface TextureSequence

Nested Class Summary

Field Summary

Method Summary

Field Detail

samplerExternalOES

sampler2D

Method Detail

getTextureTarget

getTextureUnit

getTextureMinMagFilter

getTextureWrapST

isTextureAvailable

getLastTexture

getNextTexture

getRequiredExtensionsShaderStub

getTextureSampler2DType

getTextureLookupFunctionName

getTextureLookupFragmentShaderImpl

getTextureFragmentShaderHashCode