Clutter Reference Manual: ClutterTexture

## ClutterTexture ClutterTexture — An actor for displaying and manipulating images. |

## Synopsis

    struct              ClutterTexture;
    struct              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);
    CoglPixelFormat     clutter_texture_get_pixel_format    (ClutterTexture *texture);
    gint                clutter_texture_get_max_tile_waste  (ClutterTexture *texture);

    ClutterTextureQuality clutter_texture_get_filter_quality
                                                            (ClutterTexture *texture);
    void                clutter_texture_set_filter_quality  (ClutterTexture *texture,
                                                             ClutterTextureQuality filter_quality);
    CoglHandle          clutter_texture_get_cogl_texture    (ClutterTexture *texture);
    void                clutter_texture_set_cogl_texture    (ClutterTexture *texture,
                                                             CoglHandle cogl_tex);
    CoglHandle          clutter_texture_get_cogl_material   (ClutterTexture *texture);
    void                clutter_texture_set_cogl_material   (ClutterTexture *texture,
                                                             CoglHandle cogl_material);
    gboolean            clutter_texture_get_sync_size       (ClutterTexture *texture);
    void                clutter_texture_set_sync_size       (ClutterTexture *texture,
                                                             gboolean sync_size);
    void                clutter_texture_get_repeat          (ClutterTexture *texture,
                                                             gboolean *repeat_x,
                                                             gboolean *repeat_y);
    void                clutter_texture_set_repeat          (ClutterTexture *texture,
                                                             gboolean repeat_x,
                                                             gboolean repeat_y);
    gboolean            clutter_texture_get_keep_aspect_ratio
                                                            (ClutterTexture *texture);
    void                clutter_texture_set_keep_aspect_ratio
                                                            (ClutterTexture *texture,
                                                             gboolean keep_aspect);
    gboolean            clutter_texture_get_load_async      (ClutterTexture *texture);
    void                clutter_texture_set_load_async      (ClutterTexture *texture,
                                                             gboolean load_async);
    gboolean            clutter_texture_get_load_data_async (ClutterTexture *texture);
    void                clutter_texture_set_load_data_async (ClutterTexture *texture,
                                                             gboolean load_async);
    gboolean            clutter_texture_get_pick_with_alpha (ClutterTexture *texture);
    void                clutter_texture_set_pick_with_alpha (ClutterTexture *texture,
                                                             gboolean pick_with_alpha);

## Object Hierarchy

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

## Implemented Interfaces

ClutterTexture implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Properties

      "cogl-material"            CoglHandle*           : Read / Write
      "cogl-texture"             CoglHandle*           : Read / Write
      "disable-slicing"          gboolean              : Read / Write / Construct Only
      "filename"                 gchar*                : Read / Write
      "filter-quality"           ClutterTextureQuality  : Read / Write / Construct
      "keep-aspect-ratio"        gboolean              : Read / Write
      "load-async"               gboolean              : Write
      "load-data-async"          gboolean              : Write
      "pick-with-alpha"          gboolean              : Read / Write
      "pixel-format"             CoglPixelFormat       : Read
      "repeat-x"                 gboolean              : Read / Write
      "repeat-y"                 gboolean              : Read / Write
      "sync-size"                gboolean              : Read / Write
      "tile-waste"               gint                  : Read

## Signals

      "load-finished"                                  : Run Last
      "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.

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

The ClutterTexture API is deprecated since Clutter 1.12. It is strongly recommended to use ClutterImage instead.

## Details

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

`size_change` () | handler for the "size-change" signal
`pixbuf_change` () | handler for the "pixbuf-change" signal
`load_finished` () | handler for the "load-finished" signal

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

`CLUTTER_TEXTURE_NONE` | No flags
`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,
      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);

### Warning

`clutter_texture_new` is deprecated and should not be used in newly-written code. 1.12

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);

### Warning

`clutter_texture_new_from_file` is deprecated and should not be used in newly-written code. 1.12

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);

### Warning

`clutter_texture_new_from_actor` has been deprecated since version 1.8 and should not be used in newly-written code. Use the ClutterOffscreenEffect and ClutterShaderEffect directly on the intended ClutterActor to replace the functionality of this function.

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_texture_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 ())

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

`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);

### Warning

`clutter_texture_set_from_file` is deprecated and should not be used in newly-written code. 1.12

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.

`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);

### Warning

`clutter_texture_set_from_rgb_data` is deprecated and should not be used in newly-written code. 1.12

Sets ClutterTexture image data.

`texture` : | a ClutterTexture
`data` : | image data in RGBA type colorspace. [array]
`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 the value of `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);

### Warning

`clutter_texture_set_from_yuv_data` has been deprecated since version 1.10 and should not be used in newly-written code. Use `clutter_texture_get_cogl_material()` and the Cogl API to install a fragment shader for decoding YUV formats on the GPU

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.

`texture` : | A ClutterTexture
`data` : | Image data in YUV type colorspace. [array]
`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);

