Antoine de Saint-Exupery A rock pile ceases to be a rock pile the moment a single man contemplates it, bearing within him the image of a cathedral.

Textures are one of the most important actors in Clutter. Whether they are employed as the background for a user interface control, or to show the picture of a kitten, a big part of any Clutter-based application is going to involve textures. A ClutterTexture is an actor that can hold any raw image data and paint it. ClutterTexture can also load image data from a file on disk and convert it. The actual formats supported by ClutterTexture depend on the platform on which Clutter is being used.

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 a ClutterContainer (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); ]]> 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: 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). Since a texture can scale down its contents, its minimum preferred size is 0.

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 pixel data, ClutterTexture also has a clutter_texture_set_from_rgb_data() function for loading it.

You want to create a new ClutterTexture that only displays a rectangular sub-region of an existing texture.

A possible way of achieving this is to retrieve the CoglHandle of the underlying Cogl texture of the existing ClutterTexture, create a new handle representing the sub-region with cogl_texture_new_from_sub_texture() and finally populate a new ClutterTexture with that handle. A texture and its sub-texture next to it

The key of this recipe is the Cogl handle that represents the underlying texture, the actual array of pixels the GPU will use when it's told to texture geometry. From this handle, it's possible to create a new texture handle that represents a rectangular region of the former texture. To do this one must call cogl_texture_new_from_sub_texture() with the position and size of the said region. The interesting bit about this function is that, when drawing either with the original texture or with the new one, it's still the same GPU resource (pixels) being used, meaning that creating a sub-texture doesn't use extra GPU memory. Once the sub-texture handle is created, the next step is to create a new actor that will be able to draw it, namely a new ClutterTexture. You then need to tell the texture to draw from the sub-texture. The handle you can get from clutter_texture_get_cogl_texture() is effectively the same texture than the first layer of the material retrieved by clutter_texture_get_cogl_material()

FIXME: MISSING XINCLUDE CONTENT

Now that we know how to create sub-textures, it's time to make something a bit more shiny with them. Let's animate them! In case you have not heard about implicit animations in Clutter yet, it's a good time to have a look at the animation section of this cookbook. Video showing 4 sub-textures being animated FIXME: MISSING XINCLUDE CONTENT

You want to create the reflection of a texture. The reflection is going to be positioned below the original texture, and is going to fade out as if the original was placed on a glassy surface.

You can use a ClutterClone actor and override its paint implementation with a custom one: A texture and its reflection below

The essence of painting a reflection of a texture lies in reusing the same material used by the original. This not only allows painting always an up to date version of the original, but it also saves resources. In the code example above we take the CoglMaterial out of the source ClutterTexture and we ask the Cogl pipeline to paint it by using cogl_set_source(). The main difference between this code and the equivalent code inside the ClutterTexture paint() implementation is that we also specify the texture vertices and their color by using the CoglTextureVertex structure and the cogl_polygon() function. The CoglTextureVertex structure contains three fields for the position of the vertex in 3D space: It also contains the normalized texture coordinate (also known as texture element, or texel): And, finally, the color of the vertex, expressed as a CoglColor: The example code sets the position of the vertices in clockwise order starting from the top left corner, and sets the coordinate of the texels in counter-clockwise order, starting with the bottom left corner. This makes sure that the copy of the original texture appears as being flipped vertically. The gradual fading out to the background color is done by setting the color of the top vertices to be fully opaque, and the color of the bottom ones to be fully transparent; GL will then automatically create a gradient that will be applied when painting the material. The color values must be pre-multiplied with their alpha component, otherwise the bleding will not be correct. You can either multiply the values by yourself when creating the color or, better yet, use the cogl_color_premultiply() that Cogl provides for this operation.

FIXME: MISSING XINCLUDE CONTENT

You want to do a cross-fade animation (a.k.a. a dissolve transition) between two images. An example use case would be creating a slideshow effect: load an image from a file, display it in the UI, then load a second image and cross-fade to it.

There are two main approaches you could take: Use two ClutterTextures, one on top of the other. Use a single ClutterTexture with the two images in separate layers inside it.

This approach uses two ClutterTextures, bottom and top. To begin with, the bottom texture shows the source image and is opaque; the top texture is loaded with the target image, but is not visible as it is fully transparent. An animation is then used to fade in the top texture and fade out the bottom texture, leaving just top visible. To implement this, first create the two textures inside a ClutterBinLayout: Load the source image into the bottom texture and the target image into the top one. As this is the same operation each time, it makes sense to write a function for loading an image into a texture and checking for errors, e.g.: message); g_error_free (error); exit (EXIT_FAILURE); } return success; } ]]> The load_image() function can then be called for each texture: For the animations, we use ClutterState as we want to animate two actors at once (top and bottom): Note that rather than set the start opacities manually on the actors (e.g. using clutter_actor_set_opacity()), I've used a ClutterState to define the start state (as well as the end state). This makes it easier to track transitions, as they are all kept in one data structure. The easing modes used for the cross-fade animation (CLUTTER_EASE_IN_CUBIC) can be set to whatever you like. I personally think that ease-in modes look best for cross-fading. "Warp" the two textures into the start state (bottom opaque, top transparent): Using clutter_state_warp_to_state() immediately transitions to a state without animating, which in this case sets up the initial state of the UI. Finally, use the ClutterState to animate the two textures, so top fades in and bottom fades out: Here's what it looks like: Video showing a cross-fade between two textures The full code for this example is in the appendix.

