Contents 1 CoglTexture 1.1 open issues 1.2 CoglTexture2D 1.2.1 open issues: 1.3 CoglTexturePixmapX11 1.3.1 open questions

CoglTexture

CoglTexture is an abstract base class for all texture types

cogl_texture_get_format (tex);
cogl_texture_get_width (tex);
cogl_texture_get_height (tex);
cogl_texture_get_region ();
cogl_texture_set_region ();
cogl_texture_generate_mipmaps ();
cogl_texture_is_sliced ();
cogl_texture_can_hardware_repeat();
cogl_texture_foreach_subtexture_in_region ();

CoglTextures can have a parent child ancestry such that some CoglTexture subclasses may be implemented in terms of other lower level subclasses. For example sliced textures, which handle textures larger than the hardware limits or non power of two textures may internally be represented by multiple child textures. This ancestry mechanism can also be used to apply transformations when mapping texture coordinates onto low level textures, so a high level subclass can describe a texture that maps to a subregion of another texture. This can be used to implement texture atlases.

There are a core set of low level subclasses: CoglTexture1D, CoglTexture2D, CoglTexture3D and CoglTextureRectangle which are actually the only types that can be directly drawn with.

The cogl_texture_foreach_subtexture_in_region API allows code that needs to draw primitives with arbitrary CoglTextures iterate all the lowlevel subtextures. So for example in implementing cogl_rectangle with a material referencing sliced or atlas textures the foreach mechanism is used to query what lowlevel textures (possibly more than one) map to the virtual texture coordinates of the sliced/atlas texture and for each lowlevel slice found it may generate new texture coordinates. It is then the responsibility of the code implementing primitives (such as cogl_rectangle or cogl_polygon) to derive new materials that don't contain sliced textures before drawing.

cogl_texture_is_sliced() returns TRUE if cogl_texture_foreach_subtexture_in_region must be used otherwise it can be assumed that the texture is a low level texture with a 1:1 texture coordinate mapping.

void
cogl_texture_foreach_subtexture_in_region (CoglHandle texture,
								       unsigned long flags,
								       float *virtual_coords,
								       CoglTextureRepeatMode repeat_s,
								       CoglTextureRepeatMode repeat_t,
								       CoglTextureForeachCallback callback,
								       void *data);
typedef void (*CoglTextureForeachCallback) (CoglHandle low_level_texture,
									const float *virtual_coords,
									const float *subtexture_coords,
									void *user_data);

open issues

• we want cogl_texture_foreach_subtexture_in_region to abstract away the repeat mode aspects from the primitives code, but we need to consider that some primitives may only be able to handle sliced textures if certain repeat modes are used for the slices. E.g. cogl_polygon uses a CLAMP_TO_BORDER repeat mode on the slices but may want to present REPEAT semantics to the user.

CoglTexture2D

A lowlevel 2D texture.

cogl_texture_2d_new_with_size ();
cogl_texture_2d_new_from_data ();
cogl_texture_2d_new_from_file ();
cogl_texture_2d_set_region ();
cogl_texture_2d_get_format ();
cogl_texture_2d_get_rowstride ();
cogl_texture_2d_get_data ();

open issues:

• Some platforms only support power-of-two 2D textures, how do we allow users to query this, and what do we do if a user wants to load a NPOT texture? (Slicing isn't possible here but we could potentially scale)
• NB: While GLES 2.0 supports NPOT 2D textures it doesn't support mipmapping them, and the only repeat mode that can be used with them is CLAMP_TO_EDGE. Other repeat modes can potentially be handled in the fragment shader but nothing can be done about the lack of mipmapping - http://www.khronos.org/registry/gles/extensions/OES/OES_texture_npot.txt (SGX) allows other texture wrap modes and the use minification filters.

CoglTexturePixmapX11

CoglTexturePixmapX11 will expose the GLX texture from pixmap extension.

tex = cogl_texture_pixmap_x11_new (guint32 pixmap_xid);
cogl_texture_pixmap_x11_set_automatic_update (tex, FALSE); ???
cogl_texture_pixmap_x11_damage_regions (tex, x_regions); ???
cogl_texture_pixmap_x11_update (tex);
pixmap = cogl_texture_pixmap_x11_get_pixmap (tex);

CoglTexturePixmap can be implemented as a container texture like sliced and atlas textures, where there is one child that may be a CoglTexture2D or CoglTextureRectangle depending on driver constraints. cogl_texture_foreach_child can be used to determine this and a transform function may be passed to the users foreach callback.

Note that "glx" isn't mentioned anywhere in the API; i.e. it should be considered an implementation detail that we are implementing it using the GLX tfp extension.

open questions

• do we need a way to query back what parts of the texture have changed, e.g. cogl_texture_pixmap_x11_get_damage() so that ClutterGLXTexturePixmap can queue a corresponding clipped redraw of itself. XXX: how can we literally notify Clutter of damage? Can we get away with saying that Clutter needs to listen for the damage events and actually tell Cogl about damage instead?