## ClutterCairoTexture ClutterCairoTexture — Texture with Cairo integration |

## Synopsis

    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);

    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_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 ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Properties

      "surface-height"           guint                 : Read / Write
      "surface-width"            guint                 : Read / Write

## Signals

      "create-surface"                                 : Run Last

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

ClutterCairoTexture will provide a cairo_t context by using the `clutter_cairo_texture_create()` and `clutter_cairo_texture_create_region()` functions; you can use the Cairo API to draw on the context and then call `cairo_destroy()` when done.

As soon as the context is destroyed with `cairo_destroy()`, the contents of the surface will be uploaded into the ClutterCairoTexture actor:

    1
    2
    3
    4
    5
    6
    7
    cairo_t *cr;

    cr = clutter_cairo_texture_create (CLUTTER_CAIRO_TEXTURE (texture));

    /* draw on the context */

    cairo_destroy (cr);

Although a new cairo_t is created each time you call `clutter_cairo_texture_create()` or `clutter_cairo_texture_create_region()`, it uses the same cairo_surface_t each time. You can call `clutter_cairo_texture_clear()` to erase the contents between calls.

### Warning

Note that you should never use the code above inside the "paint" or "pick" virtual functions or signal handlers because it will lead to performance degradation.

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

ClutterCairoTexture is available since Clutter 1.0.

## Details

### 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);
    };

The ClutterCairoTextureClass struct contains only private data.

`create_surface` () | class handler for the "create-surface" 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`.

`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_create ()

    cairo_t *           clutter_cairo_texture_create        (ClutterCairoTexture *self);

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);

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

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

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

Since 1.0

## Property Details

### 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)      : Run Last

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