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_swap_data ()

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

Swap the *content* of the two buffers if possible (i.e. data resides on the same memory type) or copy from src to dst otherwise.

Parameters

src

Buffer to receive data from dst

 

dst

Buffer to receive data from src

 

Since: 0.16


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_set_layout ()

void
ufo_buffer_set_layout (UfoBuffer *buffer,
                       UfoBufferLayout layout);

Set layout of the buffer.

Parameters

buffer

A UfoBuffer

 

layout

Layout of the currently residing data

 

ufo_buffer_get_layout ()

UfoBufferLayout
ufo_buffer_get_layout (UfoBuffer *buffer);

Return current layout of buffer .

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_INVALID

default for unknown/unset values

 

UFO_BUFFER_DEPTH_8U

8 bit unsigned

 

UFO_BUFFER_DEPTH_12U

12 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

 

enum UfoBufferLayout

Layout of the backed data memory.

Members

UFO_BUFFER_LAYOUT_REAL

Float values are real numbers

 

UFO_BUFFER_LAYOUT_COMPLEX_INTERLEAVED

Two adjacent float values make up a complex value