ANGLE_texture_usage

GL_ANGLE_texture_usage

Nicolas Capens, TransGaming
Daniel Koch, TransGaming

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

Complete

Last Modified Date:  November 10, 2011
Version:             2

OpenGL ES Extension #112 

This extension is written against the OpenGL ES 2.0 Specification.

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.

No known IP claims.

None

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

None

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."

None

None

None

If EXT_texture_storage is not supported, omit any references to 
TexStorage2DEXT.

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.

/* 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

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.

Rev.    Date      Author     Changes
----  ----------- ---------  ----------------------------------------
  1   10 Nov 2011 dgkoch     Initial revision
  2   10 Nov 2011 dgkoch     Add overview