TextureSequence.hpp

Go to the documentation of this file.

/*
 * Author: Sven Gothel <sgothel@jausoft.com>
 * Copyright Gothel Software e.K.
 *
 * SPDX-License-Identifier: MIT
 *
 * This Source Code Form is subject to the terms of the MIT License
 * If a copy of the MIT was not distributed with this file,
 * you can obtain one at https://opensource.org/license/mit/.
 */
#ifndef GAMP_RENDER_GL_TEXTURE_TEXTURESEQUENCE_HPP_
#define GAMP_RENDER_GL_TEXTURE_TEXTURESEQUENCE_HPP_
 
#include <jau/string_util.hpp>
 
#include <gamp/GampTypes.hpp>
#include <gamp/wt/Capabilities.hpp>
#include <gamp/av/TimeFrameI.hpp>
 
#include <gamp/render/gl/texture/Texture.hpp>
 
namespace gamp::render::gl::texture {
    /** \addtogroup Gamp_GL
     *
     *  @{
     */
 
    /**
     * Protocol for texture sequences, like animations, movies, etc.
     * <p>
     * Ensure to respect the texture coordinates provided by
     * {@link TextureFrame}.{@link TextureFrame#getTexture() getTexture()}.{@link Texture#getImageTexCoords() getImageTexCoords()}.
     * </p>
     * The user's shader shall be fitted for this implementation.
     * Assuming we use a base shader code w/o headers using </code>ShaderCode</code>.
     * (Code copied from unit test / demo <code>TexCubeES2</code>)
     * <pre>
     *
        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);
            }
            ...
     * </pre>
     * The above procedure might look complicated, however, it allows most flexibility and
     * workarounds to also deal with GLSL bugs.
     *
     */
    class TextureSequence {
      public:
        constexpr static std::string_view samplerExternalOES = "samplerExternalOES";
        constexpr static std::string_view sampler2D = "sampler2D";
    
        /**
         * Texture holder interface, maybe specialized by implementation
         * to associated related data.
         */
        class TextureFrame : public gamp::av::TimeFrameI {
          public:
            TextureFrame(final Texture t, final int pts, final int duration) {
                super(pts, duration);
                texture = t;
            }
            public TextureFrame(final Texture t) {
                texture = t;
            }
    
            public final Texture getTexture() { return texture; }
    
            @Override
            public String toString() {
                return "TextureFrame[pts " + pts + " ms, l " + duration + " ms, texID "+ (null != texture ? texture.getTextureObject() : 0) + "]";
            }
            protected final Texture texture;
        }
    
        /**
         * Event listener to notify users of updates regarding the {@link TextureSequence}.
         * <p>
         * Implementations sending events down to all listeners,
         * while not necessarily making the user's OpenGL context current.
         * </p>
         * <p>
         * Events may be sent from a 3rd-party thread, possibly holding another, maybe shared, OpenGL context current.<br/>
         * Hence a user shall not issue <i>any</i> OpenGL, time consuming
         * or {@link TextureSequence} operations directly.<br>
         * Instead, the user shall:
         * <ul>
         *   <li>off-load complex or {@link TextureSequence} commands on another thread, or</li>
         *   <li>injecting {@link GLRunnable} objects via {@link GLAutoDrawable#invoke(boolean, GLRunnable)}, or</li>
         *   <li>simply changing a volatile state of their {@link GLEventListener} implementation.</li>
         * </ul>
         * </p>
         * */
        public interface TexSeqEventListener<T extends TextureSequence> {
            /**
             * Signaling listeners that a new {@link TextureFrame} is available.
             * <p>
             * User shall utilize {@link TextureSequence#getNextTexture(GL)} to dequeue it to maintain
             * a consistent queue.
             * </p>
             * @param ts the event source
             * @param newFrame the newly enqueued frame
             * @param when system time in msec.
             **/
            public void newFrameAvailable(T ts, TextureFrame newFrame, long when);
        }
    
        /** Returns the texture target used by implementation. */
        public int getTextureTarget();
    
        /** Return the texture unit used to render the current frame. */
        public int getTextureUnit();
    
        public int[] getTextureMinMagFilter();
    
        public int[] getTextureWrapST();
    
