GLPixelBuffer.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_PIXEL_GLPIXELBUFFER_HPP_
#define GAMP_RENDER_GL_PIXEL_GLPIXELBUFFER_HPP_
 
#include <jau/string_util.hpp>
 
#include <gamp/GampTypes.hpp>
#include <gamp/render/gl/GLContext.hpp>
#include <gamp/render/pixel/PixelFormat.hpp>
#include <memory>
 
namespace gamp::render::gl::pixel {
    /** \addtogroup Gamp_GL
     *
     *  @{
     */
     
    using gamp::render::pixel::PixelFormat;
   
    class GLPixelAttributes;
    class GLPixelBuffer;
    typedef std::shared_ptr<GLPixelBuffer> GLPixelBufferRef;
    
    /** Allows user to interface with another toolkit to define {@link GLPixelAttributes} and memory buffer to produce {@link TextureData}. */
    class GLPixelBufferProvider {
        /** Allow {@link GL2ES3#GL_PACK_ROW_LENGTH}, or {@link GL2ES2#GL_UNPACK_ROW_LENGTH}. */
        virtual bool getAllowRowStride() = 0;
 
        /**
         * Returns RGB[A] {@link GLPixelAttributes} matching {@link GL}, {@code componentCount} and {@code pack}.
         *
         * @param gl the corresponding current {@link GL} context object
         * @param componentCount RGBA component count, i.e. 1 (luminance, alpha or red), 3 (RGB) or 4 (RGBA)
         * @param pack {@code true} for read mode GPU -> CPU, e.g. {@link GL#glReadPixels(int, int, int, int, int, int, Buffer) glReadPixels}.
         *             {@code false} for write mode CPU -> GPU, e.g. {@link GL#glTexImage2D(int, int, int, int, int, int, int, int, Buffer) glTexImage2D}.
         */
        virtual const GLPixelAttributes& getAttributes(const GL& gl, int componentCount, bool pack) const noexcept = 0;
 
        /**
         * Returns the host {@link PixelFormat.Composition} matching {@link GL} and {@code componentCount}
         * if required by implementation, otherwise {@code null}.
         *
         * @param glp the corresponding current {@link GL} context object
         * @param componentCount RGBA component count, i.e. 1 (luminance, alpha or red), 3 (RGB) or 4 (RGBA)
         */
        virtual PixelFormat getHostPixelComp(const GLProfile& glp, int componentCount) const noexcept = 0;
 
        /**
         * Allocates a new {@link GLPixelBuffer} object.
         * <p>
         * The minimum required {@link Buffer#remaining() remaining} byte size equals to <code>minByteSize</code>, if &gt; 0,
         * otherwise utilize {@link GLBuffers#sizeof(GL, int[], int, int, int, int, int, boolean)}
         * to calculate it.
         * </p>
         *
         * @param gl the corresponding current {@link GL} context object
         * @param hostPixComp host {@link PixelFormat pixel format}, i.e. of the source or sink depending on {@code pack},
         *                    e.g. fetched via {@link #getHostPixelComp(GLProfile, int)}.
         *                    If {@code null}, {@code pixelAttributes} instance maybe used or an exception is thrown,
         *                    depending on implementation semantics.
         * @param pixelAttributes the desired {@link GLPixelAttributes}, e.g. fetched via {@link #getAttributes(GL, int, boolean)}
         * @param pack {@code true} for read mode GPU -> CPU, e.g. {@link GL#glReadPixels(int, int, int, int, int, int, Buffer) glReadPixels}.
         *             {@code false} for write mode CPU -> GPU, e.g. {@link GL#glTexImage2D(int, int, int, int, int, int, int, int, Buffer) glTexImage2D}.
         * @param width in pixels
         * @param height in pixels
         * @param depth in pixels
         * @param minByteSize if &gt; 0, the pre-calculated minimum byte-size for the resulting buffer, otherwise ignore.
         * @see #getHostPixelComp(GLProfile, int)
         * @see #getAttributes(GL, int, boolean)
         */
        virtual GLPixelBufferRef allocate(const GL& gl, const PixelFormat& hostPixComp, const GLPixelAttributes& pixelAttributes,
                                          bool pack, int width, int height, int depth, int minByteSize);
    };
    
