JOGL 2.3.2 · jogamp.opengl.GLBufferObjectTracker

Tracking of GLBufferStorage instances via GL API callbacks.

See GLBufferStorage for generic details.

Buffer storage is created via

GL#glBufferData(int, long, java.nio.Buffer, int) - storage recreation with target via createBufferStorage(GLBufferStateTracker, GL, int, long, Buffer, int, int, CreateStorageDispatch, long)
GL2#glNamedBufferDataEXT(int, long, java.nio.Buffer, int) - storage recreation, direct, via createBufferStorage(GL, int, long, Buffer, int, CreateStorageDispatch, long)
GL4#glNamedBufferData(int, long, java.nio.Buffer, int) - storage recreation, direct, via createBufferStorage(GL, int, long, Buffer, int, CreateStorageDispatch, long)
GL4#glBufferStorage(int, long, Buffer, int) - storage creation with target via createBufferStorage(GLBufferStateTracker, GL, int, long, Buffer, int, int, CreateStorageDispatch, long)
GL4#glNamedBufferStorage(int, long, Buffer, int) - storage recreation, direct, via createBufferStorage(GL, int, long, Buffer, int, CreateStorageDispatch, long)

Note that storage recreation 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.

Buffers storage is disposed via

GL#glDeleteBuffers(int, IntBuffer) - explicit, direct, via notifyBuffersDeleted(int, IntBuffer) or notifyBuffersDeleted(int, int[], int)
GL#glBufferData(int, long, java.nio.Buffer, int) - storage recreation via target
GL2#glNamedBufferDataEXT(int, long, java.nio.Buffer, int) - storage recreation, direct
GL4#glNamedBufferData(int, long, java.nio.Buffer, int) - storage recreation, direct
GL4#glBufferStorage(int, long, Buffer, int) - storage recreation via target
GL4#glNamedBufferStorage(int, long, Buffer, int) - storage recreation, direct

Implementation throws a GLException in all construction methods as listed below, if GL-function constraints are not met. createBufferStorage also throws an exception if the native GL-function fails.

In destruction and informal methods, i.e. all others, implementation only issues a WARNING debug message, if enabled.

Buffer mapping methods like GL#mapBuffer(int, int) ..., require knowledge of the buffer's storage size as determined via it's creation with GL#glBufferData(int, long, java.nio.Buffer, int) ....

Hence we track the OpenGL buffer's GLBufferStorage to be able to access the buffer's storage size. The tracked GLBufferStorage instances also allow users to conveniently access details of their created and maybe mapped buffer storage.

The GLBufferObjectTracker and it's tracked GLBufferStorage instances maybe shared across multiple OpenGL context, hence this class is thread safe and employs synchronization.

Implementation requires and utilizes a local GLBufferStateTracker to resolve the actual buffer-name bound to the given target.

Note

This tracker requires to be notified about all OpenGL buffer storage operations, as well as the local GLBufferStateTracker to be notified about all OpenGL buffer binding operations. Hence buffer storage cannot be accessed properly if managed via native code.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	GLBufferObjectTracker.CreateStorageDispatch
pack-priv static class	GLBufferObjectTracker.GLBufferStorageImpl
public static interface	GLBufferObjectTracker.MapBufferAllDispatch
public static interface	GLBufferObjectTracker.MapBufferDispatch
public static interface	GLBufferObjectTracker.MapBufferRangeDispatch
public static interface	GLBufferObjectTracker.UnmapBufferDispatch

Field Summary

Modifier and Type	Field and Description
private final IntObjectHashMap	bufferName2StorageMap Map from buffer names to GLBufferObject.
protected static final boolean	DEBUG
private static final String	GL_INVALID_OPERATION
private static final String	GL_INVALID_VALUE
private static final String	msgClazzName
private static final String	msgCreateBound
private static final String	msgCreateNamed
private static final String	msgMapBuffer
private static final String	msgUnmapped
private static final String	warning

Constructor Summary

