the author of the epigraph a short epigraph

introduction

You want to draw 2D graphics inside a Clutter application.

Create a ClutterCairoTexture, then draw onto the Cairo context it wraps using the Cairo API: ClutterActor *texture; cairo_t *cr; guint width, height; width = 800; height = 600; texture = clutter_cairo_texture_new (width, height); cr = clutter_cairo_texture_create (CLUTTER_CAIRO_TEXTURE (texture)); /* * write onto the Cairo context cr using the Cairo API; * see the Cairo API reference for details */ cairo_move_to (cr, 0, 0); cairo_line_to (cr, 800, 600); cairo_stroke (cr); /* does the actual drawing onto the texture */ cairo_destroy (cr); Here's a useful Cairo tutorial if you want to learn more about the Cairo API itself.

A ClutterCairoTexture is a standard ClutterActor, so it can be added to ClutterContainers (e.g. a ClutterStage or ClutterGroup), animated, resized etc. in the usual ways. Other useful operations: To draw on part of the texture: use clutter_cairo_texture_create_region to retrieve a Cairo context for the region you want to draw on. To clear existing content from a texture: use clutter_cairo_texture_clear. You may need to do this as the texture reuses the same Cairo context each time you call clutter_cairo_texture_create or clutter_cairo_texture_create_region. To resize the Cairo context wrapped by a texture, use clutter_cairo_texture_set_surface_size.

Other libraries may provide an API for writing onto a Cairo context; you can make use of these APIs on the exposed Cairo context of a ClutterCairoTexture. For example, you can use the poppler-glib API to display pages from a PopplerDocument inside a Clutter application: /* snipped setup code (as above) */ /* * cast to CLUTTER_CAIRO_TEXTURE, as the functions * used below require that type */ ClutterCairoTexture *cc_texture = CLUTTER_CAIRO_TEXTURE (texture); clutter_cairo_texture_clear (cc_texture); gchar *file_uri = "file:///path/to/file.pdf"; guint page_num = 0; double page_width, page_height; PopplerDocument *doc; PopplerPage *page; GError *error = NULL; doc = poppler_document_new_from_file (file_uri, NULL, &error); page = poppler_document_get_page (doc, page_num); poppler_page_get_size (page, &page_width, &page_height); cr = clutter_cairo_texture_create (cc_texture); /* render the page to the context */ poppler_page_render (page, cr); cairo_destroy (cr); ]]> Note that if the page is larger than the Cairo context, some of it might not be visible. Similarly, if the ClutterCairoTexture is larger than the stage, some of that might not be visible. So you may need to do some work to make the ClutterCairoTexture fit inside the stage properly (e.g. resize the stage), and/or some work to make the PDF page sit inside the Cairo context (e.g. scale the PDF page or put it inside a scrollable actor).

You want want to load an image into a texture and scale it, while retaining the underlying image's aspect ratio.

Set the texture to keep the aspect ratio of the underlying image (so it doesn't distort when it's scaled); use the actor's request-mode property to set the correct geometry management (see the discussion section); then resize the texture along one dimension (height or width). Now, when an image is loaded into the texture, the image is scaled to fit the set height or width; the other dimension is automatically scaled by the same factor so the image fits the texture:

The request mode for an actor determines how geometry requisition is performed; in this case, this includes how scaling is applied if you change the actor's width or height. There are two possible values for request-mode: If set to CLUTTER_REQUEST_HEIGHT_FOR_WIDTH (the default), changing the width causes the height to be scaled by the same factor as the width. If set to CLUTTER_REQUEST_WIDTH_FOR_HEIGHT, changing the height causes the width to be scaled by the same factor as the height. In the example above, the texture is set to keep its aspect ratio then fixed to a width of 300 pixels; the request-mode is set to CLUTTER_REQUEST_HEIGHT_FOR_WIDTH. If a standard, photo-sized image in landscape orientation were loaded into it (2848 pixels wide x 2136 high), it would be scaled down to 300 pixels wide; then, its height would be scaled by the same factor as the width (i.e. scaled down to 225 pixels). With request-mode set to CLUTTER_REQUEST_WIDTH_FOR_HEIGHT, you would get the same effect by setting the height first; then, computation of the width for the scaled image would be based on the scaling factor applied to its height instead. You can work out which side of the source image is longest using clutter_texture_base_size() to get its width and height. This can be useful when trying to scale images with different orientations to fit into uniform rows or columns: Note that if you explicitly set the size (both width and height) of a texture with clutter_actor_set_size() (or with clutter_actor_set_width() and clutter_actor_set_height()), any image loaded into the texture is automatically stretched/shrunk to fit the texture. This is the case regardless of any other settings (like whether to keep aspect ratio). Also note that a texture won't try to fit itself inside the bounds of its parent container: so if it's bigger than its container, only part of it may be visible.

You want to display an image inside a Clutter application.

Create a ClutterTexture directly from an image file: Or create a texture and set its source to an image file:

Bear the following in mind when loading images into a texture: An image load may fail if: The file does not exist. The image format is unsupported: most of the common bitmap formats (PNG, JPEG, BMP, GIF, TIFF, XPM) are supported, but more exotic ones may not be. Whether you're creating a texture from an image file, or loading an image from a file into an existing texture, you should specify the filesystem path to the file, rather than a URI.

The code examples above show the simplest approach: loading an image into a texture synchronously. This means that the application waits for each image to be loaded before continuing; which is acceptable in this case, but may not be when loading images into multiple textures. Another approach is to load data into textures asynchronously. This requires some extra set up in your code: Call g_thread_init() (from the GLib library) prior to calling clutter_init(), so that a local thread is used to load the file, rather than the main loop. (Note that this is not necessary if you're using GLib version >= 2.24, since GObject initializes threading with the type system.) Set the texture to load data asynchronously. Connect a callback to the texture's load-finished signal to handle any errors which occur during loading, and/or to do extra work if data loads successfully. The code below shows how to put these together: message); else g_debug ("Image loaded from %s", image_path); } int main (int argc, char *argv[]) { /* initialize GLib's default threading implementation */ g_thread_init (NULL); clutter_init (&argc, &argv); /* ... get stage etc. */ ClutterActor *texture; GError *error = NULL; texture = clutter_texture_new (); /* load data asynchronously */ clutter_texture_set_load_async (CLUTTER_TEXTURE (texture), TRUE); /* connect a callback to the "load-finished" signal */ g_signal_connect (texture, "load-finished", G_CALLBACK (_load_finished_cb), image_path); /* load the image from a file */ clutter_texture_set_from_file (CLUTTER_TEXTURE (texture), image_path, &error); /* ... clutter_main () etc. */ } ]]>

While it's useful to load image data into a texture directly from a file, there are occasions where you may have image data in some other (non-file) format: Various GNOME libraries provide image data in GdkPixbuf structures; clutter-gtk has functions for creating or setting a texture from a GdkPixbuf: gtk_clutter_texture_new_from_pixbuf() and gtk_clutter_texture_set_from_pixbuf() respectively. If you have raw RGB or YUV pixel data, ClutterTexture has clutter_texture_set_from_rgb_data() and clutter_texture_set_from_yuv_data() methods for loading it.