GoclBuffer

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

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

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

Object Hierarchy

    GObject
    ╰── GoclBuffer
        ╰── GoclImage

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_buffer_new() 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.

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 *

The context where this buffer was created.

Owner: GoclBuffer

Flags: Read / Write / Construct Only


The “flags” property

  “flags”                    guint

The flags used when creating this buffer.

Owner: GoclBuffer

Flags: Read / Write / Construct Only

Allowed values: [1,32]

Default value: 1


The “host-ptr” property

  “host-ptr”                 gpointer

The host pointer used by this buffer.

Owner: GoclBuffer

Flags: Read / Write / Construct Only


The “size” property

  “size”                     guint64

The size of this buffer.

Owner: GoclBuffer

Flags: Read / Write / Construct Only

Default value: 0