The alternative solution is to use a single texture and the low-level COGL API to set up two different layers inside it, one for each image. Then, rather than fade between two textures, progressively combine the two layers together using an alpha value which changes over the course of an animation (from 0.0 at the start of the animation to 1.0 at its end). At any point in the cross-fade animation, you are actually seeing a combination of the color values in the two images (modified by an alpha component), rather than seeing one image through the other. This can give a smoother cross-fade effect than the two texture approach. As this solution is more complex and relies on the lower-level (and more difficult to follow) COGL API, the next section is just a short summary of how it works; see the sample code, which has liberal comments for more details. For more about texture combining, refer to the COGL API documentation (particularly the section about material blend strings). You may also find it useful to get hold of a decent OpenGL reference. (So you can look it up, what we're doing in this solution is using a texture combiner with interpolation as the texture combiner function.)

The cross-fade is implemented by combining the two layers, computing a color value for each pixel in the resulting texture. The value for each pixel at a given point in the animation is based on three things: The color value of the source pixel The color value of the target pixel The alpha value of a third colour at the given point in the animation's timeline The resulting value for each RGBA color component in each pixel is computed using an interpolation function. In pseudo-code, it looks like this: color component value = (target pixel value * alpha) + (source pixel value * (1 - alpha)) The effect is that as the alpha increases towards 1.0, progressively more of the target pixel's color is used, and progressively less of the source pixel's: so the target fades in, while the source fades out. The advantage of this approach is that color and brightness transitions only occur where pixels differ between the two images. This means that you transitions are smoother where you are cross-fading between images with similar color ranges and brightness levels. A special case is where you're cross-fading from an image to itself: the two texture approach can cause some dimming during this kind of transition; but the single texture approach results in no color or brightness changes (it's not even a transition as such, as all the pixels are identical in the two layers).

The code examples (two textures, one texture with COGL) don't take account of the size of the images being loaded. In the two texture example, this isn't so much of a problem, as you can resize the textures individually to the images: providing you use clutter_texture_set_keep_aspect_ratio(), different image sizes shouldn't be a problem. See the slideshow example, for a demonstration of how to cycle through different sized images. In the case of the single texture approach, you will get problems when cross-fading between two images with different sizes. There is no easy way to maintain the aspect ratio (as you have two layers, potentially with different sizes, in the same texture). The last layer added to the CoglMaterial determines the size of the texture; so if the previous layer has different dimensions, it will appear distorted in the UI. In the single texture code example, the source layer is added first; so, if the target layer has different dimensions, the source will appear distorted. There are a couple of ways you can remedy this: As you load each image into its own CoglTexture, get its size with cogl_texture_get_width() and cogl_texture_get_height(). Then set the ClutterTexture's size to the size of the source layer. Next, as you cross-fade, simultaneously animate a size change in the ClutterTexture to the target image's size. This could work with non-realistic images where some distortion of the image is acceptable (the target image may be the wrong size to start with, but transition to the correct size by the time it's fully faded in). But it can look a bit odd for transitions between photos. Use GdkPixbuf (or similar) to load the images into a temporary data structure. (GdkPixbuf works well for this as it can resize the image while retaining its aspect ratio.) Then load the data from the pixbuf into a region of a CoglTexture which has the same dimensions as the ClutterTexture. Here's an example of how you can rewrite the load_cogl_texture() function of the single texture example to do this: static CoglHandle load_cogl_texture (const char *type, const char *file, const guint texture_width, const guint texture_height) { GError *error = NULL; /* * Load image data from a file into a GdkPixbuf, * but constrained to the size of the target ClutterTexture; * aspect ratio is maintained * * texture_width and texture_height are set elsewhere to * the width and height of the ClutterTexture */ GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file_at_size (file, texture_width, texture_height, &error); if (error != NULL) { g_print ("Unable to load %s image: %s\n", type, error->message); g_error_free (error); exit (EXIT_FAILURE); } guint rowstride = gdk_pixbuf_get_rowstride (pixbuf); guint width = gdk_pixbuf_get_width (pixbuf); guint height = gdk_pixbuf_get_height (pixbuf); guchar *data = gdk_pixbuf_get_pixels (pixbuf); CoglPixelFormat format = COGL_PIXEL_FORMAT_RGB_888; if (gdk_pixbuf_get_has_alpha (pixbuf) == TRUE) format = COGL_PIXEL_FORMAT_RGBA_8888; /* CoglTexture with the same dimensions as the ClutterTexture */ CoglHandle *tex = cogl_texture_new_with_size (texture_width, texture_height, COGL_TEXTURE_NO_SLICING, format); /* * load the texture data into a region of the full-sized texture; * the size of the region is set from the size of the image data * (as resized by GdkPixbuf) */ cogl_texture_set_region (tex, 0, 0, /* from top-left corner of the pixbuf */ (texture_width - width) / 2, /* center on the CoglTexture */ (texture_height - height) / 2, /* center on the CoglTexture */ width, height, width, height, format, rowstride, data); return tex; } ]]> Because you're copying the image data from the file into a region of the CoglTexture that's the same size as the image data in the pixbuf, it isn't distorted.

The two texture solution can be easily extended to cycle through multiple images. To begin with, the first image is loaded into the top texture. Then, the basic pattern for transitioning to the next image is as follows: Copy the data from the top texture to the bottom texture. Make the top texture transparent and the bottom texture opaque (using clutter_state_warp_to_state()). At this point, it appears as though the textures haven't changed. Load the next image into top. When top has finished loading, fade it in while simultaneously fading out bottom (using clutter_state_set_state()). The sample code in the appendix implements this as part of a simple slideshow application.

there should be a code sample here, but there isn't... there should be a code sample here, but there isn't... there should be a code sample here, but there isn't...