com.jogamp.opengl.util.texture

## Interface TextureSequence

- 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`

  - ### 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`.

Copyright 2010 JogAmp Community.