michael@0: Name
michael@0: 
michael@0:     ANGLE_texture_usage
michael@0: 
michael@0: Name Strings
michael@0: 
michael@0:     GL_ANGLE_texture_usage
michael@0: 
michael@0: Contributors
michael@0: 
michael@0:     Nicolas Capens, TransGaming
michael@0:     Daniel Koch, TransGaming
michael@0: 
michael@0: Contact
michael@0: 
michael@0:     Daniel Koch, TransGaming (daniel 'at' transgaming.com)
michael@0: 
michael@0: Status
michael@0: 
michael@0:     Complete
michael@0: 
michael@0: Version
michael@0: 
michael@0:     Last Modified Date:  November 10, 2011
michael@0:     Version:             2
michael@0: 
michael@0: Number
michael@0: 
michael@0:     OpenGL ES Extension #112 
michael@0: 
michael@0: Dependencies
michael@0: 
michael@0:     This extension is written against the OpenGL ES 2.0 Specification.
michael@0: 
michael@0: Overview
michael@0: 
michael@0:     In some implementations it is advantageous to know the expected
michael@0:     usage of a texture before the backing storage for it is allocated.  
michael@0:     This can help to inform the implementation's choice of format
michael@0:     and type of memory used for the allocation. If the usage is not
michael@0:     known in advance, the implementation essentially has to make a 
michael@0:     guess as to how it will be used.  If it is later proven wrong,
michael@0:     it may need to perform costly re-allocations and/or reformatting 
michael@0:     of the texture data, resulting in reduced performance.
michael@0: 
michael@0:     This extension adds a texture usage flag that is specified via
michael@0:     the TEXTURE_USAGE_ANGLE TexParameter.  This can be used to 
michael@0:     indicate that the application knows that this texture will be 
michael@0:     used for rendering.
michael@0: 
michael@0: IP Status
michael@0: 
michael@0:     No known IP claims.
michael@0: 
michael@0: New Procedures and Functions
michael@0: 
michael@0:     None
michael@0: 
michael@0: New Tokens
michael@0: 
michael@0:     Accepted as a value for <pname> for the TexParameter{if} and 
michael@0:     TexParameter{if}v commands and for the <value> parameter of
michael@0:     GetTexParameter{if}v: 
michael@0: 
michael@0:         TEXTURE_USAGE_ANGLE                     0x93A2
michael@0: 
michael@0:     Accepted as a value to <param> for the TexParameter{if} and 
michael@0:     to <params> for the TexParameter{if}v commands with a <pname> of 
michael@0:     TEXTURE_USAGE_ANGLE; returned as possible values for <data> when 
michael@0:     GetTexParameter{if}v is queried with a <value> of TEXTURE_USAGE_ANGLE:
michael@0: 
michael@0:         NONE                                    0x0000
michael@0:         FRAMEBUFFER_ATTACHMENT_ANGLE            0x93A3
michael@0: 
michael@0: Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation)
michael@0: 
michael@0:     None
michael@0: 
michael@0: Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
michael@0: 
michael@0:     Add a new row to Table 3.10 (Texture parameters and their values):
michael@0: 
michael@0:     Name                | Type | Legal Values 
michael@0:     ------------------------------------------------------------
michael@0:     TEXTURE_USAGE_ANGLE | enum | NONE, FRAMEBUFFER_ATTACHMENT_ANGLE
michael@0: 
michael@0:     Add a new section 3.7.x (Texture Usage) before section 3.7.12 and 
michael@0:     renumber the subsequent sections: 
michael@0: 
michael@0:     "3.7.x Texture Usage
michael@0: 
michael@0:     Texture usage can be specified via the TEXTURE_USAGE_ANGLE value
michael@0:     for the <pname> argument to TexParameter{if}[v]. In order to take effect,
michael@0:     the texture usage must be specified before the texture contents are
michael@0:     defined either via TexImage2D or TexStorage2DEXT.
michael@0: 
michael@0:     The usage values can impact the layout and type of memory used for the 
michael@0:     texture data. Specifying incorrect usage values may result in reduced
michael@0:     functionality and/or significantly degraded performance.
michael@0: 
michael@0:     Possible values for <params> when <pname> is TEXTURE_USAGE_ANGLE are:
michael@0: 
michael@0:     NONE - the default. No particular usage has been specified and it is
michael@0:         up to the implementation to determine the usage of the texture.
michael@0:         Leaving the usage unspecified means that the implementation may 
michael@0:         have to reallocate the texture data as the texture is used in 
michael@0:         various ways.
michael@0: 
michael@0:     FRAMEBUFFER_ATTACHMENT_ANGLE - this texture will be attached to a 
michael@0:         framebuffer object and used as a desination for rendering or blits."
michael@0: 
michael@0:     Modify section 3.7.12 (Texture State) and place the last 3 sentences
michael@0:     with the following:
michael@0: 
michael@0:     "Next, there are the three sets of texture properties; each consists of
michael@0:     the selected minification and magnification filters, the wrap modes for
michael@0:     <s> and <t>, and the usage flags. In the initial state, the value assigned
michael@0:     to TEXTURE_MIN_FILTER is NEAREST_MIPMAP_LINEAR, and the value for 
michael@0:     TEXTURE_MAG_FILTER is LINEAR. <s> and <t> wrap modes are both set to
michael@0:     REPEAT. The initial value for TEXTURE_USAGE_ANGLE is NONE."
michael@0: 
michael@0: 
michael@0: Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
michael@0: Operations and the Framebuffer)
michael@0: 
michael@0:     None
michael@0: 
michael@0: Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special
michael@0: Functions):
michael@0: 
michael@0:     None
michael@0: 
michael@0: Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and
michael@0: State Requests)
michael@0: 
michael@0:     None
michael@0: 
michael@0: Dependencies on EXT_texture_storage
michael@0: 
michael@0:     If EXT_texture_storage is not supported, omit any references to 
michael@0:     TexStorage2DEXT.
michael@0: 
michael@0: Errors
michael@0: 
michael@0:     If TexParameter{if} or TexParamter{if}v is called with a <pname>
michael@0:     of TEXTURE_USAGE_ANGLE and the value of <param> or <params> is not
michael@0:     NONE or FRAMEBUFFER_ATTACHMENT_ANGLE the error INVALID_VALUE is
michael@0:     generated.
michael@0: 
michael@0: Usage Example
michael@0: 
michael@0:     /* create and bind texture */
michael@0:     glGenTextures(1, &texture);
michael@0:     glActiveTexture(GL_TEXTURE0);
michael@0:     glBindTexture(GL_TEXTURE_2D, texture);
michael@0: 
michael@0:     /* specify texture parameters */
michael@0:     glTexParameteri(GL_TEXTURE_2D, GL_*, ...);  /* as before */
michael@0:     
michael@0:     /* specify that we'll be rendering to the texture */
michael@0:     glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_USAGE_ANGLE, GL_FRAMEBUFFER_ATTACHMENT_ANGLE);
michael@0: 
michael@0:     glTexStorage2DEXT(GL_TEXTURE_2D, levels, ...); // Allocation
michael@0:     for(int level = 0; level < levels; ++level)
michael@0:         glTexSubImage2D(GL_TEXTURE_2D, level, ...); // Initialisation
michael@0: 
michael@0: Issues
michael@0: 
michael@0:     1. Should there be a dynamic usage value?
michael@0:    
michael@0:        DISCUSSION: We could accept a dynamic flag to indicate that a texture will
michael@0:        be updated frequently. We could map this to D3D9 dynamic textures. This would
michael@0:        allow us to avoid creating temporary surfaces when updating the texture.
michael@0:        However renderable textures cannot be dynamic in D3D9, which eliminates the 
michael@0:        primary use case for this.  Furthermore, the memory usage of dynamic textures
michael@0:        typically increases threefold when you lock it.
michael@0: 
michael@0:     2. Should the texture usage be an enum or a bitfield?
michael@0: 
michael@0:        UNRESOLVED.  Using a bitfield would allow combination of values to be specified.
michael@0:        On the other hand, if combinations are really required, additional <pnames>
michael@0:        could be added as necessary.  Querying a bitfield via the GetTexParameter command
michael@0:        feels a bit odd.
michael@0: 
michael@0:     3. What should happen if TEXTURE_USAGE_ANGLE is set/changed after the texture
michael@0:        contents have been specified?
michael@0: 
michael@0:        RESOLVED: It will have no effect. However, if the texture is redefined (for 
michael@0:        example by TexImage2D) the new allocation will use the updated usage.
michael@0:        GetTexParameter is used to query the value of the TEXTURE_USAGE_ANGLE
michael@0:        state that was last set by TexParameter for the currently bound texture, or
michael@0:        the default value if it has never been set. There is no way to determine the 
michael@0:        usage that was in effect at the time the texture was defined.
michael@0: 
michael@0: Revision History
michael@0: 
michael@0:     Rev.    Date      Author     Changes
michael@0:     ----  ----------- ---------  ----------------------------------------
michael@0:       1   10 Nov 2011 dgkoch     Initial revision
michael@0:       2   10 Nov 2011 dgkoch     Add overview
michael@0:    
michael@0: