com.jme3.opencl

Class Buffer

java.lang.Object

com.jme3.opencl.AbstractOpenCLObject

com.jme3.opencl.Buffer

All Implemented Interfaces:

OpenCLObject

Direct Known Subclasses:

LwjglBuffer

public abstract class Buffer
extends AbstractOpenCLObject

Wrapper for an OpenCL buffer object. A buffer object stores a one-dimensional collection of elements. Elements of a buffer object can be a scalar data type (such as an int, float), vector data type, or a user-defined structure.
Buffers are created by the Context.
All access methods (read/write/copy/map) are available in both synchronized/blocking versions and in async/non-blocking versions. The later ones always return an Event object and have the prefix -Async in their name.

See Also:

Context.createBuffer(long, com.jme3.opencl.MemoryAccess)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Buffer.AsyncMapping Result of an async mapping operation, contains the event and the target byte buffer.

Nested classes/interfaces inherited from interface com.jme3.opencl.OpenCLObject

OpenCLObject.ObjectReleaser

Field Summary

Fields inherited from class com.jme3.opencl.AbstractOpenCLObject

releaser

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Buffer(OpenCLObject.ObjectReleaser releaser)

Method Summary

Modifier and Type	Method and Description
abstract Event	acquireBufferForSharingAsync(CommandQueue queue) Acquires this buffer object for using.
void	acquireBufferForSharingNoEvent(CommandQueue queue) Acquires this buffer object for using.
void	copyTo(CommandQueue queue, Buffer dest) Alternative version of copyTo(com.jme3.opencl.CommandQueue, com.jme3.opencl.Buffer, long), sets size to this.getSize().
void	copyTo(CommandQueue queue, Buffer dest, long size) Alternative version of copyTo(com.jme3.opencl.CommandQueue, com.jme3.opencl.Buffer, long, long, long), sets srcOffset and destOffset to zero.
abstract void	copyTo(CommandQueue queue, Buffer dest, long size, long srcOffset, long destOffset) Performs a blocking copy operation from this buffer to the specified buffer.
Event	copyToAsync(CommandQueue queue, Buffer dest) Alternative version of copyToAsync(com.jme3.opencl.CommandQueue, com.jme3.opencl.Buffer, long), sets size to this.getSize().
Event	copyToAsync(CommandQueue queue, Buffer dest, long size) Alternative version of copyToAsync(com.jme3.opencl.CommandQueue, com.jme3.opencl.Buffer, long, long, long), sets srcOffset and destOffset to zero.
abstract Event	copyToAsync(CommandQueue queue, Buffer dest, long size, long srcOffset, long destOffset) Performs an async/non-blocking copy operation from this buffer to the specified buffer.
abstract Event	copyToImageAsync(CommandQueue queue, Image dest, long srcOffset, long[] destOrigin, long[] destRegion) Copies this buffer to the specified image.
abstract Event	fillAsync(CommandQueue queue, java.nio.ByteBuffer pattern, long size, long offset) Enqueues a fill operation.
abstract MemoryAccess	getMemoryAccessFlags()
abstract long	getSize()
abstract java.nio.ByteBuffer	map(CommandQueue queue, long size, long offset, MappingAccess access) Maps this buffer directly into host memory.
java.nio.ByteBuffer	map(CommandQueue queue, long size, MappingAccess access) Alternative version of map(com.jme3.opencl.CommandQueue, long, long, com.jme3.opencl.MappingAccess), sets offset to zero.
java.nio.ByteBuffer	map(CommandQueue queue, MappingAccess access) Alternative version of map(com.jme3.opencl.CommandQueue, long, com.jme3.opencl.MappingAccess), sets size to getSize().
abstract Buffer.AsyncMapping	mapAsync(CommandQueue queue, long size, long offset, MappingAccess access) Maps this buffer asynchronously into host memory.
Buffer.AsyncMapping	mapAsync(CommandQueue queue, long size, MappingAccess access) Alternative version of mapAsync(com.jme3.opencl.CommandQueue, long, long, com.jme3.opencl.MappingAccess), sets offset to zero.
Buffer.AsyncMapping	mapAsync(CommandQueue queue, MappingAccess access) Alternative version of mapAsync(com.jme3.opencl.CommandQueue, long, com.jme3.opencl.MappingAccess), sets size to getSize().
void	read(CommandQueue queue, java.nio.ByteBuffer dest) Alternative version of read(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long), sets size to getSize().
void	read(CommandQueue queue, java.nio.ByteBuffer dest, long size) Alternative version of read(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long, long), sets offset to zero.
abstract void	read(CommandQueue queue, java.nio.ByteBuffer dest, long size, long offset) Performs a blocking read of the buffer.
Event	readAsync(CommandQueue queue, java.nio.ByteBuffer dest) Alternative version of readAsync(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long), sets size to getSize()
Event	readAsync(CommandQueue queue, java.nio.ByteBuffer dest, long size) Alternative version of readAsync(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long, long), sets offset to zero.
abstract Event	readAsync(CommandQueue queue, java.nio.ByteBuffer dest, long size, long offset) Performs an async/non-blocking read of the buffer.
Buffer	register() Registers this object for automatic releasing on garbage collection.
abstract Event	releaseBufferForSharingAsync(CommandQueue queue) Releases a shared buffer object.
void	releaseBufferForSharingNoEvent(CommandQueue queue) Releases a shared buffer object.
java.lang.String	toString()
abstract void	unmap(CommandQueue queue, java.nio.ByteBuffer ptr) Unmaps a previously mapped memory.
void	write(CommandQueue queue, java.nio.ByteBuffer src) Alternative version of write(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long), sets size to getSize().
void	write(CommandQueue queue, java.nio.ByteBuffer src, long size) Alternative version of write(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long, long), sets offset to zero.
abstract void	write(CommandQueue queue, java.nio.ByteBuffer src, long size, long offset) Performs a blocking write to the buffer.
Event	writeAsync(CommandQueue queue, java.nio.ByteBuffer src) Alternative version of writeAsync(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long), sets size to getSize().
Event	writeAsync(CommandQueue queue, java.nio.ByteBuffer src, long size) Alternative version of writeAsync(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long, long), sets offset to zero.
abstract Event	writeAsync(CommandQueue queue, java.nio.ByteBuffer src, long size, long offset) Performs an async/non-blocking write to the buffer.

