# Clutter::Texture Class Reference

Inherits Clutter::Actor.

Inherited by Clutter::Cairo::Texture.

Collaboration diagram for Clutter::Texture:
[legend]

List of all members.

## Public Member Functions

virtual | ~Texture ()
ClutterTexture* | gobj ()
| Provides access to the underlying C GObject.
const ClutterTexture* | gobj () const
| Provides access to the underlying C GObject.
ClutterTexture* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
bool | set_from_file (const std::string& filename)
| Sets the Clutter::Texture image data from an image file.
bool | set_from_rgb_data (const guchar* data, bool has_alpha, int width, int height, int rowstride, int bpp, TextureFlags flags)
| Sets Clutter::Texture image data.
bool | set_from_yuv_data (const guchar* data, int width, int height, TextureFlags flags)
| Sets a Clutter::Texture from YUV image data.
bool | set_area_from_rgb_data (const guchar* data, bool has_alpha, int x, int y, int width, int height, int rowstride, int bpp, TextureFlags flags)
| Updates a sub-region of the pixel data in a Clutter::Texture.
void | get_base_size (int& width, int& height) const
| Gets the size in pixels of the untransformed underlying image.
CoglPixelFormat | get_pixel_format () const
| Retrieves the pixel format used by texture.
TextureQuality | get_filter_quality () const
| Gets the filter quality used when scaling a texture.
void | set_filter_quality (TextureQuality filter_quality)
| Sets the filter quality when scaling a texture.
int | get_max_tile_waste () const
| Gets the maximum waste that will be used when creating a texture or -1 if slicing is disabled.
CoglHandle | get_cogl_texture () const
| Retrieves the handle to the underlying COGL texture used for drawing the actor.
void | set_cogl_texture (CoglHandle handle)
| Replaces the underlying COGL texture drawn by this actor with cogl_tex.
CoglHandle | get_cogl_material () const
| Returns a handle to the underlying COGL material used for drawing the actor.
void | set_cogl_material (CoglHandle handle)
| Replaces the underlying Cogl material drawn by this actor with cogl_material.
bool | get_sync_size () const
| Retrieves the value set with get_sync_size().
void | set_sync_size (bool sync_size=true)
| Sets whether texture should have the same preferred size as the underlying image data.
void | get_repeat (bool& repeat_x, bool& repeat_y) const
| Retrieves the horizontal and vertical repeat values set using set_repeat().
void | set_repeat (bool repeat_x=true, bool repeat_y=true)
| Sets whether the texture should repeat horizontally or vertically when the actor size is bigger than the image size.
bool | get_keep_aspect_ratio () const
| Retrieves the value set using get_keep_aspect_ratio().
void | set_keep_aspect_ratio (bool keep_aspect=true)
| Sets whether texture should have a preferred size maintaining the aspect ratio of the underlying image.
bool | get_load_async () const
| Retrieves the value set using get_load_async().
void | set_load_async (bool load_async=true)
| Sets whether texture should use a worker thread to load the data from disk asynchronously.
bool | get_load_data_async () const
| Retrieves the value set by set_load_data_async().
void | set_load_data_async (bool load_async=true)
| Sets whether texture should use a worker thread to load the data from disk asynchronously.
Glib::SignalProxy2< void, int, int > | signal_size_change ()
Glib::SignalProxy0< void > | signal_pixbuf_change ()
Glib::PropertyProxy< CoglHandle > | property_cogl_texture ()
| The underlying COGL texture handle used to draw this actor.
Glib::PropertyProxy_ReadOnly < CoglHandle > | property_cogl_texture () const
| The underlying COGL texture handle used to draw this actor.
Glib::PropertyProxy_ReadOnly < bool > | property_disable_slicing () const
| Force the underlying texture to be singlularand not made of of smaller space saving inidivual textures.
Glib::PropertyProxy_WriteOnly < std::string > | property_filename ()
| The full path of the file containing the texture.
Glib::PropertyProxy < TextureQuality > | property_filter_quality ()
| Rendering quality used when drawing the texture.
Glib::PropertyProxy_ReadOnly < TextureQuality > | property_filter_quality () const
| Rendering quality used when drawing the texture.
Glib::PropertyProxy< bool > | property_keep_aspect_ratio ()
| Keep the aspect ratio of the texture when requesting the preferred width or height.
Glib::PropertyProxy_ReadOnly < bool > | property_keep_aspect_ratio () const
| Keep the aspect ratio of the texture when requesting the preferred width or height.
Glib::PropertyProxy_WriteOnly < bool > | property_load_async ()
| Load files inside a thread to avoid blocking when loading images.
Glib::PropertyProxy_WriteOnly < bool > | property_load_data_async ()
| Decode image data files inside a thread to reduce blocking when loading images.
Glib::PropertyProxy_ReadOnly< int > | property_pixel_format () const
| CoglPixelFormat to use.
Glib::PropertyProxy< bool > | property_repeat_x ()
| Repeat underlying pixbuf rather than scale in x direction.
Glib::PropertyProxy_ReadOnly < bool > | property_repeat_x () const
| Repeat underlying pixbuf rather than scale in x direction.
Glib::PropertyProxy< bool > | property_repeat_y ()
| Repeat underlying pixbuf rather than scale in y direction.
Glib::PropertyProxy_ReadOnly < bool > | property_repeat_y () const
| Repeat underlying pixbuf rather than scale in y direction.
Glib::PropertyProxy< bool > | property_sync_size ()
| Auto sync size of actor to underlying pixbuf dimensions.
Glib::PropertyProxy_ReadOnly < bool > | property_sync_size () const
| Auto sync size of actor to underlying pixbuf dimensions.
Glib::PropertyProxy_ReadOnly< int > | property_tile_waste () const
| Maximum waste area of a sliced texture.

