struct ClutterTexture

struct ClutterTexture;

The ClutterTexture structure contains only private data and should be accessed using the provided API

Since 0.1

struct ClutterTextureClass

struct ClutterTextureClass {
  void (* size_change)   (ClutterTexture *texture,
                          gint            width,
                          gint            height);
  void (* pixbuf_change) (ClutterTexture *texture);
  void (* load_finished) (ClutterTexture *texture,
                          const GError   *error);
};

The ClutterTextureClass structure contains only private data

Since 0.1

enum ClutterTextureFlags

typedef enum {
 /*< prefix=CLUTTER_TEXTURE >*/
  CLUTTER_TEXTURE_NONE             = 0,
  CLUTTER_TEXTURE_RGB_FLAG_BGR     = 1 << 1,
  CLUTTER_TEXTURE_RGB_FLAG_PREMULT = 1 << 2, /* FIXME: not handled */
  CLUTTER_TEXTURE_YUV_FLAG_YUV2    = 1 << 3

  /* FIXME: add compressed types ? */
} ClutterTextureFlags;

Flags for clutter_texture_set_from_rgb_data() and clutter_texture_set_from_yuv_data().

Since 0.4

enum ClutterTextureQuality

typedef enum {
 /*< prefix=CLUTTER_TEXTURE_QUALITY >*/
  CLUTTER_TEXTURE_QUALITY_LOW,
  CLUTTER_TEXTURE_QUALITY_MEDIUM,
  CLUTTER_TEXTURE_QUALITY_HIGH
} ClutterTextureQuality;

Enumaration controlling the texture quality.

Since 0.8

clutter_texture_new ()

ClutterActor *      clutter_texture_new                 (void);

Creates a new empty ClutterTexture object.

clutter_texture_new_from_file ()

ClutterActor *      clutter_texture_new_from_file       (const gchar *filename,
                                                         GError **error);

Creates a new ClutterTexture actor to display the image contained a file. If the image failed to load then NULL is returned and error is set.

Since 0.8

clutter_texture_new_from_actor ()

ClutterActor *      clutter_texture_new_from_actor      (ClutterActor *actor);

Creates a new ClutterTexture object with its source a prexisting actor (and associated children). The textures content will contain 'live' redirected output of the actors scene.

Note this function is intented as a utility call for uniformly applying shaders to groups and other potential visual effects. It requires that the CLUTTER_FEATURE_OFFSCREEN feature is supported by the current backend and the target system.

Some tips on usage:

Since 0.6

CLUTTER_TEXTURE_ERROR

#define CLUTTER_TEXTURE_ERROR   (clutter_texture_error_quark ())

Error domain for ClutterTexture errors

Since 0.4

enum ClutterTextureError

typedef enum {
  CLUTTER_TEXTURE_ERROR_OUT_OF_MEMORY,
  CLUTTER_TEXTURE_ERROR_NO_YUV,
  CLUTTER_TEXTURE_ERROR_BAD_FORMAT
} ClutterTextureError;

Error enumeration for ClutterTexture

Since 0.4

clutter_texture_set_from_file ()

gboolean            clutter_texture_set_from_file       (ClutterTexture *texture,
                                                         const gchar *filename,
                                                         GError **error);

Sets the ClutterTexture image data from an image file. In case of failure, FALSE is returned and error is set.

If "load-async" is set to TRUE, this function will return as soon as possible, and the actual image loading from disk will be performed asynchronously. "size-change" will be emitten when the size of the texture is available and "load-finished" will be emitted when the image has been loaded or if an error occurred.

Since 0.8

clutter_texture_set_from_rgb_data ()

gboolean            clutter_texture_set_from_rgb_data   (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gboolean has_alpha,
                                                         gint width,
                                                         gint height,
                                                         gint rowstride,
                                                         gint bpp,
                                                         ClutterTextureFlags flags,
                                                         GError **error);

Sets ClutterTexture image data.

Since 0.4

clutter_texture_set_from_yuv_data ()

gboolean            clutter_texture_set_from_yuv_data   (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gint width,
                                                         gint height,
                                                         ClutterTextureFlags flags,
                                                         GError **error);

Sets a ClutterTexture from YUV image data. If an error occurred, FALSE is returned and error is set.

The YUV support depends on the driver; the format supported by the few drivers exposing this capability are not really useful.

The proper way to convert image data in any YUV colorspace to any RGB colorspace is to use a fragment shader associated with the ClutterTexture material.

Since 0.4

clutter_texture_set_area_from_rgb_data ()

gboolean            clutter_texture_set_area_from_rgb_data
                                                        (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gboolean has_alpha,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height,
                                                         gint rowstride,
                                                         gint bpp,
                                                         ClutterTextureFlags flags,
                                                         GError **error);

Updates a sub-region of the pixel data in a ClutterTexture.

Since 0.6

clutter_texture_get_base_size ()

void                clutter_texture_get_base_size       (ClutterTexture *texture,
                                                         gint *width,
                                                         gint *height);

Gets the size in pixels of the untransformed underlying image

clutter_texture_get_pixel_format ()