    /**
     * OpenGL pixel data buffer, allowing user to provide buffers via their {@link GLPixelBufferProvider} implementation.
     * <p>
     * {@link GLPixelBufferProvider} produces a {@link GLPixelBuffer}.
     * </p>
     * <p>
     * You may use {@link #defaultProviderNoRowStride}.
     * </p>
     */
    class GLPixelBuffer {        
    
    
        /** Pixel attributes. */
        public static class GLPixelAttributes {
            /** Undefined instance of {@link GLPixelAttributes}, having componentCount:=0, format:=0 and type:= 0. */
            public static final GLPixelAttributes UNDEF = new GLPixelAttributes(null, PixelFormat.LUMINANCE, 0, 0, true, false);
    
            /**
             * Returns the matching {@link PixelFormat} for the given GL format and type if exists,
             * otherwise returns <code>null</code>.
             */
            public static final PixelFormat getPixelFormat(final int glFormat, final int glDataType) {
                PixelFormat pixFmt = null;
    
                switch(glFormat) {
                    case GL.GL_ALPHA:
                    case GL.GL_LUMINANCE:
                    case GL2ES2.GL_RED:
                        pixFmt = PixelFormat.LUMINANCE;
                        break;
                    case GL.GL_RGB:
                        switch(glDataType) {
                            case GL2GL3.GL_UNSIGNED_SHORT_5_6_5_REV:
                                pixFmt = PixelFormat.RGB565;
                                break;
                            case GL.GL_UNSIGNED_SHORT_5_6_5:
                                pixFmt = PixelFormat.BGR565;
                                break;
                            case GL.GL_UNSIGNED_BYTE:
                                pixFmt = PixelFormat.RGB888;
                                break;
                        }
                        break;
                    case GL.GL_RGBA:
                        switch(glDataType) {
                            case GL2GL3.GL_UNSIGNED_SHORT_1_5_5_5_REV:
                                pixFmt = PixelFormat.RGBA5551;
                                break;
                            case GL.GL_UNSIGNED_SHORT_5_5_5_1:
                                pixFmt = PixelFormat.ABGR1555;
                                break;
                            case GL2GL3.GL_UNSIGNED_INT_8_8_8_8_REV:
                                // fall through intended
                            case GL.GL_UNSIGNED_BYTE:
                                pixFmt = PixelFormat.RGBA8888;
                                break;
                            case GL2GL3.GL_UNSIGNED_INT_8_8_8_8:
                                pixFmt = PixelFormat.ABGR8888;
                                break;
                        }
                        break;
                    case GL.GL_BGR:
                        if( GL.GL_UNSIGNED_BYTE == glDataType ) {
                            pixFmt = PixelFormat.BGR888;
                        }
                        break;
                    case GL.GL_BGRA:
                        switch(glDataType) {
                            case GL2GL3.GL_UNSIGNED_INT_8_8_8_8:
                                pixFmt = PixelFormat.ARGB8888;
                                break;
                            case GL2GL3.GL_UNSIGNED_INT_8_8_8_8_REV:
                                // fall through intended
                            case GL.GL_UNSIGNED_BYTE:
                                pixFmt = PixelFormat.BGRA8888;
                                break;
                        }
                        break;
                }
                return pixFmt;
            }
    