Methods inherited from class com.jme3.opencl.AbstractOpenCLObject

finalize, getReleaser, release

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Buffer

protected Buffer(OpenCLObject.ObjectReleaser releaser)

Method Detail

register

public Buffer register()

Description copied from interface: OpenCLObject

Registers this object for automatic releasing on garbage collection. By default, OpenCLObjects are not registered in the OpenCLObjectManager, you have to release it manually by calling OpenCLObject.release(). Without registering or releasing, a memory leak might occur.
Returns this to allow calls like Buffer buffer = clContext.createBuffer(1024).register();.

Specified by:

register in interface OpenCLObject

Overrides:

register in class AbstractOpenCLObject

Returns:

this

getSize

public abstract long getSize()

Returns:

the size of the buffer in bytes.

See Also:

Context.createBuffer(long)

getMemoryAccessFlags

public abstract MemoryAccess getMemoryAccessFlags()

Returns:

the memory access flags set on creation.

See Also:

Context.createBuffer(long, com.jme3.opencl.MemoryAccess)

read

public abstract void read(CommandQueue queue,
                          java.nio.ByteBuffer dest,
                          long size,
                          long offset)

Performs a blocking read of the buffer. The target buffer must have at least size bytes remaining. This method may set the limit to the last byte read.

Parameters:

queue - the command queue

dest - the target buffer

size - the size in bytes being read

offset - the offset in bytes in the buffer to read from

read

public void read(CommandQueue queue,
                 java.nio.ByteBuffer dest,
                 long size)

Alternative version of read(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long, long), sets offset to zero.

Parameters:

queue - the command queue

dest - the target buffer

size - the number of bytes to read

read

public void read(CommandQueue queue,
                 java.nio.ByteBuffer dest)

Alternative version of read(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long), sets size to getSize().

Parameters:

