gfx/angle/extensions/ANGLE_texture_usage.txt@6474c204b198 (annotated)
gfx/angle/extensions/ANGLE_texture_usage.txt
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
| michael@0 | 1 | Name |
| michael@0 | 2 | |
| michael@0 | 3 | ANGLE_texture_usage |
| michael@0 | 4 | |
| michael@0 | 5 | Name Strings |
| michael@0 | 6 | |
| michael@0 | 7 | GL_ANGLE_texture_usage |
| michael@0 | 8 | |
| michael@0 | 9 | Contributors |
| michael@0 | 10 | |
| michael@0 | 11 | Nicolas Capens, TransGaming |
| michael@0 | 12 | Daniel Koch, TransGaming |
| michael@0 | 13 | |
| michael@0 | 14 | Contact |
| michael@0 | 15 | |
| michael@0 | 16 | Daniel Koch, TransGaming (daniel 'at' transgaming.com) |
| michael@0 | 17 | |
| michael@0 | 18 | Status |
| michael@0 | 19 | |
| michael@0 | 20 | Complete |
| michael@0 | 21 | |
| michael@0 | 22 | Version |
| michael@0 | 23 | |
| michael@0 | 24 | Last Modified Date: November 10, 2011 |
| michael@0 | 25 | Version: 2 |
| michael@0 | 26 | |
| michael@0 | 27 | Number |
| michael@0 | 28 | |
| michael@0 | 29 | OpenGL ES Extension #112 |
| michael@0 | 30 | |
| michael@0 | 31 | Dependencies |
| michael@0 | 32 | |
| michael@0 | 33 | This extension is written against the OpenGL ES 2.0 Specification. |
| michael@0 | 34 | |
| michael@0 | 35 | Overview |
| michael@0 | 36 | |
| michael@0 | 37 | In some implementations it is advantageous to know the expected |
| michael@0 | 38 | usage of a texture before the backing storage for it is allocated. |
| michael@0 | 39 | This can help to inform the implementation's choice of format |
| michael@0 | 40 | and type of memory used for the allocation. If the usage is not |
| michael@0 | 41 | known in advance, the implementation essentially has to make a |
| michael@0 | 42 | guess as to how it will be used. If it is later proven wrong, |
| michael@0 | 43 | it may need to perform costly re-allocations and/or reformatting |
| michael@0 | 44 | of the texture data, resulting in reduced performance. |
| michael@0 | 45 | |
| michael@0 | 46 | This extension adds a texture usage flag that is specified via |
| michael@0 | 47 | the TEXTURE_USAGE_ANGLE TexParameter. This can be used to |
| michael@0 | 48 | indicate that the application knows that this texture will be |
| michael@0 | 49 | used for rendering. |
| michael@0 | 50 | |
| michael@0 | 51 | IP Status |
| michael@0 | 52 | |
| michael@0 | 53 | No known IP claims. |
| michael@0 | 54 | |
| michael@0 | 55 | New Procedures and Functions |
| michael@0 | 56 | |
| michael@0 | 57 | None |
| michael@0 | 58 | |
| michael@0 | 59 | New Tokens |
| michael@0 | 60 | |
| michael@0 | 61 | Accepted as a value for <pname> for the TexParameter{if} and |
| michael@0 | 62 | TexParameter{if}v commands and for the <value> parameter of |
| michael@0 | 63 | GetTexParameter{if}v: |
| michael@0 | 64 | |
| michael@0 | 65 | TEXTURE_USAGE_ANGLE 0x93A2 |
| michael@0 | 66 | |
| michael@0 | 67 | Accepted as a value to <param> for the TexParameter{if} and |
| michael@0 | 68 | to <params> for the TexParameter{if}v commands with a <pname> of |
| michael@0 | 69 | TEXTURE_USAGE_ANGLE; returned as possible values for <data> when |
| michael@0 | 70 | GetTexParameter{if}v is queried with a <value> of TEXTURE_USAGE_ANGLE: |
| michael@0 | 71 | |
| michael@0 | 72 | NONE 0x0000 |
| michael@0 | 73 | FRAMEBUFFER_ATTACHMENT_ANGLE 0x93A3 |
| michael@0 | 74 | |
| michael@0 | 75 | Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation) |
| michael@0 | 76 | |
| michael@0 | 77 | None |
| michael@0 | 78 | |
| michael@0 | 79 | Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) |
| michael@0 | 80 | |
| michael@0 | 81 | Add a new row to Table 3.10 (Texture parameters and their values): |
| michael@0 | 82 | |
| michael@0 | 83 | Name | Type | Legal Values |
| michael@0 | 84 | ------------------------------------------------------------ |
| michael@0 | 85 | TEXTURE_USAGE_ANGLE | enum | NONE, FRAMEBUFFER_ATTACHMENT_ANGLE |
| michael@0 | 86 | |
| michael@0 | 87 | Add a new section 3.7.x (Texture Usage) before section 3.7.12 and |
| michael@0 | 88 | renumber the subsequent sections: |
| michael@0 | 89 | |
| michael@0 | 90 | "3.7.x Texture Usage |
| michael@0 | 91 | |
| michael@0 | 92 | Texture usage can be specified via the TEXTURE_USAGE_ANGLE value |
| michael@0 | 93 | for the <pname> argument to TexParameter{if}[v]. In order to take effect, |
| michael@0 | 94 | the texture usage must be specified before the texture contents are |
| michael@0 | 95 | defined either via TexImage2D or TexStorage2DEXT. |
| michael@0 | 96 | |
| michael@0 | 97 | The usage values can impact the layout and type of memory used for the |
| michael@0 | 98 | texture data. Specifying incorrect usage values may result in reduced |
| michael@0 | 99 | functionality and/or significantly degraded performance. |
| michael@0 | 100 | |
| michael@0 | 101 | Possible values for <params> when <pname> is TEXTURE_USAGE_ANGLE are: |
| michael@0 | 102 | |
| michael@0 | 103 | NONE - the default. No particular usage has been specified and it is |
| michael@0 | 104 | up to the implementation to determine the usage of the texture. |
| michael@0 | 105 | Leaving the usage unspecified means that the implementation may |
| michael@0 | 106 | have to reallocate the texture data as the texture is used in |
| michael@0 | 107 | various ways. |
| michael@0 | 108 | |
| michael@0 | 109 | FRAMEBUFFER_ATTACHMENT_ANGLE - this texture will be attached to a |
| michael@0 | 110 | framebuffer object and used as a desination for rendering or blits." |
| michael@0 | 111 | |
| michael@0 | 112 | Modify section 3.7.12 (Texture State) and place the last 3 sentences |
| michael@0 | 113 | with the following: |
| michael@0 | 114 | |
| michael@0 | 115 | "Next, there are the three sets of texture properties; each consists of |
| michael@0 | 116 | the selected minification and magnification filters, the wrap modes for |
| michael@0 | 117 | <s> and <t>, and the usage flags. In the initial state, the value assigned |
| michael@0 | 118 | to TEXTURE_MIN_FILTER is NEAREST_MIPMAP_LINEAR, and the value for |
| michael@0 | 119 | TEXTURE_MAG_FILTER is LINEAR. <s> and <t> wrap modes are both set to |
| michael@0 | 120 | REPEAT. The initial value for TEXTURE_USAGE_ANGLE is NONE." |
| michael@0 | 121 | |
| michael@0 | 122 | |
| michael@0 | 123 | Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment |
| michael@0 | 124 | Operations and the Framebuffer) |
| michael@0 | 125 | |
| michael@0 | 126 | None |
| michael@0 | 127 | |
| michael@0 | 128 | Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special |
| michael@0 | 129 | Functions): |
| michael@0 | 130 | |
| michael@0 | 131 | None |
| michael@0 | 132 | |
| michael@0 | 133 | Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and |
| michael@0 | 134 | State Requests) |
| michael@0 | 135 | |
| michael@0 | 136 | None |
| michael@0 | 137 | |
| michael@0 | 138 | Dependencies on EXT_texture_storage |
| michael@0 | 139 | |
| michael@0 | 140 | If EXT_texture_storage is not supported, omit any references to |
| michael@0 | 141 | TexStorage2DEXT. |
| michael@0 | 142 | |
| michael@0 | 143 | Errors |
| michael@0 | 144 | |
| michael@0 | 145 | If TexParameter{if} or TexParamter{if}v is called with a <pname> |
| michael@0 | 146 | of TEXTURE_USAGE_ANGLE and the value of <param> or <params> is not |
| michael@0 | 147 | NONE or FRAMEBUFFER_ATTACHMENT_ANGLE the error INVALID_VALUE is |
| michael@0 | 148 | generated. |
| michael@0 | 149 | |
| michael@0 | 150 | Usage Example |
| michael@0 | 151 | |
| michael@0 | 152 | /* create and bind texture */ |
| michael@0 | 153 | glGenTextures(1, &texture); |
| michael@0 | 154 | glActiveTexture(GL_TEXTURE0); |
| michael@0 | 155 | glBindTexture(GL_TEXTURE_2D, texture); |
| michael@0 | 156 | |
| michael@0 | 157 | /* specify texture parameters */ |
| michael@0 | 158 | glTexParameteri(GL_TEXTURE_2D, GL_*, ...); /* as before */ |
| michael@0 | 159 | |
| michael@0 | 160 | /* specify that we'll be rendering to the texture */ |
| michael@0 | 161 | glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_USAGE_ANGLE, GL_FRAMEBUFFER_ATTACHMENT_ANGLE); |
| michael@0 | 162 | |
| michael@0 | 163 | glTexStorage2DEXT(GL_TEXTURE_2D, levels, ...); // Allocation |
| michael@0 | 164 | for(int level = 0; level < levels; ++level) |
| michael@0 | 165 | glTexSubImage2D(GL_TEXTURE_2D, level, ...); // Initialisation |
| michael@0 | 166 | |
| michael@0 | 167 | Issues |
| michael@0 | 168 | |
| michael@0 | 169 | 1. Should there be a dynamic usage value? |
| michael@0 | 170 | |
| michael@0 | 171 | DISCUSSION: We could accept a dynamic flag to indicate that a texture will |
| michael@0 | 172 | be updated frequently. We could map this to D3D9 dynamic textures. This would |
| michael@0 | 173 | allow us to avoid creating temporary surfaces when updating the texture. |
| michael@0 | 174 | However renderable textures cannot be dynamic in D3D9, which eliminates the |
| michael@0 | 175 | primary use case for this. Furthermore, the memory usage of dynamic textures |
| michael@0 | 176 | typically increases threefold when you lock it. |
| michael@0 | 177 | |
| michael@0 | 178 | 2. Should the texture usage be an enum or a bitfield? |
| michael@0 | 179 | |
| michael@0 | 180 | UNRESOLVED. Using a bitfield would allow combination of values to be specified. |
| michael@0 | 181 | On the other hand, if combinations are really required, additional <pnames> |
| michael@0 | 182 | could be added as necessary. Querying a bitfield via the GetTexParameter command |
| michael@0 | 183 | feels a bit odd. |
| michael@0 | 184 | |
| michael@0 | 185 | 3. What should happen if TEXTURE_USAGE_ANGLE is set/changed after the texture |
| michael@0 | 186 | contents have been specified? |
| michael@0 | 187 | |
| michael@0 | 188 | RESOLVED: It will have no effect. However, if the texture is redefined (for |
| michael@0 | 189 | example by TexImage2D) the new allocation will use the updated usage. |
| michael@0 | 190 | GetTexParameter is used to query the value of the TEXTURE_USAGE_ANGLE |
| michael@0 | 191 | state that was last set by TexParameter for the currently bound texture, or |
| michael@0 | 192 | the default value if it has never been set. There is no way to determine the |
| michael@0 | 193 | usage that was in effect at the time the texture was defined. |
| michael@0 | 194 | |
| michael@0 | 195 | Revision History |
| michael@0 | 196 | |
| michael@0 | 197 | Rev. Date Author Changes |
| michael@0 | 198 | ---- ----------- --------- ---------------------------------------- |
| michael@0 | 199 | 1 10 Nov 2011 dgkoch Initial revision |
| michael@0 | 200 | 2 10 Nov 2011 dgkoch Add overview |
| michael@0 | 201 | |
| michael@0 | 202 |