Access	Constructor and Description
public	GLBufferObjectTracker()

Method Summary

Modifier and Type	Method and Description
public final synchronized void	clear() Clear all tracked buffer object knowledge.
public final synchronized void	createBufferStorage(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final long size, final Buffer data, final int `glBufferData`, `glNamedBufferData` usage mutableUsage, final int `glBufferStorage` flags immutableFlags, final GLBufferObjectTracker.CreateStorageDispatch dispatch) Must be called when [re]creating the GL buffer object via `GL#glBufferData(int, long, java.nio.Buffer, int)` and `GL4#glBufferStorage(int, long, Buffer, int)`, i.e. implies destruction of the buffer.
public final synchronized void	createBufferStorage(final GL caller, final int bufferName, final long size, final Buffer data, final int mutableUsage, final int immutableFlags, final GLBufferObjectTracker.CreateStorageDispatch dispatch) Must be called when [re]creating the GL buffer object via `glNamedBufferDataEXT`, `glNamedBufferData`, and `GL4#glNamedBufferStorage(int, long, Buffer, int)`, i.e. implies destruction of the buffer.
public final synchronized GLBufferStorage	getBufferStorage(final int bufferName)
public final synchronized GLBufferStorage	mapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final int access, final GLBufferObjectTracker.MapBufferAllDispatch dispatch) Must be called when mapping GL buffer objects via `GL#mapBuffer(int, int)`.
public final synchronized GLBufferStorage	mapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferRangeDispatch dispatch) Must be called when mapping GL buffer objects via `GL#mapBufferRange(int, long, long, int)`.
public final synchronized GLBufferStorage	mapBuffer(final int bufferName, final int access, final GLBufferObjectTracker.MapBufferAllDispatch dispatch) Must be called when mapping GL buffer objects via `GL2#mapNamedBufferEXT(int, int)`.
public final synchronized GLBufferStorage	mapBuffer(final int bufferName, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferRangeDispatch dispatch) Must be called when mapping GL buffer objects via `GL2#mapNamedBufferRangeEXT(int, long, long, int)`.
private final synchronized GLBufferStorage	mapBufferImpl(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final boolean useRange, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferDispatch dispatch)
private final synchronized GLBufferStorage	mapBufferImpl(final int target, final int bufferName, final boolean isNamedBuffer, final boolean useRange, long offset, long length, final int access, final GLBufferObjectTracker.MapBufferDispatch dispatch) A zero store size will avoid a native call and returns the unmapped `GLBufferStorage`.
private final synchronized void	notifyBufferDeleted(final int bufferName, final int i, final int count) Must be called when deleting GL buffer objects vis `GL#glDeleteBuffers(int, IntBuffer)`.
public final synchronized void	notifyBuffersDeleted(final int count, final int[] bufferNames, final int offset) Must be called when deleting GL buffer objects vis `glDeleteBuffers`.
public final synchronized void	notifyBuffersDeleted(final int n, final IntBuffer bufferNames) Must be called when deleting GL buffer objects vis `glDeleteBuffers`.
public final synchronized boolean	unmapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final GLBufferObjectTracker.UnmapBufferDispatch dispatch) Must be called when unmapping GL buffer objects via `GL#glUnmapBuffer(int)`.
public final synchronized boolean	unmapBuffer(final int bufferName, final GLBufferObjectTracker.UnmapBufferDispatch dispatch) Must be called when unmapping GL buffer objects via `GL2#glUnmapNamedBuffer(int)`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

bufferName2StorageMap	back to summary
private final IntObjectHashMap bufferName2StorageMap Map from buffer names to GLBufferObject.

DEBUG	back to summary
protected static final boolean DEBUG

GL_INVALID_OPERATION	back to summary
private static final String GL_INVALID_OPERATION

GL_INVALID_VALUE	back to summary
private static final String GL_INVALID_VALUE

msgClazzName	back to summary
private static final String msgClazzName

msgCreateBound	back to summary
private static final String msgCreateBound