            /**
             * Returns the matching {@link GLPixelAttributes} for the given byte sized RGBA {@code componentCount} and {@link GL} if exists,
             * otherwise returns {@code null}.
             *
             * @param gl the corresponding current {@link GL} context object
             * @param componentCount RGBA component count, i.e. 1 (luminance, alpha or red), 3 (RGB) or 4 (RGBA)
             * @param pack {@code true} for read mode GPU -> CPU, e.g. {@link GL#glReadPixels(int, int, int, int, int, int, Buffer) glReadPixels}.
             *             {@code false} for write mode CPU -> GPU, e.g. {@link GL#glTexImage2D(int, int, int, int, int, int, int, int, Buffer) glTexImage2D}.
             */
            public static GLPixelAttributes convert(final GL gl, final int componentCount, final boolean pack) {
                final int dFormat, dType;
                final boolean glesReadMode = pack && gl.isGLES();
    
                if( 1 == componentCount && !glesReadMode ) {
                    if( gl.isGL3ES3() ) {
                        // RED is supported on ES3 and >= GL3 [core]; ALPHA is deprecated on core
                        dFormat = GL2ES2.GL_RED;
                    } else {
                        // ALPHA is supported on ES2 and GL2, i.e. <= GL3 [core] or compatibility
                        dFormat = GL.GL_ALPHA;
                    }
                    dType   = GL.GL_UNSIGNED_BYTE;
                } else if( 3 == componentCount && !glesReadMode ) {
                    dFormat = GL.GL_RGB;
                    dType   = GL.GL_UNSIGNED_BYTE;
                } else if( 4 == componentCount || glesReadMode ) {
                    final GLContext ctx = gl.getContext();
                    final int _dFormat = ctx.getDefaultPixelDataFormat();
                    final int _dComps = GLBuffers.componentCount(_dFormat);
                    if( _dComps == componentCount || 4 == _dComps ) { // accept if desired component count or 4 components
                        // pre-check whether default is supported by implementation
                        final int _dType = ctx.getDefaultPixelDataType();
                        final PixelFormat _pixFmt = getPixelFormat(_dFormat, _dType);
                        if( null != _pixFmt) {
                            return new GLPixelAttributes(null, _pixFmt, _dFormat, _dType, pack, true);
                        }
                        if( GLContext.DEBUG ) {
                            System.err.println("GLPixelAttributes.convert("+gl.getGLProfile()+", comps "+componentCount+", pack "+pack+
                                    "): GL-impl default unsupported: "+
                                    "[fmt 0x"+Integer.toHexString(_dFormat)+", type 0x"+Integer.toHexString(_dType)+"]: Using std RGBA+UBYTE");
                            Thread.dumpStack();
                        }
                        // fall-through intended to set dFormat/dType to std values
                    }
                    dFormat = GL.GL_RGBA;
                    dType   = GL.GL_UNSIGNED_BYTE;
                } else {
                    return null;
                }
                return new GLPixelAttributes(dFormat, dType);
            }
    
            /**
             * Returns the matching {@link GLPixelAttributes} for the given {@link GLProfile}, {@link PixelFormat} and {@code pack} if exists,
             * otherwise returns {@code null}.
             * @param glp the corresponding {@link GLProfile}
             * @param pixFmt the to be matched {@link PixelFormat pixel format}
             * @param pack {@code true} for read mode GPU -> CPU, e.g. {@link GL#glReadPixels(int, int, int, int, int, int, Buffer) glReadPixels}.
             *             {@code false} for write mode CPU -> GPU, e.g. {@link GL#glTexImage2D(int, int, int, int, int, int, int, int, Buffer) glTexImage2D}.
             */
            public static final GLPixelAttributes convert(final GLProfile glp, final PixelFormat pixFmt, final boolean pack) {
                final int[] df = new int[1];
                final int[] dt = new int[1];
                convert(glp, pixFmt, pack, df, dt);
                if( 0 != df[0] ) {
                    return new GLPixelAttributes(null, pixFmt, df[0], dt[0], true /* not used */, true);
                }
                return null;
            }
            private static final int convert(final GLProfile glp, final PixelFormat pixFmt, final boolean pack,
                                             final int[] dfRes, final int[] dtRes) {
                final boolean glesReadMode = pack && glp.isGLES();
                int df = 0; // format
                int dt = GL.GL_UNSIGNED_BYTE; // data type
                switch(pixFmt) {
                    case LUMINANCE:
                        if( !glesReadMode ) {
                            if( glp.isGL3ES3() ) {
                                // RED is supported on ES3 and >= GL3 [core]; ALPHA/LUMINANCE is deprecated on core
                                df = GL2ES2.GL_RED;
                            } else {
                                // ALPHA/LUMINANCE is supported on ES2 and GL2, i.e. <= GL3 [core] or compatibility
                                df = GL.GL_LUMINANCE;
                            }
                        }
                        break;
                    case RGB565:
                        if( glp.isGL2GL3() ) {
                            df = GL.GL_RGB; dt = GL2GL3.GL_UNSIGNED_SHORT_5_6_5_REV;
                        }
                        break;
                    case BGR565:
                        if( glp.isGL2GL3() ) {
                            df = GL.GL_RGB; dt = GL.GL_UNSIGNED_SHORT_5_6_5;
                        }
                        break;
                    case RGBA5551:
                        if( glp.isGL2GL3() ) {
                            df = GL.GL_RGBA; dt = GL2GL3.GL_UNSIGNED_SHORT_1_5_5_5_REV;
                        }
                        break;
                    case ABGR1555:
                        if( glp.isGL2GL3() ) {
                            df = GL.GL_RGBA; dt = GL.GL_UNSIGNED_SHORT_5_5_5_1;
                        }
                        break;
                    case RGB888:
                        if( !glesReadMode ) {
                            df = GL.GL_RGB;
                        }
                        break;
                    case BGR888:
                        if( glp.isGL2GL3() ) {
                            df = GL.GL_BGR;
                        }
                        break;
                    case RGBx8888:
                    case RGBA8888:
                        df = GL.GL_RGBA;
                        break;
                    case ABGR8888:
                        if( glp.isGL2GL3() ) {
                            df = GL.GL_RGBA; dt = GL2GL3.GL_UNSIGNED_INT_8_8_8_8;
                        }
                        break;
                    case ARGB8888:
                        if( glp.isGL2GL3() ) {
                            df = GL.GL_BGRA; dt = GL2GL3.GL_UNSIGNED_INT_8_8_8_8;
                        }
                        break;
                    case BGRx8888:
                    case BGRA8888:
                        if( glp.isGL2GL3() ) { // FIXME: or if( !glesReadMode ) ? BGRA n/a on GLES
                            df = GL.GL_BGRA;
                        }
                        break;
                }
                dfRes[0] = df;
                dtRes[0] = dt;
                return df;
            }
    
