GoclContext

GoclContext — Object that represents an OpenCL context

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

guint device-type Read / Write / Construct Only
gpointer gl-context Read / Write / Construct Only
gpointer gl-display Read / Write / Construct Only

Object Hierarchy

    GObject
    ╰── GoclContext

Description

A GoclContext enables access to OpenCL objects such as devices, command queues, buffers, programs, kernels, etc. Obtaining a GoclContext is always the first step an OpenCL application performs.

A GoclContext can be created with gocl_context_new_sync(), providing the type of device which is a value from GoclDeviceType. For convenience, the methods gocl_context_get_default_cpu_sync() and gocl_context_get_default_gpu_sync() are provided to easily retrieve pre-created CPU and GPU contexts, respectively.

For GPU devices, it is possible to share object with existing OpenGL contexts if the <i>cl_khr_gl_sharing</i> extension is supported. To enable this support, gocl_context_gpu_new_sync() is used, passing the pointers to the corresponding GL context and display.

Once a context is successfully created, devices can be obtained by calling gocl_context_get_device_by_index(), where index must be a value between 0 and the maximum number of devices in the context, minus one. Number of devices can be obtained with gocl_context_get_num_devices().

Functions

gocl_context_new_sync ()

GoclContext *
gocl_context_new_sync (GoclDeviceType device_type);

Attempts to create a GoclContext of the type specified in device_type . Upon error, NULL is returned. On success, a new GoclContext object is returned.

Parameters

device_type

A value from GoclDeviceType

 

Returns

A newly created GoclContext.

[transfer full]


gocl_context_gpu_new_sync ()

GoclContext *
gocl_context_gpu_new_sync (gpointer gl_context,
                           gpointer gl_display);

Attemps to create a new GPU context. If gl_context and gl_display are provided (not NULL), then the context will be setup to share objects with an existing OpenGL context. For this to work, the

<i>cl_khr_gl_sharing</i> extension should be supported by the OpenCL

GPU implementation.

Parameters

gl_context

A GL context, or NULL.

[allow-none]

gl_display

A GL display, or NULL.

[allow-none]

Returns

A GoclContext object, or NULL on error.

[transfer full]


gocl_context_get_default_cpu_sync ()

GoclContext *
gocl_context_get_default_cpu_sync (void);

Returns platform's default CPU context. The first call to this method will attempt to create a new GoclContext using a device type of GOCL_DEVICE_TYPE_CPU. Upon success, the context is cached and subsequent calls will return the same object, increasing its reference count.

Returns

A GoclContext object, or NULL on error.

[transfer full]


gocl_context_get_default_gpu_sync ()

GoclContext *
gocl_context_get_default_gpu_sync (void);

Returns platform's default GPU context. The first call to this method will attempt to create a new GoclContext using a device type of GOCL_DEVICE_TYPE_GPU. Upon success, the context is cached and subsequent calls will return the same object, increasing its reference count.

Returns

A GoclContext object, or NULL on error.

[transfer full]


gocl_context_get_num_devices ()

guint
gocl_context_get_num_devices (GoclContext *self);

Obtains the number of devices in this context. Calls to gocl_context_get_device_by_index() must provide a device index between 0 and the number of devices returned by this method, minus one.

Parameters

self

The GoclContext

 

Returns

The number of devices


gocl_context_get_device_by_index ()

GoclDevice *
gocl_context_get_device_by_index (GoclContext *self,
                                  guint device_index);

Retrieves the device_index -th device from the list of context devices. Use gocl_context_get_num_devices() to get the number of devices in the context.

Notice that method creates a new GoclDevice instance every time is called.

Parameters

self

The GoclContext

 

device_index

The index of the device to retrieve

 

Returns

A newly created GoclDevice.

[transfer full]


gocl_device_get_context ()

GoclContext *
gocl_device_get_context (GoclDevice *device);

Obtains the GoclContext the device belongs to.

Parameters

device

The GoclDevice

 

Returns

A GoclContext. The returned object is owned by the device, do not free.

[transfer none]


gocl_buffer_new ()

GoclBuffer *
gocl_buffer_new (GoclContext *context,
                 guint flags,
                 gsize size,
                 gpointer host_ptr);

Creates a new buffer on context's memory. Depending on flags, the host_ptr pointer can be used to initialize the contents of the buffer from a block of memory in the host.

Parameters

context

A GoclContext to attach the buffer to

 

flags

An OR'ed combination of values from GoclBufferFlags

 

size

The size of the buffer, in bytes

 

host_ptr

A pointer to memory in the host system, or NULL.

[allow-none][type guint64]

Returns

A newly created GoclBuffer, or NULL on error.

[transfer full]


gocl_buffer_get_context ()

GoclContext *
gocl_buffer_get_context (GoclBuffer *buffer);

Retrieves the GoclContext the buffer belongs to.

Parameters

buffer

The GoclBuffer

 

Returns

A GoclContext object.

[transfer none]


gocl_image_new ()

GoclImage *
gocl_image_new (GoclContext *context,
                guint flags,
                gpointer host_ptr,
                GoclImageType type,
                gsize width,
                gsize height,
                gsize depth);

Creates a new image buffer. Currently only 8-bits unsigned integer format is supported, with RGBA channels. Other image properties like row pitch, slice pitch, etc. are assumed to be zero by now.

Parameters

context

The GoclContext to create the image in

 

flags

An OR'ed combination of values from GoclBufferFlags

 

host_ptr

Pointer to host memory, or NULL.

[allow-none]

type

Image type value from GoclImageType

 

width

Image width in pixels

 

height

Image height in pixels, zero if image type is 1D

 

depth

Image depth in pixels, or zero if image is not 3D

 

Returns

A newly created GoclImage, or NULL on error.

[transfer full]


gocl_image_new_from_gl_texture ()

GoclImage *
gocl_image_new_from_gl_texture (GoclContext *context,
                                guint flags,
                                guint texture);

Creates a new image buffer from a GL texture handle. This only works if the OpenCL platform supports the <i>cl_khr_gl_sharing</i> extension, and the context has been created for sharing with OpenGL, using gocl_context_gpu_new_sync().

Parameters

context

The GoclContext to create the image in

 

flags

An OR'ed combination of values from GoclBufferFlags

 

texture

The GL texture handle

 

Returns

A newly created GoclImage, or NULL on error.

[transfer full]


gocl_image_new_from_cogl_texture ()

GoclImage *
gocl_image_new_from_cogl_texture (GoclContext *context,
                                  guint flags,
                                  CoglTexture *texture);

Creates a new image buffer from a CoglTexture object. This only works if the OpenCL platform supports the <i>cl_khr_gl_sharing</i> extension, and the context has been created for sharing with OpenGL, using gocl_context_gpu_new_sync().

Parameters

context

The GoclContext to create the image in

 

flags

An OR'ed combination of values from GoclBufferFlags

 

texture

The CoglTexture

 

Returns

A newly created GoclImage, or NULL on error.

[transfer full]

Property Details

The “device-type” property

  “device-type”              guint

The device type for this context.

Owner: GoclContext

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 1


The “gl-context” property

  “gl-context”               gpointer

The GL context for data sharing.

Owner: GoclContext

Flags: Read / Write / Construct Only


The “gl-display” property

  “gl-display”               gpointer

The GL display for data sharing.

Owner: GoclContext

Flags: Read / Write / Construct Only