| Clutter 0.6 Reference Manual | ||||
|---|---|---|---|---|
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);
"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
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().
typedef struct {
ClutterActorClass parent_class;
void (*size_change) (ClutterTexture *texture,
gint width,
gint height);
void (*pixbuf_change) (ClutterTexture *texture);
} ClutterTextureClass;
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
ClutterActor* clutter_texture_new (void);
Creates a new empty ClutterTexture object.
| Returns : | A newly created ClutterTexture object. |
ClutterActor* clutter_texture_new_from_pixbuf (GdkPixbuf *pixbuf);
Creates a new ClutterTexture object.
pixbuf : |
A GdkPixbuf |
| Returns : | A newly created ClutterTexture object. |
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
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
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.
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.
|
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.
|
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
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.
|
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. |
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 |
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 |
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 |
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 |
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.
|
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
|
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
pixel-format" property"pixel-format" gint : Read
GL texture pixel format used.
Allowed values: >= 0
Default value: 6408
pixel-type" property"pixel-type" gint : Read
GL texture pixel type used.
Allowed values: >= 0
Default value: 5121
repeat-x" property"repeat-x" gboolean : Read / Write
Reapeat underlying pixbuf rather than scale in x direction. Currently ignored.
Default value: FALSE
repeat-y" property"repeat-y" gboolean : Read / Write
Reapeat underlying pixbuf rather than scale in y direction. Currently ignored.
Default value: FALSE
sync-size" property"sync-size" gboolean : Read / Write
Auto sync size of actor to underlying pixbuf dimensions.
Default value: TRUE
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
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. |
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. |