msgCreateNamed	back to summary
private static final String msgCreateNamed

msgMapBuffer	back to summary
private static final String msgMapBuffer

msgUnmapped	back to summary
private static final String msgUnmapped

warning	back to summary
private static final String warning

Constructor Detail

GLBufferObjectTracker	back to summary
public GLBufferObjectTracker()

Method Detail

clear	back to summary
public final synchronized void clear() Clear all tracked buffer object knowledge. Shall only be called at GLContext destruction iff there are no other shared GLContext instances left.

clear

back to summary

public final synchronized void clear()

Clear all tracked buffer object knowledge.

Shall only be called at GLContext destruction iff there are no other shared GLContext instances left.

createBufferStorage back to summary

createBufferStorage	back to summary
public final synchronized void createBufferStorage(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final long size, final Buffer data, final int mutableUsage, final int immutableFlags, final GLBufferObjectTracker.CreateStorageDispatch dispatch) throws GLException Must be called when [re]creating the GL buffer object via `GL#glBufferData(int, long, java.nio.Buffer, int)` and `GL4#glBufferStorage(int, long, Buffer, int)`, i.e. implies destruction of the buffer. Parameters mutableUsage:int `glBufferData`, `glNamedBufferData` usage immutableFlags:int `glBufferStorage` flags Exceptions GLException: if buffer is not bound to target if size is less-or-eqaul zero for `glBufferStorage`, or size is less-than zero otherwise if a native GL-Error occurs

public final synchronized void createBufferStorage(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final long size, final Buffer data, final int mutableUsage, final int immutableFlags, final GLBufferObjectTracker.CreateStorageDispatch dispatch) throws GLException

Must be called when [re]creating the GL buffer object via GL#glBufferData(int, long, java.nio.Buffer, int) and GL4#glBufferStorage(int, long, Buffer, int), i.e. implies destruction of the buffer.

Parameters

mutableUsage:int: glBufferData, glNamedBufferData usage
immutableFlags:int: glBufferStorage flags

Exceptions

GLException:

if buffer is not bound to target
if size is less-or-eqaul zero for glBufferStorage, or size is less-than zero otherwise
if a native GL-Error occurs

createBufferStorage back to summary

createBufferStorage	back to summary
public final synchronized void createBufferStorage(final GL caller, final int bufferName, final long size, final Buffer data, final int mutableUsage, final int immutableFlags, final GLBufferObjectTracker.CreateStorageDispatch dispatch) throws GLException Must be called when [re]creating the GL buffer object via `glNamedBufferDataEXT`, `glNamedBufferData`, and `GL4#glNamedBufferStorage(int, long, Buffer, int)`, i.e. implies destruction of the buffer. Exceptions GLException: if size is less-than zero if a native GL-Error occurs

public final synchronized void createBufferStorage(final GL caller, final int bufferName, final long size, final Buffer data, final int mutableUsage, final int immutableFlags, final GLBufferObjectTracker.CreateStorageDispatch dispatch) throws GLException

Must be called when [re]creating the GL buffer object via glNamedBufferDataEXT, glNamedBufferData, and GL4#glNamedBufferStorage(int, long, Buffer, int), i.e. implies destruction of the buffer.

Exceptions

GLException:

if size is less-than zero
if a native GL-Error occurs

getBufferStorage	back to summary
public final synchronized GLBufferStorage getBufferStorage(final int bufferName)

mapBuffer back to summary

mapBuffer	back to summary
public final synchronized GLBufferStorage mapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final int access, final GLBufferObjectTracker.MapBufferAllDispatch dispatch) throws GLException Must be called when mapping GL buffer objects via `GL#mapBuffer(int, int)`. Exceptions GLException: if buffer is not bound to target if buffer is not tracked if buffer is already mapped if buffer has invalid store size, i.e. less-than zero

public final synchronized GLBufferStorage mapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final int access, final GLBufferObjectTracker.MapBufferAllDispatch dispatch) throws GLException

