com.jogamp.opengl.util.texture
Interface TextureSequence

All Known Subinterfaces:

GLMediaPlayer

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

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

static String	sampler2D
static String	samplerExternalOES

Method Summary

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.:
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()

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()

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()