        /**
         * Returning {@code true} indicates texture correction for aspect-ratio in the shader.
         * Graph's {@link Region} shader will utilize {@link #setTexCoordBBox(Texture, AABBox, boolean, float[], boolean)}
         * for texture-coordinate bounding-box calculation.
         * <p>
         * Returning {@code false} indicates no correction for aspect-ratio in the shader.
         * Graph's {@link Region} shader will utilize {@link #setTexCoordBBoxSimple(Texture, AABBox, float[], boolean)}
         * for texture-coordinate bounding-box calculation.
         * </p>
         * <p>
         * Default value is implementation specific
         * and toggling is optional.
         * </p>
         * @see #setTexCoordBBox(Texture, AABBox, boolean, float[], boolean)
         * @see #setTexCoordBBoxSimple(Texture, AABBox, float[], boolean)
         * @see #useARatioLetterbox()
         */
        public boolean useARatioAdjustment();
    
        /**
         * Toggles {@link #useARatioLetterbox()}.
         * <p>
         * Default value is implementation specific
         * and toggling is optional.
         * </p>
         * @see #useARatioLetterbox()
         * @see #useARatioAdjustment()
         */
        public void setARatioAdjustment(final boolean v);
    
        /**
         * Returns whether {@link #useARatioAdjustment()} shall add letter-box space to match aspect-ratio, otherwise it will be zoomed in.
         * <p>
         * Default value is implementation specific
         * and toggling is optional.
         * </p>
         * @see #useARatioAdjustment()
         * @see #setARatioLetterbox(boolean, Vec4f)
         */
        public boolean useARatioLetterbox();
    
        /** Returns {@link #useARatioLetterbox()} background color for added letter-box space, defaults to transparent zero. */
        public Vec4f getARatioLetterboxBackColor();
    
        /**
         * Toggles {@link #useARatioLetterbox()}.
         * <p>
         * Default value is implementation specific
         * and toggling is optional.
         * </p>
         * <p>
         * Impacts only if {@link #useARatioAdjustment()} returns {@code true}.
         * </p>
         * @param v new value for {@link #useARatioLetterbox()}
         * @param backColor optional background color for added letter-box space, defaults to transparent zero
         * @see #useARatioLetterbox()
         * @see #useARatioAdjustment()
         */
        public void setARatioLetterbox(final boolean v, Vec4f backColor);
    
        /**
         * Returns true if texture source is ready <i>and</i> a texture is available
         * via {@link #getNextTexture(GL)} and {@link #getLastTexture()}.
         */
        public boolean isTextureAvailable();
    
        /**
         * Returns the last updated texture.
         * <p>
         * In case the instance is just initialized, it shall return a <code>TextureFrame</code>
         * object with valid attributes. The texture content may be undefined
         * until the first call of {@link #getNextTexture(GL)}.<br>
         * </p>
         * Not blocking.
         *
         * @throws IllegalStateException if instance is not initialized
         */
        public TextureFrame getLastTexture() throws IllegalStateException ;
    
        /**
         * Returns the next texture to be rendered.
         * <p>
         * Implementation shall return the next frame if available, may block if a next frame may arrive <i>soon</i>.
         * Otherwise implementation shall return the last frame.
         * </p>
         * <p>
         * Shall return <code>null</code> in case <i>no</i> next or last frame is available.
         * </p>
         *
         * @throws IllegalStateException if instance is not initialized
         */
        public TextureFrame getNextTexture(GL gl) 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.:
         * <pre>
         * #extension GL_OES_EGL_image_external : enable
         * </pre>
         *
         * @throws IllegalStateException if instance is not initialized
         */
        public String getRequiredExtensionsShaderStub() throws IllegalStateException ;
    
        /**
         * Returns either <code>sampler2D</code> or <code>samplerExternalOES</code>
         * depending on {@link #getLastTexture()}.{@link TextureFrame#getTexture() getTexture()}.{@link Texture#getTarget() getTarget()}.
         *
         * @throws IllegalStateException if instance is not initialized
         **/
        public String getTextureSampler2DType() throws IllegalStateException ;
    
        /**
         * Set the desired shader code's texture lookup function name.
         *
         * @param texLookupFuncName desired lookup function name. If <code>null</code> or ignored by the implementation,
         *                          a build-in name is returned.
         * @return the chosen lookup function name
         *
         * @throws IllegalStateException if instance is not initialized
         * @see #getTextureLookupFunctionName()
         * @see #getTextureFragmentShaderHashCode()
         * @see #getTextureLookupFragmentShaderImpl()
         */
        public String setTextureLookupFunctionName(String texLookupFuncName) throws IllegalStateException ;
    
