GoclBuffer

GoclBuffer — Object that represents a block of memory in an OpenCL context

Stability Level

Unstable, unless otherwise indicated

Synopsis

struct              GoclBuffer;
struct              GoclBufferClass;
cl_mem              gocl_buffer_get_buffer              (GoclBuffer *self);
GoclEvent *         gocl_buffer_read                    (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         gpointer target_ptr,
                                                         gsize size,
                                                         goffset offset,
                                                         GList *event_wait_list);
gboolean            gocl_buffer_read_sync               (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         gpointer target_ptr,
                                                         gsize size,
                                                         goffset offset,
                                                         GList *event_wait_list);
GoclEvent *         gocl_buffer_write                   (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         const gpointer data,
                                                         gsize size,
                                                         goffset offset,
                                                         GList *event_wait_list);
gboolean            gocl_buffer_write_sync              (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         const gpointer data,
                                                         gsize size,
                                                         goffset offset,
                                                         GList *event_wait_list);
gboolean            gocl_buffer_read_all_sync           (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         gpointer target_ptr,
                                                         gsize *size,
                                                         GList *event_wait_list);
cl_mem *            gocl_buffer_list_to_array           (GList *list,
                                                         guint *len);

Object Hierarchy

  GObject
   +----GoclBuffer
         +----GoclImage

Implemented Interfaces

GoclBuffer implements GInitable.

Properties

  "context"                  GoclContext*          : Read / Write / Construct Only
  "flags"                    guint                 : Read / Write / Construct Only
  "host-ptr"                 gpointer              : Read / Write / Construct Only
  "size"                     guint64               : Read / Write / Construct Only

Description

A GoclBuffer represents a buffer object in an OpenCL context. These objects are directly accessible from OpenCL programs.

Buffers are created from a GoclContext, by calling gocl_context_create_buffer() method. It is possible to initialize the contents of the buffer upon creating, by specifying a block of host memory to copy data from, and the appropriate flag from GoclBufferFlags. Also, buffers can be initialized at any time by calling gocl_buffer_write() or gocl_buffer_write_sync().

To read data from a buffer into host memory, gocl_buffer_read() and gocl_buffer_read_sync() methods are provided. These are normally used after the execution of a kernel that affected the contents of the buffer.

Both gocl_buffer_write_sync() and gocl_buffer_read_sync() block program execution, while gocl_buffer_write() and gocl_buffer_read() are asynchronous versions and safe to call from the application's main loop.

Details

struct GoclBuffer

struct GoclBuffer;

struct GoclBufferClass

struct GoclBufferClass {
  GObjectClass parent_class;

  /* virtual methods */
  cl_int (* create_cl_mem) (GoclBuffer  *self,
                            cl_context   context,
                            cl_mem      *obj,
                            guint        flags,
                            gsize        size,
                            gpointer     host_ptr);
  cl_int   (* read_all)    (GoclBuffer          *self,
                            cl_mem               buffer,
                            cl_command_queue     queue,
                            gpointer             target_ptr,
                            gsize               *size,
                            gboolean             blocking,
                            cl_event            *event_wait_list,
                            guint                event_wait_list_len,
                            cl_event            *out_event);
};

The class for GoclBuffer objects.

GObjectClass parent_class;

 The parent class

create_cl_mem ()

read_all ()

gocl_buffer_get_buffer ()

cl_mem              gocl_buffer_get_buffer              (GoclBuffer *self);

Retrieves the internal OpenCL cl_mem object. This is not normally called by applications. It is rather a low-level, internal API.

self :

 The GoclBuffer

Returns :

 The internal cl_mem object. [type guint64][transfer none]

gocl_buffer_read ()

GoclEvent *         gocl_buffer_read                    (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         gpointer target_ptr,
                                                         gsize size,
                                                         goffset offset,
                                                         GList *event_wait_list);

Asynchronously reads a block of data of size bytes from remote context into host memory, starting at offset. The operation is enqueued in queue, and the program execution continues without blocking. For a synchronous version of this methid, see gocl_buffer_read_sync().

A GoclEvent is returned so that the application can get notified when the operation finishes, by calling gocl_event_then(). Also, the returned event can be added to the event_wait_list argument of other operations, to synchronize their execution with the completion of this operation.

If event_wait_list is provided, the read operation will start only when all the GoclEvent in the list have triggered.

self :

 The GoclBuffer

queue :

 A GoclQueue where the operation will be enqueued

target_ptr :

 The pointer to copy the data to. [array length=size][element-type guint8]

size :

 The size of the data to be read

offset :

 The offset to start reading from

event_wait_list :

 List or GoclEvent object to wait for, or NULL. [element-type Gocl.Event][allow-none]

Returns :

 A GoclEvent to get notified when the read operation finishes. [transfer none]

gocl_buffer_read_sync ()

