ClutterCairoTexture

## ClutterCairoTexture ClutterCairoTexture — Texture with Cairo integration |

## Synopsis

    #define             CLUTTER_CAIRO_FORMAT_ARGB32
    struct              ClutterCairoTexture;
    struct              ClutterCairoTextureClass;
    ClutterActor *      clutter_cairo_texture_new           (guint width,
                                                             guint height);
    void                clutter_cairo_texture_set_surface_size
                                                            (ClutterCairoTexture *self,
                                                             guint width,
                                                             guint height);
    void                clutter_cairo_texture_get_surface_size
                                                            (ClutterCairoTexture *self,
                                                             guint *width,
                                                             guint *height);
    void                clutter_cairo_texture_set_auto_resize
                                                            (ClutterCairoTexture *self,
                                                             gboolean value);
    gboolean            clutter_cairo_texture_get_auto_resize
                                                            (ClutterCairoTexture *self);

    cairo_t *           clutter_cairo_texture_create        (ClutterCairoTexture *self);
    cairo_t *           clutter_cairo_texture_create_region (ClutterCairoTexture *self,
                                                             gint x_offset,
                                                             gint y_offset,
                                                             gint width,
                                                             gint height);

    void                clutter_cairo_texture_invalidate_rectangle
                                                            (ClutterCairoTexture *self,
                                                             cairo_rectangle_int_t *rect);
    void                clutter_cairo_texture_invalidate    (ClutterCairoTexture *self);
    void                clutter_cairo_texture_clear         (ClutterCairoTexture *self);

    void                clutter_cairo_set_source_color      (cairo_t *cr,
                                                             const ClutterColor *color);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----ClutterTexture
                         +----ClutterCairoTexture

## Implemented Interfaces

ClutterCairoTexture implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Properties

      "auto-resize"              gboolean              : Read / Write
      "surface-height"           guint                 : Read / Write
      "surface-width"            guint                 : Read / Write

## Signals

      "create-surface"                                 : No Recursion
      "draw"                                           : No Recursion

## Description

ClutterCairoTexture is a ClutterTexture that displays the contents of a Cairo context. The ClutterCairoTexture actor will create a Cairo image surface which will then be uploaded to a GL texture when needed.

### Note

Since ClutterCairoTexture uses a Cairo image surface internally all the drawing operations will be performed in software and not using hardware acceleration. This can lead to performance degradation if the contents of the texture change frequently.

In order to use a ClutterCairoTexture you should connect to the "draw" signal; the signal is emitted each time the ClutterCairoTexture has been told to invalidate its contents, by using `clutter_cairo_texture_invalidate_rectangle()` or its sister function, `clutter_cairo_texture_invalidate()`.

Each callback to the "draw" signal will receive a cairo_t context which can be used for drawing; the Cairo context is owned by the ClutterCairoTexture and should not be destroyed explicitly.

