ClutterImage: Clutter Reference Manual

## ClutterImage ClutterImage — Image data content |

## Functions

#define | CLUTTER_IMAGE_ERROR
ClutterContent * | clutter_image_new ()
gboolean | clutter_image_set_data ()
gboolean | clutter_image_set_bytes ()
gboolean | clutter_image_set_area ()
CoglTexture * | clutter_image_get_texture ()

## Types and Values

struct | ClutterImage
struct | ClutterImageClass
enum | ClutterImageError

## Object Hierarchy

        GObject
        ╰── ClutterImage

## Implemented Interfaces

ClutterImage implements ClutterContent.

## Description

ClutterImage is a ClutterContent implementation that displays image data inside a ClutterActor.

See image.c for an example of how to use ClutterImage.

ClutterImage is available since Clutter 1.10.

## Functions

### CLUTTER_IMAGE_ERROR

    #define CLUTTER_IMAGE_ERROR             (clutter_image_error_quark ())

Error domain for the ClutterImageError enumeration.

Since: 1.10

### clutter_image_new ()

    ClutterContent *
    clutter_image_new (void);

Creates a new ClutterImage instance.

#### Returns

the newly created ClutterImage instance. Use `g_object_unref()` when done.

[transfer full]

Since: 1.10

### clutter_image_set_data ()

    gboolean
    clutter_image_set_data (ClutterImage *image,
                            const guint8 *data,
                            CoglPixelFormat pixel_format,
                            guint width,
                            guint height,
                            guint row_stride,
                            GError **error);

Sets the image data to be displayed by `image` .

If the image data was successfully loaded, the `image` will be invalidated.

In case of error, the `error` value will be set, and this function will return `FALSE`.

The image data is copied in texture memory.

The image data is expected to be a linear array of RGBA or RGB pixel data; how to retrieve that data is left to platform specific image loaders. For instance, if you use the GdkPixbuf library:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    ClutterContent *image = clutter_image_new ();

    GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file (filename, NULL);

    clutter_image_set_data (CLUTTER_IMAGE (image),
                            gdk_pixbuf_get_pixels (pixbuf),
                            gdk_pixbuf_get_has_alpha (pixbuf)
                              ? COGL_PIXEL_FORMAT_RGBA_8888
                              : COGL_PIXEL_FORMAT_RGB_888,
                            gdk_pixbuf_get_width (pixbuf),
                            gdk_pixbuf_get_height (pixbuf),
                            gdk_pixbuf_get_rowstride (pixbuf),
                            &error);

    g_object_unref (pixbuf);

#### Parameters

image | a ClutterImage |
data | the image data, as an array of bytes. | [array]
pixel_format | the Cogl pixel format of the image data |
width | the width of the image data |
height | the height of the image data |
row_stride | the length of each row inside `data` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the image data was successfully loaded, and `FALSE` otherwise.

Since: 1.10

### clutter_image_set_bytes ()

    gboolean
    clutter_image_set_bytes (ClutterImage *image,
                             GBytes *data,
                             CoglPixelFormat pixel_format,
                             guint width,
                             guint height,
                             guint row_stride,
                             GError **error);

Sets the image data stored inside a GBytes to be displayed by `image` .

If the image data was successfully loaded, the `image` will be invalidated.

In case of error, the `error` value will be set, and this function will return `FALSE`.

The image data contained inside the GBytes is copied in texture memory, and no additional reference is acquired on the `data` .

#### Parameters

image | a ClutterImage |
data | the image data, as a GBytes |
pixel_format | the Cogl pixel format of the image data |
width | the width of the image data |
height | the height of the image data |
row_stride | the length of each row inside `data` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the image data was successfully loaded, and `FALSE` otherwise.

Since: 1.12

### clutter_image_set_area ()

    gboolean
    clutter_image_set_area (ClutterImage *image,
                            const guint8 *data,
                            CoglPixelFormat pixel_format,
                            const cairo_rectangle_int_t *rect,
                            guint row_stride,
                            GError **error);

Sets the image data to be display by `image` , using `rect` to indicate the position and size of the image data to be set.

If the `image` does not have any image data set when this function is called, a new texture will be created with the size of the width and height of the rectangle, i.e. calling this function on a newly created ClutterImage will be the equivalent of calling `clutter_image_set_data()`.

If the image data was successfully loaded, the `image` will be invalidated.

In case of error, the `error` value will be set, and this function will return `FALSE`.

The image data is copied in texture memory.

#### Parameters

image | a ClutterImage |
data | the image data, as an array of bytes. | [array]
pixel_format | the Cogl pixel format of the image data |
rect | a rectangle indicating the area that should be set |
row_stride | the length of each row inside `data` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the image data was successfully loaded, and `FALSE` otherwise.

Since: 1.10

### clutter_image_get_texture ()

    CoglTexture *
    clutter_image_get_texture (ClutterImage *image);

Retrieves a pointer to the Cogl texture used by `image` .

If you change the contents of the returned Cogl texture you will need to manually invalidate the `image` with `clutter_content_invalidate()` in order to update the actors using `image` as their content.

#### Parameters

image | a ClutterImage |

#### Returns

a pointer to the Cogl texture, or `NULL`.

[transfer none]

Since: 1.10

Stability Level: Unstable

## Types and Values

### struct ClutterImage

    struct ClutterImage;

The ClutterImage structure contains private data and should only be accessed using the provided API.

Since: 1.10

### struct ClutterImageClass

    struct ClutterImageClass {
    };

The ClutterImageClass structure contains private data.

Since: 1.10

### enum ClutterImageError

Error enumeration for ClutterImage.

#### Members

CLUTTER_IMAGE_ERROR_INVALID_DATA | Invalid data passed to the `clutter_image_set_data()` function. |

Since: 1.10