## Static Public Member Functions

static Glib::RefPtr< Texture > | create ()
static Glib::RefPtr< Texture > | create_from_file (const std::string& filename)

## Protected Member Functions

| Texture ()
virtual void | on_size_change (int width, int height)
virtual void | on_pixbuf_change ()

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Clutter::Texture > | wrap (ClutterTexture* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Constructor & Destructor Documentation

virtual Clutter::Texture::~Texture | ( |  | ) | `[virtual]`

Reimplemented in Clutter::Cairo::Texture.

Clutter::Texture::Texture | ( |  | ) | `[protected]`

## Member Function Documentation

static Glib::RefPtr<Texture> Clutter::Texture::create | ( |  | ) | `[static]`

static Glib::RefPtr<Texture> Clutter::Texture::create_from_file | ( | const std::string & | filename | ) | `[static]`

void Clutter::Texture::get_base_size | ( | int & | width,
|  | int & | height |
| ) |  |  | const

Gets the size in pixels of the untransformed underlying image.

Parameters:

  | width | Return location for the width, or `0`.
  | height | Return location for the height, or `0`.

CoglHandle Clutter::Texture::get_cogl_material | ( |  | ) | const

Returns a handle to the underlying COGL material 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.

Since cluttermm 1.0:

Returns:
  COGL material handle.

CoglHandle Clutter::Texture::get_cogl_texture | ( |  | ) | const

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 Clutter::Texture. If you need to access the other layers you should use get_cogl_material() instead and use the Cogl::Material API.

Since cluttermm 0.8:

Returns:
  COGL texture handle.

TextureQuality Clutter::Texture::get_filter_quality | ( |  | ) | const

Gets the filter quality used when scaling a texture.

Since cluttermm 0.8:

Returns:
  The filter quality value.

bool Clutter::Texture::get_keep_aspect_ratio | ( |  | ) | const

Retrieves the value set using get_keep_aspect_ratio().

Since cluttermm 1.0:

Returns:
  `true` if the Clutter::Texture should maintain the aspect ratio of the underlying image.

bool Clutter::Texture::get_load_async | ( |  | ) | const

Retrieves the value set using get_load_async().

Since cluttermm 1.0:

Returns:
  `true` if the Clutter::Texture should load the data from disk asynchronously.

bool Clutter::Texture::get_load_data_async | ( |  | ) | const

Retrieves the value set by set_load_data_async().

Since cluttermm 1.0:

Returns:
  `true` if the Clutter::Texture should load the image data from a file asynchronously.

int Clutter::Texture::get_max_tile_waste | ( |  | ) | const

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

Since cluttermm 0.8:

Returns:
  The maximum waste or -1 if the texture waste is unlimited.

CoglPixelFormat Clutter::Texture::get_pixel_format | ( |  | ) | const

Retrieves the pixel format used by texture.

This is equivalent to:

|[ handle = clutter_texture_get_pixel_format (texture);

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

Since cluttermm 1.0:

Returns:
  A Cogl::PixelFormat value.

void Clutter::Texture::get_repeat | ( | bool & | repeat_x,
|  | bool & | repeat_y |
| ) |  |  | const

Retrieves the horizontal and vertical repeat values set using set_repeat().

Since cluttermm 1.0:

Parameters:

  | repeat_x | Return location for the horizontal repeat.
  | repeat_y | Return location for the vertical repeat.

bool Clutter::Texture::get_sync_size | ( |  | ) | const

Retrieves the value set with get_sync_size().

Since cluttermm 1.0:

Returns:
  `true` if the Clutter::Texture should have the same preferred size of the underlying image data.

const ClutterTexture* Clutter::Texture::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Clutter::Actor.

Reimplemented in Clutter::Cairo::Texture.

ClutterTexture* Clutter::Texture::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Clutter::Actor.

Reimplemented in Clutter::Cairo::Texture.

ClutterTexture* Clutter::Texture::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Reimplemented from Clutter::Actor.

Reimplemented in Clutter::Cairo::Texture.

virtual void Clutter::Texture::on_pixbuf_change | ( |  | ) | `[protected, virtual]`

virtual void Clutter::Texture::on_size_change | ( | int | width,
|  | int | height |
| ) |  |  | `[protected, virtual]`

Glib::PropertyProxy_ReadOnly<CoglHandle> Clutter::Texture::property_cogl_texture | ( |  | ) | const

The underlying COGL texture handle used to draw this actor.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<CoglHandle> Clutter::Texture::property_cogl_texture | ( |  | ) |

The underlying COGL texture handle used to draw this actor.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Texture::property_disable_slicing | ( |  | ) | const

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

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_WriteOnly<std::string> Clutter::Texture::property_filename | ( |  | ) |

The full path of the file containing the texture.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<TextureQuality> Clutter::Texture::property_filter_quality | ( |  | ) | const

Rendering quality used when drawing the texture.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<TextureQuality> Clutter::Texture::property_filter_quality | ( |  | ) |

Rendering quality used when drawing the texture.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Texture::property_keep_aspect_ratio | ( |  | ) | const

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

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Clutter::Texture::property_keep_aspect_ratio | ( |  | ) |

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

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_WriteOnly<bool> Clutter::Texture::property_load_async | ( |  | ) |

Load files inside a thread to avoid blocking when loading images.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_WriteOnly<bool> Clutter::Texture::property_load_data_async | ( |  | ) |

Decode image data files inside a thread to reduce blocking when loading images.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<int> Clutter::Texture::property_pixel_format | ( |  | ) | const

CoglPixelFormat to use.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Texture::property_repeat_x | ( |  | ) | const

Repeat underlying pixbuf rather than scale in x direction.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Clutter::Texture::property_repeat_x | ( |  | ) |

Repeat underlying pixbuf rather than scale in x direction.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Texture::property_repeat_y | ( |  | ) | const

Repeat underlying pixbuf rather than scale in y direction.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Clutter::Texture::property_repeat_y | ( |  | ) |

Repeat underlying pixbuf rather than scale in y direction.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Clutter::Texture::property_sync_size | ( |  | ) | const

Auto sync size of actor to underlying pixbuf dimensions.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Clutter::Texture::property_sync_size | ( |  | ) |

Auto sync size of actor to underlying pixbuf dimensions.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<int> Clutter::Texture::property_tile_waste | ( |  | ) | const

Maximum waste area of a sliced texture.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

bool Clutter::Texture::set_area_from_rgb_data | ( | const guchar * | data,
|  | bool | has_alpha,
|  | int | x,
|  | int | y,
|  | int | width,
|  | int | height,
|  | int | rowstride,
|  | int | bpp,
|  | TextureFlags | flags |
| ) |  |  |

Updates a sub-region of the pixel data in a Clutter::Texture.

Since cluttermm 0.6:

Parameters:

  | 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 | Clutter::TextureFlags.

Returns:
  `true` on success, `false` on failure.

void Clutter::Texture::set_cogl_material | ( | CoglHandle | handle | ) |

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. Clutter::Texture requires that the material have a texture layer so you should set one on the material before calling this function.

Since cluttermm 0.8:

Parameters:

  | cogl_material | A CoglHandle for a material.

void Clutter::Texture::set_cogl_texture | ( | CoglHandle | handle | ) |

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.

This should not be called on an unrealizable texture (one that isn't inside a stage). (Currently the ClutterTexture implementation relies on being able to have a GL texture while unrealized, which means you can get away with it, but it's not correct and may change in the future.)

Since cluttermm 0.8:

Parameters:

  | cogl_tex | A CoglHandle for a texture.

void Clutter::Texture::set_filter_quality | ( | TextureQuality | 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 cluttermm 0.8:

Parameters:

  | filter_quality | New filter quality value.

bool Clutter::Texture::set_from_file | ( | const std::string & | filename | ) |

Sets the Clutter::Texture image data from an image file.

In case of failure, `false` is returned and error is set.

If Clutter::Texture: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. Clutter::Texture::size-change will be emitten when the size of the texture is available and Clutter::Texture::load-finished will be emitted when the image has been loaded or if an error occurred.

Since cluttermm 0.8:

Parameters:

  | filename | The filename of the image in GLib file name encoding.

Returns:
  `true` if the image was successfully loaded and set.

bool Clutter::Texture::set_from_rgb_data | ( | const guchar * | data,
|  | bool | has_alpha,
|  | int | width,
|  | int | height,
|  | int | rowstride,
|  | int | bpp,
|  | TextureFlags | flags |
| ) |  |  |

Sets Clutter::Texture image data.

Since cluttermm 0.4:

Parameters:

  | 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 | Clutter::TextureFlags.

Returns:
  `true` on success, `false` on failure.

bool Clutter::Texture::set_from_yuv_data | ( | const guchar * | data,
|  | int | width,
|  | int | height,
|  | TextureFlags | flags |
| ) |  |  |

Sets a Clutter::Texture from YUV image data.

If an error occurred, `false` is returned and error is set.

Since cluttermm 0.4:

Parameters:

  | data | Image data in YUV type colorspace.
  | width | Width in pixels of image data.
  | height | Height in pixels of image data.
  | flags | Clutter::TextureFlags.

Returns:
  `true` if the texture was successfully updated.

void Clutter::Texture::set_keep_aspect_ratio | ( | bool | keep_aspect = `true` | ) |

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

Since cluttermm 1.0:

Parameters:

  | keep_aspect | `true` to maintain aspect ratio.

void Clutter::Texture::set_load_async | ( | bool | load_async = `true` | ) |

Sets whether texture should use a worker thread to load the data from disk asynchronously.

Setting load_async to `true` will make set_from_file() return immediately.

See the Clutter::Texture:load-async property documentation, and set_load_data_async().

Since cluttermm 1.0:

Parameters:

  | load_async | `true` if the texture should asynchronously load data from a filename.

void Clutter::Texture::set_load_data_async | ( | bool | load_async = `true` | ) |

Sets whether texture should use a worker thread to load the data from disk asynchronously.

Setting load_async to `true` will make set_from_file() block until the Clutter::Texture has determined the width and height of the image data.

See the Clutter::Texture:load-async property documentation, and set_load_async().

Since cluttermm 1.0:

Parameters:

  | load_async | `true` if the texture should asynchronously load data from a filename.

void Clutter::Texture::set_repeat | ( | bool | repeat_x = `true`,
|  | bool | repeat_y = `true` |
| ) |  |  |

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

Since cluttermm 1.0:

Parameters:

  | repeat_x | `true` if the texture should repeat horizontally.
  | repeat_y | `true` if the texture should repeat vertically.

void Clutter::Texture::set_sync_size | ( | bool | sync_size = `true` | ) |

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

Since cluttermm 1.0:

Parameters:

  | sync_size | `true` if the texture should have the same size of the underlying image data.

Glib::SignalProxy0< void > Clutter::Texture::signal_pixbuf_change | ( |  | ) |

Prototype:
  `void on_my_pixbuf_change()`

Glib::SignalProxy2< void,int,int > Clutter::Texture::signal_size_change | ( |  | ) |

Prototype:
  `void on_my_size_change(int width, int height)`

## Friends And Related Function Documentation

Glib::RefPtr< Clutter::Texture > wrap | ( | ClutterTexture * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- cluttermm/texture.h