Tweak documentation for the CoglTexture interface

The following changes are made to the documentation for CoglTexture:

• The description of the default value for the components property is
  changed to say that it is always RGBA for textures created by the
  ‘_with_size’ textures. Previously it said that the default is based
  on the pixel format used the first time data is set on the texture,
  but this is only true if the data is set using a constructor.

• Added documentation for the CoglTextureComponents enum.

• Changed it to say that it _specifies_ what components are required
  for sampling rather than determinging [sic] them.

• Added ‘Since: 1.18’ to
  cogl_texture_{set,get}_{components,premultiplied}

• Changed the since tag for CoglTextureError from 2.0 to 1.8.

• Added documentation for COGL_TEXTURE_ERROR_{FORMAT,TYPE}.

• Added the following to the cogl2-sections.txt file:
  COGL_TEXTURE_ERROR
  CoglTextureError
  cogl_texture_allocate
  cogl_texture_set_components
  cogl_texture_get_components
  cogl_texture_set_premultiplied
  cogl_texture_get_premultiplied

Reviewed-by: Robert Bragg <robert@linux.intel.com>
(cherry picked from commit 2f12c4329c519fa14b927b2dcd708dddcc903c32)
This commit is contained in:
Neil Roberts 2014-01-15 16:43:55 +00:00
parent 5085919acc
commit 06c75ea2e7
2 changed files with 44 additions and 11 deletions

View File

@ -67,7 +67,7 @@ COGL_BEGIN_DECLS
* *
* #CoglError domain for texture errors. * #CoglError domain for texture errors.
* *
* Since: 2.0 * Since: 1.8
* Stability: Unstable * Stability: Unstable
*/ */
#define COGL_TEXTURE_ERROR (cogl_texture_error_quark ()) #define COGL_TEXTURE_ERROR (cogl_texture_error_quark ())
@ -76,10 +76,13 @@ COGL_BEGIN_DECLS
/** /**
* CoglTextureError: * CoglTextureError:
* @COGL_TEXTURE_ERROR_SIZE: Unsupported size * @COGL_TEXTURE_ERROR_SIZE: Unsupported size
* @COGL_TEXTURE_ERROR_FORMAT: Unsupported format
* @COGL_TEXTURE_ERROR_TYPE: A primitive texture type that is
* unsupported by the driver was used
* *
* Error codes that can be thrown when allocating textures. * Error codes that can be thrown when allocating textures.
* *
* Since: 2.0 * Since: 1.8
* Stability: Unstable * Stability: Unstable
*/ */
typedef enum { typedef enum {
@ -121,6 +124,17 @@ uint32_t cogl_texture_error_quark (void);
CoglBool CoglBool
cogl_is_texture (void *object); cogl_is_texture (void *object);
/**
* CoglTextureComponents:
* @COGL_TEXTURE_COMPONENTS_A: Only the alpha component
* @COGL_TEXTURE_COMPONENTS_RGB: Red, green and blue components
* @COGL_TEXTURE_COMPONENTS_RGBA: Red, green, blue and alpha components
* @COGL_TEXTURE_COMPONENTS_DEPTH: Only a depth component
*
* See cogl_texture_set_components().
*
* Since: 1.18
*/
typedef enum _CoglTextureComponents typedef enum _CoglTextureComponents
{ {
COGL_TEXTURE_COMPONENTS_A = 1, COGL_TEXTURE_COMPONENTS_A = 1,
@ -133,15 +147,18 @@ typedef enum _CoglTextureComponents
* cogl_texture_set_components: * cogl_texture_set_components:
* @texture: a #CoglTexture pointer. * @texture: a #CoglTexture pointer.
* *
* Affects the internal storage format for this texture by * Affects the internal storage format for this texture by specifying
* determinging what components will be required for sampling later. * what components will be required for sampling later.
* *
* This api affects how data is uploaded to the GPU since unused * This api affects how data is uploaded to the GPU since unused
* components can potentially be discarded from source data. * components can potentially be discarded from source data.
* *
* By default the required components are automatically determined * For textures created by the _with_size constructors the default
* using the format of the source data that is first uploaded to * is %COGL_TEXTURE_COMPONENTS_RGBA. The other constructors which take
* the given @texture. * a %CoglBitmap or a data pointer default to the same components as
* the pixel format of the data.
*
* Since: 1.18
*/ */
void void
cogl_texture_set_components (CoglTexture *texture, cogl_texture_set_components (CoglTexture *texture,
@ -154,9 +171,12 @@ cogl_texture_set_components (CoglTexture *texture,
* Queries what components the given @texture stores internally as set * Queries what components the given @texture stores internally as set
* via cogl_texture_set_components(). * via cogl_texture_set_components().
* *
* By default the required components are automatically determined * For textures created by the _with_size constructors the default
* using the format of the source data that is first uploaded to * is %COGL_TEXTURE_COMPONENTS_RGBA. The other constructors which take
* the given @texture. * a %CoglBitmap or a data pointer default to the same components as
* the pixel format of the data.
*
* Since: 1.18
*/ */
CoglTextureComponents CoglTextureComponents
cogl_texture_get_components (CoglTexture *texture); cogl_texture_get_components (CoglTexture *texture);
@ -168,7 +188,7 @@ cogl_texture_get_components (CoglTexture *texture);
* components are pre-multiplied by an alpha * components are pre-multiplied by an alpha
* component. * component.
* *
* Affects the internal storage format for this texture by determining * Affects the internal storage format for this texture by specifying
* whether red, green and blue color components should be stored as * whether red, green and blue color components should be stored as
* pre-multiplied alpha values. * pre-multiplied alpha values.
* *
@ -189,6 +209,8 @@ cogl_texture_get_components (CoglTexture *texture);
* converted. * converted.
* *
* By default the @premultipled state is @TRUE. * By default the @premultipled state is @TRUE.
*
* Since: 1.18
*/ */
void void
cogl_texture_set_premultiplied (CoglTexture *texture, cogl_texture_set_premultiplied (CoglTexture *texture,
@ -207,6 +229,7 @@ cogl_texture_set_premultiplied (CoglTexture *texture,
* Return value: %TRUE if red, green and blue components are * Return value: %TRUE if red, green and blue components are
* internally stored pre-multiplied by the alpha * internally stored pre-multiplied by the alpha
* value or %FALSE if not. * value or %FALSE if not.
* Since: 1.18
*/ */
CoglBool CoglBool
cogl_texture_get_premultiplied (CoglTexture *texture); cogl_texture_get_premultiplied (CoglTexture *texture);

View File

@ -400,6 +400,11 @@ CoglTexture
cogl_is_texture cogl_is_texture
<SUBSECTION> <SUBSECTION>
COGL_TEXTURE_ERROR
CoglTextureError
<SUBSECTION>
cogl_texture_allocate
cogl_texture_get_width cogl_texture_get_width
cogl_texture_get_height cogl_texture_get_height
cogl_texture_is_sliced cogl_texture_is_sliced
@ -407,6 +412,11 @@ cogl_texture_get_data
cogl_texture_set_data cogl_texture_set_data
cogl_texture_set_region cogl_texture_set_region
CoglTextureType CoglTextureType
CoglTextureComponents
cogl_texture_set_components
cogl_texture_get_components
cogl_texture_set_premultiplied
cogl_texture_get_premultiplied
<SUBSECTION Private> <SUBSECTION Private>
COGL_TEXTURE_MAX_WASTE COGL_TEXTURE_MAX_WASTE