        /**
         * Returns the chosen lookup function name, which can be set via {@link #setTextureLookupFunctionName(String)}.
         *
         * @throws IllegalStateException if instance is not initialized
         * @see #setTextureLookupFunctionName(String)
         * @see #getTextureFragmentShaderHashCode()
         * @see #getTextureLookupFragmentShaderImpl()
         */
        public String getTextureLookupFunctionName() throws IllegalStateException ;
    
        /**
         * Returns the complete texture2D lookup function code of type
         * <pre>
         *   vec4 <i>funcName</i>(in <i>getTextureSampler2DType()</i> image, in vec2 texCoord) {
         *      vec4 texColor = do_something_with(image, texCoord);
         *      return texColor;
         *   }
         * </pre>
         * <p>
         * <i>funcName</i> is set via {@link #setTextureLookupFunctionName(String)}
         * and queried via {@link #getTextureLookupFunctionName()}.
         * </p>
         * <p>
         * User shall call {@link #setTextureLookupFunctionName(String)} first if intended.
         * </p>
         * <p>
         * Note: This function may return an empty string in case a build-in lookup
         * function is being chosen. If the implementation desires so,
         * {@link #getTextureLookupFunctionName()} will ignore the desired function name
         * and returns the build-in lookup function name.
         * </p>
         * @throws IllegalStateException if instance is not initialized
         * @see #getTextureLookupFunctionName()
         * @see #setTextureLookupFunctionName(String)
         * @see #getTextureFragmentShaderHashID()
         * @see #getTextureFragmentShaderHashCode()
         * @see #getTextureSampler2DType()
         */
        public String getTextureLookupFragmentShaderImpl() throws IllegalStateException;
    
        /**
         * Returns the concatenated string representing the following values
         * utilized for {@link #getTextureFragmentShaderHashCode()}.
         * <ul>
         *   <li>{@link #getTextureSampler2DType()}</li>
         *   <li>{@link #getTextureLookupFunctionName()}</li>
         *   <li>{@link #getTextureLookupFragmentShaderImpl()}</li>
         * </ul>
         * <p>
         * To reduce string concatenating, implementation may simply return {@link #getTextureLookupFragmentShaderImpl()},
         * if it covers {@link #getTextureSampler2DType()} and {@link #getTextureLookupFunctionName()}.
         * </p>
         * @see #getTextureFragmentShaderHashCode()
         */
        public String getTextureFragmentShaderHashID();
    
        /**
         * Returns the hash code of the string {@link #getTextureFragmentShaderHashID()}.
         * <p>
         * User shall call {@link #setTextureLookupFunctionName(String)} first if intended.
         * </p>
         * <p>
         * Returns zero if {@link #isTextureAvailable() texture is not available}.
         * </p>
         * The returned hash code allows selection of a matching shader program for this {@link TextureSequence} instance.
         * <p>
         * </p>
         * <p>
         * Implementation caches the resulting hash code, which is reset by {@link #setTextureLookupFunctionName(String)}
         * and this method if {@link #isTextureAvailable() texture is not available}.
         * </p>
         * @see #setTextureLookupFunctionName(String)
         * @see #getTextureLookupFunctionName()
         * @see #getTextureLookupFragmentShaderImpl()
         * @see #getTextureFragmentShaderHashID()
         */
        public int getTextureFragmentShaderHashCode();
    