            /** The OpenGL pixel data format */
            public final int format;
            /** The OpenGL pixel data type  */
            public final int type;
    
            /** {@link PixelFormat} describing the {@link PixelFormat.Composition component} layout */
            public final PixelFormat pfmt;
    
            @Override
            public final int hashCode() {
                // 31 * x == (x << 5) - x
                int hash = pfmt.hashCode();
                hash = ((hash << 5) - hash) + format;
                return ((hash << 5) - hash) + type;
            }
    
            @Override
            public final boolean equals(final Object obj) {
                if(this == obj)  { return true; }
                if( obj instanceof GLPixelAttributes ) {
                    final GLPixelAttributes other = (GLPixelAttributes) obj;
                    return format == other.format &&
                           type == other.type &&
                           pfmt.equals(other.pfmt);
                } else {
                    return false;
                }
            }
    
            /**
             * Create a new {@link GLPixelAttributes} instance based on GL format and type.
             * @param dataFormat GL data format
             * @param dataType GL data type
             * @throws GLException if {@link PixelFormat} could not be determined, see {@link #getPixelFormat(int, int)}.
             */
            public GLPixelAttributes(final int dataFormat, final int dataType) throws GLException {
                this(null, null, dataFormat, dataType, true /* not used */, true);
            }
    
            /**
             * Create a new {@link GLPixelAttributes} instance based on {@link GLProfile}, {@link PixelFormat} and {@code pack}.
             * @param glp the corresponding {@link GLProfile}
             * @param pixFmt the to be matched {@link PixelFormat pixel format}
             * @param pack {@code true} for read mode GPU -> CPU, e.g. {@link GL#glReadPixels(int, int, int, int, int, int, Buffer) glReadPixels}.
             *             {@code false} for write mode CPU -> GPU, e.g. {@link GL#glTexImage2D(int, int, int, int, int, int, int, int, Buffer) glTexImage2D}.
             * @throws GLException if GL format or type could not be determined, see {@link #convert(GLProfile, PixelFormat, boolean)}.
             */
            public GLPixelAttributes(final GLProfile glp, final PixelFormat pixFmt, final boolean pack) throws GLException {
                this(glp, pixFmt, 0, 0, pack, true);
            }
    