Example 4. A simple ClutterCairoTexture canvas

    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
    111
    112
    113
    114
    115
    116
    117
    118
    119
    #include <stdlib.h>
    #include <math.h>
    #include <cairo.h>
    #include <clutter/clutter.h>

    static gboolean
    draw_clock (ClutterCairoTexture *canvas,
                cairo_t             *cr)
    {
      guint width, height;
      GDateTime *now;
      float hours, minutes, seconds;

      /* get the current time and compute the angles */
      now = g_date_time_new_now_local ();
      seconds = g_date_time_get_second (now) * G_PI / 30;
      minutes = g_date_time_get_minute (now) * G_PI / 30;
      hours = g_date_time_get_hour (now) * G_PI / 6;

      /* clear the contents of the canvas, to avoid painting
       * over the previous frame
       */
      clutter_cairo_texture_clear (canvas);

      /* scale the modelview to the size of the surface */
      clutter_cairo_texture_get_surface_size (canvas, &width, &height);
      cairo_scale (cr, width, height);

      cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND);
      cairo_set_line_width (cr, 0.1);

      /* the black rail that holds the seconds indicator */
      clutter_cairo_set_source_color (cr, CLUTTER_COLOR_Black);
      cairo_translate (cr, 0.5, 0.5);
      cairo_arc (cr, 0, 0, 0.4, 0, G_PI * 2);
      cairo_stroke (cr);

      /* the seconds indicator */
      clutter_cairo_set_source_color (cr, CLUTTER_COLOR_White);
      cairo_move_to (cr, 0, 0);
      cairo_arc (cr, sinf (seconds) * 0.4, - cosf (seconds) * 0.4, 0.05, 0, G_PI * 2);
      cairo_fill (cr);

      /* the minutes hand */
      clutter_cairo_set_source_color (cr, CLUTTER_COLOR_DarkChameleon);
      cairo_move_to (cr, 0, 0);
      cairo_line_to (cr, sinf (minutes) * 0.4, -cosf (minutes) * 0.4);
      cairo_stroke (cr);

      /* the hours hand */
      cairo_move_to (cr, 0, 0);
      cairo_line_to (cr, sinf (hours) * 0.2, -cosf (hours) * 0.2);
      cairo_stroke (cr);

      g_date_time_unref (now);

      /* we're done drawing */
      return TRUE;
    }

    static gboolean
    invalidate_clock (gpointer data_)
    {
      /* invalidate the contents of the canvas */
      clutter_cairo_texture_invalidate (data_);

      /* keep the timeout source */
      return TRUE;
    }

    G_MODULE_EXPORT int
    test_cairo_clock_main (int argc, char *argv[])
    {
      ClutterActor *stage, *canvas;

      /* initialize Clutter */
      if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
        return EXIT_FAILURE;

      /* create a resizable stage */
      stage = clutter_stage_new ();
      clutter_stage_set_title (CLUTTER_STAGE (stage), "2D Clock");
      clutter_stage_set_user_resizable (CLUTTER_STAGE (stage), TRUE);
      clutter_actor_set_background_color (stage, CLUTTER_COLOR_LightSkyBlue);
      clutter_actor_set_size (stage, 300, 300);
      clutter_actor_show (stage);

      /* our 2D canvas, courtesy of Cairo */
      canvas = clutter_cairo_texture_new (300, 300);
      clutter_container_add_actor (CLUTTER_CONTAINER (stage), canvas);

      /* bind the size of the canvas to that of the stage */
      clutter_actor_add_constraint (canvas, clutter_bind_constraint_new (stage, CLUTTER_BIND_SIZE, 0));

      /* make sure to match allocation to canvas size */
      clutter_cairo_texture_set_auto_resize (CLUTTER_CAIRO_TEXTURE (canvas), TRUE);

      /* quit on destroy */
      g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);

      /* connect our drawing code */
      g_signal_connect (canvas, "draw", G_CALLBACK (draw_clock), NULL);

      /* invalidate the canvas, so that we can draw before the main loop starts */
      clutter_cairo_texture_invalidate (CLUTTER_CAIRO_TEXTURE (canvas));

      /* set up a timer that invalidates the canvas every second */
      clutter_threads_add_timeout (1000, invalidate_clock, canvas);

      clutter_main ();

      return EXIT_SUCCESS;
    }

    G_MODULE_EXPORT const char *
    test_cairo_clock_describe (void)
    {
      return "Simple 2D canvas using a Cairo texture actor";
    }

ClutterCairoTexture is available since Clutter 1.0.

## Details

### CLUTTER_CAIRO_FORMAT_ARGB32

    #define CLUTTER_CAIRO_FORMAT_ARGB32     (COGL_PIXEL_FORMAT_BGRA_8888_PRE)

The CoglPixelFormat to be used when uploading image data from and to a Cairo image surface using `CAIRO_FORMAT_ARGB32` and `CAIRO_FORMAT_RGB24` as cairo_format_t.

Since 1.8

### struct ClutterCairoTexture

    struct ClutterCairoTexture;

The ClutterCairoTexture struct contains only private data.

Since 1.0

### struct ClutterCairoTextureClass

    struct ClutterCairoTextureClass {
      cairo_surface_t *(* create_surface) (ClutterCairoTexture *texture,
                                           guint                width,
                                           guint                height);

      gboolean         (* draw)           (ClutterCairoTexture *texture,
                                           cairo_t             *cr);
    };

The ClutterCairoTextureClass struct contains only private data.

`create_surface` () | class handler for the "create-surface" signal
`draw` () | class handler for the "draw" signal

