Updates to ANGLE_depth_texture

Trac #20959
 - fix a number of incorrect error values
 - disallow multi-level depth textures

git-svn-id: https://angleproject.googlecode.com/svn/trunk@1132 736b8ea6-26fd-11df-bfd4-992fa37f6226

1 files changed, 51 insertions, 27 deletions

diff --git a/extensions/ANGLE_depth_texture.txt b/extensions/ANGLE_depth_texture.txt
index 48ba830f..1ffc0a85 100644
--- a/extensions/ANGLE_depth_texture.txt
+++ b/extensions/ANGLE_depth_texture.txt
@@ -11,6 +11,7 @@ Contributors
     Nicolas Capens, TransGaming
     Kenneth Russell, Google
     Vangelis Kokkevis, Google
+    Gregg Tavares, Google
     Contributors to OES_depth_texture
     Contributors to OES_packed_depth_stencil
 
@@ -24,8 +25,8 @@ Status
 
 Version
 
-    Last Modifed Date: May 30, 2012
-    Revision: #2
+    Last Modifed Date: June 4, 2012
+    Revision: #3
 
 Number
 
@@ -50,7 +51,8 @@ Overview
     provide the ability to load existing data via TexImage2D or
     TexSubImage2D. This extension also allows implementation 
     variability in which components from a sampled depth texture
-    contain the depth data.
+    contain the depth data. Depth textures created with this
+    extension only support 1 level.
 
 New Procedures and Functions
 
@@ -162,6 +164,10 @@ Additions to Chapter 3 of the OpenGL ES 2.0 specification (Rasterizatoin)
     only if <target> is TEXTURE_2D.  Using these formats in conjunction with
     any other <target> will result in an INVALID_OPERATION error.
 
+    Textures with a base internal format of DEPTH_COMPONENT or
+    DEPTH_STENCIL_OES only support one level of image data.  Specifying a
+    non-zero value for <level> will result in an INVALID_OPERATION error.
+
     Textures with a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES
     require either depth component data or depth/stencil component data.
     Textures with other base internal formats require RGBA component data.  The
@@ -289,49 +295,55 @@ Interactions with EXT_texture_storage
         DEPTH_COMPONENT32_OES  DEPTH_COMPONENT    UNSIGNED_INT
         DEPTH24_STENCIL8_OES   DEPTH_STENCIL_OES  UNSIGNED_INT
 
+    Textures with the above <internalformats> only support one level of
+    image data. Specifying a value other than one for the <levels> parameter
+    to TexStorage2DEXT will result in an INVALID_OPERATION error.
+
     If EXT_texture_storage is not supported, ignore any references
     to TexStorage2DEXT. 
 
 Errors
 
-    The error INVALID_ENUM is generated by TexImage2D if <format> and 
+    The error INVALID_OPERATION is generated by TexImage2D if <format> and 
     <internalformat> are DEPTH_COMPONENT and <type> is not UNSIGNED_SHORT,
     or UNSIGNED_INT.
 
-    The error INVALID_ENUM is generated by TexSubImage2D if <format> is 
+    The error INVALID_OPERATION is generated by TexSubImage2D if <format> is 
     DEPTH_COMPONENT and <type> is not UNSIGNED_SHORT, or UNSIGNED_INT.
 
-    The error INVALID_ENUM is generated by TexImage2D if <format> and
+    The error INVALID_OPERATION is generated by TexImage2D if <format> and
     <internalformat> are not DEPTH_COMPONENT and <type> is UNSIGNED_SHORT,
     or UNSIGNED_INT.
 
-    The error INVALID_ENUM is generated by TexSubImage2D if <format> is
+    The error INVALID_OPERATION is generated by TexSubImage2D if <format> is
     not DEPTH_COMPONENT and <type> is UNSIGNED_SHORT, or UNSIGNED_INT.
 
-    The error INVALID_ENUM is generated by TexImage2D if <format> and
+    The error INVALID_OPERATION is generated by TexImage2D if <format> and
     <internalformat> are DEPTH_STENCIL_OES and <type> is not
     UNSIGNED_INT_24_8_OES. 
 
