UfoBuffer

UfoBuffer — Manages and represents n-dimensional data

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── UfoBuffer

Description

Functions

UFO_BUFFER_PARAM_SPEC()

#define UFO_BUFFER_PARAM_SPEC(pspec)     (G_TYPE_CHECK_INSTANCE_CAST((pspec), UFO_TYPE_PARAM_BUFFER, UfoBufferParamSpec))

ufo_buffer_new ()

UfoBuffer *
ufo_buffer_new (UfoRequisition *requisition,
                gpointer context);

Create a new UfoBuffer.

Parameters

requisition

size requisition.

[in]

context

cl_context to use for creating the device array.

[in][allow-none]

Returns

A new UfoBuffer with the given dimensions.


ufo_buffer_new_with_size ()

UfoBuffer *
ufo_buffer_new_with_size (GList *dims,
                          gpointer context);

Create a new UfoBuffer with a list of dimensions.

Parameters

dims

size requisition.

[element-type guint]

context

cl_context to use for creating the device array.

[allow-none]

Returns

A new UfoBuffer with the given dimensions.


ufo_buffer_new_with_data ()

UfoBuffer *
ufo_buffer_new_with_data (UfoRequisition *requisition,
                          gpointer data,
                          gpointer context);

Create a new buffer using existing host memory.

Parameters

requisition

size requisition

 

data

Pointer to host memory that will be used by

 

context

OpenCL context for this buffer

 

ufo_buffer_resize ()

void
ufo_buffer_resize (UfoBuffer *buffer,
                   UfoRequisition *requisition);

Resize an existing buffer. If the new requisition has the same size as before, resizing is a no-op.

Parameters

buffer

A UfoBuffer

 

requisition

A UfoRequisition structure

 

Since: 0.2


ufo_buffer_cmp_dimensions ()

gint
ufo_buffer_cmp_dimensions (UfoBuffer *buffer,
                           UfoRequisition *requisition);

Compare the size of buffer with a given requisition .

Parameters

buffer

A UfoBuffer

 

requisition

UfoRequisition

 

Returns

value < 0, 0 or > 0 if requisition is smaller, equal or larger.


ufo_buffer_get_requisition ()

void
ufo_buffer_get_requisition (UfoBuffer *buffer,
                            UfoRequisition *requisition);

Return the size of buffer .

Parameters

buffer

A UfoBuffer

 

requisition

A location to store the requisition of buffer .

[out]

ufo_buffer_get_size ()

gsize
ufo_buffer_get_size (UfoBuffer *buffer);

Get the number of bytes of raw data that is managed by the buffer .

Parameters

buffer

A UfoBuffer

 

Returns

The size of buffer 's data.


ufo_buffer_copy ()

void
ufo_buffer_copy (UfoBuffer *src,
                 UfoBuffer *dst);

Copy contents of src to dst . The final memory location is determined by the destination buffer.

Parameters

src

Source UfoBuffer

 

dst

Destination UfoBuffer

 

ufo_buffer_dup ()

UfoBuffer *
ufo_buffer_dup (UfoBuffer *buffer);

Create a new buffer with the same requisition as buffer . Note, that this is not a copy of buffer !

Parameters

buffer

A UfoBuffer

 

Returns

A UfoBuffer with the same size as buffer .

[transfer full]


ufo_buffer_set_host_array ()

void
ufo_buffer_set_host_array (UfoBuffer *buffer,
                           gpointer array,
                           gboolean free_data);

Use this function to set a host array with a user-provided memory buffer. This is useful to expose private data of a generator filter to a subsequent consumer. Note, that the buffer *must* have an appropriate size.

Parameters

buffer

A UfoBuffer

 

array

A pointer to a float array with suitable size.

[type gulong]

free_data

TRUE if buffer is supposed to clean up the host array.

 

ufo_buffer_copy_host_array ()

void
ufo_buffer_copy_host_array (UfoBuffer *buffer,
                            gpointer array);

Copy data into the buffer.

Parameters

buffer

A UfoBuffer

 

array

A pointer to a float array with suitable size.

[type gulong]

ufo_buffer_get_host_array ()

gfloat *
ufo_buffer_get_host_array (UfoBuffer *buffer,
                           gpointer cmd_queue);

Returns a flat C-array containing the raw float data.

Parameters

buffer

