ClutterTexture

ClutterTexture — An actor for displaying and manipulating images.

Synopsis




                    ClutterTexture;
                    ClutterTextureClass;
enum                ClutterTextureFlags;
ClutterActor*       clutter_texture_new                 (void);
ClutterActor*       clutter_texture_new_from_pixbuf     (GdkPixbuf *pixbuf);
ClutterActor*       clutter_texture_new_from_actor      (ClutterActor *actor);
#define             CLUTTER_TEXTURE_ERROR
enum                ClutterTextureError;
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);
gboolean            clutter_texture_set_pixbuf          (ClutterTexture *texture,
                                                         GdkPixbuf *pixbuf,
                                                         GError **error);
GdkPixbuf*          clutter_texture_get_pixbuf          (ClutterTexture *texture);
void                clutter_texture_get_base_size       (ClutterTexture *texture,
                                                         gint *width,
                                                         gint *height);

void                clutter_texture_bind_tile           (ClutterTexture *texture,
                                                         gint index_);
void                clutter_texture_get_n_tiles         (ClutterTexture *texture,
                                                         gint *n_x_tiles,
                                                         gint *n_y_tiles);
void                clutter_texture_get_x_tile_detail   (ClutterTexture *texture,
                                                         gint x_index,
                                                         gint *pos,
                                                         gint *size,
                                                         gint *waste);
void                clutter_texture_get_y_tile_detail   (ClutterTexture *texture,
                                                         gint y_index,
                                                         gint *pos,
                                                         gint *size,
                                                         gint *waste);
gboolean            clutter_texture_has_generated_tiles (ClutterTexture *texture);
gboolean            clutter_texture_is_tiled            (ClutterTexture *texture);


Object Hierarchy


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

Implemented Interfaces

ClutterTexture implements

Properties


  "filter-quality"           gint                  : Read / Write
  "pixbuf"                   GdkPixbuf             : Read / Write
  "pixel-format"             gint                  : Read
  "pixel-type"               gint                  : Read
  "repeat-x"                 gboolean              : Read / Write
  "repeat-y"                 gboolean              : Read / Write
  "sync-size"                gboolean              : Read / Write
  "tile-waste"               gint                  : Read / Write / Construct Only
  "tiled"                    gboolean              : 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_pixbuf() 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/hiding 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_request_coords() and its wrappers. 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


clutter_texture_new ()

ClutterActor*       clutter_texture_new                 (void);

Creates a new empty ClutterTexture object.

Returns : A newly created ClutterTexture object.

clutter_texture_new_from_pixbuf ()

ClutterActor*       clutter_texture_new_from_pixbuf     (GdkPixbuf *pixbuf);

Creates a new ClutterTexture object.

pixbuf : A GdkPixbuf
Returns : A newly created ClutterTexture object.

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 both CLUTTER_FEATURE_TEXTURE_RECTANGLE and CLUTTER_FEATURE_OFFSCREEN features are 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 does not however have to have a parent.

  • 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 clutter_actor_set_pixbuf) will destroy the offscreen texture data and end redirection.

  • clutter_texture_get_pixbuf 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
} 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

Since 0.4


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 4 supported )
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 4 supported )
flags : ClutterTextureFlags
error : return location for a GError, or NULL
Returns : TRUE on success, FALSE on failure. Since 0.6.

clutter_texture_set_pixbuf ()

gboolean            clutter_texture_set_pixbuf          (ClutterTexture *texture,
                                                         GdkPixbuf *pixbuf,
                                                         GError **error);

Sets a ClutterTexture image data from a GdkPixbuf. In case of failure, FALSE is returned and error is set.

texture : A ClutterTexture
pixbuf : A GdkPixbuf
error : Return location for a GError, or NULL
Returns : TRUE if the pixbuf was successfully set

Since 0.4


clutter_texture_get_pixbuf ()

GdkPixbuf*          clutter_texture_get_pixbuf          (ClutterTexture *texture);

Gets a GdkPixbuf representation of the ClutterTexture data. The created GdkPixbuf is not owned by the texture but the caller.