        /**
         * Calculates the texture coordinates bounding box w/o correcting aspect-ratio.
         * @param tex the {@link Texture}
         * @param box the {@Link AABBox} of the destination
         * @param colorTexBBox destination float[6] array for the following three texture-coordinate tuples: minX/minY, maxX/maxY, texW/texH
         * @param verbose TODO
         * @see #useARatioAdjustment()
         */
        public static void setTexCoordBBoxSimple(final Texture tex, final AABBox box, final float[] colorTexBBox, final boolean verbose) {
            final TextureCoords tc = tex.getImageTexCoords();
            final float tcW = tc.right() - tc.left();
            final float tcH;
            colorTexBBox[0] = box.getMinX() / tcW;
            colorTexBBox[2] = box.getMaxX() / tcW;
            if( tex.getMustFlipVertically() ) {
                tcH = tc.bottom() - tc.top();
                colorTexBBox[1] = box.getMaxY() / tcH;
                colorTexBBox[3] = box.getMinY() / tcH;
            } else {
                tcH = tc.top() - tc.bottom();
                colorTexBBox[1] = box.getMinY() / tcH;
                colorTexBBox[3] = box.getMaxY() / tcH;
            }
            colorTexBBox[4] = tcW;
            colorTexBBox[5] = tcH;
            if( verbose ) {
                final float colorTexBBoxW = colorTexBBox[2] - colorTexBBox[0];
                final float colorTexBBoxH = colorTexBBox[3] - colorTexBBox[1];
                System.err.println("XXX setTexCoordBBoxSimple:");
                System.err.println("XXX ColorTex "+tex);
                System.err.println("XXX ColorTexBBox min "+colorTexBBox[0]+"/"+colorTexBBox[1]+", max "+colorTexBBox[2]+"/"+colorTexBBox[3]+
                        ", dim "+colorTexBBoxW+" x "+colorTexBBoxH+
                        ", tc-dim "+tcW+" x "+tcH+", tc "+tc);
            }
    
        }
    
