/**
 * Copyright 2014 JogAmp Community. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are
 * permitted provided that the following conditions are met:
 *
 *    1. Redistributions of source code must retain the above copyright notice, this list of
 *       conditions and the following disclaimer.
 *
 *    2. Redistributions in binary form must reproduce the above copyright notice, this list
 *       of conditions and the following disclaimer in the documentation and/or other materials
 *       provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * The views and conclusions contained in the software and documentation are those of the
 * authors and should not be interpreted as representing official policies, either expressed
 * or implied, of JogAmp Community.
 */
package com.jogamp.opengl;

import java.nio.Buffer;
import java.nio.ByteBuffer;
import java.nio.IntBuffer;

/**
 * OpenGL buffer storage object reflecting it's
 * <ul>
 *   <li>storage size</li>
 *   <li>storage memory if mapped</li>
 *   <li>mutable usage or immutable flags</li>
 * </ul>
 * <p>
 * Buffer storage is created via:
 * <ul>
 *   <li>{@link GL#glBufferData(int, long, java.nio.Buffer, int)} - storage creation via target</li>
 *   <li>{@link GL2#glNamedBufferDataEXT(int, long, java.nio.Buffer, int)} - storage creation, direct</li>
 *   <li>{@link GL4#glNamedBufferData(int, long, java.nio.Buffer, int)} - storage creation, direct</li>
 *   <li>{@link GL4#glBufferStorage(int, long, Buffer, int)} - storage creation via target</li>
 *   <li>{@link GL4#glNamedBufferStorage(int, long, Buffer, int)} - storage creation, direct</li>
 * </ul>
 * Note that storage <i>recreation</i> as mentioned above also invalidate a previous storage instance,
 * i.e. disposed the buffer's current storage if exist and attaches a new storage instance.
 * </p>
 * <p>
 * Buffer storage is disposed via:
 * <ul>
 *   <li>{@link GL#glDeleteBuffers(int, IntBuffer)} - explicit, direct, via {@link #notifyBuffersDeleted(int, IntBuffer)} or {@link #notifyBuffersDeleted(int, int[], int)}</li>
 *   <li>{@link GL#glBufferData(int, long, java.nio.Buffer, int)} - storage recreation via target</li>
 *   <li>{@link GL2#glNamedBufferDataEXT(int, long, java.nio.Buffer, int)} - storage recreation, direct</li>
 *   <li>{@link GL4#glNamedBufferData(int, long, java.nio.Buffer, int)} - storage recreation, direct</li>
 *   <li>{@link GL4#glBufferStorage(int, long, Buffer, int)} - storage recreation via target</li>
 *   <li>{@link GL4#glNamedBufferStorage(int, long, Buffer, int)} - storage recreation, direct</li>
 * </ul>
 * </p>
 * <p>
 * GL buffer storage is mapped via
 * <ul>
 *   <li>{@link GL#mapBuffer(int, int)}</li>
 *   <li>{@link GL#mapBufferRange(int, long, long, int)}</li>
 *   <li>{@link GL2#mapNamedBufferEXT(int, int)}</li>
 *   <li>{@link GL2#mapNamedBufferRangeEXT(int, long, long, int)}</li>
 *   <li>{@link GL4#mapNamedBuffer(int, int)}</li>
 *   <li>{@link GL4#mapNamedBufferRange(int, long, long, int)}</li>
 * </ul>
 * </p>
 * <p>
 * GL buffer storage is unmapped via
 * <ul>
 *   <li>{@link GL#glDeleteBuffers(int, IntBuffer)} - buffer deletion</li>
 *   <li>{@link GL#glUnmapBuffer(int)} - explicit via target</li>
 *   <li>{@link GL2#glUnmapNamedBufferEXT(int)} - explicit direct</li>
 *   <li>{@link GL4#glUnmapNamedBuffer(int)} - explicit direct</li>
 *   <li>{@link GL#glBufferData(int, long, java.nio.Buffer, int)} - storage recreation via target</li>
 *   <li>{@link GL2#glNamedBufferDataEXT(int, long, java.nio.Buffer, int)} - storage recreation, direct</li>
 *   <li>{@link GL4#glNamedBufferData(int, long, java.nio.Buffer, int)} - storage recreation, direct</li>
 *   <li>{@link GL4#glBufferStorage(int, long, Buffer, int)} - storage creation via target</li>
 *   <li>{@link GL4#glNamedBufferStorage(int, long, Buffer, int)} - storage creation, direct</li>
 * </ul>
 * </p>
 */
public abstract class GLBufferStorage {
        private final int name;
        private /* final */ long size;
        private /* final */ int mutableUsage;
        private /* final */ int immutableFlags;
        private ByteBuffer mappedBuffer;

        protected GLBufferStorage(final int name, final long size, final int mutableUsage, final int immutableFlags) {
            this.name = name;
            this.size = size;
            this.mutableUsage = mutableUsage;
            this.immutableFlags = immutableFlags;
            this.mappedBuffer = null;
        }

        protected void reset(final long size, final int mutableUsage, final int immutableFlags) {
            this.size = size;
            this.mutableUsage = mutableUsage;
            this.immutableFlags = immutableFlags;
            this.mappedBuffer = null;
        }
        protected void setMappedBuffer(final ByteBuffer buffer) {
            this.mappedBuffer = buffer;
        }

        /** Return the buffer name */
        public final int getName() { return name; }

        /** Return the buffer's storage size. */
        public final long getSize() { return size; }

        /**
         * Returns <code>true</code> if buffer's storage is mutable, i.e.
         * created via {@link GL#glBufferData(int, long, java.nio.Buffer, int)}.
         * <p>
         * Returns <code>false</code> if buffer's storage is immutable, i.e.
         * created via {@link GL4#glBufferStorage(int, long, Buffer, int)}.
         * </p>
         * @return
         */
        public final boolean isMutableStorage() { return 0 != mutableUsage; }

        /**
         * Returns the mutable storage usage or 0 if storage is not {@link #isMutableStorage() mutable}.
         */
        public final int getMutableUsage() { return mutableUsage; }

        /**
         * Returns the immutable storage flags, invalid if storage is {@link #isMutableStorage() mutable}.
         */
        public final int getImmutableFlags() { return immutableFlags; }

        /**
         * Returns the mapped ByteBuffer, or null if not mapped.
         * Mapping may occur via:
         * <ul>
         *   <li>{@link GL#glMapBuffer(int, int)}</li>
         *   <li>{@link GL#glMapBufferRange(int, long, long, int)}</li>
         *   <li>{@link GL2#glMapNamedBufferEXT(int, int)}</li>
         *   <li>{@link GL2#glMapNamedBufferRangeEXT(int, long, long, int)}
         * </ul>
         */
        public final ByteBuffer getMappedBuffer() { return mappedBuffer; }

        public final String toString() {
            return toString(false);
        }
        public final String toString(final boolean skipMappedBuffer) {
            final String s0;
            if( isMutableStorage() ) {
                s0 = String.format("%s[name %s, size %d, mutable usage 0x%X", msgClazzName, name, size, mutableUsage);
            } else {
                s0 = String.format("%s[name %s, size %d, immutable flags 0x%X", msgClazzName, name, size, immutableFlags);
            }
            if(skipMappedBuffer) {
                return s0+"]";
            } else {
                return s0+", mapped "+mappedBuffer+"]";
            }
        }
        private static final String msgClazzName = "GLBufferStorage";
}