com.nativelibs4java.opencl

Class CLMem

java.lang.Object

com.nativelibs4java.opencl.CLMem

Direct Known Subclasses:

CLBuffer, CLImage

public abstract class CLMem
extends Object

OpenCL memory object.
Memory objects are categorized into two types: buffer objects, and image objects.
A buffer object stores a one-dimensional collection of elements whereas an image object is used to store a two- or three- dimensional texture, frame-buffer or image.
Elements of a buffer object can be a scalar data type (such as an int, float), vector data type, or a user-defined structure. An image object is used to represent a buffer that can be used as a texture or a frame-buffer. The elements of an image object are selected from a list of predefined image formats.
The minimum number of elements in a memory object is one.
The fundamental differences between a buffer and an image object are:

• Elements in a buffer are stored in sequential fashion and can be accessed using a pointer by a kernel executing on a device. Elements of an image are stored in a format that is opaque to the user and cannot be directly accessed using a pointer. Built-in functions are provided by the OpenCL C programming language to allow a kernel to read from or write to an image.
• For a buffer object, the data is stored in the same format as it is accessed by the kernel, but in the case of an image object the data format used to store the image elements may not be the same as the data format used inside the kernel. Image elements are always a 4- component vector (each component can be a float or signed/unsigned integer) in a kernel. The built-in function to read from an image converts image element from the format it is stored into a 4-component vector. Similarly, the built-in function to write to an image converts the image element from a 4-component vector to the appropriate image format specified such as 4 8-bit elements, for example.

Kernels take memory objects as input, and output to one or more memory objects.

Author:

Olivier Chafik

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	CLMem.DestructorCallback
static class	CLMem.Flags
static class	CLMem.GLObjectInfo
static class	CLMem.GLObjectType
static class	CLMem.MapFlags
static class	CLMem.Migration Memory object migration options (see CLQueue#enqueueMigrateMemObjects(CLMem[], java.lang.EnumSet, CLEvent[])).
static class	CLMem.ObjectType
static class	CLMem.Usage Memory Object Usage enum

Method Summary

Modifier and Type	Method and Description
CLEvent	acquireGLObject(CLQueue queue, CLEvent... eventsToWaitFor)
boolean	equals(Object obj) Underyling implementation pointer-based equality test
long	getByteCount() Get the actual size of the memory object in bytes
CLContext	getContext()
static <E extends TypedPointer,A extends com.nativelibs4java.opencl.CLAbstractEntity> Pointer<E>	getEntities(A[] objects, Pointer<E> out)
CLMem.GLObjectInfo	getGLObjectInfo() Calls clGetGLObjectInfo.
int	hashCode() Underyling implementation pointer-based hashCode computation
void	release() Manual release of the OpenCL resources represented by this object.
CLEvent	releaseGLObject(CLQueue queue, CLEvent... eventsToWaitFor)
void	setDestructorCallback(CLMem.DestructorCallback callback) Calls clSetMemObjectDestructorCallback.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

getContext

public CLContext getContext()

setDestructorCallback

public void setDestructorCallback(CLMem.DestructorCallback callback)

Calls clSetMemObjectDestructorCallback.
Registers a user callback function that will be called when the memory object is deleted and its resources freed.
Each call to clSetMemObjectDestructorCallback registers the specified user callback function on a callback stack associated with memobj.
The registered user callback functions are called in the reverse order in which they were registered.
The user callback functions are called and then the memory object's resources are freed and the memory object is deleted.
This provides a mechanism for the application (and libraries) using memobj to be notified when the memory referenced by host_ptr, specified when the memory object is created and used as the storage bits for the memory object, can be reused or freed.

Parameters:

callback -

Since:

OpenCL 1.1

acquireGLObject

public CLEvent acquireGLObject(CLQueue queue,
                               CLEvent... eventsToWaitFor)

releaseGLObject

public CLEvent releaseGLObject(CLQueue queue,
                               CLEvent... eventsToWaitFor)

getByteCount

public long getByteCount()

Get the actual size of the memory object in bytes

Returns:

actual size of the memory object in bytes

getGLObjectInfo

public CLMem.GLObjectInfo getGLObjectInfo()

Calls clGetGLObjectInfo.

release

public void release()

Manual release of the OpenCL resources represented by this object.
Note that resources are automatically released by the garbage collector, so in general there's no need to call this method.
In an environment with fast allocation/deallocation of large objects, it might be safer to call release() manually, though.
Note that release() does not necessarily free the object immediately : OpenCL maintains a reference count for all its objects, and an object released on the Java side might still be pointed to by running kernels or queued operations.

getEntities

public static <E extends TypedPointer,A extends com.nativelibs4java.opencl.CLAbstractEntity> Pointer<E> getEntities(A[] objects,
                                                                                                                    Pointer<E> out)

hashCode

public int hashCode()

Underyling implementation pointer-based hashCode computation

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Underyling implementation pointer-based equality test

Overrides:

equals in class Object