queue - the command queue

dest - the target buffer

readAsync

public abstract Event readAsync(CommandQueue queue,
                                java.nio.ByteBuffer dest,
                                long size,
                                long offset)

Performs an async/non-blocking read of the buffer. The target buffer must have at least size bytes remaining. This method may set the limit to the last byte read.

Parameters:

queue - the command queue

dest - the target buffer

size - the size in bytes being read

offset - the offset in bytes in the buffer to read from

Returns:

the event indicating when the memory has been fully read into the provided buffer

readAsync

public Event readAsync(CommandQueue queue,
                       java.nio.ByteBuffer dest,
                       long size)

Alternative version of readAsync(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long, long), sets offset to zero.

Parameters:

queue - the command queue

dest - the target buffer

size - the number of bytes to read

Returns:

an Event to indicate completion

readAsync

public Event readAsync(CommandQueue queue,
                       java.nio.ByteBuffer dest)

Alternative version of readAsync(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long), sets size to getSize()

Parameters:

queue - the command queue

dest - the target buffer

Returns:

an Event to indicate completion

write

public abstract void write(CommandQueue queue,
                           java.nio.ByteBuffer src,
                           long size,
                           long offset)

Performs a blocking write to the buffer. The target buffer must have at least size bytes remaining. This method may set the limit to the last byte that will be written.

Parameters:

queue - the command queue

src - the source buffer, its data is written to this buffer

size - the size in bytes to write

offset - the offset into the target buffer

write

public void write(CommandQueue queue,
                  java.nio.ByteBuffer src,
                  long size)

Alternative version of write(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long, long), sets offset to zero.

Parameters:

queue - the command queue

src - the source buffer, its data is written to this buffer

size - the number of bytes to write

write

public void write(CommandQueue queue,
                  java.nio.ByteBuffer src)

Alternative version of write(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long), sets size to getSize().

Parameters:

queue - the command queue

src - the source buffer, its data is written to this buffer

writeAsync

public abstract Event writeAsync(CommandQueue queue,
                                 java.nio.ByteBuffer src,
                                 long size,
                                 long offset)

Performs an async/non-blocking write to the buffer. The target buffer must have at least size bytes remaining. This method may set the limit to the last byte that will be written.

Parameters:

queue - the command queue

src - the source buffer, its data is written to this buffer

size - the size in bytes to write

offset - the offset into the target buffer

Returns:

an Event to indicate completion

writeAsync

public Event writeAsync(CommandQueue queue,
                        java.nio.ByteBuffer src,
                        long size)

Alternative version of writeAsync(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long, long), sets offset to zero.

Parameters:

queue - the command queue

src - the source buffer, its data is written to this buffer

size - the number of bytes to write

Returns:

an Event to indicate completion

writeAsync

public Event writeAsync(CommandQueue queue,
                        java.nio.ByteBuffer src)

Alternative version of writeAsync(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer, long), sets size to getSize().

Parameters:

queue - the command queue

src - the source buffer, its data is written to this buffer

Returns:

an Event to indicate completion

copyTo

public abstract void copyTo(CommandQueue queue,
                            Buffer dest,
                            long size,
                            long srcOffset,
                            long destOffset)

Performs a blocking copy operation from this buffer to the specified buffer.

Parameters:

queue - the command queue

dest - the target buffer

size - the size in bytes to copy

srcOffset - offset in bytes into this buffer

destOffset - offset in bytes into the target buffer

copyTo

public void copyTo(CommandQueue queue,
                   Buffer dest,
                   long size)

Alternative version of copyTo(com.jme3.opencl.CommandQueue, com.jme3.opencl.Buffer, long, long, long), sets srcOffset and destOffset to zero.

Parameters:

queue - the command queue

dest - the target buffer

size - the number of bytes to copy

copyTo

public void copyTo(CommandQueue queue,
                   Buffer dest)

Alternative version of copyTo(com.jme3.opencl.CommandQueue, com.jme3.opencl.Buffer, long), sets size to this.getSize().

Parameters:

queue - the command queue

dest - the target buffer

copyToAsync

