## ClutterTexture

ClutterTexture — An actor for displaying and manipulating images.

## Synopsis

                        ClutterTexture;
                        ClutterTextureClass;
    enum                ClutterTextureFlags;
    enum                ClutterTextureQuality;
    ClutterActor*       clutter_texture_new                 (void);
    ClutterActor*       clutter_texture_new_from_file       (const gchar *filename,
                                                             GError **error);
    ClutterActor*       clutter_texture_new_from_actor      (ClutterActor *actor);
    #define             CLUTTER_TEXTURE_ERROR
    enum                ClutterTextureError;
    gboolean            clutter_texture_set_from_file       (ClutterTexture *texture,
                                                             const gchar *filename,
                                                             GError **error);
    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);
    gboolean            clutter_texture_set_from_yuv_data   (ClutterTexture *texture,
                                                             const guchar *data,
                                                             gint width,
                                                             gint height,
                                                             ClutterTextureFlags flags,
                                                             GError **error);
    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);
    void                clutter_texture_get_base_size       (ClutterTexture *texture,
                                                             gint *width,
                                                             gint *height);
    ClutterTextureQuality clutter_texture_get_filter_quality
                                                            (ClutterTexture *texture);
    void                clutter_texture_set_filter_quality  (ClutterTexture *texture,
                                                             ClutterTextureQuality filter_quality);
    gint                clutter_texture_get_max_tile_waste  (ClutterTexture *texture);
    void                clutter_texture_set_max_tile_waste  (ClutterTexture *texture,
                                                             gint max_tile_waste);
    CoglHandle          clutter_texture_get_cogl_texture    (ClutterTexture *texture);
    void                clutter_texture_set_cogl_texture    (ClutterTexture *texture,
                                                             CoglHandle cogl_tex);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----ClutterTexture

## Implemented Interfaces

ClutterTexture implements

## Properties

      "cogl-texture"             ClutterTextureHandle*  : Read / Write
      "disable-slicing"          gboolean              : Read / Write / Construct Only
      "filename"                 gchar*                : Write
      "filter-quality"           ClutterTextureQuality  : Read / Write / Construct
      "keep-aspect-ratio"        gboolean              : Read / Write
      "pixel-format"             gint                  : Read
      "repeat-x"                 gboolean              : Read / Write
      "repeat-y"                 gboolean              : Read / Write
      "sync-size"                gboolean              : Read / Write
      "tile-waste"               gint                  : Read / Write / Construct Only

## Signals

      "pixbuf-change"                                  : Run Last
      "size-change"                                    : Run Last

## Description

ClutterTexture is a base class for displaying and manipulating pixel buffer type data.

The `clutter_texture_set_from_rgb_data()` and `clutter_texture_set_from_file()` functions are used to copy image data into texture memory and subsequently realize the texture.

If texture reads are supported by underlying GL implementation, unrealizing frees image data from texture memory moving to main system memory. Re-realizing then performs the opposite operation. This process allows basic management of commonly limited available texture memory.

Note: a ClutterTexture will scale its contents to fit the bounding box requested using `clutter_actor_set_size()`. To display an area of a texture without scaling, you should set the clip area using `clutter_actor_set_clip()`.

## Details

### ClutterTexture

    typedef struct _ClutterTexture ClutterTexture;

### ClutterTextureClass

    typedef struct {
      ClutterActorClass parent_class;

      void (*size_change)   (ClutterTexture *texture,
    		         gint            width,
    		         gint            height);
      void (*pixbuf_change) (ClutterTexture *texture);
    } ClutterTextureClass;

