From 347f3b614dc542318065cefce7a4b6db56bc55e0 Mon Sep 17 00:00:00 2001 From: Elliot Smith Date: Tue, 29 Jun 2010 15:49:40 +0100 Subject: [PATCH] cookbook: Add a recipe for image loading http://bugzilla.clutter-project.org/show_bug.cgi?id=2165 Signed-off-by: Emmanuele Bassi --- doc/cookbook/clutter-cookbook.xml.in | 208 +++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) diff --git a/doc/cookbook/clutter-cookbook.xml.in b/doc/cookbook/clutter-cookbook.xml.in index f9a390ce1..bc5c0944f 100644 --- a/doc/cookbook/clutter-cookbook.xml.in +++ b/doc/cookbook/clutter-cookbook.xml.in @@ -996,6 +996,214 @@ clutter_texture_get_base_size (CLUTTER_TEXTURE (texture), &width, &height); +
+ Loading image data into a texture + +
+ Problem + + You want to display an image inside a Clutter + application. +
+ +
+ Solution + + Create a ClutterTexture directly from an image file: + + + + + + + + Or create a texture and set its source to an image + file: + + + + + + + +
+ +
+ Discussion + + 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. + + + +
+ Synchronous vs. asynchronous image loading + + 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. */ +} +]]> + + + +
+ +
+ Other ways to load image data into a texture + + 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. + + + +
+ +
+
+