[Cogl] [PATCH] Tweak documentation for the CoglTexture interface

[Robert Bragg]

One thing I'm not entirely sure about is whether documenting
CoglTextureComponents in terms of what components it determines are
"available" is clearer or not. Just talking to you briefly about this
in the office, you mentioned the idea of using "specifying" instead of
"determining" in the documentation for _set_components() which sounded
better in either the old or new wording, so maybe you could tweak that
description again.

Apart from that, this looks good to land to me:

Reviewed-by: Robert Bragg <robert at linux.intel.com>

Thanks,
Robert

On Wed, Jan 15, 2014 at 5:15 PM, Neil Roberts <neil at linux.intel.com> wrote:
> 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.
>
> • Fixed a typo in ‘determinging’.
>
> • Changed it to say that it determines what components are _available_
>   for sampling rather than which ones are required.
>
> • 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
> ---
>  cogl/cogl-texture.h                    | 45 ++++++++++++++++++++++++++--------
>  doc/reference/cogl2/cogl2-sections.txt | 10 ++++++++
>  2 files changed, 45 insertions(+), 10 deletions(-)
>
> diff --git a/cogl/cogl-texture.h b/cogl/cogl-texture.h
> index b77cf9b..112af0d 100644
> --- a/cogl/cogl-texture.h
> +++ b/cogl/cogl-texture.h
> @@ -76,7 +76,7 @@ COGL_BEGIN_DECLS
>   *
>   * #CoglError domain for texture errors.
>   *
> - * Since: 2.0
> + * Since: 1.8
>   * Stability: Unstable
>   */
>  #define COGL_TEXTURE_ERROR (cogl_texture_error_domain ())
> @@ -85,10 +85,13 @@ COGL_BEGIN_DECLS
>  /**
>   * CoglTextureError:
>   * @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.
>   *
> - * Since: 2.0
> + * Since: 1.8
>   * Stability: Unstable
>   */
>  typedef enum {
> @@ -130,6 +133,19 @@ uint32_t cogl_texture_error_domain (void);
>  CoglBool
>  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
> + *
> + * The possible combinations of components available for the internal
> + * storage of a texture. This can be set with
> + * cogl_texture_set_components().
> + *
> + * Since: 1.18
> + */
>  typedef enum _CoglTextureComponents
>  {
>    COGL_TEXTURE_COMPONENTS_A = 1,
> @@ -142,15 +158,18 @@ typedef enum _CoglTextureComponents
>   * cogl_texture_set_components:
>   * @texture: a #CoglTexture pointer.
>   *
> - * Affects the internal storage format for this texture by
> - * determinging what components will be required for sampling later.
> + * Affects the internal storage format for this texture by determining
> + * what components will be available for sampling later.
>   *
>   * This api affects how data is uploaded to the GPU since unused
>   * components can potentially be discarded from source data.
>   *
> - * By default the required components are automatically determined
> - * using the format of the source data that is first uploaded to
> - * the given @texture.
> + * For textures created by the ‘_with_size’ constructors the default
> + * is %COGL_TEXTURE_COMPONENTS_RGBA. The other constructors which take
> + * a %CoglBitmap or a data pointer default to the same components as
> + * the pixel format of the data.
> + *
> + * Since: 1.18
>   */
>  void
>  cogl_texture_set_components (CoglTexture *texture,
> @@ -163,9 +182,12 @@ cogl_texture_set_components (CoglTexture *texture,
>   * Queries what components the given @texture stores internally as set
>   * via cogl_texture_set_components().
>   *
> - * By default the required components are automatically determined
> - * using the format of the source data that is first uploaded to
> - * the given @texture.
> + * For textures created by the ‘_with_size’ constructors the default
> + * is %COGL_TEXTURE_COMPONENTS_RGBA. The other constructors which take
> + * a %CoglBitmap or a data pointer default to the same components as
> + * the pixel format of the data.
> + *
> + * Since: 1.18
>   */
>  CoglTextureComponents
>  cogl_texture_get_components (CoglTexture *texture);
> @@ -198,6 +220,8 @@ cogl_texture_get_components (CoglTexture *texture);
>   * converted.
>   *
>   * By default the @premultipled state is @TRUE.
> + *
> + * Since: 1.18
>   */
>  void
>  cogl_texture_set_premultiplied (CoglTexture *texture,
> @@ -216,6 +240,7 @@ cogl_texture_set_premultiplied (CoglTexture *texture,
>   * Return value: %TRUE if red, green and blue components are
>   *               internally stored pre-multiplied by the alpha
>   *               value or %FALSE if not.
> + * Since: 1.18
>   */
>  CoglBool
>  cogl_texture_get_premultiplied (CoglTexture *texture);
> diff --git a/doc/reference/cogl2/cogl2-sections.txt b/doc/reference/cogl2/cogl2-sections.txt
> index b12e89a..7cd53d0 100644
> --- a/doc/reference/cogl2/cogl2-sections.txt
> +++ b/doc/reference/cogl2/cogl2-sections.txt
> @@ -336,6 +336,11 @@ CoglTexture
>  cogl_is_texture
>
>  <SUBSECTION>
> +COGL_TEXTURE_ERROR
> +CoglTextureError
> +
> +<SUBSECTION>
> +cogl_texture_allocate
>  cogl_texture_get_width
>  cogl_texture_get_height
>  cogl_texture_is_sliced
> @@ -343,6 +348,11 @@ cogl_texture_get_data
>  cogl_texture_set_data
>  cogl_texture_set_region
>  CoglTextureType
> +CoglTextureComponents
> +cogl_texture_set_components
> +cogl_texture_get_components
> +cogl_texture_set_premultiplied
> +cogl_texture_get_premultiplied
>
>  <SUBSECTION Private>
>  COGL_TEXTURE_MAX_WASTE
> --
> 1.8.4.2
>
> _______________________________________________
> Cogl mailing list
> Cogl at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/cogl