## UfoBuffer

UfoBuffer — Manages and represents n-dimensional data

## Functions

#define | UFO_BUFFER_PARAM_SPEC()
UfoBuffer * | ufo_buffer_new ()
UfoBuffer * | ufo_buffer_new_with_size ()
UfoBuffer * | ufo_buffer_new_with_data ()
void | ufo_buffer_resize ()
gint | ufo_buffer_cmp_dimensions ()
void | ufo_buffer_get_requisition ()
gsize | ufo_buffer_get_size ()
void | ufo_buffer_copy ()
UfoBuffer * | ufo_buffer_dup ()
void | ufo_buffer_swap_data ()
void | ufo_buffer_set_host_array ()
void | ufo_buffer_copy_host_array ()
gfloat * | ufo_buffer_get_host_array ()
void | ufo_buffer_set_device_array ()
gpointer | ufo_buffer_get_device_array ()
gpointer | ufo_buffer_get_device_array_view ()
gpointer | ufo_buffer_get_device_image ()
gpointer | ufo_buffer_get_device_array_with_offset ()
UfoBufferLocation | ufo_buffer_get_location ()
void | ufo_buffer_discard_location ()
void | ufo_buffer_set_layout ()
UfoBufferLayout | ufo_buffer_get_layout ()
void | ufo_buffer_convert ()
void | ufo_buffer_convert_from_data ()
GValue * | ufo_buffer_get_metadata ()
void | ufo_buffer_set_metadata ()
void | ufo_buffer_copy_metadata ()
GList * | ufo_buffer_get_metadata_keys ()
gfloat | ufo_buffer_max ()
gfloat | ufo_buffer_min ()
GParamSpec * | ufo_buffer_param_spec ()

## Types and Values

struct | UfoBuffer
#define | UFO_BUFFER_MAX_NDIMS
struct | UfoBufferClass
struct | UfoBufferParamSpec
struct | UfoRequisition
struct | UfoRegion
enum | UfoBufferDepth
enum | UfoBufferLocation
enum | UfoBufferLayout

## 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 |