            private GLPixelAttributes(final GLProfile glp, final PixelFormat pixFmt,
                                      final int dataFormat, final int dataType, final boolean pack, final boolean checkArgs) throws GLException {
                if( checkArgs && ( 0 == dataFormat || 0 == dataType ) ) {
                    if( null == pixFmt || null == glp ) {
                        throw new GLException("Zero format and/or type w/o pixFmt or glp: "+this);
                    }
                    final int[] df = new int[1];
                    final int[] dt = new int[1];
                    if( 0 == convert(glp, pixFmt, pack, df, dt) ) {
                        throw new GLException("Could not find format and type for "+pixFmt+" and "+glp+", "+this);
                    }
                    this.format = df[0];
                    this.type = dt[0];
                    this.pfmt = pixFmt;
                } else {
                    this.format = dataFormat;
                    this.type = dataType;
                    this.pfmt = null != pixFmt ? pixFmt : getPixelFormat(dataFormat, dataType);
                    if( null == this.pfmt ) {
                        throw new GLException("Could not find PixelFormat for format and/or type: "+this);
                    }
                }
                if( checkArgs ) {
                    final int bytesPerPixel = GLBuffers.bytesPerPixel(this.format, this.type);
                    if( 0 == bytesPerPixel ) {
                        throw new GLException("Zero bytesPerPixel: "+this);
                    }
                }
            }
    
            @Override
            public String toString() {
                return "PixelAttributes[fmt 0x"+Integer.toHexString(format)+", type 0x"+Integer.toHexString(type)+", "+pfmt+"]";
            }
        }
    
        /** The {@link GLPixelAttributes}. */
        public final GLPixelAttributes pixelAttributes;
        /**
         * Width in pixels, representing {@link #buffer}'s {@link #byteSize}.
         * <p>
         * May not represent actual image width as user may re-use buffer for different dimensions, see {@link #requiresNewBuffer(GL, int, int, int)}.
         * </p>
         */
        public final int width;
        /**
         * Height in pixels, representing {@link #buffer}'s {@link #byteSize}.
         * <p>
         * May not represent actual image height as user may re-use buffer for different dimensions, see {@link #requiresNewBuffer(GL, int, int, int)}.
         * </p>
         */
        public final int height;
        /** Depth in pixels. */
        public final int depth;
        /**
         * Data packing direction.
         * <p>{@code true} for read mode GPU -> CPU, e.g. {@link GL#glReadPixels(int, int, int, int, int, int, Buffer) glReadPixels}.</p>
         * <p>{@code false} for write mode CPU -> GPU, e.g. {@link GL#glTexImage2D(int, int, int, int, int, int, int, int, Buffer) glTexImage2D}.</p>
         */
        public final boolean pack;
        /** Byte size of the buffer. Actually the number of {@link Buffer#remaining()} bytes when passed in ctor. */
        public final int byteSize;
        /**
         * Buffer holding the pixel data. If {@link #rewind()}, it holds <code>byteSize</code> {@link Buffer#remaining()} bytes.
         * <p>
         * By default the {@link Buffer} is a {@link ByteBuffer}, due to {@link DefProvider#allocate(GL, PixelFormat.Composition, GLPixelAttributes, boolean, int, int, int, int)}.
         * However, other {@link GLPixelBufferProvider} may utilize different {@link Buffer} types.
         * </p>
         */
        public final Buffer buffer;
        /** Buffer element size in bytes. */
        public final int bufferElemSize;
    
        /** Allow {@link GL2ES3#GL_PACK_ROW_LENGTH}, or {@link GL2ES2#GL_UNPACK_ROW_LENGTH}. See {@link #requiresNewBuffer(GL, int, int, int)}. */
        public final boolean allowRowStride;
    
        private boolean disposed = false;
    
        public StringBuilder toString(StringBuilder sb) {
            if(null == sb) {
                sb = new StringBuilder();
            }
            sb.append(pixelAttributes).append(", dim ").append(width).append("x").append(height).append("x").append(depth).append(", pack ").append(pack)
            .append(", disposed ").append(disposed).append(", valid ").append(isValid())
            .append(", buffer[bytes ").append(byteSize).append(", elemSize ").append(bufferElemSize).append(", ").append(buffer).append("]");
            return sb;
        }
        @Override
        public String toString() {
            return "GLPixelBuffer["+toString(null).toString()+"]";
        }
    
