com.jogamp.opengl.util.GLPixelBuffer Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jogl-all Show documentation
Show all versions of jogl-all Show documentation
Java™ Binding for the OpenGL® API
/**
* Copyright 2013 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.util;
import java.nio.Buffer;
import java.nio.ByteBuffer;
import javax.media.nativewindow.util.PixelFormat;
import javax.media.opengl.GL;
import javax.media.opengl.GL2ES2;
import javax.media.opengl.GL2ES3;
import javax.media.opengl.GL2GL3;
import javax.media.opengl.GLContext;
import javax.media.opengl.GLException;
import javax.media.opengl.GLProfile;
import com.jogamp.common.nio.Buffers;
import com.jogamp.opengl.util.texture.TextureData;
/**
* OpenGL pixel data buffer, allowing user to provide buffers via their {@link GLPixelBufferProvider} implementation.
*
* {@link GLPixelBufferProvider} produces a {@link GLPixelBuffer}.
*
*
* You may use {@link #defaultProviderNoRowStride}.
*
*/
public class GLPixelBuffer {
/** Allows user to interface with another toolkit to define {@link GLPixelAttributes} and memory buffer to produce {@link TextureData}. */
public static interface GLPixelBufferProvider {
/** Allow {@link GL2ES3#GL_PACK_ROW_LENGTH}, or {@link GL2ES2#GL_UNPACK_ROW_LENGTH}. */
boolean getAllowRowStride();
/** Called first to determine {@link GLPixelAttributes}. */
GLPixelAttributes getAttributes(GL gl, int componentCount);
/**
* Allocates a new {@link GLPixelBuffer} object.
*
* Being called to gather the initial {@link GLPixelBuffer},
* or a new replacement {@link GLPixelBuffer} if {@link GLPixelBuffer#requiresNewBuffer(GL, int, int, int)}.
*
*
* The minimum required {@link Buffer#remaining() remaining} byte size equals to minByteSize, if > 0,
* otherwise utilize {@link GLBuffers#sizeof(GL, int[], int, int, int, int, int, boolean)}
* to calculate it.
*
*
* @param gl the corresponding current GL context object
* @param pixelAttributes the desired {@link GLPixelAttributes}
* @param width in pixels
* @param height in pixels
* @param depth in pixels
* @param pack true for read mode GPU -> CPU, otherwise false for write mode CPU -> GPU
* @param minByteSize if > 0, the pre-calculated minimum byte-size for the resulting buffer, otherwise ignore.
*/
GLPixelBuffer allocate(GL gl, GLPixelAttributes pixelAttributes, int width, int height, int depth, boolean pack, int minByteSize);
}
/** Single {@link GLPixelBuffer} provider. */
public static interface SingletonGLPixelBufferProvider extends GLPixelBufferProvider {
/** Return the last {@link #allocate(GL, GLPixelAttributes, int, int, int, boolean, int) allocated} {@link GLPixelBuffer} w/ {@link GLPixelAttributes#componentCount}. */
GLPixelBuffer getSingleBuffer(GLPixelAttributes pixelAttributes);
/**
* Initializes the single {@link GLPixelBuffer} w/ a given size, if not yet {@link #allocate(GL, GLPixelAttributes, int, int, int, boolean, int) allocated}.
* @return the newly initialized single {@link GLPixelBuffer}, or null if already allocated.
*/
GLPixelBuffer initSingleton(int componentCount, int width, int height, int depth, boolean pack);
}
public static class DefaultGLPixelBufferProvider implements GLPixelBufferProvider {
private final boolean allowRowStride;
/**
* @param allowRowStride If true, allow row-stride, otherwise not.
* See {@link #getAllowRowStride()} and {@link GLPixelBuffer#requiresNewBuffer(GL, int, int, int)}.
*/
public DefaultGLPixelBufferProvider(final boolean allowRowStride) {
this.allowRowStride = allowRowStride;
}
@Override
public boolean getAllowRowStride() { return allowRowStride; }
@Override
public GLPixelAttributes getAttributes(final GL gl, final int componentCount) {
final GLContext ctx = gl.getContext();
final int dFormat, dType;
if( 1 == componentCount ) {
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 ) {
dFormat = GL.GL_RGB;
dType = GL.GL_UNSIGNED_BYTE;
} else if( 4 == componentCount ) {
final int _dFormat = ctx.getDefaultPixelDataFormat();
final int dComps = GLBuffers.componentCount(_dFormat);
if( dComps == componentCount ) {
dFormat = _dFormat;
dType = ctx.getDefaultPixelDataType();
} else {
dFormat = GL.GL_RGBA;
dType = GL.GL_UNSIGNED_BYTE;
}
} else {
throw new GLException("Unsupported componentCount "+componentCount+", contact maintainer to enhance");
}
return new GLPixelAttributes(componentCount, dFormat, dType);
}
/**
* {@inheritDoc}
*
* Returns an NIO {@link ByteBuffer}.
*
*/
@Override
public GLPixelBuffer allocate(final GL gl, final GLPixelAttributes pixelAttributes, final int width, final int height, final int depth, final boolean pack, final int minByteSize) {
if( minByteSize > 0 ) {
return new GLPixelBuffer(pixelAttributes, width, height, depth, pack, Buffers.newDirectByteBuffer(minByteSize), getAllowRowStride());
} else {
final int[] tmp = { 0 };
final int byteSize = GLBuffers.sizeof(gl, tmp, pixelAttributes.bytesPerPixel, width, height, depth, pack);
return new GLPixelBuffer(pixelAttributes, width, height, depth, pack, Buffers.newDirectByteBuffer(byteSize), getAllowRowStride());
}
}
}
/**
* Default {@link GLPixelBufferProvider} with {@link GLPixelBufferProvider#getAllowRowStride()} == false,
* utilizing best match for {@link GLPixelAttributes}
* and {@link GLPixelBufferProvider#allocate(GL, GLPixelAttributes, int, int, int, boolean, int) allocating} a {@link ByteBuffer}.
*/
public static final GLPixelBufferProvider defaultProviderNoRowStride = new DefaultGLPixelBufferProvider(false);
/**
* Default {@link GLPixelBufferProvider} with {@link GLPixelBufferProvider#getAllowRowStride()} == true,
* utilizing best match for {@link GLPixelAttributes}
* and {@link GLPixelBufferProvider#allocate(GL, GLPixelAttributes, int, int, int, boolean, int) allocating} a {@link ByteBuffer}.
*/
public static final GLPixelBufferProvider defaultProviderWithRowStride = new DefaultGLPixelBufferProvider(true);
/** 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(0, 0, 0, false);
/** Pixel source component count, i.e. number of meaningful components. */
public final int componentCount;
/** The OpenGL pixel data format */
public final int format;
/** The OpenGL pixel data type */
public final int type;
/** The OpenGL pixel size in bytes */
public final int bytesPerPixel;
/**
* Deriving {@link #componentCount} via GL dataFormat, i.e. {@link GLBuffers#componentCount(int)} if > 0.
* @param dataFormat GL data format
* @param dataType GL data type
*/
public GLPixelAttributes(final int dataFormat, final int dataType) {
this(0 < dataFormat ? GLBuffers.componentCount(dataFormat) : 0, dataFormat, dataType);
}
/**
* Using user specified source {@link #componentCount}.
* @param componentCount source component count
* @param dataFormat GL data format
* @param dataType GL data type
*/
public GLPixelAttributes(final int componentCount, final int dataFormat, final int dataType) {
this(componentCount, dataFormat, dataType, true);
}
/**
* Returns the matching {@link GLPixelAttributes} for the given {@link PixelFormat} and {@link GLProfile} if exists,
* otherwise returns null.
*/
public static final GLPixelAttributes convert(final PixelFormat pixFmt, final GLProfile glp) {
int df = 0; // format
int dt = GL.GL_UNSIGNED_BYTE; // data type
switch(pixFmt) {
case LUMINANCE:
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 BGR888:
if( glp.isGL2GL3() ) {
df = GL2GL3.GL_BGR;
}
break;
case RGB888:
df = GL.GL_RGB;
break;
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 BGRA8888:
df = GL.GL_BGRA;
break;
case ARGB8888:
if( glp.isGL2GL3() ) {
df = GL.GL_BGRA; dt = GL2GL3.GL_UNSIGNED_INT_8_8_8_8;
}
break;
default:
break;
}
if( 0 != df ) {
return new GLPixelAttributes(pixFmt.componentCount, df, dt, true);
}
return null;
}
private GLPixelAttributes(final int componentCount, final int dataFormat, final int dataType, final boolean checkArgs) {
this.componentCount = componentCount;
this.format = dataFormat;
this.type = dataType;
this.bytesPerPixel = ( 0 < dataFormat && 0 < dataType ) ? GLBuffers.bytesPerPixel(dataFormat, dataType) : 0;
if( checkArgs ) {
if( 0 == componentCount || 0 == format || 0 == type ) {
throw new GLException("Zero components, format and/or type: "+this);
}
if( 0 == bytesPerPixel ) {
throw new GLException("Zero bytesPerPixel: "+this);
}
}
}
/**
* Returns the matching {@link PixelFormat} of this {@link GLPixelAttributes} if exists,
* otherwise returns null.
*/
public final PixelFormat getPixelFormat() {
final PixelFormat pixFmt;
// FIXME: Take 'type' into consideration and complete mapping!
switch(format) {
case GL.GL_ALPHA:
case GL.GL_LUMINANCE:
case GL2ES2.GL_RED:
pixFmt = PixelFormat.LUMINANCE;
break;
case GL.GL_RGB:
pixFmt = PixelFormat.RGB888;
break;
case GL.GL_RGBA:
pixFmt = PixelFormat.RGBA8888;
break;
case GL2GL3.GL_BGR:
pixFmt = PixelFormat.BGR888;
break;
case GL.GL_BGRA:
pixFmt = PixelFormat.BGRA8888;
break;
default:
switch( bytesPerPixel ) {
case 1:
pixFmt = PixelFormat.LUMINANCE;
break;
case 3:
pixFmt = PixelFormat.RGB888;
break;
case 4:
pixFmt = PixelFormat.RGBA8888;
break;
default:
pixFmt = null;
break;
}
break;
}
return pixFmt;
}
@Override
public String toString() {
return "PixelAttributes[comp "+componentCount+", fmt 0x"+Integer.toHexString(format)+", type 0x"+Integer.toHexString(type)+", bytesPerPixel "+bytesPerPixel+"]";
}
}
/** The {@link GLPixelAttributes}. */
public final GLPixelAttributes pixelAttributes;
/**
* Width in pixels, representing {@link #buffer}'s {@link #byteSize}.
*
* May not represent actual image width as user may re-use buffer for different dimensions, see {@link #requiresNewBuffer(GL, int, int, int)}.
*
*/
public final int width;
/**
* Height in pixels, representing {@link #buffer}'s {@link #byteSize}.
*
* May not represent actual image height as user may re-use buffer for different dimensions, see {@link #requiresNewBuffer(GL, int, int, int)}.
*
*/
public final int height;
/** Depth in pixels. */
public final int depth;
/** Data packing direction. If true for read mode GPU -> CPU, false for write mode CPU -> GPU. */
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 byteSize {@link Buffer#remaining()} bytes.
*
* By default the {@link Buffer} is a {@link ByteBuffer}, due to {@link DefProvider#allocate(GL, GLPixelAttributes, int, int, int, boolean, int)}.
* However, other {@link GLPixelBufferProvider} may utilize different {@link Buffer} types.
*
*/
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 width in pixels
* @param height in pixels
* @param depth in pixels
* @param pack true for read mode GPU -> CPU, otherwise false for write mode CPU -> GPU
* @param buffer the backing array
* @param allowRowStride If true, allow row-stride, otherwise not. See {@link #requiresNewBuffer(GL, int, int, int)}.
*/
public GLPixelBuffer(final GLPixelAttributes pixelAttributes, final int width, final int height, final int depth, final boolean pack, 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} > 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.
*
* It is assumed that pixelAttributes, depth and pack stays the same!
*
*
* The minimum required byte size equals to minByteSize, if > 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 newByteSize.
*
*
* If {@link #allowRowStride} = false,
* method returns true if the newByteSize > currentByteSize
* or the newWidth != currentWidth.
*
*
* If {@link #allowRowStride} = true, see {@link GLPixelBufferProvider#getAllowRowStride()},
* method returns true only if the newByteSize > currentByteSize.
* Assuming user utilizes the row-stride when dealing w/ the data, i.e. {@link GL2ES3#GL_PACK_ROW_LENGTH}.
*
* @param gl the corresponding current GL context object
* @param newWidth new width in pixels
* @param newHeight new height in pixels
* @param newByteSize if > 0, the pre-calculated minimum byte-size for the resulting buffer, otherwise ignore.
* @see GLPixelBufferProvider#allocate(GL, GLPixelAttributes, int, int, int, boolean, 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.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();
}
}