### enum ClutterTextureFlags

    typedef enum { /*< prefix=CLUTTER_TEXTURE >*/
        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()`.

`CLUTTER_TEXTURE_RGB_FLAG_BGR` | FIXME
`CLUTTER_TEXTURE_RGB_FLAG_PREMULT` | FIXME
`CLUTTER_TEXTURE_YUV_FLAG_YUV2` | FIXME

Since 0.4

### enum ClutterTextureQuality

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

Enumaration controlling the texture quality.

`CLUTTER_TEXTURE_QUALITY_LOW` | fastest rendering will use nearest neighbour interpolation when rendering. good setting.
`CLUTTER_TEXTURE_QUALITY_MEDIUM` | higher quality rendering without using extra resources.
`CLUTTER_TEXTURE_QUALITY_HIGH` | render the texture with the best quality available using extra memory.

Since 0.8

### clutter_texture_new ()

    ClutterActor*       clutter_texture_new                 (void);

Creates a new empty ClutterTexture object.

Returns : | A newly created 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.

`filename` : | The name of an image file to load.
`error` : | Return locatoin for an error.
Returns : | A newly created ClutterTexture object or NULL on error.

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:

- The source actor must be made visible (i.e by calling clutter_actor_show).

- The source actor must have a parent in order for it to be allocated a size from the layouting mechanism. If the source actor does not have a parent when this function is called then the ClutterTexture will adopt it and allocate it at its preferred size. Using this you can clone an actor that is otherwise not displayed. Because of this feature if you do intend to display the source actor then you must make sure that the actor is parented before calling `clutter_texture_new_from_actor()` or that you unparent it before adding it to a container.

- When getting the image for the clone texture, Clutter will attempt to render the source actor exactly as it would appear if it was rendered on screen. The source actor's parent transformations are taken into account. Therefore if your source actor is rotated along the X or Y axes so that it has some depth, the texture will appear differently depending on the on-screen location of the source actor. While painting the source actor, Clutter will set up a temporary asymmetric perspective matrix as the projection matrix so that the source actor will be projected as if a small section of the screen was being viewed. Before version 0.8.2, an orthogonal identity projection was used which meant that the source actor would be clipped if any part of it was not on the zero Z-plane.

- Avoid reparenting the source with the created texture.

- A group can be padded with a transparent rectangle as to provide a border to contents for shader output (blurring text for example).

- The texture will automatically resize to contain a further transformed source. However, this involves overhead and can be avoided by placing the source actor in a bounding group sized large enough to contain any child tranformations.

- Uploading pixel data to the texture (e.g by using `clutter_actor_set_from_file()`) will destroy the offscreen texture data and end redirection.

- `cogl_texture_get_data()` with the handle returned by `clutter_texture_get_cogl_texture()` can be used to read the offscreen texture pixels into a pixbuf.

`actor` : | A source ClutterActor
Returns : | A newly created ClutterTexture object, or `NULL` on failure.

Since 0.6

### CLUTTER_TEXTURE_ERROR

    #define CLUTTER_TEXTURE_ERROR   (clutter_texture_error_quark ())

### 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

`CLUTTER_TEXTURE_ERROR_OUT_OF_MEMORY` | OOM condition
`CLUTTER_TEXTURE_ERROR_NO_YUV` | YUV operation attempted but no YUV support found
`CLUTTER_TEXTURE_ERROR_BAD_FORMAT` | The requested format for clutter_texture_set_from_rgb_data or clutter_texture_set_from_yuv_data is unsupported.

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.

`texture` : | A ClutterTexture
`filename` : | The filename of the image in GLib file name encoding
`error` : | Return location for a GError, or `NULL`
Returns : | `TRUE` if the image was successfully loaded and set

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.

Note: This function is likely to change in future versions.

`texture` : | A ClutterTexture
`data` : | Image data in RGBA type colorspace.
`has_alpha` : | Set to TRUE if image data has an alpha channel.
`width` : | Width in pixels of image data.
`height` : | Height in pixels of image data
`rowstride` : | Distance in bytes between row starts.
`bpp` : | bytes per pixel (Currently only 3 and 4 supported, depending on `has_alpha`)
`flags` : | ClutterTextureFlags
`error` : | return location for a GError, or `NULL`.
Returns : | `TRUE` on success, `FALSE` on failure.

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.

This function is likely to change in future versions.

`texture` : | A ClutterTexture
`data` : | Image data in YUV type colorspace.
`width` : | Width in pixels of image data.
`height` : | Height in pixels of image data
`flags` : | ClutterTextureFlags
`error` : | Return location for a GError, or `NULL`.
Returns : | `TRUE` if the texture was successfully updated 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.

`texture` : | A ClutterTexture
`data` : | Image data in RGB type colorspace.
`has_alpha` : | Set to TRUE if image data has an alpha channel.
`x` : | X coordinate of upper left corner of region to update.
`y` : | Y coordinate of upper left corner of region to update.
`width` : | Width in pixels of region to update.
`height` : | Height in pixels of region to update.
`rowstride` : | Distance in bytes between row starts on source buffer.
`bpp` : | bytes per pixel (Currently only 3 and 4 supported, depending on `has_alpha`)
`flags` : | ClutterTextureFlags
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure. 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 texture pixbuf data.

`texture` : | A ClutterTexture
`width` : | Pointer to gint to be populated with width value if non NULL.
`height` : | Pointer to gint to be populated with height value if non NULL.

### clutter_texture_get_filter_quality ()

    ClutterTextureQuality clutter_texture_get_filter_quality
                                                            (ClutterTexture *texture);

Gets the filter quality used when scaling a texture.

`texture` : | A ClutterTexture
Returns : | The filter quality value.

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`.

`texture` : | a ClutterTexture
`filter_quality` : | new filter quality value

Since 0.8

### 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.

`texture` : | A ClutterTexture
Returns : | The maximum waste or -1 if the texture waste is unlimited.

Since 0.8

### clutter_texture_set_max_tile_waste ()

    void                clutter_texture_set_max_tile_waste  (ClutterTexture *texture,
                                                             gint max_tile_waste);

Sets the maximum number of pixels in either axis that can be wasted for an individual texture slice. If -1 is specified then the texture is forced not to be sliced and the texture creation will fail if the hardware can't create a texture large enough.

The value is only used when first creating a texture so changing it after the texture data has been set has no effect.

`texture` : | A ClutterTexture
`max_tile_waste` : | Maximum amount of waste in pixels or -1

Since 0.8

### clutter_texture_get_cogl_texture ()

    CoglHandle          clutter_texture_get_cogl_texture    (ClutterTexture *texture);

Returns a 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_texture_ref on it.

`texture` : | A ClutterTexture
Returns : | COGL texture handle

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_texture_unref.

`texture` : | A ClutterTexture
`cogl_tex` : | A CoglHandle for a texture

Since 0.8

## Property Details

### The `"cogl-texture"` property

      "cogl-texture"             ClutterTextureHandle*  : Read / Write

The underlying COGL texture handle used to draw this actor.

### The `"disable-slicing"` property

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

Force the underlying texture to be singlularand not made of of smaller space saving inidivual textures.

Default value: FALSE

### The `"filename"` property

      "filename"                 gchar*                : Write

The full path of the file containing the texture.

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 `"pixel-format"` property

      "pixel-format"             gint                  : Read

CoglPixelFormat to use.

Allowed values: >= 0

Default value: 19

### The `"repeat-x"` property

      "repeat-x"                 gboolean              : Read / Write

Repeat underlying pixbuf rather than scale in x direction.

Default value: FALSE

### The `"repeat-y"` property

      "repeat-y"                 gboolean              : Read / Write

Repeat underlying pixbuf rather than scale in y direction.

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 / Write / Construct Only

Max wastage dimension of a texture when using sliced textures or -1 to disable slicing. Bigger values use less textures, smaller values less texture memory.

Allowed values: >= -1

Default value: 64

## Signal Details

### 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.

`texture` : | the texture which received the signal
`user_data` : | user data set when the signal handler was connected.

### 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.

`texture` : | the texture which received the signal
`width` : | the width of the new texture
`height` : | the height of the new texture
`user_data` : | user data set when the signal handler was connected.