A UfoBuffer.

 

cmd_queue

A cl_command_queue object or NULL.

[allow-none]

Returns

Float array.


ufo_buffer_set_device_array ()

void
ufo_buffer_set_device_array (UfoBuffer *buffer,
                             gpointer array,
                             gboolean free_data);

Set the current cl_mem object.

Parameters

buffer

A UfoBuffer.

 

array

A cl_mem object.

 

free_data

TRUE if buffer is supposed to call clReleaseMemObject on the existing device array.

 

ufo_buffer_get_device_array ()

gpointer
ufo_buffer_get_device_array (UfoBuffer *buffer,
                             gpointer cmd_queue);

Return the current cl_mem object of buffer . If the data is not yet in device memory, it is transfered via cmd_queue to the object. If cmd_queue is NULL cmd_queue , the last used command queue is used.

Parameters

buffer

A UfoBuffer.

 

cmd_queue

A cl_command_queue object or NULL.

[allow-none]

Returns

A cl_mem object associated with buffer .

[transfer none]


ufo_buffer_get_device_array_view ()

gpointer
ufo_buffer_get_device_array_view (UfoBuffer *buffer,
                                  gpointer cmd_queue,
                                  UfoRegion *region);

This method creates a new memory buffer that must be freed by the user. Moreover, the original buffer is kept intact.

Parameters

buffer

A UfoBuffer

 

cmd_queue

A cl_command_queue object

 

region

A UfoRegion specifying the view of the sub buffer

 

Returns

A newly allocated cl_mem that the user must release himself with clReleaseMemObject().

[transfer full]


ufo_buffer_get_device_image ()

gpointer
ufo_buffer_get_device_image (UfoBuffer *buffer,
                             gpointer cmd_queue);

Return the current cl_mem image object of buffer . If the data is not yet in device memory, it is transfered via cmd_queue to the object. If cmd_queue is NULL cmd_queue , the last used command queue is used.

Parameters

buffer

A UfoBuffer.

 

cmd_queue

A cl_command_queue object or NULL.

[allow-none]

Returns

A cl_mem image object associated with buffer .

[transfer none]


ufo_buffer_get_device_array_with_offset ()

gpointer
ufo_buffer_get_device_array_with_offset
                               (UfoBuffer *buffer,
                                gpointer cmd_queue,
                                gsize offset);

Creates a new cl_mem object with the given offset and a size that is the original size minus the offset.

Parameters

buffer

A UfoBuffer

 

cmd_queue

A cl_command_queue object or NULL.

[allow-none]

offset

Offset in bytes from the original buffer

 

Returns

A cl_mem sub buffer of the original data.

[transfer none]


ufo_buffer_get_location ()

UfoBufferLocation
ufo_buffer_get_location (UfoBuffer *buffer);

Return current location of data backed by buffer .

Parameters

buffer

A UfoBuffer

 

ufo_buffer_discard_location ()

void
ufo_buffer_discard_location (UfoBuffer *buffer);

Discard the current and use the last location without copying to it first.

Parameters

buffer

A UfoBuffer

 

ufo_buffer_convert ()

void
ufo_buffer_convert (UfoBuffer *buffer,
                    UfoBufferDepth depth);

Convert host data according to its depth to the internal 32-bit floating point representation.

Parameters

buffer

A UfoBuffer

 

depth

Source bit depth of host data

 

ufo_buffer_convert_from_data ()

void
ufo_buffer_convert_from_data (UfoBuffer *buffer,
                              gconstpointer data,
                              UfoBufferDepth depth);

Convert data according from depth to the internal 32-bit floating point representation.

Note: data must provide as many bytes as the buffer was initialized with.

Parameters

buffer

A UfoBuffer

 

data

Pointer to data that should be converted

 

depth

Source bit depth of host data

 

ufo_buffer_get_metadata ()

GValue *
ufo_buffer_get_metadata (UfoBuffer *buffer,
                         const gchar *name);

Retrieve meta data.

Parameters

buffer

A UfoBuffer

 

name

Name of the associated meta data

 

Returns

previously defined metadata GValue for this buffer.


ufo_buffer_set_metadata ()

void
ufo_buffer_set_metadata (UfoBuffer *buffer,
                         const gchar *name,
                         GValue *value);

Associates a key-value pair with buffer .

Parameters

buffer

A UfoBuffer

 