Must be called when mapping GL buffer objects via GL#mapBuffer(int, int).

Exceptions

GLException:

if buffer is not bound to target
if buffer is not tracked
if buffer is already mapped
if buffer has invalid store size, i.e. less-than zero

mapBuffer back to summary

mapBuffer	back to summary
public final synchronized GLBufferStorage mapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferRangeDispatch dispatch) throws GLException Must be called when mapping GL buffer objects via `GL#mapBufferRange(int, long, long, int)`. Exceptions GLException: if buffer is not bound to target if buffer is not tracked if buffer is already mapped if buffer has invalid store size, i.e. less-than zero if buffer mapping range does not fit, incl. offset

public final synchronized GLBufferStorage mapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferRangeDispatch dispatch) throws GLException

Must be called when mapping GL buffer objects via GL#mapBufferRange(int, long, long, int).

Exceptions

GLException:

if buffer is not bound to target
if buffer is not tracked
if buffer is already mapped
if buffer has invalid store size, i.e. less-than zero
if buffer mapping range does not fit, incl. offset

mapBuffer back to summary

mapBuffer	back to summary
public final synchronized GLBufferStorage mapBuffer(final int bufferName, final int access, final GLBufferObjectTracker.MapBufferAllDispatch dispatch) throws GLException Must be called when mapping GL buffer objects via `GL2#mapNamedBufferEXT(int, int)`. Exceptions GLException: if buffer is not tracked if buffer is already mapped if buffer has invalid store size, i.e. less-than zero

public final synchronized GLBufferStorage mapBuffer(final int bufferName, final int access, final GLBufferObjectTracker.MapBufferAllDispatch dispatch) throws GLException

Must be called when mapping GL buffer objects via GL2#mapNamedBufferEXT(int, int).

Exceptions

GLException:

if buffer is not tracked
if buffer is already mapped
if buffer has invalid store size, i.e. less-than zero

mapBuffer back to summary

mapBuffer	back to summary
public final synchronized GLBufferStorage mapBuffer(final int bufferName, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferRangeDispatch dispatch) throws GLException Must be called when mapping GL buffer objects via `GL2#mapNamedBufferRangeEXT(int, long, long, int)`. Exceptions GLException: if buffer is not tracked if buffer is already mapped if buffer has invalid store size, i.e. less-than zero if buffer mapping range does not fit, incl. offset

public final synchronized GLBufferStorage mapBuffer(final int bufferName, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferRangeDispatch dispatch) throws GLException

Must be called when mapping GL buffer objects via GL2#mapNamedBufferRangeEXT(int, long, long, int).

Exceptions

GLException:

if buffer is not tracked
if buffer is already mapped
if buffer has invalid store size, i.e. less-than zero
if buffer mapping range does not fit, incl. offset

mapBufferImpl	back to summary
private final synchronized GLBufferStorage mapBufferImpl(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final boolean useRange, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferDispatch dispatch) throws GLException Exceptions GLException: if buffer is not bound to target if buffer is not tracked if buffer is already mapped if buffer has invalid store size, i.e. less-than zero if buffer mapping range does not fit, incl. optional offset

mapBufferImpl

back to summary

private final synchronized GLBufferStorage mapBufferImpl(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final boolean useRange, final long offset, final long length, final int access, final GLBufferObjectTracker.MapBufferDispatch dispatch) throws GLException

Exceptions

GLException:

if buffer is not bound to target
if buffer is not tracked
if buffer is already mapped
if buffer has invalid store size, i.e. less-than zero
if buffer mapping range does not fit, incl. optional offset

mapBufferImpl back to summary

mapBufferImpl	back to summary
private final synchronized GLBufferStorage mapBufferImpl(final int target, final int bufferName, final boolean isNamedBuffer, final boolean useRange, long offset, long length, final int access, final GLBufferObjectTracker.MapBufferDispatch dispatch) throws GLException A zero store size will avoid a native call and returns the unmapped `GLBufferStorage`. A null native mapping result indicating an error will not cause a GLException but returns the unmapped `GLBufferStorage`. This allows the user to handle this case. Exceptions GLException: if buffer is not tracked if buffer is already mapped if buffer has invalid store size, i.e. less-than zero if buffer mapping range does not fit, incl. optional offset

