![]() |
![]() |
![]() |
COGL 0.8.2 Reference Manual | ![]() |
---|---|---|---|---|
CoglTextureVertex; CoglHandle cogl_texture_new_with_size (guint width, guint height, gint max_waste, gboolean auto_mipmap, CoglPixelFormat internal_format); CoglHandle cogl_texture_new_from_file (const gchar *filename, gint max_waste, gboolean auto_mipmap, CoglPixelFormat internal_format, GError **error); CoglHandle cogl_texture_new_from_data (guint width, guint height, gint max_waste, gboolean auto_mipmap, CoglPixelFormat format, CoglPixelFormat internal_format, guint rowstride, const guchar *data); CoglHandle cogl_texture_new_from_foreign (GLuint gl_handle, GLenum gl_target, GLuint width, GLuint height, GLuint x_pot_waste, GLuint y_pot_waste, CoglPixelFormat format); gboolean cogl_is_texture (CoglHandle handle); guint cogl_texture_get_width (CoglHandle handle); guint cogl_texture_get_height (CoglHandle handle); CoglPixelFormat cogl_texture_get_format (CoglHandle handle); guint cogl_texture_get_rowstride (CoglHandle handle); gint cogl_texture_get_max_waste (CoglHandle handle); COGLenum cogl_texture_get_min_filter (CoglHandle handle); COGLenum cogl_texture_get_mag_filter (CoglHandle handle); gboolean cogl_texture_is_sliced (CoglHandle handle); gboolean cogl_texture_get_gl_texture (CoglHandle handle, GLuint *out_gl_handle, GLenum *out_gl_target); gint cogl_texture_get_data (CoglHandle handle, CoglPixelFormat format, guint rowstride, guchar *data); void cogl_texture_set_filters (CoglHandle handle, COGLenum min_filter, COGLenum mag_filter); gboolean cogl_texture_set_region (CoglHandle handle, gint src_x, gint src_y, gint dst_x, gint dst_y, guint dst_width, guint dst_height, gint width, gint height, CoglPixelFormat format, guint rowstride, const guchar *data); CoglHandle cogl_texture_ref (CoglHandle handle); void cogl_texture_unref (CoglHandle handle); void cogl_texture_rectangle (CoglHandle handle, ClutterFixed x1, ClutterFixed y1, ClutterFixed x2, ClutterFixed y2, ClutterFixed tx1, ClutterFixed ty1, ClutterFixed tx2, ClutterFixed ty2); void cogl_texture_polygon (CoglHandle handle, guint n_vertices, CoglTextureVertex *vertices, gboolean use_color);
COGL allows creating and manipulating GL textures using a uniform API that tries to hide all the various complexities of creating, loading and manipulating textures.
typedef struct { ClutterFixed x, y, z; ClutterFixed tx, ty; ClutterColor color; } CoglTextureVertex;
Used to specify vertex information when calling cogl_texture_polygon()
.
ClutterFixed |
Model x-coordinate |
ClutterFixed |
Model y-coordinate |
ClutterFixed |
Model z-coordinate |
ClutterFixed |
Texture x-coordinate |
ClutterFixed |
Texture y-coordinate |
ClutterColor |
The color to use at this vertex. This is ignored if
use_color is FALSE when calling cogl_texture_polygon() .
|
CoglHandle cogl_texture_new_with_size (guint width, guint height, gint max_waste, gboolean auto_mipmap, CoglPixelFormat internal_format);
Create a new texture with specified dimensions and pixel format.
|
width of texture in pixels. |
|
height of texture in pixels. |
|
maximum extra horizontal and|or vertical margin pixels to make texture fit GPU limitations. |
|
enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated. |
|
the CoglPixelFormat to use for the GPU storage of the texture. |
Returns : |
a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if texture creation failed. |
CoglHandle cogl_texture_new_from_file (const gchar *filename, gint max_waste, gboolean auto_mipmap, CoglPixelFormat internal_format, GError **error);
Load an image file from disk.
|
the file to load |
|
maximum extra horizontal and|or vertical margin pixels to make texture fit GPU limitations. |
|
enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated. |
|
the CoglPixelFormat to use for the GPU storage of the texture. |
|
a GError or NULL. |
Returns : |
a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if creating the texture failed. |
CoglHandle cogl_texture_new_from_data (guint width, guint height, gint max_waste, gboolean auto_mipmap, CoglPixelFormat format, CoglPixelFormat internal_format, guint rowstride, const guchar *data);
Create a new cogl texture based on data residing in memory.
|
width of texture in pixels. |
|
height of texture in pixels. |
|
maximum extra horizontal and|or vertical margin pixels to make |
|
enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated. |
|
the CoglPixelFormat the buffer is stored in in RAM |
|
the CoglPixelFormat that will be used for storing the buffer on the GPU. |
|
the memory offset in bytes between the starts of scanlines in
data .
|
|
pointer the memory region where the source buffer resides. |
Returns : |
a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if creating the texture failed. |
CoglHandle cogl_texture_new_from_foreign (GLuint gl_handle, GLenum gl_target, GLuint width, GLuint height, GLuint x_pot_waste, GLuint y_pot_waste, CoglPixelFormat format);
Create a cogl texture based on an existing OpenGL texture, the width, height and format are passed along since it is not possible to query this from a handle with GLES 1.0.
|
opengl target type of foreign texture |
|
opengl handle of foreign texture. |
|
width of foreign texture |
|
height of foreign texture. |
|
maximum horizontal waste. |
|
maximum vertical waste. |
|
format of the foreign texture. |
Returns : |
a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if creating the texture failed. |
gboolean cogl_is_texture (CoglHandle handle);
Gets whether the given handle references an existing texture object.
guint cogl_texture_get_width (CoglHandle handle);
Query the width of a cogl texture.
|
a CoglHandle for a texture. |
Returns : |
the width of the GPU side texture in pixels: |
guint cogl_texture_get_height (CoglHandle handle);
Query the height of a cogl texture.
|
a CoglHandle for a texture. |
Returns : |
the height of the GPU side texture in pixels: |
CoglPixelFormat cogl_texture_get_format (CoglHandle handle);
Query the CoglPixelFormat of a cogl texture.
|
a CoglHandle for a texture. |
Returns : |
the CoglPixelFormat of the GPU side texture. |
guint cogl_texture_get_rowstride (CoglHandle handle);
Query the rowstride of a cogl texture.
|
a CoglHandle for a texture. |
Returns : |
the offset in bytes between each consequetive row of pixels. |
gint cogl_texture_get_max_waste (CoglHandle handle);
Query the maximum wasted (unused) pixels in one dimension of a GPU side texture.
|
a CoglHandle for a texture. |
Returns : |
the maximum waste. |
COGLenum cogl_texture_get_min_filter (CoglHandle handle);
Query the currently set downscaling filter for a cogl texture.
|
a CoglHandle for a texture. |
Returns : |
the current downscaling filter for a cogl texture. |
COGLenum cogl_texture_get_mag_filter (CoglHandle handle);
Query the currently set downscaling filter for a cogl texture.
|
a CoglHandle for a texture. |
Returns : |
the current downscaling filter for a cogl texture. |
gboolean cogl_texture_is_sliced (CoglHandle handle);
Query if a texture is sliced (stored as multiple GPU side tecture objects).
|
a CoglHandle for a texture. |
Returns : |
TRUE if the texture is sliced, FALSE if the texture
is stored as a single GPU texture.
|
gboolean cogl_texture_get_gl_texture (CoglHandle handle, GLuint *out_gl_handle, GLenum *out_gl_target);
Query the GL handles for a GPU side texture through it's CoglHandle, if the texture is spliced the data for the first sub texture will be queried.
|
a CoglHandle for a texture. |
|
pointer to return location for the textures GL handle, or NULL. |
|
pointer to return location for the GL target type, or NULL. |
Returns : |
TRUE if the handle was successfully retrieved FALSE
if the handle was invalid.
|
gint cogl_texture_get_data (CoglHandle handle, CoglPixelFormat format, guint rowstride, guchar *data);
Copy the pixel data from a cogl texture to system memory.
|
a CoglHandle for a texture. |
|
the CoglPixelFormat to store the texture as. |
|
the rowstride of data or retrieved from texture if none is
specified.
|
|
memory location to write contents of buffer, or NULL if we're
only querying the data size through the return value.
|
Returns : |
the size of the texture data in bytes (or 0 if the texture is not valid.) |
void cogl_texture_set_filters (CoglHandle handle, COGLenum min_filter, COGLenum mag_filter);
Changes the decimation and interpolation filters used when the texture is drawn at other scales than 100%.
|
a CoglHandle. |
|
the filter used when scaling the texture down. |
|
the filter used when magnifying the texture. |
gboolean cogl_texture_set_region (CoglHandle handle, gint src_x, gint src_y, gint dst_x, gint dst_y, guint dst_width, guint dst_height, gint width, gint height, CoglPixelFormat format, guint rowstride, const guchar *data);
Sets the pixels in a rectangular subregion of handle
from an in-memory
buffer containing pixel data.
|
a CoglHandle. |
|
upper left coordinate to use from source data. |
|
upper left coordinate to use from source data. |
|
upper left destination horizontal coordinate. |
|
upper left destination vertical coordinate. |
|
width of destination region to write. |
|
height of destination region to write. |
|
width of source data buffer. |
|
height of source data buffer. |
|
the CoglPixelFormat used in the source buffer. |
|
rowstride of source buffer (computed from width if none specified) |
|
the actual pixel data. |
Returns : |
TRUE if the subregion upload was successful, otherwise FALSE .
|
CoglHandle cogl_texture_ref (CoglHandle handle);
Increment the reference count for a cogl texture.
|
a CoglHandle .
|
Returns : |
the handle .
|
void cogl_texture_unref (CoglHandle handle);
Deccrement the reference count for a cogl texture.
|
a CoglHandle .
|
void cogl_texture_rectangle (CoglHandle handle, ClutterFixed x1, ClutterFixed y1, ClutterFixed x2, ClutterFixed y2, ClutterFixed tx1, ClutterFixed ty1, ClutterFixed tx2, ClutterFixed ty2);
Draw a rectangle from a texture to the display, to draw the entire
texture pass in tx1
=0.0 ty1
=0.0 tx2
=1.0 ty2
=1.0.
|
a CoglHandle .
|
|
x coordinate upper left on screen. |
|
y coordinate upper left on screen. |
|
x coordinate lower right on screen. |
|
y coordinate lower right on screen. |
|
x part of texture coordinate to use for upper left pixel |
|
y part of texture coordinate to use for upper left pixel |
|
x part of texture coordinate to use for lower right pixel |
|
y part of texture coordinate to use for left pixel |
void cogl_texture_polygon (CoglHandle handle, guint n_vertices, CoglTextureVertex *vertices, gboolean use_color);
Draws a polygon from a texture with the given model and texture
coordinates. This can be used to draw arbitrary shapes textured
with a COGL texture. If use_color
is TRUE
then the current COGL
color will be changed for each vertex using the value specified in
the color member of CoglTextureVertex. This can be used for
example to make the texture fade out by setting the alpha value of
the color.
All of the texture coordinates must be in the range [0,1] and repeating the texture is not supported.
Because of the way this function is implemented it will currently only work if either the texture is not sliced or the backend is not OpenGL ES and the minifying and magnifying functions are both set to CGL_NEAREST.
|
A CoglHandle for a texture |
|
The length of the vertices array |
|
An array of CoglTextureVertex structs |
|
TRUE if the color member of CoglTextureVertex should be used
|