Clutter Reference Manual: ClutterImage

## ClutterImage ClutterImage — Image data content |

## Synopsis

    struct              ClutterImage;
    struct              ClutterImageClass;
    #define             CLUTTER_IMAGE_ERROR
    enum                ClutterImageError;
    ClutterContent *    clutter_image_new                   (void);
    gboolean            clutter_image_set_data              (ClutterImage *image,
                                                             const guint8 *data,
                                                             CoglPixelFormat pixel_format,
                                                             guint width,
                                                             guint height,
                                                             guint row_stride,
                                                             GError **error);
    gboolean            clutter_image_set_bytes             (ClutterImage *image,
                                                             GBytes *data,
                                                             CoglPixelFormat pixel_format,
                                                             guint width,
                                                             guint height,
                                                             guint row_stride,
                                                             GError **error);
    gboolean            clutter_image_set_area              (ClutterImage *image,
                                                             const guint8 *data,
                                                             CoglPixelFormat pixel_format,
                                                             const cairo_rectangle_int_t *rect,
                                                             guint row_stride,
                                                             GError **error);
    CoglTexture *       clutter_image_get_texture           (ClutterImage *image);

## Object Hierarchy

      GObject
       +----ClutterImage

## Implemented Interfaces

ClutterImage implements ClutterContent.

## Description

ClutterImage is a ClutterContent implementation that displays image data.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    #include <stdlib.h>
    #include <gdk-pixbuf/gdk-pixbuf.h>
    #include <clutter/clutter.h>

    static const struct {
      ClutterContentGravity gravity;
      const char *name;
    } gravities[] = {
      { CLUTTER_CONTENT_GRAVITY_TOP_LEFT, "Top Left" },
      { CLUTTER_CONTENT_GRAVITY_TOP, "Top" },
      { CLUTTER_CONTENT_GRAVITY_TOP_RIGHT, "Top Right" },

      { CLUTTER_CONTENT_GRAVITY_LEFT, "Left" },
      { CLUTTER_CONTENT_GRAVITY_CENTER, "Center" },
      { CLUTTER_CONTENT_GRAVITY_RIGHT, "Right" },

      { CLUTTER_CONTENT_GRAVITY_BOTTOM_LEFT, "Bottom Left" },
      { CLUTTER_CONTENT_GRAVITY_BOTTOM, "Bottom" },
      { CLUTTER_CONTENT_GRAVITY_BOTTOM_RIGHT, "Bottom Right" },

      { CLUTTER_CONTENT_GRAVITY_RESIZE_FILL, "Resize Fill" },
      { CLUTTER_CONTENT_GRAVITY_RESIZE_ASPECT, "Resize Aspect" },
    };

    static int n_gravities = G_N_ELEMENTS (gravities);
    static int cur_gravity = 0;

    static void
    on_tap (ClutterTapAction *action,
            ClutterActor     *actor,
            ClutterText      *label)
    {
      gchar *str;

      clutter_actor_save_easing_state (actor);
      clutter_actor_set_content_gravity (actor, gravities[cur_gravity].gravity);
      clutter_actor_restore_easing_state (actor);

      str = g_strconcat ("Content gravity: ", gravities[cur_gravity].name, NULL);
      clutter_text_set_text (label, str);
      g_free (str);

      cur_gravity += 1;

      if (cur_gravity >= n_gravities)
        cur_gravity = 0;
    }

    int
    main (int argc, char *argv[])
    {
      ClutterActor *stage, *text;
      ClutterContent *image;
      ClutterAction *action;
      GdkPixbuf *pixbuf;
      gchar *str;

      if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
        return EXIT_FAILURE;

      stage = clutter_stage_new ();
      clutter_actor_set_name (stage, "Stage");
      clutter_stage_set_title (CLUTTER_STAGE (stage), "Content Box");
      clutter_stage_set_user_resizable (CLUTTER_STAGE (stage), TRUE);
      g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
      clutter_actor_set_margin_top (stage, 12);
      clutter_actor_set_margin_right (stage, 12);
      clutter_actor_set_margin_bottom (stage, 12);
      clutter_actor_set_margin_left (stage, 12);
      clutter_actor_show (stage);

      pixbuf = gdk_pixbuf_new_from_file (TESTS_DATADIR G_DIR_SEPARATOR_S "redhand.png", NULL);
      image = clutter_image_new ();
      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),
                              NULL);
      g_object_unref (pixbuf);

      clutter_actor_set_content_scaling_filters (stage,
                                                 CLUTTER_SCALING_FILTER_TRILINEAR,
                                                 CLUTTER_SCALING_FILTER_LINEAR);
      clutter_actor_set_content_gravity (stage, gravities[n_gravities - 1].gravity);
      clutter_actor_set_content (stage, image);
      g_object_unref (image);

      str = g_strconcat ("Content gravity: ",
                         gravities[n_gravities - 1].name,
                         NULL);

      text = clutter_text_new ();
      clutter_text_set_text (CLUTTER_TEXT (text), str);
      clutter_actor_add_constraint (text, clutter_align_constraint_new (stage, CLUTTER_ALIGN_BOTH, 0.5));
      clutter_actor_add_child (stage, text);

      g_free (str);

      action = clutter_tap_action_new ();
      g_signal_connect (action, "tap", G_CALLBACK (on_tap), text);
      clutter_actor_add_action (stage, action);

      clutter_main ();

      return EXIT_SUCCESS;
    }

ClutterImage is available since Clutter 1.10.

## Details

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

### CLUTTER_IMAGE_ERROR

    #define CLUTTER_IMAGE_ERROR             (clutter_image_error_quark ())

Error domain for the ClutterImageError enumeration.

Since 1.10

### enum ClutterImageError

    typedef enum {
      CLUTTER_IMAGE_ERROR_INVALID_DATA
    } ClutterImageError;

Error enumeration for ClutterImage.

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

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.

`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`.

`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.

`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.

`image` : | a ClutterImage
Returns : | a pointer to the Cogl texture, or `NULL`. [transfer none]

Since 1.10

Stability Level: Unstable