private final synchronized GLBufferStorage mapBufferImpl(final int target, final int bufferName, final boolean isNamedBuffer, final boolean useRange, long offset, long length, final int access, final GLBufferObjectTracker.MapBufferDispatch dispatch) throws GLException

A zero store size will avoid a native call and returns the unmapped GLBufferStorage.

A null native mapping result indicating an error will not cause a GLException but returns the unmapped GLBufferStorage. This allows the user to handle this case.

Exceptions

GLException:

if buffer is not tracked
if buffer is already mapped
if buffer has invalid store size, i.e. less-than zero
if buffer mapping range does not fit, incl. optional offset

notifyBufferDeleted	back to summary
private final synchronized void notifyBufferDeleted(final int bufferName, final int i, final int count) Must be called when deleting GL buffer objects vis `GL#glDeleteBuffers(int, IntBuffer)`.

notifyBuffersDeleted	back to summary
public final synchronized void notifyBuffersDeleted(final int count, final int[] bufferNames, final int offset) Must be called when deleting GL buffer objects vis `glDeleteBuffers`.

notifyBuffersDeleted	back to summary
public final synchronized void notifyBuffersDeleted(final int n, final IntBuffer bufferNames) Must be called when deleting GL buffer objects vis `glDeleteBuffers`.

unmapBuffer back to summary

unmapBuffer	back to summary
public final synchronized boolean unmapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final GLBufferObjectTracker.UnmapBufferDispatch dispatch) Must be called when unmapping GL buffer objects via `GL#glUnmapBuffer(int)`. Only clear mapped buffer reference of `GLBufferStorage` if native unmapping was successful.

public final synchronized boolean unmapBuffer(final GLBufferStateTracker bufferStateTracker, final GL caller, final int target, final GLBufferObjectTracker.UnmapBufferDispatch dispatch)

Must be called when unmapping GL buffer objects via GL#glUnmapBuffer(int).

Only clear mapped buffer reference of GLBufferStorage if native unmapping was successful.

unmapBuffer back to summary

unmapBuffer	back to summary
public final synchronized boolean unmapBuffer(final int bufferName, final GLBufferObjectTracker.UnmapBufferDispatch dispatch) Must be called when unmapping GL buffer objects via `GL2#glUnmapNamedBuffer(int)`. Only clear mapped buffer reference of `GLBufferStorage` if native unmapping was successful.

public final synchronized boolean unmapBuffer(final int bufferName, final GLBufferObjectTracker.UnmapBufferDispatch dispatch)

Must be called when unmapping GL buffer objects via GL2#glUnmapNamedBuffer(int).

Only clear mapped buffer reference of GLBufferStorage if native unmapping was successful.

Modifier and Type	Method and Description
protected final void	reset(final long size, final int mutableUsage, final int immutableFlags) Overrides com.jogamp.opengl.GLBufferStorage.reset.
protected final void	setMappedBuffer(final ByteBuffer buffer) Overrides com.jogamp.opengl.GLBufferStorage.setMappedBuffer.

public Class GLBufferObjectTracker

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Interface GLBufferObjectTracker.CreateStorageDispatch

Method Summary

Method Detail

pack-priv final Class GLBufferObjectTracker.GLBufferStorageImpl

Constructor Summary

Method Summary

Constructor Detail

Method Detail

public Interface GLBufferObjectTracker.MapBufferAllDispatch

Method Summary

Method Detail

public Interface GLBufferObjectTracker.MapBufferDispatch

Method Summary

Method Detail

public Interface GLBufferObjectTracker.MapBufferRangeDispatch

Method Summary

Method Detail

public Interface GLBufferObjectTracker.UnmapBufferDispatch

Method Summary

Method Detail