name

Name of the associated meta data

 

value

GValue of the meta data

 

ufo_buffer_copy_metadata ()

void
ufo_buffer_copy_metadata (UfoBuffer *src,
                          UfoBuffer *dst);

Copies meta data content from src to dst .

Parameters

src

Source buffer

 

dst

Destination buffer

 

ufo_buffer_get_metadata_keys ()

GList *
ufo_buffer_get_metadata_keys (UfoBuffer *buffer);

Get all meta data keys associated with buffer .

Parameters

buffer

A UfoBuffer

 

Returns

A GList with C strings. The content of the list owned by the buffer and should not be modified or freed. Use g_list_free() when done using the list.

[element-type utf8][transfer container]


ufo_buffer_max ()

gfloat
ufo_buffer_max (UfoBuffer *buffer,
                gpointer cmd_queue);

Return the maximum value of buffer .

Parameters

buffer

A UfoBuffer

 

cmd_queue

An OpenCL command queue or NULL

 

Returns

The maximum found.


ufo_buffer_min ()

gfloat
ufo_buffer_min (UfoBuffer *buffer,
                gpointer cmd_queue);

Return the minimum value of buffer .

Parameters

buffer

A UfoBuffer

 

cmd_queue

An OpenCL command queue or NULL

 

Returns

The minimum found.


ufo_buffer_param_spec ()

GParamSpec *
ufo_buffer_param_spec (const gchar *name,
                       const gchar *nick,
                       const gchar *blurb,
                       UfoBuffer *default_value,
                       GParamFlags flags);

Creates a new UfoBufferParamSpec instance specifying a UFO_TYPE_BUFFER property.

Parameters

name

canonical name of the property specified

 

nick

nick name for the property specified

 

blurb

description of the property specified

 

default_value

default value for the property specified

 

flags

flags for the property specified

 

Returns

a newly created parameter specification

see g_param_spec_internal() for details on property names.

[transfer none]

Types and Values

struct UfoBuffer

struct UfoBuffer;

Represents n-dimensional data. The contents of the UfoBuffer structure are private and should only be accessed via the provided API.


UFO_BUFFER_MAX_NDIMS

#define UFO_BUFFER_MAX_NDIMS 3

Maximum number of allowed dimensions. This is a pre-processor macro instead of const variable because of C constraints.


struct UfoBufferClass

struct UfoBufferClass {
};

UfoBuffer class


struct UfoBufferParamSpec

struct UfoBufferParamSpec {
};

UfoBufferParamSpec class


struct UfoRequisition

struct UfoRequisition {
    guint n_dims;
    gsize dims[UFO_BUFFER_MAX_NDIMS];
};

Used to specify buffer size requirements.

Members

guint n_dims;

Number of dimensions

 

gsize dims[UFO_BUFFER_MAX_NDIMS];

Size of dimension

 

struct UfoRegion

struct UfoRegion {
    gsize origin[UFO_BUFFER_MAX_NDIMS];
    gsize size[UFO_BUFFER_MAX_NDIMS];
};

Defines a region with at most UFO_BUFFER_MAX_NDIMS dimensions for use with ufo_buffer_get_device_array_view().

Members

gsize origin[UFO_BUFFER_MAX_NDIMS];

n-dimensional origin of the region

 

gsize size[UFO_BUFFER_MAX_NDIMS];

n-dimensional size of the region

 

enum UfoBufferDepth

Source depth of data as used in ufo_buffer_convert().

Members

UFO_BUFFER_DEPTH_8U

8 bit unsigned

 

UFO_BUFFER_DEPTH_16U

16 bit unsigned

 

UFO_BUFFER_DEPTH_16S

16 bit signed

 

UFO_BUFFER_DEPTH_32S

32 bit signed

 

UFO_BUFFER_DEPTH_32U

32 bit unsigned

 

UFO_BUFFER_DEPTH_32F

32 bit float

 

enum UfoBufferLocation

Location of the backed data memory.

Members

UFO_BUFFER_LOCATION_HOST

Data is located in main memory

 

UFO_BUFFER_LOCATION_DEVICE

Data is located in regular device memory

 

UFO_BUFFER_LOCATION_DEVICE_IMAGE

Data is located in image device memory

 

UFO_BUFFER_LOCATION_INVALID

There is currently no data associated with the buffer