        /**
         * @param pixelAttributes the desired {@link GLPixelAttributes}
         * @param pack {@code true} for read mode GPU -> CPU, e.g. {@link GL#glReadPixels(int, int, int, int, int, int, Buffer) glReadPixels}.
         *             {@code false} for write mode CPU -> GPU, e.g. {@link GL#glTexImage2D(int, int, int, int, int, int, int, int, Buffer) glTexImage2D}.
         * @param width in pixels
         * @param height in pixels
         * @param depth in pixels
         * @param buffer the backing array
         * @param allowRowStride If <code>true</code>, allow row-stride, otherwise not. See {@link #requiresNewBuffer(GL, int, int, int)}.
         * @param hostPixelComp the host {@link PixelFormat.Composition}
         */
        public GLPixelBuffer(final GLPixelAttributes pixelAttributes, final boolean pack, final int width, final int height, final int depth, final Buffer buffer, final boolean allowRowStride) {
            this.pixelAttributes = pixelAttributes;
            this.width = width;
            this.height = height;
            this.depth = depth;
            this.pack = pack;
            this.buffer = buffer;
            this.byteSize = Buffers.remainingBytes(buffer);
            this.bufferElemSize = Buffers.sizeOfBufferElem(buffer);
            this.allowRowStride = allowRowStride;
        }
    
        /** Allow {@link GL2ES3#GL_PACK_ROW_LENGTH}, or {@link GL2ES2#GL_UNPACK_ROW_LENGTH}. */
        public final boolean getAllowRowStride() { return allowRowStride; }
    
        /** Is not {@link #dispose() disposed} and has {@link #byteSize} &gt; 0. */
        public boolean isValid() {
            return !disposed && 0 < byteSize;
        }
    
        /** See {@link Buffer#rewind()}. */
        public Buffer rewind() {
            return buffer.rewind();
        }
    
        /** Returns the byte position of the {@link #buffer}. */
        public int position() {
            return buffer.position() * bufferElemSize;
        }
    
        /** Sets the byte position of the {@link #buffer}. */
        public Buffer position(final int bytePos) {
            return buffer.position( bytePos / bufferElemSize );
        }
    
        /** Returns the byte capacity of the {@link #buffer}. */
        public int capacity() {
            return buffer.capacity() * bufferElemSize;
        }
    
        /** Returns the byte limit of the {@link #buffer}. */
        public int limit() {
            return buffer.limit() * bufferElemSize;
        }
    
        /** See {@link Buffer#flip()}. */
        public Buffer flip() {
            return buffer.flip();
        }
    
        /** See {@link Buffer#clear()}. */
        public Buffer clear() {
            return buffer.clear();
        }
    
        /**
         * Returns true, if {@link #isValid() invalid} or implementation requires a new buffer based on the new size
         * due to pixel alignment or byte size, otherwise false.
         * <p>
         * It is assumed that <code>pixelAttributes</code>, <code>depth</code> and <code>pack</code> stays the same!
         * </p>
         * <p>
         * The minimum required byte size equals to <code>minByteSize</code>, if &gt; 0,
         * otherwise {@link GLBuffers#sizeof(GL, int[], int, int, int, int, int, boolean) GLBuffers.sizeof(..)}
         * is being used to calculate it. This value is referred to <i>newByteSize</i>.
         * </p>
         * <p>
         * If <code>{@link #allowRowStride} = false</code>,
         * method returns <code>true</code> if the <i>newByteSize</i> &gt; <i>currentByteSize</i>
         * or the <code>newWidth</code> != <code>currentWidth</code>.
         * </p>
         * <p>
         * If <code>{@link #allowRowStride} = true</code>, see {@link GLPixelBufferProvider#getAllowRowStride()},
         * method returns <code>true</code> only if the <i>newByteSize</i> &gt; <i>currentByteSize</i>.
         * Assuming user utilizes the row-stride when dealing w/ the data, i.e. {@link GL2ES3#GL_PACK_ROW_LENGTH}.
         * </p>
         * @param gl the corresponding current GL context object
         * @param newWidth new width in pixels
         * @param newHeight new height in pixels
         * @param newByteSize if &gt; 0, the pre-calculated minimum byte-size for the resulting buffer, otherwise ignore.
         * @see GLPixelBufferProvider#allocate(GL, PixelFormat.Composition, GLPixelAttributes, boolean, int, int, int, int)
         */
        public boolean requiresNewBuffer(final GL gl, final int newWidth, final int newHeight, int newByteSize) {
            if( !isValid() ) {
                return true;
            }
            if( 0 >= newByteSize ) {
                final int[] tmp = { 0 };
                newByteSize = GLBuffers.sizeof(gl, tmp, pixelAttributes.pfmt.comp.bytesPerPixel(), newWidth, newHeight, 1, true);
            }
            if( allowRowStride ) {
                return byteSize < newByteSize;
            }
            return byteSize < newByteSize || width != newWidth;
        }
    