Note: NULL is always returned with OpenGL ES.

texture : A ClutterTexture
Returns : A GdkPixbuf, or NULL on fail.

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

void                clutter_texture_bind_tile           (ClutterTexture *texture,
                                                         gint index_);

Proxies a call to glBindTexture to bind an internal 'tile'.

This function is only useful for ClutterTexture sub-classes and should never be called by an application.

texture : A ClutterTexture
index_ : Tile index to bind

clutter_texture_get_n_tiles ()

void                clutter_texture_get_n_tiles         (ClutterTexture *texture,
                                                         gint *n_x_tiles,
                                                         gint *n_y_tiles);

Retreives internal tile dimensioning.

This function is only useful for ClutterTexture sub-classes and should never be called by an application.

texture : A ClutterTexture
n_x_tiles : Location to store number of tiles in horizonally axis
n_y_tiles : Location to store number of tiles in vertical axis

clutter_texture_get_x_tile_detail ()

void                clutter_texture_get_x_tile_detail   (ClutterTexture *texture,
                                                         gint x_index,
                                                         gint *pos,
                                                         gint *size,
                                                         gint *waste);

Retreives details of a tile on the X axis.

This function is only useful for ClutterTexture sub-classes and should never be called by an application.

texture : A ClutterTexture
x_index : X index of tile to query
pos : Location to store tile's X position
size : Location to store tile's horizontal size in pixels
waste : Location to store tile's horizontal wastage in pixels

clutter_texture_get_y_tile_detail ()

void                clutter_texture_get_y_tile_detail   (ClutterTexture *texture,
                                                         gint y_index,
                                                         gint *pos,
                                                         gint *size,
                                                         gint *waste);

Retreives details of a tile on the Y axis.

This function is only useful for ClutterTexture sub-classes and should never be called by an application.

texture : A ClutterTexture
y_index : Y index of tile to query
pos : Location to store tile's Y position
size : Location to store tile's vertical size in pixels
waste : Location to store tile's vertical wastage in pixels

clutter_texture_has_generated_tiles ()

gboolean            clutter_texture_has_generated_tiles (ClutterTexture *texture);

Checks if ClutterTexture has generated underlying GL texture tiles.

This function is only useful for ClutterTexture sub-classes and should never be called by an application.

texture : A ClutterTexture
Returns : TRUE if texture has pre-generated GL tiles.

clutter_texture_is_tiled ()

gboolean            clutter_texture_is_tiled            (ClutterTexture *texture);

Checks if ClutterTexture is tiled.

This function is only useful for ClutterTexture sub-classes and should never be called by an application.

texture : A ClutterTexture
Returns : TRUE if texture is tiled

Property Details

The "filter-quality" property

  "filter-quality"           gint                  : Read / Write

Values 0 and 1 current only supported, with 0 being lower quality but fast, 1 being better quality but slower. ( Currently just maps to GL_NEAREST / GL_LINEAR ).

Allowed values: >= 0

Default value: 1


The "pixbuf" property

  "pixbuf"                   GdkPixbuf             : Read / Write

Pixbuf source for Texture.


The "pixel-format" property

  "pixel-format"             gint                  : Read

GL texture pixel format used.

Allowed values: >= 0

Default value: 6408


The "pixel-type" property

  "pixel-type"               gint                  : Read

GL texture pixel type used.

Allowed values: >= 0

Default value: 5121


The "repeat-x" property

  "repeat-x"                 gboolean              : Read / Write

Reapeat underlying pixbuf rather than scale in x direction. Currently ignored.

Default value: FALSE


The "repeat-y" property

  "repeat-y"                 gboolean              : Read / Write

Reapeat underlying pixbuf rather than scale in y direction. Currently ignored.

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 tiled textures. Bigger values use less textures, smaller values less texture memory.

Allowed values: >= 0

Default value: 64


The "tiled" property

  "tiled"                    gboolean              : Read / Write / Construct Only

Enables the use of tiled GL textures to more efficiently use available texture memory.

Default value: TRUE

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.