Buffer (jMonkeyEngine3)

java.lang.Object
- com.jme3.opencl.AbstractOpenCLObject
- - com.jme3.opencl.Buffer

All Implemented Interfaces:

OpenCLObject

Direct Known Subclasses:

JoclBuffer, 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 sychronized/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

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.

Field Summary
- Fields inherited from class com.jme3.opencl.AbstractOpenCLObject
  releaser

Constructor Summary

Constructors
Modifier Constructor and Description

protected Buffer(OpenCLObject.ObjectReleaser releaser)

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

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract Event`	`acquireBufferForSharingAsync(CommandQueue queue)` Aquires this buffer object for using.
`void`	`acquireBufferForSharingNoEvent(CommandQueue queue)` Aquires 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.
  - 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().
  - 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.
  - 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()
  - 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.
  - 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().
  - 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:
    
    the event object indicating when the write operation is completed
  - 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.
  - 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().
  - 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.
  - 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().
  - 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.
  - 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().
  - 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).
  - 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).
  - 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).
  - 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).
  - 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 paramenter, 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)
```
    Aquires 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)
```
    Aquires 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

Class Buffer

Nested Class Summary

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

Field Summary

Fields inherited from class com.jme3.opencl.AbstractOpenCLObject

Constructor Summary

Method Summary

Methods inherited from class com.jme3.opencl.AbstractOpenCLObject

Methods inherited from class java.lang.Object

Constructor Detail

Buffer

Method Detail

register

getSize

getMemoryAccessFlags

read

read

read

readAsync

readAsync

readAsync

write

write

write

writeAsync

writeAsync

writeAsync

copyTo

copyTo

copyTo

copyToAsync

copyToAsync

copyToAsync

map

map

map

unmap

mapAsync

mapAsync

mapAsync

fillAsync

copyToImageAsync

acquireBufferForSharingAsync

acquireBufferForSharingNoEvent

releaseBufferForSharingAsync

releaseBufferForSharingNoEvent

toString