### Warning

`clutter_texture_set_area_from_rgb_data` is deprecated and should not be used in newly-written code. 1.12

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

`texture` : | A ClutterTexture
`data` : | Image data in RGB type colorspace. [array]
`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);

### Warning

`clutter_texture_get_base_size` is deprecated and should not be used in newly-written code. 1.12

Gets the size in pixels of the untransformed underlying image

`texture` : | a ClutterTexture
`width` : | return location for the width, or `NULL`. [out]
`height` : | return location for the height, or `NULL`. [out]

### clutter_texture_get_pixel_format ()

    CoglPixelFormat     clutter_texture_get_pixel_format    (ClutterTexture *texture);

### Warning

`clutter_texture_get_pixel_format` is deprecated and should not be used in newly-written code. 1.12

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);

`texture` : | a ClutterTexture
Returns : | a CoglPixelFormat value

Since 1.0

### clutter_texture_get_max_tile_waste ()

    gint                clutter_texture_get_max_tile_waste  (ClutterTexture *texture);

### Warning

`clutter_texture_get_max_tile_waste` is deprecated and should not be used in newly-written code. 1.12

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_get_filter_quality ()

    ClutterTextureQuality clutter_texture_get_filter_quality
                                                            (ClutterTexture *texture);

### Warning

`clutter_texture_get_filter_quality` is deprecated and should not be used in newly-written code. 1.12

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);

### Warning

`clutter_texture_set_filter_quality` is deprecated and should not be used in newly-written code. 1.12

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_cogl_texture ()

    CoglHandle          clutter_texture_get_cogl_texture    (ClutterTexture *texture);

### Warning

`clutter_texture_get_cogl_texture` is deprecated and should not be used in newly-written code. 1.12

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.

`texture` : | A ClutterTexture
Returns : | a CoglHandle for the texture. The returned handle is owned by the ClutterTexture and it should not be unreferenced. [transfer none]

Since 0.8

### clutter_texture_set_cogl_texture ()

    void                clutter_texture_set_cogl_texture    (ClutterTexture *texture,
                                                             CoglHandle cogl_tex);

### Warning

`clutter_texture_set_cogl_texture` is deprecated and should not be used in newly-written code. 1.12

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.

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

Since 0.8

### clutter_texture_get_cogl_material ()

    CoglHandle          clutter_texture_get_cogl_material   (ClutterTexture *texture);

### Warning

`clutter_texture_get_cogl_material` is deprecated and should not be used in newly-written code. 1.12

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

`texture` : | A ClutterTexture
Returns : | a handle for a CoglMaterial. The material is owned by the ClutterTexture and it should not be unreferenced. [transfer none]

Since 1.0

### clutter_texture_set_cogl_material ()

    void                clutter_texture_set_cogl_material   (ClutterTexture *texture,
                                                             CoglHandle cogl_material);

### Warning

`clutter_texture_set_cogl_material` is deprecated and should not be used in newly-written code. 1.12

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.

`texture` : | A ClutterTexture
`cogl_material` : | A CoglHandle for a material

Since 0.8

### clutter_texture_get_sync_size ()

    gboolean            clutter_texture_get_sync_size       (ClutterTexture *texture);

### Warning

`clutter_texture_get_sync_size` is deprecated and should not be used in newly-written code. 1.12

Retrieves the value set with `clutter_texture_set_sync_size()`

`texture` : | a ClutterTexture
Returns : | `TRUE` if the ClutterTexture should have the same preferred size of the underlying image data

Since 1.0

### clutter_texture_set_sync_size ()

    void                clutter_texture_set_sync_size       (ClutterTexture *texture,
                                                             gboolean sync_size);

### Warning

`clutter_texture_set_sync_size` is deprecated and should not be used in newly-written code. 1.12

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

`texture` : | a ClutterTexture
`sync_size` : | `TRUE` if the texture should have the same size of the underlying image data

Since 1.0

### clutter_texture_get_repeat ()

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

### Warning

`clutter_texture_get_repeat` is deprecated and should not be used in newly-written code. 1.12

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

`texture` : | a ClutterTexture
`repeat_x` : | return location for the horizontal repeat. [out]
`repeat_y` : | return location for the vertical repeat. [out]

Since 1.0

### clutter_texture_set_repeat ()

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

### Warning

`clutter_texture_set_repeat` is deprecated and should not be used in newly-written code. 1.12

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

`texture` : | a ClutterTexture
`repeat_x` : | `TRUE` if the texture should repeat horizontally
`repeat_y` : | `TRUE` if the texture should repeat vertically

Since 1.0

### clutter_texture_get_keep_aspect_ratio ()

    gboolean            clutter_texture_get_keep_aspect_ratio
                                                            (ClutterTexture *texture);

### Warning

`clutter_texture_get_keep_aspect_ratio` is deprecated and should not be used in newly-written code. 1.12

Retrieves the value set using `clutter_texture_set_keep_aspect_ratio()`

`texture` : | a ClutterTexture
Returns : | `TRUE` if the ClutterTexture should maintain the aspect ratio of the underlying image

Since 1.0

### clutter_texture_set_keep_aspect_ratio ()

    void                clutter_texture_set_keep_aspect_ratio
                                                            (ClutterTexture *texture,
                                                             gboolean keep_aspect);

### Warning

`clutter_texture_set_keep_aspect_ratio` is deprecated and should not be used in newly-written code. 1.12

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

`texture` : | a ClutterTexture
`keep_aspect` : | `TRUE` to maintain aspect ratio

Since 1.0

### clutter_texture_get_load_async ()

    gboolean            clutter_texture_get_load_async      (ClutterTexture *texture);

### Warning

`clutter_texture_get_load_async` is deprecated and should not be used in newly-written code. 1.12

Retrieves the value set using `clutter_texture_set_load_async()`

`texture` : | a ClutterTexture
Returns : | `TRUE` if the ClutterTexture should load the data from disk asynchronously

Since 1.0

### clutter_texture_set_load_async ()

    void                clutter_texture_set_load_async      (ClutterTexture *texture,
                                                             gboolean load_async);

### Warning

`clutter_texture_set_load_async` is deprecated and should not be used in newly-written code. 1.12

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

`texture` : | a ClutterTexture
`load_async` : | `TRUE` if the texture should asynchronously load data from a filename

Since 1.0

### clutter_texture_get_load_data_async ()

    gboolean            clutter_texture_get_load_data_async (ClutterTexture *texture);

### Warning

`clutter_texture_get_load_data_async` is deprecated and should not be used in newly-written code. 1.12

Retrieves the value set by `clutter_texture_set_load_data_async()`

`texture` : | a ClutterTexture
Returns : | `TRUE` if the ClutterTexture should load the image data from a file asynchronously

Since 1.0

### clutter_texture_set_load_data_async ()

    void                clutter_texture_set_load_data_async (ClutterTexture *texture,
                                                             gboolean load_async);

### Warning

`clutter_texture_set_load_data_async` is deprecated and should not be used in newly-written code. 1.12

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

`texture` : | a ClutterTexture
`load_async` : | `TRUE` if the texture should asynchronously load data from a filename

Since 1.0

### clutter_texture_get_pick_with_alpha ()

    gboolean            clutter_texture_get_pick_with_alpha (ClutterTexture *texture);

### Warning

`clutter_texture_get_pick_with_alpha` is deprecated and should not be used in newly-written code. 1.12

Retrieves the value set by `clutter_texture_set_load_data_async()`

`texture` : | a ClutterTexture
Returns : | `TRUE` if the ClutterTexture should define its shape using the alpha channel when picking.

Since 1.4

### clutter_texture_set_pick_with_alpha ()

    void                clutter_texture_set_pick_with_alpha (ClutterTexture *texture,
                                                             gboolean pick_with_alpha);

### Warning

`clutter_texture_set_pick_with_alpha` is deprecated and should not be used in newly-written code. 1.12

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.

`texture` : | a ClutterTexture
`pick_with_alpha` : | `TRUE` if the alpha channel should affect the picking shape

Since 1.4

## Property Details

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

### Warning

`ClutterTexture:filename` is deprecated and should not be used in newly-written code. 1.12

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

### Warning

`ClutterTexture:load-async` is deprecated and should not be used in newly-written code. 1.12

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

### Warning

`ClutterTexture:load-data-async` is deprecated and should not be used in newly-written code. 1.12

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: >= -1

Default value: 127

## Signal Details

### The `"load-finished"` signal

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

### Warning

`ClutterTexture::load-finished` is deprecated and should not be used in newly-written code. 1.12

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`

`texture` : | the texture which received the signal
`error` : | A set error, or `NULL`
`user_data` : | user data set when the signal handler was connected.

Since 1.0

### The `"pixbuf-change"` signal

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

### Warning

`ClutterTexture::pixbuf-change` is deprecated and should not be used in newly-written code. 1.12

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

### Warning

`ClutterTexture::size-change` is deprecated and should not be used in newly-written code. 1.12

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.