Clutter.Texture¶

Subclasses:: Clutter.CairoTexture

Methods¶

Inherited:: Clutter.Actor (238), GObject.Object (37), Clutter.Animatable (5), Clutter.Container (17), Clutter.Scriptable (4)
Structs:: GObject.ObjectClass (5)

class	`new` ()
class	`new_from_actor` (actor)
class	`new_from_file` (filename)
	`get_base_size` ()
	`get_cogl_material` ()
	`get_cogl_texture` ()
	`get_filter_quality` ()
	`get_keep_aspect_ratio` ()
	`get_load_async` ()
	`get_load_data_async` ()
	`get_max_tile_waste` ()
	`get_pick_with_alpha` ()
	`get_pixel_format` ()
	`get_repeat` ()
	`get_sync_size` ()
	`set_area_from_rgb_data` (data, has_alpha, x, y, width, height, rowstride, bpp, flags)
	`set_cogl_material` (cogl_material)
	`set_cogl_texture` (cogl_tex)
	`set_filter_quality` (filter_quality)
	`set_from_file` (filename)
	`set_from_rgb_data` (data, has_alpha, width, height, rowstride, bpp, flags)
	`set_from_yuv_data` (data, width, height, flags)
	`set_keep_aspect_ratio` (keep_aspect)
	`set_load_async` (load_async)
	`set_load_data_async` (load_async)
	`set_pick_with_alpha` (pick_with_alpha)
	`set_repeat` (repeat_x, repeat_y)
	`set_sync_size` (sync_size)

Virtual Methods¶

Inherited:: Clutter.Actor (35), GObject.Object (7), Clutter.Animatable (5), Clutter.Container (13), Clutter.Scriptable (4)

	`do_load_finished` (error)
	`do_pixbuf_change` ()
	`do_size_change` (width, height)

Properties¶

Inherited:: Clutter.Actor (82)

Name	Type	Flags	Short Description
`disable-slicing`	`bool`	r/w/co	Forces the underlying texture to be singular and not made of smaller space saving individual textures
`filename`	`str`	r/w	The path of the file containing the image data `deprecated`
`filter-quality`	`Clutter.TextureQuality`	r/w/c	Rendering quality used when drawing the texture
`keep-aspect-ratio`	`bool`	r/w	Keep the aspect ratio of the texture when requesting the preferred width or height
`load-async`	`bool`	w	Load files inside a thread to avoid blocking when loading images from disk `deprecated`
`load-data-async`	`bool`	w	Decode image data files inside a thread to reduce blocking when loading images from disk `deprecated`
`pick-with-alpha`	`bool`	r/w	Shape actor with alpha channel when picking
`pixel-format`	`Cogl.PixelFormat`	r	The Cogl pixel format to use
`repeat-x`	`bool`	r/w	Repeat the contents rather than scaling them horizontally
`repeat-y`	`bool`	r/w	Repeat the contents rather than scaling them vertically
`sync-size`	`bool`	r/w	Auto sync size of actor to underlying pixbuf dimensions
`tile-waste`	`int`	r	Maximum waste area of a sliced texture

Signals¶

Inherited:: Clutter.Actor (26), GObject.Object (1), Clutter.Container (3)

Name	Short Description
`load-finished`	The `::load-finished` signal is emitted when a texture load has completed. `deprecated`
`pixbuf-change`	The `::pixbuf-change` signal is emitted each time the pixbuf used by texture changes. `deprecated`
`size-change`	The `::size-change` signal is emitted each time the size of the pixbuf used by texture changes. `deprecated`

Fields¶

Inherited:: Clutter.Actor (26), GObject.Object (1), Clutter.Container (3)

Name	Type	Access	Description
parent	`Clutter.Actor`	r

Class Details¶

class Clutter.Texture(**kwargs)¶

Bases:: Clutter.Actor
Abstract:: No
Structure:: Clutter.TextureClass

The Clutter.Texture structure contains only private data and should be accessed using the provided API

New in version 0.2.

classmethod new()¶

Returns:: A newly created Clutter.Texture object.
Return type:: Clutter.Actor

Creates a new empty Clutter.Texture object.

Deprecated since version 1.12: Use Clutter.Image instead

classmethod new_from_actor(actor)¶

Parameters:: actor (Clutter.Actor) – A source Clutter.Actor
Returns:: A newly created Clutter.Texture object, or None on failure.
Return type:: Clutter.Actor

Creates a new Clutter.Texture 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.FeatureFlags.OFFSCREEN feature is supported by the current backend and the target system.

