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);
CoglHandle          clutter_texture_get_cogl_material   (ClutterTexture *texture);
void                clutter_texture_set_cogl_material   (ClutterTexture *texture,
                                                         CoglHandle cogl_material);

Object Hierarchy

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

Implemented Interfaces

ClutterTexture implements ClutterScriptable.

Properties

  "cogl-material"            CoglHandle*           : Read / Write
  "cogl-texture"             CoglHandle*           : Read / Write
  "disable-slicing"          gboolean              : Read / Write / Construct Only
  "filename"                 gchar*                : Write
  "filter-quality"           ClutterTextureQuality  : Read / Write / Construct
  "keep-aspect-ratio"        gboolean              : Read / Write
  "load-async"               gboolean              : Write / Construct
  "load-data-async"          gboolean              : Write / Construct
  "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

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

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;

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

Since 0.1


ClutterTextureClass

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

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

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

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

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

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 :

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

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.

texture :

A ClutterTexture

Returns :

COGL material handle

Since 1.0


clutter_texture_set_cogl_material ()

void                clutter_texture_set_cogl_material   (ClutterTexture *texture,
                                                         CoglHandle cogl_material);

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_material :

A CoglHandle for a material

Since 0.8

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

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 "load-async" property

  "load-async"               gboolean              : Write / Construct

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

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

Default value: FALSE

Since 1.0


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: 63

Signal Details

The "load-finished" signal

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

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

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

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.