diff -r 000000000000 -r 6474c204b198 gfx/angle/extensions/ANGLE_texture_usage.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/gfx/angle/extensions/ANGLE_texture_usage.txt Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,202 @@ +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 for the TexParameter{if} and + TexParameter{if}v commands and for the parameter of + GetTexParameter{if}v: + + TEXTURE_USAGE_ANGLE 0x93A2 + + Accepted as a value to for the TexParameter{if} and + to for the TexParameter{if}v commands with a of + TEXTURE_USAGE_ANGLE; returned as possible values for when + GetTexParameter{if}v is queried with a 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 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 when 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 + and , 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. and 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 + of TEXTURE_USAGE_ANGLE and the value of or 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 + 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 + +