Some tips on usage:

The source actor must be visible
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 Clutter.Texture 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.

New in version 0.6.

Deprecated since version 1.8: Use the Clutter.OffscreenEffect and Clutter.ShaderEffect directly on the intended Clutter.Actor to replace the functionality of this function.

classmethod new_from_file(filename)¶

Parameters:: filename (str) – The name of an image file to load.
Raises:: GLib.Error
Returns:: A newly created Clutter.Texture object or None on error.
Return type:: Clutter.Actor

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

New in version 0.8.

Deprecated since version 1.12: No direct replacement is available. Use Clutter.Image and platform-specific image loading API, like GdkPixbuf, instead

get_base_size()¶

Returns:

width:: return location for the width, or None
height:: return location for the height, or None

Return type:

(width: int, height: int)

Gets the size in pixels of the untransformed underlying image

Deprecated since version 1.12: Use Clutter.Image and Clutter.Content.get_preferred_size() instead

get_cogl_material()¶

Returns:: a handle for a Cogl.Material. The material is owned by the Clutter.Texture and it should not be unreferenced
Return type:: object

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

New in version 1.0.

Deprecated since version 1.12: No replacement is available; it’s not advisable to modify the Cogl pipeline of an actor. Use a Clutter.Content implementation and modify the pipeline during the paint sequence

get_cogl_texture()¶

Returns:: a #CoglHandle for the texture. The returned handle is owned by the Clutter.Texture and it should not be unreferenced
Return type:: object

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 Clutter.Texture.get_cogl_material() instead and use the Cogl.Material API.

New in version 0.8.

Deprecated since version 1.12: No replacement available; it’s not advisable to modify the Cogl pipeline of an actor. Use a Clutter.Content implementation and set up the pipeline during the paint sequence instead.

get_filter_quality()¶

Returns:: The filter quality value.
Return type:: Clutter.TextureQuality

Gets the filter quality used when scaling a texture.

New in version 0.8.

Deprecated since version 1.12: Use Clutter.Image and Clutter.Actor.get_content_scaling_filters() instead

get_keep_aspect_ratio()¶

Returns:: True if the Clutter.Texture should maintain the aspect ratio of the underlying image
Return type:: bool

Retrieves the value set using Clutter.Texture.set_keep_aspect_ratio()

New in version 1.0.

Deprecated since version 1.12: Use Clutter.Image and Clutter.Actor.get_content_gravity() instead

get_load_async()¶

Returns:: True if the Clutter.Texture should load the data from disk asynchronously
Return type:: bool

Retrieves the value set using Clutter.Texture.set_load_async()

New in version 1.0.

Deprecated since version 1.12: There is no direct replacement for this function

get_load_data_async()¶

Returns:: True if the Clutter.Texture should load the image data from a file asynchronously
Return type:: bool

Retrieves the value set by Clutter.Texture.set_load_data_async()

New in version 1.0.

Deprecated since version 1.12: There is no direct replacement for this function

get_max_tile_waste()¶

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

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

New in version 0.8.

Deprecated since version 1.12: No replacement is available

get_pick_with_alpha()¶

Returns:: True if the Clutter.Texture should define its shape using the alpha channel when picking.
Return type:: bool

Retrieves the value set by Clutter.Texture.set_load_data_async()

New in version 1.4.

Deprecated since version 1.12: There is no direct replacement for this function

get_pixel_format()¶

Returns:: a Cogl.PixelFormat value
Return type:: Cogl.PixelFormat

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

handle = clutter_texture_get_pixel_format (texture);

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

New in version 1.0.

Deprecated since version 1.12: There is no direct replacement for this function

get_repeat()¶

Returns:

repeat_x:: return location for the horizontal repeat
repeat_y:: return location for the vertical repeat

Return type:

(repeat_x: bool, repeat_y: bool)

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

New in version 1.0.

Deprecated since version 1.12: Use Clutter.Image and Clutter.Actor.get_content_repeat() instead

get_sync_size()¶

Returns:: True if the Clutter.Texture should have the same preferred size of the underlying image data
Return type:: bool

Retrieves the value set with Clutter.Texture.set_sync_size()

New in version 1.0.

Deprecated since version 1.12: There is no direct replacement

set_area_from_rgb_data(data, has_alpha, x, y, width, height, rowstride, bpp, flags)¶

Parameters:

