[cogl/wip/rig: 9/33] framebuffer: update docs for _get_depth_texture()
- From: Robert Bragg <rbragg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [cogl/wip/rig: 9/33] framebuffer: update docs for _get_depth_texture()
- Date: Mon, 23 Feb 2015 21:35:03 +0000 (UTC)
commit 6b385bd6b082ae63a3353f24378161562670e24b
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
*
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]