Since 1.0

### clutter_cairo_texture_new ()

    ClutterActor *      clutter_cairo_texture_new           (guint width,
                                                             guint height);

Creates a new ClutterCairoTexture actor, with a surface of `width` by `height` pixels.

`width` : | the width of the surface
`height` : | the height of the surface
Returns : | the newly created ClutterCairoTexture actor

Since 1.0

### clutter_cairo_texture_set_surface_size ()

    void                clutter_cairo_texture_set_surface_size
                                                            (ClutterCairoTexture *self,
                                                             guint width,
                                                             guint height);

Resizes the Cairo surface used by `self` to `width` and `height`.

This function will not invalidate the contents of the Cairo texture: you will have to explicitly call either `clutter_cairo_texture_invalidate_rectangle()` or `clutter_cairo_texture_invalidate()`.

`self` : | a ClutterCairoTexture
`width` : | the new width of the surface
`height` : | the new height of the surface

Since 1.0

### clutter_cairo_texture_get_surface_size ()

    void                clutter_cairo_texture_get_surface_size
                                                            (ClutterCairoTexture *self,
                                                             guint *width,
                                                             guint *height);

Retrieves the surface width and height for `self`.

`self` : | a ClutterCairoTexture
`width` : | return location for the surface width, or `NULL`. [out]
`height` : | return location for the surface height, or `NULL`. [out]

Since 1.0

### clutter_cairo_texture_set_auto_resize ()

    void                clutter_cairo_texture_set_auto_resize
                                                            (ClutterCairoTexture *self,
                                                             gboolean value);

Sets whether the ClutterCairoTexture should ensure that the backing Cairo surface used matches the allocation assigned to the actor. If the allocation changes, the contents of the ClutterCairoTexture will also be invalidated automatically.

`self` : | a ClutterCairoTexture
`value` : | `TRUE` if the ClutterCairoTexture should bind the surface size to the allocation

Since 1.8

### clutter_cairo_texture_get_auto_resize ()

    gboolean            clutter_cairo_texture_get_auto_resize
                                                            (ClutterCairoTexture *self);

Retrieves the value set using `clutter_cairo_texture_set_auto_resize()`.

`self` : | a ClutterCairoTexture
Returns : | `TRUE` if the ClutterCairoTexture should track the allocation, and `FALSE` otherwise

Since 1.8

### clutter_cairo_texture_create ()

    cairo_t *           clutter_cairo_texture_create        (ClutterCairoTexture *self);

### Warning

`clutter_cairo_texture_create` has been deprecated since version 1.8 and should not be used in newly-written code. Use the "draw" signal and the `clutter_cairo_texture_invalidate()` function to obtain a Cairo context for 2D drawing.

Creates a new Cairo context for the `cairo` texture. It is similar to using `clutter_cairo_texture_create_region()` with `x_offset` and `y_offset` of 0, `width` equal to the `cairo` texture surface width and `height` equal to the `cairo` texture surface height.

### Warning

Do not call this function within the paint virtual function or from a callback to the "paint" signal.

`self` : | a ClutterCairoTexture
Returns : | a newly created Cairo context. Use `cairo_destroy()` to upload the contents of the context when done drawing

Since 1.0

### clutter_cairo_texture_create_region ()

    cairo_t *           clutter_cairo_texture_create_region (ClutterCairoTexture *self,
                                                             gint x_offset,
                                                             gint y_offset,
                                                             gint width,
                                                             gint height);

### Warning

`clutter_cairo_texture_create_region` has been deprecated since version 1.8 and should not be used in newly-written code. Use the "draw" signal and `clutter_cairo_texture_invalidate_rectangle()` to obtain a clipped Cairo context for 2D drawing.

Creates a new Cairo context that will updat the region defined by `x_offset`, `y_offset`, `width` and `height`.

### Warning

Do not call this function within the paint virtual function or from a callback to the "paint" signal.

`self` : | a ClutterCairoTexture
`x_offset` : | offset of the region on the X axis
`y_offset` : | offset of the region on the Y axis
`width` : | width of the region, or -1 for the full surface width
`height` : | height of the region, or -1 for the full surface height
Returns : | a newly created Cairo context. Use `cairo_destroy()` to upload the contents of the context when done drawing