CoglPixelFormat     clutter_texture_get_pixel_format    (ClutterTexture *texture);

Retrieves the pixel format used by texture. This is equivalent to:

1
2
3
4

handle = clutter_texture_get_pixel_format (texture);

if (handle != COGL_INVALID_HANDLE)
  format = cogl_texture_get_format (handle);

Since 1.0

clutter_texture_get_max_tile_waste ()

gint                clutter_texture_get_max_tile_waste  (ClutterTexture *texture);

Gets the maximum waste that will be used when creating a texture or -1 if slicing is disabled.

Since 0.8

clutter_texture_get_filter_quality ()

ClutterTextureQuality clutter_texture_get_filter_quality
                                                        (ClutterTexture *texture);

Gets the filter quality used when scaling a texture.

Since 0.8

clutter_texture_set_filter_quality ()

void                clutter_texture_set_filter_quality  (ClutterTexture *texture,
                                                         ClutterTextureQuality filter_quality);

Sets the filter quality when scaling a texture. The quality is an enumeration currently the following values are supported: CLUTTER_TEXTURE_QUALITY_LOW which is fast but only uses nearest neighbour interpolation. CLUTTER_TEXTURE_QUALITY_MEDIUM which is computationally a bit more expensive (bilinear interpolation), and CLUTTER_TEXTURE_QUALITY_HIGH which uses extra texture memory resources to improve scaled down rendering as well (by using mipmaps). The default value is CLUTTER_TEXTURE_QUALITY_MEDIUM.

Since 0.8

clutter_texture_get_cogl_texture ()

CoglHandle          clutter_texture_get_cogl_texture    (ClutterTexture *texture);

Retrieves the handle to the underlying COGL texture used for drawing the actor. No extra reference is taken so if you need to keep the handle then you should call cogl_handle_ref() on it.

The texture handle returned is the first layer of the material handle used by the ClutterTexture. If you need to access the other layers you should use clutter_texture_get_cogl_material() instead and use the CoglMaterial API.

Since 0.8

clutter_texture_set_cogl_texture ()

void                clutter_texture_set_cogl_texture    (ClutterTexture *texture,
                                                         CoglHandle cogl_tex);

Replaces the underlying COGL texture drawn by this actor with cogl_tex. A reference to the texture is taken so if the handle is no longer needed it should be deref'd with cogl_handle_unref.

Since 0.8

clutter_texture_get_cogl_material ()

CoglHandle          clutter_texture_get_cogl_material   (ClutterTexture *texture);

Returns a handle to the underlying COGL material used for drawing the actor.

Since 1.0

clutter_texture_set_cogl_material ()

void                clutter_texture_set_cogl_material   (ClutterTexture *texture,
                                                         CoglHandle cogl_material);

Replaces the underlying Cogl material drawn by this actor with cogl_material. A reference to the material is taken so if the handle is no longer needed it should be deref'd with cogl_handle_unref. Texture data is attached to the material so calling this function also replaces the Cogl texture. ClutterTexture requires that the material have a texture layer so you should set one on the material before calling this function.

Since 0.8

clutter_texture_get_sync_size ()

gboolean            clutter_texture_get_sync_size       (ClutterTexture *texture);

Retrieves the value set with clutter_texture_set_sync_size()

Since 1.0

clutter_texture_set_sync_size ()

void                clutter_texture_set_sync_size       (ClutterTexture *texture,
                                                         gboolean sync_size);

Sets whether texture should have the same preferred size as the underlying image data.

Since 1.0

clutter_texture_get_repeat ()

void                clutter_texture_get_repeat          (ClutterTexture *texture,
                                                         gboolean *repeat_x,
                                                         gboolean *repeat_y);

Retrieves the horizontal and vertical repeat values set using clutter_texture_set_repeat()

Since 1.0

clutter_texture_set_repeat ()

void                clutter_texture_set_repeat          (ClutterTexture *texture,
                                                         gboolean repeat_x,
                                                         gboolean repeat_y);

Sets whether the texture should repeat horizontally or vertically when the actor size is bigger than the image size

Since 1.0

clutter_texture_get_keep_aspect_ratio ()

gboolean            clutter_texture_get_keep_aspect_ratio
                                                        (ClutterTexture *texture);

Retrieves the value set using clutter_texture_set_keep_aspect_ratio()

Since 1.0

clutter_texture_set_keep_aspect_ratio ()

void                clutter_texture_set_keep_aspect_ratio
                                                        (ClutterTexture *texture,
                                                         gboolean keep_aspect);

Sets whether texture should have a preferred size maintaining the aspect ratio of the underlying image

Since 1.0

clutter_texture_get_load_async ()

gboolean            clutter_texture_get_load_async      (ClutterTexture *texture);

Retrieves the value set using clutter_texture_set_load_async()

Since 1.0

clutter_texture_set_load_async ()

void                clutter_texture_set_load_async      (ClutterTexture *texture,
                                                         gboolean load_async);

Sets whether texture should use a worker thread to load the data from disk asynchronously. Setting load_async to TRUE will make clutter_texture_set_from_file() return immediately.

