![]() |
![]() |
![]() |
Clutter Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
#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
); 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
);
GObject +----GInitiallyUnowned +----ClutterActor +----ClutterTexture +----ClutterCairoTexture
ClutterCairoTexture implements ClutterScriptable, ClutterAnimatable and AtkImplementorIface.
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.
Example 5. 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 |
#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_set_source_rgba (cr, 0.2, 0.2, 1, 0.6); 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 fixed size stage */ stage = clutter_stage_new (); clutter_stage_set_title (CLUTTER_STAGE (stage), "2D Clock"); clutter_stage_set_color (CLUTTER_STAGE (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); /* 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; } |
ClutterCairoTexture is available since Clutter 1.0.
#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;
The ClutterCairoTexture struct contains only private data.
Since 1.0
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.
class handler for the "create-surface" signal | |
class handler for the "draw" signal |
Since 1.0
ClutterActor * clutter_cairo_texture_new (guint width
,guint height
);
Creates a new ClutterCairoTexture actor, with a surface of width
by
height
pixels.
|
the width of the surface |
|
the height of the surface |
Returns : |
the newly created ClutterCairoTexture actor |
Since 1.0
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()
.
|
a ClutterCairoTexture |
|
the new width of the surface |
|
the new height of the surface |
Since 1.0
void clutter_cairo_texture_get_surface_size (ClutterCairoTexture *self
,guint *width
,guint *height
);
Retrieves the surface width and height for self
.
|
a ClutterCairoTexture |
|
return location for the surface width, or NULL . [out]
|
|
return location for the surface height, or NULL . [out]
|
Since 1.0
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.
|
a ClutterCairoTexture |
Returns : |
a newly created Cairo context. Use cairo_destroy()
to upload the contents of the context when done drawing |
Since 1.0
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.
|
a ClutterCairoTexture |
|
offset of the region on the X axis |
|
offset of the region on the Y axis |
|
width of the region, or -1 for the full surface width |
|
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
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()
|
a ClutterCairoTexture |
|
a rectangle with the area to invalida,
or NULL to perform an unbounded invalidation. [allow-none]
|
Since 1.8
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()
|
a ClutterCairoTexture |
Since 1.8
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.
|
a ClutterCairoTexture |
Since 1.0
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); |
|
a Cairo context |
|
a ClutterColor |
Since 1.0
"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
"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
"create-surface"
signalCairoSurface* 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.
|
the ClutterCairoTexture that emitted the signal |
|
the width of the surface to create |
|
the height of the surface to create |
|
user data set when the signal handler was connected. |
Returns : |
the newly created cairo_surface_t for the texture |
Since 1.6
"draw"
signalgboolean 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()
.
|
the ClutterCairoTexture that emitted the signal |
|
the Cairo context to use to draw |
|
user data set when the signal handler was connected. |
Returns : |
TRUE if the signal emission should stop, and FALSE
to continue |
Since 1.8