The Tor Browser / file revision

 Name

     ANGLE_texture_usage

 Name Strings

     GL_ANGLE_texture_usage

 Contributors

     Nicolas Capens, TransGaming

     Daniel Koch, TransGaming

 Contact

     Daniel Koch, TransGaming (daniel 'at' transgaming.com)

 Status

     Complete

 Version

     Last Modified Date:  November 10, 2011

     Version:             2

 Number

     OpenGL ES Extension #112 

 Dependencies

     This extension is written against the OpenGL ES 2.0 Specification.

 Overview

     In some implementations it is advantageous to know the expected

     usage of a texture before the backing storage for it is allocated.  

     This can help to inform the implementation's choice of format

     and type of memory used for the allocation. If the usage is not

     known in advance, the implementation essentially has to make a 

     guess as to how it will be used.  If it is later proven wrong,

     it may need to perform costly re-allocations and/or reformatting 

     of the texture data, resulting in reduced performance.

     This extension adds a texture usage flag that is specified via

     the TEXTURE_USAGE_ANGLE TexParameter.  This can be used to 

     indicate that the application knows that this texture will be 

     used for rendering.

 IP Status

     No known IP claims.

 New Procedures and Functions

     None

 New Tokens

     Accepted as a value for <pname> for the TexParameter{if} and 

     TexParameter{if}v commands and for the <value> parameter of

     GetTexParameter{if}v: 

         TEXTURE_USAGE_ANGLE                     0x93A2

     Accepted as a value to <param> for the TexParameter{if} and 

     to <params> for the TexParameter{if}v commands with a <pname> of 

     TEXTURE_USAGE_ANGLE; returned as possible values for <data> when 

     GetTexParameter{if}v is queried with a <value> of TEXTURE_USAGE_ANGLE:

         NONE                                    0x0000

         FRAMEBUFFER_ATTACHMENT_ANGLE            0x93A3

 Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation)

     None

 Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)

     Add a new row to Table 3.10 (Texture parameters and their values):

     Name                | Type | Legal Values 

     ------------------------------------------------------------

     TEXTURE_USAGE_ANGLE | enum | NONE, FRAMEBUFFER_ATTACHMENT_ANGLE

     Add a new section 3.7.x (Texture Usage) before section 3.7.12 and 

     renumber the subsequent sections: 

     "3.7.x Texture Usage

     Texture usage can be specified via the TEXTURE_USAGE_ANGLE value

     for the <pname> argument to TexParameter{if}[v]. In order to take effect,

     the texture usage must be specified before the texture contents are

     defined either via TexImage2D or TexStorage2DEXT.

     The usage values can impact the layout and type of memory used for the 

     texture data. Specifying incorrect usage values may result in reduced

     functionality and/or significantly degraded performance.

     Possible values for <params> when <pname> is TEXTURE_USAGE_ANGLE are:

     NONE - the default. No particular usage has been specified and it is

         up to the implementation to determine the usage of the texture.

         Leaving the usage unspecified means that the implementation may 

         have to reallocate the texture data as the texture is used in 

         various ways.

     FRAMEBUFFER_ATTACHMENT_ANGLE - this texture will be attached to a 

         framebuffer object and used as a desination for rendering or blits."

     Modify section 3.7.12 (Texture State) and place the last 3 sentences

     with the following:

     "Next, there are the three sets of texture properties; each consists of

     the selected minification and magnification filters, the wrap modes for

     <s> and <t>, and the usage flags. In the initial state, the value assigned

     to TEXTURE_MIN_FILTER is NEAREST_MIPMAP_LINEAR, and the value for 

     TEXTURE_MAG_FILTER is LINEAR. <s> and <t> wrap modes are both set to

     REPEAT. The initial value for TEXTURE_USAGE_ANGLE is NONE."

 Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment

 Operations and the Framebuffer)

     None

 Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special

 Functions):

     None

 Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and

 State Requests)

     None

 Dependencies on EXT_texture_storage

     If EXT_texture_storage is not supported, omit any references to 

     TexStorage2DEXT.

 Errors

     If TexParameter{if} or TexParamter{if}v is called with a <pname>

     of TEXTURE_USAGE_ANGLE and the value of <param> or <params> is not

     NONE or FRAMEBUFFER_ATTACHMENT_ANGLE the error INVALID_VALUE is

     generated.

 Usage Example

     /* create and bind texture */

     glGenTextures(1, &texture);

     glActiveTexture(GL_TEXTURE0);

     glBindTexture(GL_TEXTURE_2D, texture);

     /* specify texture parameters */

     glTexParameteri(GL_TEXTURE_2D, GL_*, ...);  /* as before */

     /* specify that we'll be rendering to the texture */

     glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_USAGE_ANGLE, GL_FRAMEBUFFER_ATTACHMENT_ANGLE);

     glTexStorage2DEXT(GL_TEXTURE_2D, levels, ...); // Allocation

     for(int level = 0; level < levels; ++level)

         glTexSubImage2D(GL_TEXTURE_2D, level, ...); // Initialisation

 Issues

     1. Should there be a dynamic usage value?

        DISCUSSION: We could accept a dynamic flag to indicate that a texture will

        be updated frequently. We could map this to D3D9 dynamic textures. This would

        allow us to avoid creating temporary surfaces when updating the texture.

        However renderable textures cannot be dynamic in D3D9, which eliminates the 

        primary use case for this.  Furthermore, the memory usage of dynamic textures

        typically increases threefold when you lock it.

     2. Should the texture usage be an enum or a bitfield?

        UNRESOLVED.  Using a bitfield would allow combination of values to be specified.

        On the other hand, if combinations are really required, additional <pnames>

        could be added as necessary.  Querying a bitfield via the GetTexParameter command

        feels a bit odd.

     3. What should happen if TEXTURE_USAGE_ANGLE is set/changed after the texture

        contents have been specified?

        RESOLVED: It will have no effect. However, if the texture is redefined (for 

        example by TexImage2D) the new allocation will use the updated usage.

        GetTexParameter is used to query the value of the TEXTURE_USAGE_ANGLE

        state that was last set by TexParameter for the currently bound texture, or

        the default value if it has never been set. There is no way to determine the 

        usage that was in effect at the time the texture was defined.

 Revision History

     Rev.    Date      Author     Changes

     ----  ----------- ---------  ----------------------------------------

       1   10 Nov 2011 dgkoch     Initial revision

       2   10 Nov 2011 dgkoch     Add overview