        /**
         * Calculates the texture coordinates bounding box while correcting for aspect-ratio.
         * @param tex the {@link Texture}
         * @param box the {@Link AABBox} of the destination
         * @param letterBox true to produce letter-box space to match aspect-ratio, otherwise will zoom in
         * @param colorTexBBox destination float[6] array for the following three texture-coordinate tuples: minX/minY, maxX/maxY, texW/texH
         * @param verbose TODO
         * @see #useARatioAdjustment()
         */
        public static void setTexCoordBBox(final Texture tex, final AABBox box, final boolean letterBox, final float[] colorTexBBox, final boolean verbose) {
            final TextureCoords tc = tex.getImageTexCoords();
            final float boxRatio = box.getWidth() / box.getHeight();
            final float imgRatio = tex.getAspectRatio();
            final float box2ImgRatio = boxRatio / imgRatio;
            final float tcW = tc.right() - tc.left();
            final float tcH;
            float boxWidthCut=0, boxHeightCut=0, boxWidthExt=0, boxHeightExt=0;
    
            if( box2ImgRatio >= 1.0f ) {
                if( letterBox ) {
                    boxWidthCut = box.getWidth() * ( 1f - 1f / box2ImgRatio );
                    final float tcWH = tcW * 0.5f;
                    final float boxWidthCutL = boxWidthCut * tcWH;
                    final float boxWidthCutR = boxWidthCut * ( 1f - tcWH );
                    colorTexBBox[0] = ( box.getMinX() + boxWidthCutL ) / tcW;
                    colorTexBBox[2] = ( box.getMaxX() - boxWidthCutR ) / tcW;
                    if( tex.getMustFlipVertically() ) {
                        tcH = tc.bottom() - tc.top();
                        colorTexBBox[1] = box.getMaxY() / tcH;
                        colorTexBBox[3] = box.getMinY() / tcH;
                    } else {
                        tcH = tc.top() - tc.bottom();
                        colorTexBBox[1] = box.getMinY() / tcH;
                        colorTexBBox[3] = box.getMaxY() / tcH;
                    }
                } else {
                    colorTexBBox[0] = box.getMinX() / tcW;
                    colorTexBBox[2] = box.getMaxX() / tcW;
                    boxHeightExt = box.getHeight() * ( box2ImgRatio - 1f );
                    if( tex.getMustFlipVertically() ) {
                        tcH = tc.bottom() - tc.top();
                        final float tcHH = tcH * 0.5f;
                        final float boxHeightExtB = boxHeightExt * tcHH;
                        final float boxHeightExtT = boxHeightExt * ( 1f - tcHH );
                        colorTexBBox[1] = ( box.getMaxY() + boxHeightExtT ) / tcH;
                        colorTexBBox[3] = ( box.getMinY() - boxHeightExtB ) / tcH;
                    } else {
                        tcH = tc.top() - tc.bottom();
                        final float tcHH = tcH * 0.5f;
                        final float boxHeightExtB = boxHeightExt * tcHH;
                        final float boxHeightExtT = boxHeightExt * ( 1f - tcHH );
                        colorTexBBox[1] = ( box.getMinY() - boxHeightExtB ) / tcH;
                        colorTexBBox[3] = ( box.getMaxY() + boxHeightExtT ) / tcH;
                    }
                }
            } else {
                if( letterBox ) {
                    colorTexBBox[0] = box.getMinX() / tcW;
                    colorTexBBox[2] = box.getMaxX() / tcW;
                    boxHeightCut = box.getHeight() * ( 1f - box2ImgRatio );
                    if( tex.getMustFlipVertically() ) {
                        tcH = tc.bottom() - tc.top();
                        final float tcHH = tcH * 0.5f;
                        final float boxHeightCutB = boxHeightCut * tcHH;
                        final float boxHeightCutT = boxHeightCut * ( 1f - tcHH );
                        colorTexBBox[1] = ( box.getMaxY() - boxHeightCutT ) / tcH;
                        colorTexBBox[3] = ( box.getMinY() + boxHeightCutB ) / tcH;
                    } else {
                        tcH = tc.top() - tc.bottom();
                        final float tcHH = tcH * 0.5f;
                        final float boxHeightCutB = boxHeightCut * tcHH;
                        final float boxHeightCutT = boxHeightCut * ( 1f - tcHH );
                        colorTexBBox[1] = ( box.getMinY() + boxHeightCutB ) / tcH;
                        colorTexBBox[3] = ( box.getMaxY() - boxHeightCutT ) / tcH;
                    }
                } else {
                    boxWidthExt = box.getWidth() * ( 1f / box2ImgRatio - 1f );
                    final float tcWH = tcW * 0.5f;
                    final float boxWidthExtL = boxWidthExt * tcWH;
                    final float boxWidthExtR = boxWidthExt * ( 1f - tcWH );
                    colorTexBBox[0] = ( box.getMinX() - boxWidthExtL ) / tcW;
                    colorTexBBox[2] = ( box.getMaxX() + boxWidthExtR ) / tcW;
                    if( tex.getMustFlipVertically() ) {
                        tcH = tc.bottom() - tc.top();
                        colorTexBBox[1] = box.getMaxY() / tcH;
                        colorTexBBox[3] = box.getMinY() / tcH;
                    } else {
                        tcH = tc.top() - tc.bottom();
                        colorTexBBox[1] = box.getMinY() / tcH;
                        colorTexBBox[3] = box.getMaxY() / tcH;
                    }
                }
            }
            colorTexBBox[4] = tcW;
            colorTexBBox[5] = tcH;
            if( verbose ) {
                final float texWidthRatio = (float)tex.getImageWidth() / (float)tex.getWidth();
                final float texHeightRatio = (float)tex.getImageHeight() / (float)tex.getHeight();
                final float texRatio = ( tc.right() - tc.left() ) / ( tc.bottom() - tc.top() );
                final float box2TexRatio = boxRatio / texRatio;
                final float colorTexBBoxW = colorTexBBox[2] - colorTexBBox[0];
                final float colorTexBBoxH = colorTexBBox[3] - colorTexBBox[1];
                System.err.println("XXX setTexCoordBBox:");
                System.err.println("XXX ColorTex imgRatio "+imgRatio+", texRatio "+texRatio+", texPixelRatio[w "+texWidthRatio+", h "+texHeightRatio+"], "+tex);
                System.err.println("XXX ColorTexBBox lbox "+letterBox+", cut "+boxWidthCut+"/"+boxHeightCut+", ext "+boxWidthExt+"/"+boxHeightExt);
                System.err.println("XXX ColorTexBBox min "+colorTexBBox[0]+"/"+colorTexBBox[1]+", max "+colorTexBBox[2]+"/"+colorTexBBox[3]+
                        ", dim "+colorTexBBoxW+" x "+colorTexBBoxH+
                        ", tc-dim "+tcW+" x "+tcH+", tc "+tc+", box2ImgRatio "+box2ImgRatio+", box2TexRatio "+box2TexRatio);
                System.err.println("XXX Box ratio "+boxRatio+", "+box);
            }
        }
    };
    
    /**@}*/
 
}  // namespace gamp::render::gl
 
#endif /* GAMP_RENDER_GL_TEXTURE_TEXTURESEQUENCE_HPP_ */