See the "load-async" property documentation, and clutter_texture_set_load_data_async().

Since 1.0

clutter_texture_get_load_data_async ()

gboolean            clutter_texture_get_load_data_async (ClutterTexture *texture);

Retrieves the value set by clutter_texture_set_load_data_async()

Since 1.0

clutter_texture_set_load_data_async ()

void                clutter_texture_set_load_data_async (ClutterTexture *texture,
                                                         gboolean load_async);

Sets whether texture should use a worker thread to load the data from disk asynchronously. Setting load_async to TRUE will make clutter_texture_set_from_file() block until the ClutterTexture has determined the width and height of the image data.

See the "load-async" property documentation, and clutter_texture_set_load_async().

Since 1.0

clutter_texture_get_pick_with_alpha ()

gboolean            clutter_texture_get_pick_with_alpha (ClutterTexture *texture);

Retrieves the value set by clutter_texture_set_load_data_async()

Since 1.4

clutter_texture_set_pick_with_alpha ()

void                clutter_texture_set_pick_with_alpha (ClutterTexture *texture,
                                                         gboolean pick_with_alpha);

Sets whether texture should have it's shape defined by the alpha channel when picking.

Be aware that this is a bit more costly than the default picking due to the texture lookup, extra test against the alpha value and the fact that it will also interrupt the batching of geometry done internally.

Also there is currently no control over the threshold used to determine what value of alpha is considered pickable, and so only fully opaque parts of the texture will react to picking.

Since 1.4

The "cogl-material" property

  "cogl-material"            CoglHandle*           : Read / Write

The underlying Cogl material handle used to draw this actor.

The "cogl-texture" property

  "cogl-texture"             CoglHandle*           : Read / Write

The underlying Cogl texture handle used to draw this actor.

The "disable-slicing" property

  "disable-slicing"          gboolean              : Read / Write / Construct Only

Forces the underlying texture to be singular and not made of smaller space saving individual textures.

Default value: FALSE

The "filename" property

  "filename"                 gchar*                : Read / Write

The path of the file containing the image data to be displayed by the texture.

This property is unset when using the clutter_texture_set_from_*_data() family of functions.

Default value: NULL

The "filter-quality" property

  "filter-quality"           ClutterTextureQuality  : Read / Write / Construct

Rendering quality used when drawing the texture.

Default value: CLUTTER_TEXTURE_QUALITY_MEDIUM

The "keep-aspect-ratio" property

  "keep-aspect-ratio"        gboolean              : Read / Write

Keep the aspect ratio of the texture when requesting the preferred width or height.

Default value: FALSE

The "load-async" property

  "load-async"               gboolean              : Write

Tries to load a texture from a filename by using a local thread to perform the read operations. The initially created texture has dimensions 0x0 when the true size becomes available the "size-change" signal is emitted and when the image has completed loading the "load-finished" signal is emitted.

Threading is only enabled if g_thread_init() has been called prior to clutter_init(), otherwise ClutterTexture will use the main loop to load the image.

The upload of the texture data on the GL pipeline is not asynchronous, as it must be performed from within the same thread that called clutter_main().

Default value: FALSE

Since 1.0

The "load-data-async" property

  "load-data-async"          gboolean              : Write

Like "load-async" but loads the width and height synchronously causing some blocking.

Default value: FALSE

Since 1.0

The "pick-with-alpha" property

  "pick-with-alpha"          gboolean              : Read / Write

Shape actor with alpha channel when picking.

Default value: FALSE

The "pixel-format" property

  "pixel-format"             CoglPixelFormat       : Read

The Cogl pixel format to use.

Default value: COGL_PIXEL_FORMAT_RGBA_8888

The "repeat-x" property

  "repeat-x"                 gboolean              : Read / Write

Repeat the contents rather than scaling them horizontally.

Default value: FALSE

The "repeat-y" property

  "repeat-y"                 gboolean              : Read / Write

Repeat the contents rather than scaling them vertically.

Default value: FALSE

The "sync-size" property

  "sync-size"                gboolean              : Read / Write

Auto sync size of actor to underlying pixbuf dimensions.

Default value: TRUE

The "tile-waste" property

  "tile-waste"               gint                  : Read

Maximum waste area of a sliced texture.

Allowed values: >= G_MAXULONG

Default value: 127

The "load-finished" signal

void                user_function                      (ClutterTexture *texture,
                                                        GError         *error,
                                                        gpointer        user_data)      : Run Last

The ::load-finished signal is emitted when a texture load has completed. If there was an error during loading, error will be set, otherwise it will be NULL

Since 1.0

The "pixbuf-change" signal

void                user_function                      (ClutterTexture *texture,
                                                        gpointer        user_data)      : Run Last

The ::pixbuf-change signal is emitted each time the pixbuf used by texture changes.

The "size-change" signal

void                user_function                      (ClutterTexture *texture,
                                                        gint            width,
                                                        gint            height,
                                                        gpointer        user_data)      : Run Last

The ::size-change signal is emitted each time the size of the pixbuf used by texture changes. The new size is given as argument to the callback.