data (bytes) – Image data in RGB type colorspace.
has_alpha (bool) – Set to True if image data has an alpha channel.
x (int) – X coordinate of upper left corner of region to update.
y (int) – Y coordinate of upper left corner of region to update.
width (int) – Width in pixels of region to update.
height (int) – Height in pixels of region to update.
rowstride (int) – Distance in bytes between row starts on source buffer.
bpp (int) – bytes per pixel (Currently only 3 and 4 supported, depending on has_alpha)
flags (Clutter.TextureFlags) – Clutter.TextureFlags

Raises:

GLib.Error

Returns:

True on success, False on failure.

Return type:

bool

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

New in version 0.6.

Deprecated since version 1.12: Use Clutter.Image and Clutter.Image.set_area() instead

set_cogl_material(cogl_material)¶

Parameters:: cogl_material (object) – A CoglHandle for a 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. Clutter.Texture requires that the material have a texture layer so you should set one on the material before calling this function.

New in version 0.8.

Deprecated since version 1.12: No replacement is available; it’s not advisable to modify the Cogl pipeline of an actor. Use a Clutter.Content implementation and modify the pipeline during the paint sequence

set_cogl_texture(cogl_tex)¶

Parameters:: cogl_tex (object) – A CoglHandle for a texture

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.

New in version 0.8.

Deprecated since version 1.12: No replacement available; it’s not advisable to modify the Cogl pipeline of an actor. Use a Clutter.Content implementation and set up the pipeline during the paint sequence instead.

set_filter_quality(filter_quality)¶

Parameters:: filter_quality (Clutter.TextureQuality) – new filter quality value

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

New in version 0.8.

Deprecated since version 1.12: Use Clutter.Image and Clutter.Actor.set_content_scaling_filters() instead

set_from_file(filename)¶

Parameters:: filename (str) – The filename of the image in GLib file name encoding
Raises:: GLib.Error
Returns:: True if the image was successfully loaded and set
Return type:: bool

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.

New in version 0.8.

Deprecated since version 1.12: Use Clutter.Image and platform-specific image loading API, like GdkPixbuf, instead

set_from_rgb_data(data, has_alpha, width, height, rowstride, bpp, flags)¶

Parameters:

data (bytes) – image data in RGBA type colorspace.
has_alpha (bool) – set to True if image data has an alpha channel.
width (int) – width in pixels of image data.
height (int) – height in pixels of image data
rowstride (int) – distance in bytes between row starts.
bpp (int) – bytes per pixel (currently only 3 and 4 supported, depending on the value of has_alpha)
flags (Clutter.TextureFlags) – Clutter.TextureFlags

Raises:

GLib.Error

Returns:

True on success, False on failure.

Return type:

bool

Sets Clutter.Texture image data.

New in version 0.4.

Deprecated since version 1.12: Use Clutter.Image and Clutter.Image.set_data() instead

set_from_yuv_data(data, width, height, flags)¶

Parameters:

data (bytes) – Image data in YUV type colorspace.
width (int) – Width in pixels of image data.
height (int) – Height in pixels of image data
flags (Clutter.TextureFlags) – Clutter.TextureFlags

Raises:

GLib.Error

Returns:

True if the texture was successfully updated

Return type:

bool

Sets a Clutter.Texture 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 Clutter.Texture material.

New in version 0.4.

Deprecated since version 1.10: Use a custom Clutter.Content implementation and set up the Cogl pipeline using a Clutter.PipelineNode with a fragment shader instead.

set_keep_aspect_ratio(keep_aspect)¶

Parameters:: keep_aspect (bool) – True to maintain aspect ratio

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

New in version 1.0.

Deprecated since version 1.12: Use Clutter.Image and Clutter.Actor.set_content_gravity() with Clutter.ContentGravity.RESIZE_ASPECT instead

set_load_async(load_async)¶

Parameters:: load_async (bool) – True if the texture should asynchronously load data from a filename

Sets whether self 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 Clutter.Texture :load-async property documentation, and Clutter.Texture.set_load_data_async().

New in version 1.0.

Deprecated since version 1.12: There is no direct replacement for this function. Use Clutter.Image and platform-specific API for loading image data asynchronously, like GdkPixbuf

set_load_data_async(load_async)¶

Parameters:: load_async (bool) – True if the texture should asynchronously load data from a filename

Sets whether self 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 Clutter.Texture has determined the width and height of the image data.

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

New in version 1.0.

Deprecated since version 1.12: There is no direct replacement for this function. Use Clutter.Image and platform-specific API for loading image data asynchronously, like GdkPixbuf