-    The error INVALID_ENUM is generated by TexSubImage2D if <format>
+    The error INVALID_OPERATION is generated by TexSubImage2D if <format>
     is DEPTH_STENCIL_OES and <type> is not UNSIGNED_INT_24_8_OES. 
 
-    The error INVALID_ENUM is generated by TexImage2D if <format> and
+    The error INVALID_OPERATION is generated by TexImage2D if <format> and
     <internalformat> is not DEPTH_STENCIL_OES and <type> is 
     UNSIGNED_INT_24_8_OES.
 
-    The error INVALID_ENUM is generated by TexSubImage2D if <format>
+    The error INVALID_OPERATION is generated by TexSubImage2D if <format>
     is not DEPTH_STENCIL_OES and <type> is UNSIGNED_INT_24_8_OES.
 
     The error INVALID_OPERATION is generated in the following situations:
     - TexImage2D is called with <format> and <internalformat> of
       DEPTH_COMPONENT or DEPTH_STENCIL_OES and
-       - <target> is not TEXTURE_2D, or
-       - <data> is not NULL
+       - <target> is not TEXTURE_2D,
+       - <data> is not NULL, or
+       - <level> is not zero.
     - TexSubImage2D is called with <format> of DEPTH_COMPONENT or 
       DEPTH_STENCIL_OES.
     - TexStorage2DEXT is called with <internalformat> of DEPTH_COMPONENT16,
-      DEPTH_COMPONENT32_OES, DEPTH24_STENCIL8_OES, and 
-       - <target> is not TEXTURE_2D
+      DEPTH_COMPONENT32_OES, or DEPTH24_STENCIL8_OES, and 
+       - <target> is not TEXTURE_2D, or
+       - <levels> is not one.
     - CopyTexImage2D is called with an <internalformat> that has a base
       internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES.
     - CopyTexSubImage2D is called with a target texture that has a base
@@ -348,27 +360,39 @@ Issues
     1) What are the differences between this extension and OES_depth_texture
        and OES_packed_depth_stencil?
     
-       RESOLVED: This extension does not support loading pre-baked depth
-       or stencil data via TexImage2D or TexSubImage2D. This extension
-       also allows variability in w-component of the sample results from
-       depth textures.  This version also explicitly lists the errors for
-       unsupported functionality. Since this was not clearly specified in
-       the OES_depth_texture extension there may be differences in error
-       values between implementations of OES_depth_texture and 
-       ANGLE_depth_texture. This specification was also rebased to apply
-       against the OpenGL ES 2.0 specification instead of the OpenGL
-       specification, making it more obvious what all the functionality
-       changes are.
+       RESOLVED: This extension:
+         - does not support loading pre-baked depth stencil data via 
+           TexImage2D or TexSubImage2D.
+         - allows variability in w-component of the sample results from
+           depth textures.
+         - only supports one level textures.
+         - explicitly lists the errors for unsupported functionality.
+           Since these were not clearly specified in the OES_depth_texture
+           extension there may be differences in error values between 
+           implementations of OES_depth_texture and ANGLE_depth_texture.
+       This specification was also rebased to apply against the OpenGL ES 2.0
+       specification instead of the OpenGL specification, making it more 
+       obvious what all the functionality changes are.
 
     2) Why does TexSubImage2D accept the new format/type combinations even
        though it does not actually support loading data?
 
-       RESOLVE: This was done to be more consistent with the OES_depth_texture
+       RESOLVED: This was done to be more consistent with the OES_depth_texture
        extension and to make it easier to add support for loading texture
        data if it is possible to support in the future.
 
+    3) Why are only 1-level depth textures supported? 
+
+       RESOLVED: The only use for multiple levels of depth textures would
+       be for fitlered texturing. However since it is not possible to
+       render to non-zero-level texture levels in OpenGL ES 2.0, and since
+       this extension forbids loading existing data and GenerateMipmap on 
+       depth textures, it is impossible to initialize or specify contents
+       for non-zero levels of depth textures.
+
 Revision History
  
+    06/04/2012  dgkoch  fix errors, disallow multi-level depth textures.
     05/30/2012  dgkoch  minor updates and add issues.
     05/23/2012  dgkoch  intial revision based on OES_depth_texture and 
                         OES_packed_depth_stencil and rebased against the ES 2.0 spec