        /** Dispose resources. See {@link #isValid()}. */
        public void dispose() {
            disposed = true;
            buffer.clear();
        }
    };
 
    class DefaultGLPixelBufferProvider : public GLPixelBufferProvider {
      private:
        bool m_allowRowStride;
 
      public:
        /**
         * @param allowRowStride If <code>true</code>, allow row-stride, otherwise not.
         * See {@link #getAllowRowStride()} and {@link GLPixelBuffer#requiresNewBuffer(GL, int, int, int)}.
         */
        DefaultGLPixelBufferProvider(bool allowRowStride)
        : m_allowRowStride(allowRowStride) {} 
 
        bool getAllowRowStride() const noexcept override { return m_allowRowStride; }
 
        @Override
        public GLPixelAttributes getAttributes(final GL gl, final int componentCount, final boolean pack) {
            final GLPixelAttributes res = GLPixelAttributes.convert(gl, componentCount, pack);
            if( null == res ) {
                throw new GLException("Unsupported componentCount "+componentCount+", contact maintainer to enhance");
            } else {
                return res;
            }
        }
 
        /**
         * {@inheritDoc}
         * <p>
         * Returns {@code null}!
         * </p>
         */
        @Override
        public PixelFormat.Composition getHostPixelComp(final GLProfile glp, final int componentCount) {
            return null;
        }
 
        /**
         * {@inheritDoc}
         * <p>
         * Returns an NIO {@link ByteBuffer}.
         * </p>
         */
        @Override
        public GLPixelBuffer allocate(final GL gl, final PixelFormat.Composition hostPixComp, final GLPixelAttributes pixelAttributes,
                                      final boolean pack, final int width, final int height, final int depth, final int minByteSize) {
            // unused: hostPixComp
            if( minByteSize > 0 ) {
                return new GLPixelBuffer(pixelAttributes, pack, width, height, depth, Buffers.newDirectByteBuffer(minByteSize), getAllowRowStride());
            } else {
                final int[] tmp = { 0 };
                final int byteSize = GLBuffers.sizeof(gl, tmp, pixelAttributes.pfmt.comp.bytesPerPixel(), width, height, depth, pack);
                return new GLPixelBuffer(pixelAttributes, pack, width, height, depth, Buffers.newDirectByteBuffer(byteSize), getAllowRowStride());
            }
        }
    }
 
    /**
     * Default {@link GLPixelBufferProvider} with {@link GLPixelBufferProvider#getAllowRowStride()} == <code>false</code>,
     * utilizing best match for {@link GLPixelAttributes}
     * and {@link GLPixelBufferProvider#allocate(GL, PixelFormat.Composition, GLPixelAttributes, boolean, int, int, int, int) allocating} a {@link ByteBuffer}.
     */
    public static final GLPixelBufferProvider defaultProviderNoRowStride = new DefaultGLPixelBufferProvider(false);
 
    /**
     * Default {@link GLPixelBufferProvider} with {@link GLPixelBufferProvider#getAllowRowStride()} == <code>true</code>,
     * utilizing best match for {@link GLPixelAttributes}
     * and {@link GLPixelBufferProvider#allocate(GL, PixelFormat.Composition, GLPixelAttributes, boolean, int, int, int, int) allocating} a {@link ByteBuffer}.
     */
    public static final GLPixelBufferProvider defaultProviderWithRowStride = new DefaultGLPixelBufferProvider(true);
       
}  // namespace gamp::render::pixel::pixel
 
#endif /* GAMP_RENDER_GL_PIXEL_GLPIXELBUFFER_HPP_ */