[cogl/wip/rig: 24/34] framebuffer: update docs for _get_depth_texture()

[Robert Bragg <rbragg src gnome org>]

commit 8266a8a085550019c88b986a6e7cc13e78cf6974
Author: Robert Bragg <robert bragg intel com>
Date:   Sat Mar 15 00:34:57 2014 +0000

    framebuffer: update docs for _get_depth_texture()
    
    This clarifies in the documentation for
    cogl_framebuffer_get_depth_texture() that if a depth texture is added as
    a layer to a pipeline and sampled then depth values should be read from
    the red component and that all other components are undefined.
    
    It depends on the version of OpenGL, and what profile is selected
    whether sampling depth textures behaves like sampling a luminance
    texture (L,L,L,1) or a component red texture (R,0,0,1).
    
    In particular I was caught out by this issue in Rig where we were
    referencing the .z component of shadow map textures, and this had worked
    ok until updating to a recent version of mesa which has updated its
    behaviour. The relevant mesa commit is: 678ac190a5a6fd39b8568587fac28
    
    Reading the mailing list discussion that happened around that patch it
    looks like Kenneth Graunke investigated the different variations so for
    posterity it could be handy note them here:
    
    Apparently it works like this:
    - Core: RED
    - Forward Compatible: RED
    - Compatibility or <= 3.0: LUMINANCE
    - ES2 with OES_depth_texture: LUMINANCE
    - ES3 for unsized formats: RED
    - ES3 for sized formats: LUMINANCE

 cogl/cogl-framebuffer.h |   23 ++++++++++++++++-------
 1 files changed, 16 insertions(+), 7 deletions(-)
---
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index c9f17ec..5972277 100644
--- a/cogl/cogl-framebuffer.h
+++ b/cogl/cogl-framebuffer.h
@@ -882,13 +882,22 @@ cogl_framebuffer_get_depth_texture_enabled (CoglFramebuffer *framebuffer);
  * cogl_framebuffer_get_depth_texture:
  * @framebuffer: A #CoglFramebuffer
  *
- * Retrieves the depth buffer of @framebuffer as a #CoglTexture. You need to
- * call cogl_framebuffer_get_depth_texture(fb, TRUE); before using this
- * function.
- *
- * <note>Calling this function implicitely allocates the framebuffer.</note>
- * <note>The texture returned stays valid as long as the framebuffer stays
- * valid.</note>
+ * Retrieves the depth buffer of @framebuffer as a #CoglTexture. You
+ * must have called cogl_framebuffer_set_depth_texture(fb, TRUE);
+ * before using this function.
+ *
+ * If the returned texture is subsequently added to a pipeline layer
+ * and sampled from, then depth values should be read from the red
+ * component of the texture. The values of other components are
+ * undefined.
+ *
+ * <note>Calling this function implicitly allocates the
+ * framebuffer.</note>
+ *
+ * <note>The returned texture pointer is only guaranteed to remain
+ * valid as long as @framebuffer stays valid, but it's safe to keep
+ * the texture alive for longer by taking a reference on the returned
+ * texture.</note>
  *
  * Returns: (transfer none): the depth texture
  *