1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/gfx/angle/extensions/ANGLE_texture_usage.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,202 @@
1.4 +Name
1.5 +
1.6 + ANGLE_texture_usage
1.7 +
1.8 +Name Strings
1.9 +
1.10 + GL_ANGLE_texture_usage
1.11 +
1.12 +Contributors
1.13 +
1.14 + Nicolas Capens, TransGaming
1.15 + Daniel Koch, TransGaming
1.16 +
1.17 +Contact
1.18 +
1.19 + Daniel Koch, TransGaming (daniel 'at' transgaming.com)
1.20 +
1.21 +Status
1.22 +
1.23 + Complete
1.24 +
1.25 +Version
1.26 +
1.27 + Last Modified Date: November 10, 2011
1.28 + Version: 2
1.29 +
1.30 +Number
1.31 +
1.32 + OpenGL ES Extension #112
1.33 +
1.34 +Dependencies
1.35 +
1.36 + This extension is written against the OpenGL ES 2.0 Specification.
1.37 +
1.38 +Overview
1.39 +
1.40 + In some implementations it is advantageous to know the expected
1.41 + usage of a texture before the backing storage for it is allocated.
1.42 + This can help to inform the implementation's choice of format
1.43 + and type of memory used for the allocation. If the usage is not
1.44 + known in advance, the implementation essentially has to make a
1.45 + guess as to how it will be used. If it is later proven wrong,
1.46 + it may need to perform costly re-allocations and/or reformatting
1.47 + of the texture data, resulting in reduced performance.
1.48 +
1.49 + This extension adds a texture usage flag that is specified via
1.50 + the TEXTURE_USAGE_ANGLE TexParameter. This can be used to
1.51 + indicate that the application knows that this texture will be
1.52 + used for rendering.
1.53 +
1.54 +IP Status
1.55 +
1.56 + No known IP claims.
1.57 +
1.58 +New Procedures and Functions
1.59 +
1.60 + None
1.61 +
1.62 +New Tokens
1.63 +
1.64 + Accepted as a value for <pname> for the TexParameter{if} and
1.65 + TexParameter{if}v commands and for the <value> parameter of
1.66 + GetTexParameter{if}v:
1.67 +
1.68 + TEXTURE_USAGE_ANGLE 0x93A2
1.69 +
1.70 + Accepted as a value to <param> for the TexParameter{if} and
1.71 + to <params> for the TexParameter{if}v commands with a <pname> of
1.72 + TEXTURE_USAGE_ANGLE; returned as possible values for <data> when
1.73 + GetTexParameter{if}v is queried with a <value> of TEXTURE_USAGE_ANGLE:
1.74 +
1.75 + NONE 0x0000
1.76 + FRAMEBUFFER_ATTACHMENT_ANGLE 0x93A3
1.77 +
1.78 +Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation)
1.79 +
1.80 + None
1.81 +
1.82 +Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
1.83 +
1.84 + Add a new row to Table 3.10 (Texture parameters and their values):
1.85 +
1.86 + Name | Type | Legal Values
1.87 + ------------------------------------------------------------
1.88 + TEXTURE_USAGE_ANGLE | enum | NONE, FRAMEBUFFER_ATTACHMENT_ANGLE
1.89 +
1.90 + Add a new section 3.7.x (Texture Usage) before section 3.7.12 and
1.91 + renumber the subsequent sections:
1.92 +
1.93 + "3.7.x Texture Usage
1.94 +
1.95 + Texture usage can be specified via the TEXTURE_USAGE_ANGLE value
1.96 + for the <pname> argument to TexParameter{if}[v]. In order to take effect,
1.97 + the texture usage must be specified before the texture contents are
1.98 + defined either via TexImage2D or TexStorage2DEXT.
1.99 +
1.100 + The usage values can impact the layout and type of memory used for the
1.101 + texture data. Specifying incorrect usage values may result in reduced
1.102 + functionality and/or significantly degraded performance.
1.103 +
1.104 + Possible values for <params> when <pname> is TEXTURE_USAGE_ANGLE are:
1.105 +
1.106 + NONE - the default. No particular usage has been specified and it is
1.107 + up to the implementation to determine the usage of the texture.
1.108 + Leaving the usage unspecified means that the implementation may
1.109 + have to reallocate the texture data as the texture is used in
1.110 + various ways.
1.111 +
1.112 + FRAMEBUFFER_ATTACHMENT_ANGLE - this texture will be attached to a
1.113 + framebuffer object and used as a desination for rendering or blits."
1.114 +
1.115 + Modify section 3.7.12 (Texture State) and place the last 3 sentences
1.116 + with the following:
1.117 +
1.118 + "Next, there are the three sets of texture properties; each consists of
1.119 + the selected minification and magnification filters, the wrap modes for
1.120 + <s> and <t>, and the usage flags. In the initial state, the value assigned
1.121 + to TEXTURE_MIN_FILTER is NEAREST_MIPMAP_LINEAR, and the value for
1.122 + TEXTURE_MAG_FILTER is LINEAR. <s> and <t> wrap modes are both set to
1.123 + REPEAT. The initial value for TEXTURE_USAGE_ANGLE is NONE."
1.124 +
1.125 +
1.126 +Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
1.127 +Operations and the Framebuffer)
1.128 +
1.129 + None
1.130 +
1.131 +Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special
1.132 +Functions):
1.133 +
1.134 + None
1.135 +
1.136 +Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and
1.137 +State Requests)
1.138 +
1.139 + None
1.140 +
1.141 +Dependencies on EXT_texture_storage
1.142 +
1.143 + If EXT_texture_storage is not supported, omit any references to
1.144 + TexStorage2DEXT.
1.145 +
1.146 +Errors
1.147 +
1.148 + If TexParameter{if} or TexParamter{if}v is called with a <pname>
1.149 + of TEXTURE_USAGE_ANGLE and the value of <param> or <params> is not
1.150 + NONE or FRAMEBUFFER_ATTACHMENT_ANGLE the error INVALID_VALUE is
1.151 + generated.
1.152 +
1.153 +Usage Example
1.154 +
1.155 + /* create and bind texture */
1.156 + glGenTextures(1, &texture);
1.157 + glActiveTexture(GL_TEXTURE0);
1.158 + glBindTexture(GL_TEXTURE_2D, texture);
1.159 +
1.160 + /* specify texture parameters */
1.161 + glTexParameteri(GL_TEXTURE_2D, GL_*, ...); /* as before */
1.162 +
1.163 + /* specify that we'll be rendering to the texture */
1.164 + glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_USAGE_ANGLE, GL_FRAMEBUFFER_ATTACHMENT_ANGLE);
1.165 +
1.166 + glTexStorage2DEXT(GL_TEXTURE_2D, levels, ...); // Allocation
1.167 + for(int level = 0; level < levels; ++level)
1.168 + glTexSubImage2D(GL_TEXTURE_2D, level, ...); // Initialisation
1.169 +
1.170 +Issues
1.171 +
1.172 + 1. Should there be a dynamic usage value?
1.173 +
1.174 + DISCUSSION: We could accept a dynamic flag to indicate that a texture will
1.175 + be updated frequently. We could map this to D3D9 dynamic textures. This would
1.176 + allow us to avoid creating temporary surfaces when updating the texture.
1.177 + However renderable textures cannot be dynamic in D3D9, which eliminates the
1.178 + primary use case for this. Furthermore, the memory usage of dynamic textures
1.179 + typically increases threefold when you lock it.
1.180 +
1.181 + 2. Should the texture usage be an enum or a bitfield?
1.182 +
1.183 + UNRESOLVED. Using a bitfield would allow combination of values to be specified.
1.184 + On the other hand, if combinations are really required, additional <pnames>
1.185 + could be added as necessary. Querying a bitfield via the GetTexParameter command
1.186 + feels a bit odd.
1.187 +
1.188 + 3. What should happen if TEXTURE_USAGE_ANGLE is set/changed after the texture
1.189 + contents have been specified?
1.190 +
1.191 + RESOLVED: It will have no effect. However, if the texture is redefined (for
1.192 + example by TexImage2D) the new allocation will use the updated usage.
1.193 + GetTexParameter is used to query the value of the TEXTURE_USAGE_ANGLE
1.194 + state that was last set by TexParameter for the currently bound texture, or
1.195 + the default value if it has never been set. There is no way to determine the
1.196 + usage that was in effect at the time the texture was defined.
1.197 +
1.198 +Revision History
1.199 +
1.200 + Rev. Date Author Changes
1.201 + ---- ----------- --------- ----------------------------------------
1.202 + 1 10 Nov 2011 dgkoch Initial revision
1.203 + 2 10 Nov 2011 dgkoch Add overview
1.204 +
1.205 +
