ClutterTexture

The ClutterTexture is a high level texture wrapper, it is a ClutterActor and can be added directly into a ClutterStage. ClutterTexture is defined with following member

struct _ClutterTexturePrivate {
 gint                         width;
 gint                         height;
 gint                         max_tile_waste;
 ClutterTextureQuality        filter_quality;
 CoglHandle                   texture;
 gboolean                     no_slice;

 ClutterActor                *fbo_source;
 CoglHandle                   fbo_handle;
  /* Non video memory copy of image data */
 guint                        local_data_width, local_data_height;
 guint                        local_data_rowstride;
 guint                        local_data_has_alpha;
 guchar                      *local_data;

 guint                        sync_actor_size : 1;
 guint                        repeat_x : 1;
 guint                        repeat_y : 1;
 guint                        in_dispose : 1;
 guint                        keep_aspect_ratio : 1;

};

with:

• width: the width of the actor.
• height: the height of the actor.
• max_tile_waste: the number of byte that the slice texture is allowed to have wasted. It is used when no_slice is set to false.
  
• filter_quality: the filter quality to apply into the texture actor.
  
• texture: the internal CoglTexture handle.
• no_slice: value indicate that the created texture is not using slicing method to prevent wasting in texture uploading. It means that the big texture will be sliced into multiple sub-texture if no_slice is set to true. When no_slice is set to true, the max_tile_waste is used to determine the number of byte that allow to be wasted for each sub-texture.
• fbo_source: the FBO source if using FBO
• fbo_handle: the FBO texture handle if using FBO
• local_data_width, local_data_height: width and height of the local data buffer when saving the actor into local.
• local_data_rowstride: rowstride of the local data buffer
• local_data_has_alpha
• local_data: the actual local data buffer
• sync_actor_size:
  
• repeat_x
• repeat_y
• in_dispose: flag used to check if the texture is in dispose state or not
  
• keep_aspect_ratio

To create the texture we have following functions

• ClutterActor * clutter_texture_new (void);
• Create a new blank texture object
  
• ClutterActor * clutter_texture_new_from_file (const gchar *filename, GError **error);
• Create a new texture object from specified file name. The function use clutter_texture_new to create the texture object and then use clutter_texture_set_from_file to set data for the texture.
  
• ClutterActor * clutter_texture_new_from_actor (ClutterActor *actor);
• Create a new texture object from specified actor. The function is to clone the ClutterActor object into a ClutterTexture object to use as an offscreen buffer. It need the offscreen feature available in the EGL otherwise the function return NULL.
  

And some following functions to change the texture data

• clutter_texture_set_from_file: set the internal texture data of the texture object from specified file
• clutter_texture_set_from_rgb_data: set using RGB data
• clutter_texture_set_from_yuv_data: set using YUV data
• clutter_texture_set_area_from_rgb_data: set a sub-region using RGB data

Some notes when working with ClutterTexture

• The no_slice property must be set before the texture attempt to load its data buffer. If we don't want to using slicing of the ClutterTexture, we SHOULD NOT use the clutter_texture_new_from_file as default ClutterTexture use slicing method to save memory. We SHOULD use clutter_texture_new, then set the disable-slice property to false then call clutter_texture_set_from_file to setup data buffer for the texture.
• For OpenGL system that allow read/write pixel, we can have the texture memory automatically saved into system memory when the texture is not using via realize/unrealize function. And in that case, the local_data_* variable is used.
• The FBO is much useful when we want to do transition effect without costing the GL to draw the buffer again and again, in that case the texture object is re-used to draw to onscreen.
• ClutterTexture class know nothing about its internal texture loading/uploading, all are control under Cogl layer.