ClutterTexture

ClutterTexture — An actor for displaying and manipulating images.

Synopsis

                    ClutterTexture;
                    ClutterTextureClass;
enum                ClutterTextureFlags;
enum                ClutterTextureQuality;
ClutterActor*       clutter_texture_new                 (void);
ClutterActor*       clutter_texture_new_from_file       (const gchar *filename,
                                                         GError **error);
ClutterActor*       clutter_texture_new_from_actor      (ClutterActor *actor);
#define             CLUTTER_TEXTURE_ERROR
enum                ClutterTextureError;
gboolean            clutter_texture_set_from_file       (ClutterTexture *texture,
                                                         const gchar *filename,
                                                         GError **error);
gboolean            clutter_texture_set_from_rgb_data   (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gboolean has_alpha,
                                                         gint width,
                                                         gint height,
                                                         gint rowstride,
                                                         gint bpp,
                                                         ClutterTextureFlags flags,
                                                         GError **error);
gboolean            clutter_texture_set_from_yuv_data   (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gint width,
                                                         gint height,
                                                         ClutterTextureFlags flags,
                                                         GError **error);
gboolean            clutter_texture_set_area_from_rgb_data
                                                        (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gboolean has_alpha,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height,
                                                         gint rowstride,
                                                         gint bpp,
                                                         ClutterTextureFlags flags,
                                                         GError **error);
void                clutter_texture_get_base_size       (ClutterTexture *texture,
                                                         gint *width,
                                                         gint *height);
ClutterTextureQuality clutter_texture_get_filter_quality
                                                        (ClutterTexture *texture);
void                clutter_texture_set_filter_quality  (ClutterTexture *texture,
                                                         ClutterTextureQuality filter_quality);
gint                clutter_texture_get_max_tile_waste  (ClutterTexture *texture);
void                clutter_texture_set_max_tile_waste  (ClutterTexture *texture,
                                                         gint max_tile_waste);
CoglHandle          clutter_texture_get_cogl_texture    (ClutterTexture *texture);
void                clutter_texture_set_cogl_texture    (ClutterTexture *texture,
                                                         CoglHandle cogl_tex);

Object Hierarchy

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

Implemented Interfaces

ClutterTexture implements

Properties

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

Signals

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

Description

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

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

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

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

Details

ClutterTexture

typedef struct _ClutterTexture ClutterTexture;

ClutterTextureClass