public abstract Event copyToAsync(CommandQueue queue,
                                  Buffer dest,
                                  long size,
                                  long srcOffset,
                                  long destOffset)

Performs an async/non-blocking copy operation from this buffer to the specified buffer.

Parameters:

queue - the command queue

dest - the target buffer

size - the size in bytes to copy

srcOffset - offset in bytes into this buffer

destOffset - offset in bytes into the target buffer

Returns:

the event object indicating when the copy operation is finished

copyToAsync

public Event copyToAsync(CommandQueue queue,
                         Buffer dest,
                         long size)

Alternative version of copyToAsync(com.jme3.opencl.CommandQueue, com.jme3.opencl.Buffer, long, long, long), sets srcOffset and destOffset to zero.

Parameters:

queue - the command queue

dest - the target buffer

size - the number of bytes to copy

Returns:

an Event to indicate completion

copyToAsync

public Event copyToAsync(CommandQueue queue,
                         Buffer dest)

Alternative version of copyToAsync(com.jme3.opencl.CommandQueue, com.jme3.opencl.Buffer, long), sets size to this.getSize().

Parameters:

queue - the command queue

dest - the target buffer

Returns:

an Event to indicate completion

map

public abstract java.nio.ByteBuffer map(CommandQueue queue,
                                        long size,
                                        long offset,
                                        MappingAccess access)

Maps this buffer directly into host memory. This might be the fastest method to access the contents of the buffer since the OpenCL implementation directly provides the memory.
Important: The mapped memory MUST be released by calling unmap(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer).

Parameters:

queue - the command queue

size - the size in bytes to map

offset - the offset into this buffer

access - specifies the possible access to the memory: READ_ONLY, WRITE_ONLY, READ_WRITE

Returns:

the byte buffer directly reflecting the buffer contents

map

public java.nio.ByteBuffer map(CommandQueue queue,
                               long size,
                               MappingAccess access)

Alternative version of map(com.jme3.opencl.CommandQueue, long, long, com.jme3.opencl.MappingAccess), sets offset to zero. Important: The mapped memory MUST be released by calling unmap(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer).

Parameters:

queue - the command queue

size - the number of bytes to map

access - specifies the possible access to the memory: READ_ONLY, WRITE_ONLY, READ_WRITE

Returns:

the byte buffer directly reflecting the buffer contents

map

public java.nio.ByteBuffer map(CommandQueue queue,
                               MappingAccess access)

Alternative version of map(com.jme3.opencl.CommandQueue, long, com.jme3.opencl.MappingAccess), sets size to getSize(). Important: The mapped memory MUST be released by calling unmap(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer).

Parameters:

queue - the command queue

access - specifies the possible access to the memory: READ_ONLY, WRITE_ONLY, READ_WRITE

Returns:

the byte buffer directly reflecting the buffer contents

unmap

public abstract void unmap(CommandQueue queue,
                           java.nio.ByteBuffer ptr)

Unmaps a previously mapped memory. This releases the native resources and for WRITE_ONLY or READ_WRITE access, the memory content is sent back to the GPU.

Parameters:

queue - the command queue

ptr - the buffer that was previously mapped

mapAsync

public abstract Buffer.AsyncMapping mapAsync(CommandQueue queue,
                                             long size,
                                             long offset,
                                             MappingAccess access)

Maps this buffer asynchronously into host memory. This might be the fastest method to access the contents of the buffer since the OpenCL implementation directly provides the memory.
Important: The mapped memory MUST be released by calling unmap(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer).

Parameters:

queue - the command queue

size - the size in bytes to map

offset - the offset into this buffer

access - specifies the possible access to the memory: READ_ONLY, WRITE_ONLY, READ_WRITE

Returns:

the byte buffer directly reflecting the buffer contents and the event indicating when the buffer contents are available

mapAsync

public Buffer.AsyncMapping mapAsync(CommandQueue queue,
                                    long size,
                                    MappingAccess access)

Alternative version of mapAsync(com.jme3.opencl.CommandQueue, long, long, com.jme3.opencl.MappingAccess), sets offset to zero. Important: The mapped memory MUST be released by calling unmap(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer).

