1Name 2 INTEL_map_texture 3 4Name Strings 5 GL_INTEL_map_texture 6 7Contact 8 Slawomir Grajewski, INTEL (slawomir.grajewski 'at' intel.com) 9 10Contributors 11 Jan Paul van Waveren, id Software 12 Kamil Patelczyk, INTEL 13 Aneta Roztkowska, INTEL 14 Piotr Uminski, INTEL 15 16Status 17 Draft. 18 19Version 20 Last Modified Date: June 5, 2012 21 Author Revision: 1 22 23Number 24 25 429 26 27Dependencies 28 OpenGL 3.0 is required. 29 30 This extension is written against the OpenGL 4.2 Specification 31 compatibility profile. 32 33Overview 34 Systems with integrated GPUs can share the same physical memory between CPU 35 and GPU. This feature, if exposed by API, can bring significant performance 36 benefits for graphics applications by reducing the complexity of 37 uploading/accessing texture contents. This extension enables CPU direct 38 access to the GPU memory holding textures. 39 40 The problem with texture memory directly exposed to clients is that 41 textures are often 'tiled'. Texels are kept in specific layout to improve 42 locality of reference and thus performance of texturing. This 'tiling' 43 is specific to particular hardware and would be thus difficult to use. 44 45 This extension allows to create textures with 'linear' layout which allows 46 for simplified access on user side (potentially sacrificing some 47 performance during texture sampling). 48 49New Procedures and Functions 50 51 void* MapTexture2DINTEL(uint texture, int level, bitfield access, 52 int *stride, enum *layout); 53 54 void UnmapTexture2DINTEL(uint texture, int level); 55 56 void SyncTextureINTEL(uint texture); 57 58 59New Tokens 60 61 Accepted by the <pname> parameter of TexParameteri, for target TEXTURE_2D 62 63 TEXTURE_MEMORY_LAYOUT_INTEL 0x83FF 64 65 Accepted by the <params> when <pname> is set to 66 <TEXTURE_MEMORY_LAYOUT_INTEL>: 67 68 LAYOUT_DEFAULT_INTEL 0 69 LAYOUT_LINEAR_INTEL 1 70 LAYOUT_LINEAR_CPU_CACHED_INTEL 2 71 72Additions to Chapter 3.10.8 of the OpenGL 4.2 (Compatibility Profile) 73Specification 74 75Add a row to the table 3.22 76 77 Name: 78 TEXTURE_MEMORY_LAYOUT_INTEL 79 80 Type: 81 enum 82 83 Legal Values: 84 LAYOUT_DEFAULT_INTEL 85 LAYOUT_LINEAR_INTEL 86 LAYOUT_LINEAR_CPU_CACHED_INTEL 87 88Add a paragraph in the end of the section: 89 90 When <pname> is TEXTURE_MEMORY_LAYOUT_INTEL and <params> is 91 LAYOUT_LINEAR_INTEL the texture is forced to be allocated as linear and can 92 be mapped directly to the CPU address space by MapTexture2DINTEL (see section 93 3.10.4). 94 95 When <pname> is TEXTURE_MEMORY_LAYOUT_INTEL and <params> is 96 LAYOUT_LINEAR_CPU_CACHED_INTEL the behavior is the same as in case of 97 <params> set to LAYOUT_LINEAR_INTEL with an exception that texture is 98 cached for CPU accesses. This can result in better performance when reading 99 texture on CPU but might negatively impact the GPU side access to the 100 texture. Thus the option is intended only for cases when volume of the read 101 access from CPU justifies such effect. 102 103 Only when <pname> is TEXTURE_MEMORY_LAYOUT_INTEL or 104 LAYOUT_LINEAR_CPU_CACHED_INTEL, MapTexture2DINTEL returns CPU accessible 105 pointer. 106 107 The allocation of the texture can be reverted to the default, 108 implementation-specific format, including tiled formats, by calling 109 TexParameteri with <pname> set to TEXTURE_MEMORY_LAYOUT_INTEL and <params> 110 set to LAYOUT_DEFAULT_INTEL. The configured texture layout is ignored until 111 the texture is allocated or reallocated using TexImage2D function. 112 113 The error INVALID_VALUE is generated when <pname> is 114 TEXTURE_MEMORY_LAYOUT_INTEL and the texture target is not TEXTURE_2D. 115 116Additions to Chapter 3.10.4 of the OpenGL 4.2 (Compatibility Profile) Specification 117 118 The command 119 120 void* MapTexture2DINTEL(uint texture, int level, bitfield access, 121 int *stride, enum *layout); 122 123 attempts to return a direct pointer to the graphics storage for 2D texture 124 indicated by the <texture> parameter. 125 126 The <level> parameter indicates the mipmap level-of-detail of the texture 127 for which pointer is requested. 128 129 The <access> bitfield indicates type of access that will be performed by 130 the application on the memory accessed via the returned pointer: reading - 131 MAP_READ_BIT, writing - MAP_WRITE_BIT. Performing access on mapped memory 132 different then specified in <access> is undefined (and may result in 133 application termination). 134 135 If the operation is successful, the function returns a valid pointer, 136 otherwise NULL is returned. Upon successful completion, the function also 137 returns 'stride', which is the distance in bytes between subsequent rows in the 138 texture, and <layout>, indicating the internal layout of the texture in the 139 graphics memory. 140 141 When texture uses linear memory layout, subsequent texels in a row of the 142 image are occupying subsequent addresses in memory. Subsequent rows of 143 image are located at 'stride' bytes distance within each other. For tiled 144 layout, the relationship between texels and addresses in memory is 145 different and will not be further discussed in this extension. 146 147 The layout of the texture, discussed in the preceding section, is returned 148 via <layout> parameter. In this version of the extension, the only texture 149 memory layout that can be returned is LAYOUT_LINEAR_INTEL or 150 LAYOUT_LINEAR_CPU_CACHED_INTEL. 151 152 All of the following conditions need to be met for the operation to succeed: 153 - <texture> is a texture first bound to TEXTURE_2D target 154 - <texture> has sized color internal format (see section 3.10.3) 155 - texture parameter TEXTURE_MEMORY_LAYOUT_INTEL was either 156 LAYOUT_LINEAR_INTEL or LAYOUT_LINEAR_CPU_CACHED_INTEL during texture 157 image specification 158 - <level> texture mipmap level is defined 159 - texture border of <texture> is zero 160 Otherwise MapTexture2DINTEL fails with INVALID_OPERATION error, and return 161 NULL. 162 163 Please note that texture allocated as linear is noticeably slower than 164 tiled when accessed by the GPU, however in many scenarios direct access to 165 such texture from CPU is more important than slower GPU access, especially 166 when texture is frequently updated with limited number of accesses from 167 GPU. 168 169 The command MapTexture2DINTEL can return valid pointer only if given 170 internalformat as specified by TexImage2D() is sized (as indicated in 171 tables 16 and 17) and natively supported by the GPU hardware. This means 172 that there has to be 1:1 match between internalformat and underlying 173 hardware format with respect to the number of components, their sizes and 174 order in graphics memory. 175 176 It is an error to attempt to map texture that is defined inconsistently (one 177 which doesn't provide mipmap levels with the same internal format or with 178 sizes not being half the previous level) or to redefine texture levels 179 (through TexImage2D, CopyTexImage2D) when texture mappings exist for this 180 texture. These cases will result in undefined behavior. 181 182 The command 183 184 void UnmapTexture2DINTEL(uint texture, int level); 185 186 releases the pointer obtained previously via MapTexture2DINTEL. This means 187 that virtual memory space dedicated to make the texture available via 188 a pointer is released and an application can no longer assume this memory 189 is accessible from CPU. Successful execution of this command has an additional 190 effect as if SyncTextureINTEL was called with <texture> parameter. 191 192 The command 193 194 void SyncTextureINTEL(uint texture); 195 196 makes sure that changes made by CPU are visible to GPU by flushing texture 197 cache in GPU. The GL implementation tracks the cache usage and ignores the 198 command if such flush is not needed. 199 200 It is worth noting that this extension does not address automatic 201 synchronization between CPU and GPU when both entities operate on the same 202 texture at the same time. This is up to the application to assure such 203 synchronization. Otherwise, the results may not be deterministic (writes 204 from different entities may interleave in a non-deterministic way). 205 206Modifications to the OpenGL Shading Language Specification. 207 208 None. 209 210Errors 211 212 INVALID_OPERATION is generated by MapTexture2DINTEL when <texture> is 0 or 213 not a name of texture object first bound to TEXTURE_2D target, when <level> 214 of <texture> is already mapped, when <texture> storage was allocated with 215 TEXTURE_MEMORY_LAYOUT_INTEL different then LAYOUT_LINEAR_INTEL or 216 LAYOUT_LINEAR_CPU_CACHED_INTEL or <level> is mipmap level not defined in 217 <texture>. 218 219 INVALID_VALUE is generated by MapTexture2DINTEL when <access> has bits other 220 then MAP_WRITE_BIT or MAP_READ_BIT set or is 0. 221 222 INVALID_OPERATION is generated by UnmapTexture2DINTEL when <texture> is not 223 an existing texture object or is 0, <level> of <texture> is not currently 224 mapped. 225 226New State 227 228(add to table 6.24, "Textures (state per texture object)") 229 230 Get Value Type Get Command Initial Value Description Section Attribute 231 ------------------------------- ------ ------------- ------------- -------------------- ------------ --------- 232 TEXTURE_MEMORY_LAYOUT_INTEL Z GetTexParameteriv LAYOUT_DEFAULT_INTEL Texture memory layout - - 233 234Issues 235 236 (1) Is it possible to ensure that contents of mapped texture is 237 automatically updated after rendering to texture or GPU write (using 238 texture as FBO attachment or using image_load_store functionality)? 239 240 RESOLUTION: 241 a) No guarantees are given in case of 'rendering loops' when surface 242 is mapped. To make sure that contents of mapping is 'current', 243 texture data mutation needs to be guaranteed as is done already 244 and mapped only after that. 245 246 RESOLVED: No. 247 248 249 (2) What happens if Tex(Sub)Image* or CopyTex(Sub)Image is called on 250 mapped texture? What happens if mapped texture is deleted? 251 252 RESOLUTION: 253 a) Calling Tex(Sub)Image may cause the texture to be reallocated, thus 254 it is necessary to unmap texture before calling these functions 255 (after these functions complete, the pointer may become invalid). 256 257 b) Calling CopyTex(Sub)Image is safe for a texture for which a CPU 258 pointer has been obtained via MapTexture2DINTEL. 259 260 c) After deleting the texture, the pointer obtained via 261 MapTexture2DINTEL becomes invalid. 262 263 RESOLVED: Yes. 264 265 266 (3) Is it possible to enforce alignment of mapped texture level? 267 268 RESOLUTION: No. 269 270 271 (4) Is it legal to write to / read from regions between row end and stride? 272 273 RESOLUTION: 274 a) Yes. Writing to memory that is after end of the row up to stride is 275 safe and has no effect. 276 277 RESOLVED: Yes. 278 279 280 (5) What happens if texture with unsupported (not native) format is 281 mapped? 282 283 RESOLUTION: 284 NULL pointer is returned. 285 286 RESOLVED: Yes. 287 288 289 (6) Are compressed formats supported? 290 291 RESOLUTION: 292 a) Yes. 293 294 RESOLVED: Yes. 295 296 297 298Revision History 299 300 Rev. Date Author Changes 301 ---- -------- -------- ----------------------------------------- 302 1 06/05/12 S. Grajewski Initial revision. 303