set_pick_with_alpha(pick_with_alpha)¶

Parameters:: pick_with_alpha (bool) – True if the alpha channel should affect the picking shape

Sets whether self 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.

New in version 1.4.

Deprecated since version 1.12: There is no direct replacement for this function

set_repeat(repeat_x, repeat_y)¶

Parameters:

repeat_x (bool) – True if the texture should repeat horizontally
repeat_y (bool) – True if the texture should repeat vertically

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

New in version 1.0.

Deprecated since version 1.12: Use Clutter.Image and Clutter.Actor.set_content_repeat() instead

set_sync_size(sync_size)¶

Parameters:: sync_size (bool) – True if the texture should have the same size of the underlying image data

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

New in version 1.0.

Deprecated since version 1.12: No replacement is available. A Clutter.Actor using Clutter.Image with a Clutter.RequestMode.CONTENT_SIZE request mode will automatically bind the preferred size of the content to the preferred size of the actor

do_load_finished(error) virtual¶

Parameters:: error (GLib.Error) –

do_pixbuf_change() virtual¶

do_size_change(width, height) virtual¶

Parameters:

width (int) –
height (int) –

Signal Details¶

Clutter.Texture.signals.load_finished(texture, error)¶

Signal Name:

load-finished

Flags:

RUN_LAST

Parameters:

texture (Clutter.Texture) – The object which received the signal
error (GLib.Error) – A set error, or None

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 None

New in version 1.0.

Deprecated since version 1.12: No replacement is available

Clutter.Texture.signals.pixbuf_change(texture)¶

Signal Name:: pixbuf-change
Flags:: RUN_LAST
Parameters:: texture (Clutter.Texture) – The object which received the signal

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

Deprecated since version 1.12: No replacement is available

Clutter.Texture.signals.size_change(texture, width, height)¶

Signal Name:

size-change

Flags:

RUN_LAST

Parameters:

texture (Clutter.Texture) – The object which received the signal
width (int) – the width of the new texture
height (int) – the height of the new texture

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.

Deprecated since version 1.12: No replacement is available

Property Details¶

Clutter.Texture.props.disable_slicing¶

Name:: disable-slicing
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

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

Clutter.Texture.props.filename¶

Name:: filename
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

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.

Deprecated since version 1.12: Use Clutter.Image and platform-specific image loading API, like GdkPixbuf

Clutter.Texture.props.filter_quality¶

Name:: filter-quality
Type:: Clutter.TextureQuality
Default Value:: Clutter.TextureQuality.MEDIUM
Flags:: READABLE, WRITABLE, CONSTRUCT

Rendering quality used when drawing the texture

Clutter.Texture.props.keep_aspect_ratio¶

Name:: keep-aspect-ratio
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

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

Clutter.Texture.props.load_async¶

Name:: load-async
Type:: bool
Default Value:: False
Flags:: WRITABLE

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 Clutter.Texture ::size-change signal is emitted and when the image has completed loading the Clutter.Texture ::load-finished signal is emitted.

Threading is only enabled if g_thread_init() has been called prior to Clutter.init(), otherwise Clutter.Texture 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().

New in version 1.0.

Deprecated since version 1.12: Use platform-specific image loading API, like GdkPixbuf

Clutter.Texture.props.load_data_async¶

Name:: load-data-async
Type:: bool
Default Value:: False
Flags:: WRITABLE

Like Clutter.Texture :load-async but loads the width and height synchronously causing some blocking.

New in version 1.0.

Deprecated since version 1.12: Use platform-specific image loading API, like GdkPixbuf

Clutter.Texture.props.pick_with_alpha¶

Name:: pick-with-alpha
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Shape actor with alpha channel when picking

Clutter.Texture.props.pixel_format¶

Name:: pixel-format
Type:: Cogl.PixelFormat
Default Value:: Cogl.PixelFormat.RGBA_8888
Flags:: READABLE

The Cogl pixel format to use

Clutter.Texture.props.repeat_x¶

Name:: repeat-x
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Repeat the contents rather than scaling them horizontally

Clutter.Texture.props.repeat_y¶

Name:: repeat-y
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Repeat the contents rather than scaling them vertically

Clutter.Texture.props.sync_size¶

Name:: sync-size
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE

Auto sync size of actor to underlying pixbuf dimensions

Clutter.Texture.props.tile_waste¶

Name:: tile-waste
Type:: int
Default Value:: 127
Flags:: READABLE

Maximum waste area of a sliced texture