gboolean            gocl_buffer_read_sync               (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         gpointer target_ptr,
                                                         gsize size,
                                                         goffset offset,
                                                         GList *event_wait_list);

Reads a block of data of size bytes from remote context into host memory, starting at offset. The operation is actually enqueued in queue, and the program execution blocks until the read finishes. If event_wait_list is provided, the read operation will start only when all the GoclEvent in the list have triggered.

self :

 The GoclBuffer

queue :

 A GoclQueue where the operation will be enqueued

target_ptr :

 The pointer to copy the data to. [array length=size][element-type guint8]

size :

 The size of the data to be read

offset :

 The offset to start reading from

event_wait_list :

 List or GoclEvent object to wait for, or NULL. [element-type Gocl.Event][allow-none]

Returns :

 TRUE on success, FALSE on error

gocl_buffer_write ()

GoclEvent *         gocl_buffer_write                   (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         const gpointer data,
                                                         gsize size,
                                                         goffset offset,
                                                         GList *event_wait_list);

Asynchronously writes a block of data of size bytes from host memory into remote context, starting at offset. The operation is enqueued in queue, and the program execution continues without blocking. For a synchronous version of this methid, see gocl_buffer_write_sync().

A GoclEvent is returned so that the application can get notified when the operation finishes, by calling gocl_event_then(). Also, the returned event can be added to the event_wait_list argument of other operations, to synchronize their execution with the completion of this operation.

If event_wait_list is provided, the write operation will start only when all the GoclEvent in the list have triggered.

self :

 The GoclBuffer

queue :

 A GoclQueue where the operation will be enqueued

data :

 A pointer to write data from

size :

 The size of the data to be written

offset :

 The offset to start writing data to

event_wait_list :

 List or GoclEvent object to wait for, or NULL. [element-type Gocl.Event][allow-none]

Returns :

 A GoclEvent to get notified when the write operation finishes. [transfer none]

gocl_buffer_write_sync ()

gboolean            gocl_buffer_write_sync              (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         const gpointer data,
                                                         gsize size,
                                                         goffset offset,
                                                         GList *event_wait_list);

Writes a block of data of size bytes from host memory into remote context memory, starting at offset. The operation is actually enqueued in queue, and the program execution blocks until the read finishes. If event_wait_list is provided, the read operation will start only when all the GoclEvent in the list have triggered.

self :

 The GoclBuffer

queue :

 A GoclQueue where the operation will be enqueued

data :

 A pointer to write data from

size :

 The size of the data to be written

offset :

 The offset to start writing data to

event_wait_list :

 List or GoclEvent object to wait for, or NULL. [element-type Gocl.Event][allow-none]

Returns :

 TRUE on success, FALSE on error

gocl_buffer_read_all_sync ()

gboolean            gocl_buffer_read_all_sync           (GoclBuffer *self,
                                                         GoclQueue *queue,
                                                         gpointer target_ptr,
                                                         gsize *size,
                                                         GList *event_wait_list);

Reads all the data in buffer from remote context into the host memory referenced by target_ptr. The operation is enqueued in queue, and the program execution blocks until the read finishes.

If size is not NULL, it will store the total size read.

If event_wait_list is provided, the read operation will start only when all the GoclEvent in the list have triggered.

self :

 The GoclBuffer

queue :

 A GoclQueue where the operation will be enqueued

target_ptr :

 The pointer to copy the data to. [array length=size][element-type guint8][allow-none]

size :

 A pointer to retrieve the size of the buffer, or NULL. [out][allow-none]

event_wait_list :

 List or GoclEvent object to wait for, or NULL. [element-type Gocl.Event][allow-none]

Returns :

 TRUE on success, FALSE on error

gocl_buffer_list_to_array ()

cl_mem *            gocl_buffer_list_to_array           (GList *list,
                                                         guint *len);

A convenient method to retrieve a GList of GoclBuffer's as an array of cl_mem's corresponding to the internal objects of each GoclBuffer in the GList. This is a rather low-level method and should not normally be called by applications.

list :

 A GList containing GoclBuffer objects. [element-type Gocl.Buffer][allow-none]

len :

 A pointer to a value to retrieve list length. [out][allow-none]

Returns :

 An array of cl_mem objects. Free with g_free(). [transfer container][array length=len]

Property Details

The "context" property

  "context"                  GoclContext*          : Read / Write / Construct Only

The context where this buffer was created.

The "flags" property

  "flags"                    guint                 : Read / Write / Construct Only

The flags used when creating this buffer.

Allowed values: [1,32]

Default value: 1

The "host-ptr" property

  "host-ptr"                 gpointer              : Read / Write / Construct Only

The host pointer used by this buffer.

The "size" property

  "size"                     guint64               : Read / Write / Construct Only

The size of this buffer.

Default value: 0

Generated by GTK-Doc V1.19