typedef struct {
  ClutterActorClass parent_class;

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

enum ClutterTextureFlags

typedef enum { /*< prefix=CLUTTER_TEXTURE >*/
    CLUTTER_TEXTURE_RGB_FLAG_BGR     = 1 << 1,
    CLUTTER_TEXTURE_RGB_FLAG_PREMULT = 1 << 2, /* FIXME: not handled */
    CLUTTER_TEXTURE_YUV_FLAG_YUV2    = 1 << 3

    /* FIXME: add compressed types ? */
} ClutterTextureFlags;

Flags for clutter_texture_set_from_rgb_data() and clutter_texture_set_from_yuv_data().

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

Since 0.4

enum ClutterTextureQuality

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

Enumaration controlling the texture quality.

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

Since 0.8

clutter_texture_new ()

ClutterActor*       clutter_texture_new                 (void);

Creates a new empty ClutterTexture object.

Returns :

A newly created ClutterTexture object.

clutter_texture_new_from_file ()

ClutterActor*       clutter_texture_new_from_file       (const gchar *filename,
                                                         GError **error);

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

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

Since 0.8

clutter_texture_new_from_actor ()

ClutterActor*       clutter_texture_new_from_actor      (ClutterActor *actor);

Creates a new ClutterTexture object with its source a prexisting actor (and associated children). The textures content will contain 'live' redirected output of the actors scene.

Note this function is intented as a utility call for uniformly applying shaders to groups and other potential visual effects. It requires that the CLUTTER_FEATURE_OFFSCREEN feature is supported by the current backend and the target system.

Some tips on usage:

The source actor must be made visible (i.e by calling clutter_actor_show).
The source actor must have a parent in order for it to be allocated a size from the layouting mechanism. If the source actor does not have a parent when this function is called then the ClutterTexture will adopt it and allocate it at its preferred size. Using this you can clone an actor that is otherwise not displayed. Because of this feature if you do intend to display the source actor then you must make sure that the actor is parented before calling clutter_texture_new_from_actor() or that you unparent it before adding it to a container.
When getting the image for the clone texture, Clutter will attempt to render the source actor exactly as it would appear if it was rendered on screen. The source actor's parent transformations are taken into account. Therefore if your source actor is rotated along the X or Y axes so that it has some depth, the texture will appear differently depending on the on-screen location of the source actor. While painting the source actor, Clutter will set up a temporary asymmetric perspective matrix as the projection matrix so that the source actor will be projected as if a small section of the screen was being viewed. Before version 0.8.2, an orthogonal identity projection was used which meant that the source actor would be clipped if any part of it was not on the zero Z-plane.
Avoid reparenting the source with the created texture.
A group can be padded with a transparent rectangle as to provide a border to contents for shader output (blurring text for example).
The texture will automatically resize to contain a further transformed source. However, this involves overhead and can be avoided by placing the source actor in a bounding group sized large enough to contain any child tranformations.
Uploading pixel data to the texture (e.g by using clutter_actor_set_from_file()) will destroy the offscreen texture data and end redirection.
cogl_texture_get_data() with the handle returned by clutter_texture_get_cogl_texture() can be used to read the offscreen texture pixels into a pixbuf.

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

Since 0.6

CLUTTER_TEXTURE_ERROR

#define CLUTTER_TEXTURE_ERROR   (clutter_texture_error_quark ())

enum ClutterTextureError

typedef enum {
  CLUTTER_TEXTURE_ERROR_OUT_OF_MEMORY,
  CLUTTER_TEXTURE_ERROR_NO_YUV,
  CLUTTER_TEXTURE_ERROR_BAD_FORMAT
} ClutterTextureError;

Error enumeration for ClutterTexture

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

Since 0.4

clutter_texture_set_from_file ()

gboolean            clutter_texture_set_from_file       (ClutterTexture *texture,
                                                         const gchar *filename,
                                                         GError **error);

Sets the ClutterTexture image data from an image file. In case of failure, FALSE is returned and error is set.

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

Since 0.8

clutter_texture_set_from_rgb_data ()

gboolean            clutter_texture_set_from_rgb_data   (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gboolean has_alpha,
                                                         gint width,
                                                         gint height,
                                                         gint rowstride,
                                                         gint bpp,
                                                         ClutterTextureFlags flags,
                                                         GError **error);

Sets ClutterTexture image data.

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

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

Since 0.4.

clutter_texture_set_from_yuv_data ()

gboolean            clutter_texture_set_from_yuv_data   (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gint width,
                                                         gint height,
                                                         ClutterTextureFlags flags,
                                                         GError **error);

Sets a ClutterTexture from YUV image data. If an error occurred, FALSE is returned and error is set.

This function is likely to change in future versions.

`texture` :	A ClutterTexture
`data` :	Image data in YUV type colorspace.
`width` :	Width in pixels of image data.
`height` :	Height in pixels of image data
`flags` :	ClutterTextureFlags
`error` :	Return location for a GError, or `NULL`.
Returns :	`TRUE` if the texture was successfully updated Since 0.4.

clutter_texture_set_area_from_rgb_data ()

gboolean            clutter_texture_set_area_from_rgb_data
                                                        (ClutterTexture *texture,
                                                         const guchar *data,
                                                         gboolean has_alpha,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height,
                                                         gint rowstride,
                                                         gint bpp,
                                                         ClutterTextureFlags flags,
                                                         GError **error);

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

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

clutter_texture_get_base_size ()

void                clutter_texture_get_base_size       (ClutterTexture *texture,
                                                         gint *width,
                                                         gint *height);

Gets the size in pixels of the untransformed underlying texture pixbuf data.

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

clutter_texture_get_filter_quality ()

ClutterTextureQuality clutter_texture_get_filter_quality
                                                        (ClutterTexture *texture);

Gets the filter quality used when scaling a texture.

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

Since 0.8

clutter_texture_set_filter_quality ()

void                clutter_texture_set_filter_quality  (ClutterTexture *texture,
                                                         ClutterTextureQuality filter_quality);

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

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

Since 0.8

clutter_texture_get_max_tile_waste ()

gint                clutter_texture_get_max_tile_waste  (ClutterTexture *texture);

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

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

Since 0.8

clutter_texture_set_max_tile_waste ()

void                clutter_texture_set_max_tile_waste  (ClutterTexture *texture,
                                                         gint max_tile_waste);

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

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

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

Since 0.8

clutter_texture_get_cogl_texture ()

CoglHandle          clutter_texture_get_cogl_texture    (ClutterTexture *texture);

Returns a handle to the underlying COGL texture used for drawing the actor. No extra reference is taken so if you need to keep the handle then you should call cogl_texture_ref on it.

`texture` :	A ClutterTexture
Returns :	COGL texture handle

Since 0.8

clutter_texture_set_cogl_texture ()

void                clutter_texture_set_cogl_texture    (ClutterTexture *texture,
                                                         CoglHandle cogl_tex);

Replaces the underlying COGL texture drawn by this actor with cogl_tex. A reference to the texture is taken so if the handle is no longer needed it should be deref'd with cogl_texture_unref.

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

Since 0.8

Property Details

The `"cogl-texture"` property

  "cogl-texture"             ClutterTextureHandle*  : Read / Write

The underlying COGL texture handle used to draw this actor.

The `"disable-slicing"` property

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

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

Default value: FALSE

The `"filename"` property

  "filename"                 gchar*                : Write

The full path of the file containing the texture.

Default value: NULL

The `"filter-quality"` property

  "filter-quality"           ClutterTextureQuality  : Read / Write / Construct

Rendering quality used when drawing the texture.

Default value: CLUTTER_TEXTURE_QUALITY_MEDIUM

The `"keep-aspect-ratio"` property

  "keep-aspect-ratio"        gboolean              : Read / Write

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

Default value: FALSE

The `"pixel-format"` property

  "pixel-format"             gint                  : Read

CoglPixelFormat to use.

Allowed values: >= 0

Default value: 19

The `"repeat-x"` property

  "repeat-x"                 gboolean              : Read / Write

Repeat underlying pixbuf rather than scale in x direction.

Default value: FALSE

The `"repeat-y"` property

  "repeat-y"                 gboolean              : Read / Write

Repeat underlying pixbuf rather than scale in y direction.

Default value: FALSE

The `"sync-size"` property

  "sync-size"                gboolean              : Read / Write

Auto sync size of actor to underlying pixbuf dimensions.

Default value: TRUE

The `"tile-waste"` property

  "tile-waste"               gint                  : Read / Write / Construct Only

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

Allowed values: >= -1

Default value: 64

Signal Details

The `"pixbuf-change"` signal

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

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

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

The `"size-change"` signal

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

The ::size-change signal is emitted each time the size of the pixbuf used by texture changes. The new size is given as argument to the callback.

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

			Clutter 0.8.2 Reference Manual
Top \| Description \| Object Hierarchy \| Implemented Interfaces \| Properties \| Signals

ClutterTexture

Synopsis

Object Hierarchy

Implemented Interfaces

Properties

Signals

Description

Details

ClutterTexture

ClutterTextureClass

enum ClutterTextureFlags

enum ClutterTextureQuality

clutter_texture_new ()

clutter_texture_new_from_file ()

clutter_texture_new_from_actor ()

CLUTTER_TEXTURE_ERROR

enum ClutterTextureError

clutter_texture_set_from_file ()

clutter_texture_set_from_rgb_data ()

clutter_texture_set_from_yuv_data ()

clutter_texture_set_area_from_rgb_data ()

clutter_texture_get_base_size ()

clutter_texture_get_filter_quality ()

clutter_texture_set_filter_quality ()

clutter_texture_get_max_tile_waste ()

clutter_texture_set_max_tile_waste ()

clutter_texture_get_cogl_texture ()

clutter_texture_set_cogl_texture ()

Property Details

The "cogl-texture" property

The "disable-slicing" property

The "filename" property

The "filter-quality" property

The "keep-aspect-ratio" property

The "pixel-format" property

The "repeat-x" property

The "repeat-y" property

The "sync-size" property

The "tile-waste" property

Signal Details

The "pixbuf-change" signal

The "size-change" signal

The `"cogl-texture"` property

The `"disable-slicing"` property

The `"filename"` property

The `"filter-quality"` property

The `"keep-aspect-ratio"` property

The `"pixel-format"` property

The `"repeat-x"` property

The `"repeat-y"` property

The `"sync-size"` property

The `"tile-waste"` property

The `"pixbuf-change"` signal

The `"size-change"` signal