ClutterCairoTexture: Clutter Reference Manual

## ClutterCairoTexture ClutterCairoTexture — Texture with Cairo integration |

## Functions

ClutterActor * | clutter_cairo_texture_new ()
void | clutter_cairo_texture_set_surface_size ()
void | clutter_cairo_texture_get_surface_size ()
void | clutter_cairo_texture_set_auto_resize ()
gboolean | clutter_cairo_texture_get_auto_resize ()
cairo_t * | clutter_cairo_texture_create ()
cairo_t * | clutter_cairo_texture_create_region ()
void | clutter_cairo_texture_invalidate_rectangle ()
void | clutter_cairo_texture_invalidate ()
void | clutter_cairo_texture_clear ()

## Properties

gboolean | auto-resize | Read / Write
guint | surface-height | Read / Write
guint | surface-width | Read / Write

## Signals

CairoSurface* | create-surface | No Recursion
gboolean | draw | No Recursion

## Types and Values

struct | ClutterCairoTexture
struct | ClutterCairoTextureClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActor
                ╰── ClutterTexture
                    ╰── ClutterCairoTexture

## Implemented Interfaces

ClutterCairoTexture implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

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

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.

ClutterCairoTexture is available since Clutter 1.0.

ClutterCairoTexture is deprecated since Clutter 1.12. You should use ClutterCanvas instead.

## Functions

### clutter_cairo_texture_new ()

    ClutterActor *
    clutter_cairo_texture_new (guint width,
                               guint height);

`clutter_cairo_texture_new` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

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

#### Parameters

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

`clutter_cairo_texture_set_surface_size` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

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

#### Parameters

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

`clutter_cairo_texture_get_surface_size` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

Retrieves the surface width and height for `self` .

#### Parameters

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

`clutter_cairo_texture_set_auto_resize` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

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.

#### Parameters

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

`clutter_cairo_texture_get_auto_resize` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

Retrieves the value set using `clutter_cairo_texture_set_auto_resize()`.

#### Parameters

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

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

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

#### Parameters

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

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

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

#### Parameters

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

`clutter_cairo_texture_invalidate_rectangle` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

Invalidates a rectangular region of a ClutterCairoTexture.

The invalidation will cause the “draw” signal to be emitted.

See also: `clutter_cairo_texture_invalidate()`

#### Parameters

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

`clutter_cairo_texture_invalidate` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

Invalidates the whole surface of a ClutterCairoTexture.

This function will cause the “draw” signal to be emitted.

See also: `clutter_cairo_texture_invalidate_rectangle()`

#### Parameters

self | a ClutterCairoTexture |

Since 1.8

### clutter_cairo_texture_clear ()

    void
    clutter_cairo_texture_clear (ClutterCairoTexture *self);

`clutter_cairo_texture_clear` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

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.

#### Parameters

self | a ClutterCairoTexture |

Since 1.0

## Types and Values

### struct ClutterCairoTexture

    struct ClutterCairoTexture;

`ClutterCairoTexture` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

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

`ClutterCairoTextureClass` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterCanvas instead

The ClutterCairoTextureClass struct contains only private data.

#### Members

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

Since 1.0

## Property Details

### The `“auto-resize”` property

      “auto-resize”              gboolean

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.

`ClutterCairoTexture:auto-resize` has been deprecated since version 1.12 and should not be used in newly-written code.

Flags: Read / Write

Default value: FALSE

Since 1.8

### The `“surface-height”` property

      “surface-height”           guint

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

`ClutterCairoTexture:surface-height` has been deprecated since version 1.12 and should not be used in newly-written code.

Flags: Read / Write

Default value: 0

Since 1.0

### The `“surface-width”` property

      “surface-width”            guint

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

`ClutterCairoTexture:surface-width` has been deprecated since version 1.12 and should not be used in newly-written code.

Flags: Read / Write

Default value: 0

Since 1.0

## Signal Details

### The `“create-surface”` signal

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

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.

`ClutterCairoTexture::create-surface` has been deprecated since version 1.12 and should not be used in newly-written code.

#### Parameters

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

Flags: No Recursion

Since 1.6

### The `“draw”` signal

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

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

`ClutterCairoTexture::draw` has been deprecated since version 1.12 and should not be used in newly-written code.

#### Parameters

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

Flags: No Recursion

Since 1.8