Parameters:

queue - the command queue

size - the size in bytes to map

access - specifies the possible access to the memory: READ_ONLY, WRITE_ONLY, READ_WRITE

Returns:

the byte buffer directly reflecting the buffer contents and the event indicating when the buffer contents are available

mapAsync

public Buffer.AsyncMapping mapAsync(CommandQueue queue,
                                    MappingAccess access)

Alternative version of mapAsync(com.jme3.opencl.CommandQueue, long, com.jme3.opencl.MappingAccess), sets size to getSize(). Important: The mapped memory MUST be released by calling unmap(com.jme3.opencl.CommandQueue, java.nio.ByteBuffer).

Parameters:

queue - the command queue

access - specifies the possible access to the memory: READ_ONLY, WRITE_ONLY, READ_WRITE

Returns:

the byte buffer directly reflecting the buffer contents and the event indicating when the buffer contents are available

fillAsync

public abstract Event fillAsync(CommandQueue queue,
                                java.nio.ByteBuffer pattern,
                                long size,
                                long offset)

Enqueues a fill operation. This method can be used to initialize or clear a buffer with a certain value.

Parameters:

queue - the command queue

pattern - the buffer containing the filling pattern. The remaining bytes specify the pattern length

size - the size in bytes to fill, must be a multiple of the pattern length

offset - the offset in bytes into the buffer, must be a multiple of the pattern length

Returns:

an event indicating when this operation is finished

copyToImageAsync

public abstract Event copyToImageAsync(CommandQueue queue,
                                       Image dest,
                                       long srcOffset,
                                       long[] destOrigin,
                                       long[] destRegion)

Copies this buffer to the specified image. Note that no format conversion is done.
For detailed description of the origin and region parameter, see the documentation of the Image class.

Parameters:

queue - the command queue

dest - the target image

srcOffset - the offset in bytes into this buffer

destOrigin - the origin of the copied area

destRegion - the size of the copied area

Returns:

the event object

acquireBufferForSharingAsync

public abstract Event acquireBufferForSharingAsync(CommandQueue queue)

Acquires this buffer object for using. Only call this method if this buffer represents a shared object from OpenGL, created with e.g. Context.bindVertexBuffer(com.jme3.scene.VertexBuffer, com.jme3.opencl.MemoryAccess). This method must be called before the buffer is used. After the work is done, the buffer must be released by calling releaseBufferForSharingAsync(com.jme3.opencl.CommandQueue) so that OpenGL can use the VertexBuffer again.

Parameters:

queue - the command queue

Returns:

the event object

acquireBufferForSharingNoEvent

public void acquireBufferForSharingNoEvent(CommandQueue queue)

Acquires this buffer object for using. Only call this method if this buffer represents a shared object from OpenGL, created with e.g. Context.bindVertexBuffer(com.jme3.scene.VertexBuffer, com.jme3.opencl.MemoryAccess). This method must be called before the buffer is used. After the work is done, the buffer must be released by calling releaseBufferForSharingAsync(com.jme3.opencl.CommandQueue) so that OpenGL can use the VertexBuffer again. The generated event object is directly released. This brings a performance improvement when the resource is e.g. directly used by a kernel afterwards on the same queue (this implicitly waits for this action). If you need the event, use acquireBufferForSharingAsync(com.jme3.opencl.CommandQueue) instead.

Parameters:

queue - the command queue

releaseBufferForSharingAsync

public abstract Event releaseBufferForSharingAsync(CommandQueue queue)

Releases a shared buffer object. Call this method after the buffer object was acquired by acquireBufferForSharingAsync(com.jme3.opencl.CommandQueue) to hand the control back to OpenGL.

Parameters:

queue - the command queue

Returns:

the event object

releaseBufferForSharingNoEvent

public void releaseBufferForSharingNoEvent(CommandQueue queue)

Releases a shared buffer object. Call this method after the buffer object was acquired by acquireBufferForSharingAsync(com.jme3.opencl.CommandQueue) to hand the control back to OpenGL. The generated event object is directly released, resulting in performance improvements.

Parameters:

queue - the command queue

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object