Since 1.0

### clutter_cairo_texture_invalidate_rectangle ()

    void                clutter_cairo_texture_invalidate_rectangle
                                                            (ClutterCairoTexture *self,
                                                             cairo_rectangle_int_t *rect);

Invalidates a rectangular region of a ClutterCairoTexture.

The invalidation will cause the "draw" signal to be emitted.

See also: `clutter_cairo_texture_invalidate()`

`self` : | a ClutterCairoTexture
`rect` : | a rectangle with the area to invalida, or `NULL` to perform an unbounded invalidation. [allow-none]

Since 1.8

### clutter_cairo_texture_invalidate ()

    void                clutter_cairo_texture_invalidate    (ClutterCairoTexture *self);

Invalidates the whole surface of a ClutterCairoTexture.

This function will cause the "draw" signal to be emitted.

See also: `clutter_cairo_texture_invalidate_rectangle()`

`self` : | a ClutterCairoTexture

Since 1.8

### clutter_cairo_texture_clear ()

    void                clutter_cairo_texture_clear         (ClutterCairoTexture *self);

Clears `self`'s internal drawing surface, so that the next upload will replace the previous contents of the ClutterCairoTexture rather than adding to it.

Calling this function from within a "draw" signal handler will clear the invalidated area.

`self` : | a ClutterCairoTexture

Since 1.0

### clutter_cairo_set_source_color ()

    void                clutter_cairo_set_source_color      (cairo_t *cr,
                                                             const ClutterColor *color);

Utility function for setting the source color of `cr` using a ClutterColor. This function is the equivalent of:

    1
    2
    3
    4
    5
    cairo_set_source_rgba (cr,
                           color->red / 255.0,
                           color->green / 255.0,
                           color->blue / 255.0,
                           color->alpha / 255.0);

`cr` : | a Cairo context
`color` : | a ClutterColor

Since 1.0

## Property Details

### The `"auto-resize"` property

      "auto-resize"              gboolean              : Read / Write

Controls whether the ClutterCairoTexture should automatically resize the Cairo surface whenever the actor's allocation changes. If :auto-resize is set to `TRUE` the surface contents will also be invalidated automatically.

Default value: FALSE

Since 1.8

### The `"surface-height"` property

      "surface-height"           guint                 : Read / Write

The height of the Cairo surface used by the ClutterCairoTexture actor, in pixels.

Default value: 0

Since 1.0

### The `"surface-width"` property

      "surface-width"            guint                 : Read / Write

The width of the Cairo surface used by the ClutterCairoTexture actor, in pixels.

Default value: 0

Since 1.0

## Signal Details

### The `"create-surface"` signal

    CairoSurface*       user_function                      (ClutterCairoTexture *texture,
                                                            guint                width,
                                                            guint                height,
                                                            gpointer             user_data)      : No Recursion

The ::create-surface signal is emitted when a ClutterCairoTexture news its surface (re)created, which happens either when the Cairo context is created with `clutter_cairo_texture_create()` or `clutter_cairo_texture_create_region()`, or when the surface is resized through `clutter_cairo_texture_set_surface_size()`.

The first signal handler that returns a non-`NULL`, valid surface will stop any further signal emission, and the returned surface will be the one used.

`texture` : | the ClutterCairoTexture that emitted the signal
`width` : | the width of the surface to create
`height` : | the height of the surface to create
`user_data` : | user data set when the signal handler was connected.
Returns : | the newly created cairo_surface_t for the texture

Since 1.6

### The `"draw"` signal

    gboolean            user_function                      (ClutterCairoTexture *texture,
                                                            CairoContext        *cr,
                                                            gpointer             user_data)      : No Recursion

The ::draw signal is emitted each time a ClutterCairoTexture has been invalidated.

The passed Cairo context passed will be clipped to the invalidated area.

It is safe to connect multiple callbacks to this signals; the state of the Cairo context passed to each callback is automatically saved and restored, so it's not necessary to call `cairo_save()` and `cairo_restore()`.

`texture` : | the ClutterCairoTexture that emitted the signal
`cr` : | the Cairo context to use to draw
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if the signal emission should stop, and `FALSE` to continue

Since 1.8