1Name 2 3 ANGLE_external_objects_flags 4 5Name Strings 6 7 GL_ANGLE_memory_object_flags 8 9Contributors 10 11 Shahbaz Youssefi, Google 12 13Contact 14 15 Shahbaz Youssefi, Google (syoussefi 'at' google.com) 16 17Status 18 19 Draft 20 21Version 22 23 Last Modified Date: Nov 10, 2021 24 Revision: 2 25 26Number 27 28 TBD 29 30Dependencies 31 32 Written against the OpenGL 4.5 and OpenGL ES 3.2 specifications 33 34 GL_ANGLE_memory_object_flags requires GL_EXT_memory_object. 35 36Overview 37 38 Building upon the OpenGL memory object framework defined in 39 EXT_external_objects, this extension introduces new Texture entry points 40 for specifying create and usage flags parameters. These parameters match 41 an external Texture's corresponding Vulkan create and usage flags. This 42 allows applications to drop usage flags that are detrimental to 43 performance, or add create flags as necessary. 44 45 Additionally, these entry points take the pointer to the chain of extension 46 structures appended to VkImageCreateInfo, so that the OpenGL implementation 47 can recreate the image identically. 48 49New Procedures and Functions 50 51 The following commands are added: 52 53 void TexStorageMemFlags2DANGLE(enum target, 54 sizei levels, 55 enum internalFormat, 56 sizei width, 57 sizei height, 58 uint memory, 59 uint64 offset, 60 bitfield createFlags, 61 bitfield usageFlags, 62 const void *imageCreateInfoPNext); 63 64 void TexStorageMemFlags2DMultisampleANGLE(enum target, 65 sizei samples, 66 enum internalFormat, 67 sizei width, 68 sizei height, 69 boolean fixedSampleLocations, 70 uint memory, 71 uint64 offset, 72 bitfield createFlags, 73 bitfield usageFlags, 74 const void *imageCreateInfoPNext); 75 76 void TexStorageMemFlags3DANGLE(enum target, 77 sizei levels, 78 enum internalFormat, 79 sizei width, 80 sizei height, 81 sizei depth, 82 uint memory, 83 uint64 offset, 84 bitfield createFlags, 85 bitfield usageFlags, 86 const void *imageCreateInfoPNext); 87 88 void TexStorageMemFlags3DMultisampleANGLE(enum target, 89 sizei samples, 90 enum internalFormat, 91 sizei width, 92 sizei height, 93 sizei depth, 94 boolean fixedSampleLocations, 95 uint memory, 96 uint64 offset, 97 bitfield createFlags, 98 bitfield usageFlags, 99 const void *imageCreateInfoPNext); 100 101 [[ The following are added if direct state access is supported ]] 102 103 void TextureStorageMemFlags2DANGLE(uint texture, 104 sizei levels, 105 enum internalFormat, 106 sizei width, 107 sizei height, 108 uint memory, 109 uint64 offset, 110 bitfield createFlags, 111 bitfield usageFlags, 112 const void *imageCreateInfoPNext); 113 114 void TextureStorageMemFlags2DMultisampleANGLE(uint texture, 115 sizei samples, 116 enum internalFormat, 117 sizei width, 118 sizei height, 119 boolean fixedSampleLocations, 120 uint memory, 121 uint64 offset, 122 bitfield createFlags, 123 bitfield usageFlags, 124 const void *imageCreateInfoPNext); 125 126 void TextureStorageMemFlags3DANGLE(uint texture, 127 sizei levels, 128 enum internalFormat, 129 sizei width, 130 sizei height, 131 sizei depth, 132 uint memory, 133 uint64 offset, 134 bitfield createFlags, 135 bitfield usageFlags, 136 const void *imageCreateInfoPNext); 137 138 void TextureStorageMemFlags3DMultisampleANGLE(uint texture, 139 sizei samples, 140 enum internalFormat, 141 sizei width, 142 sizei height, 143 sizei depth, 144 boolean fixedSampleLocations, 145 uint memory, 146 uint64 offset, 147 bitfield createFlags, 148 bitfield usageFlags, 149 const void *imageCreateInfoPNext); 150 151 [[ The following are available in OpenGL only ]] 152 153 void TexStorageMemFlags1DANGLE(enum target, 154 sizei levels, 155 enum internalFormat, 156 sizei width, 157 uint memory, 158 uint64 offset, 159 bitfield createFlags, 160 bitfield usageFlags, 161 const void *imageCreateInfoPNext); 162 163 [[ The following are availble in OpenGL only, and only when 164 direct state access is available ]] 165 166 void TextureStorageMemFlags1DANGLE(uint texture, 167 sizei levels, 168 enum internalFormat, 169 sizei width, 170 uint memory, 171 uint64 offset, 172 bitfield createFlags, 173 bitfield usageFlags, 174 const void *imageCreateInfoPNext); 175 176New Tokens 177 178 The following tokens are added: 179 180 Accepted by the <createFlags> parameter of TexStorageMemFlags*ANGLE() and 181 TextureStorageMemFlags*ANGLE(). 182 183 CREATE_SPARSE_BINDING_BIT_ANGLE 0x00000001 184 CREATE_SPARSE_RESIDENCY_BIT_ANGLE 0x00000002 185 CREATE_SPARSE_ALIASED_BIT_ANGLE 0x00000004 186 CREATE_MUTABLE_FORMAT_BIT_ANGLE 0x00000008 187 CREATE_CUBE_COMPATIBLE_BIT_ANGLE 0x00000010 188 CREATE_ALIAS_BIT_ANGLE 0x00000400 189 CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_ANGLE 0x00000040 190 CREATE_2D_ARRAY_COMPATIBLE_BIT_ANGLE 0x00000020 191 CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_ANGLE 0x00000080 192 CREATE_EXTENDED_USAGE_BIT_ANGLE 0x00000100 193 CREATE_PROTECTED_BIT_ANGLE 0x00000800 194 CREATE_DISJOINT_BIT_ANGLE 0x00000200 195 CREATE_CORNER_SAMPLED_BIT_ANGLE 0x00002000 196 CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_ANGLE 0x00001000 197 CREATE_SUBSAMPLED_BIT_ANGLE 0x00004000 198 199 Accepted by the <usageFlags> parameter of TexStorageMemFlags*ANGLE() and 200 TextureStorageMemFlags*ANGLE(). 201 202 USAGE_TRANSFER_SRC_BIT_ANGLE 0x00000001 203 USAGE_TRANSFER_DST_BIT_ANGLE 0x00000002 204 USAGE_SAMPLED_BIT_ANGLE 0x00000004 205 USAGE_STORAGE_BIT_ANGLE 0x00000008 206 USAGE_COLOR_ATTACHMENT_BIT_ANGLE 0x00000010 207 USAGE_DEPTH_STENCIL_ATTACHMENT_BIT_ANGLE 0x00000020 208 USAGE_TRANSIENT_ATTACHMENT_BIT_ANGLE 0x00000040 209 USAGE_INPUT_ATTACHMENT_BIT_ANGLE 0x00000080 210 USAGE_SHADING_RATE_IMAGE_BIT_ANGLE 0x00000100 211 USAGE_FRAGMENT_DENSITY_MAP_BIT_ANGLE 0x00000200 212 213Additions to Chapter 8 of the OpenGL 4.5 Specification (Textures and 214Samplers) 215 216 For each list of TexStorage* commands in the 1D, 2D, 3D, 217 2DMultisample, and 3DMultisample families, add the following 218 variants: 219 220 void TexStorageMemFlags*ANGLE(<existing parameters>, 221 uint memory, 222 uint64 offset, 223 bitfield createFlags, 224 bitfield usageFlags, 225 const void *imageCreateInfoPNext); 226 227 void TextureStorageMemFlags*ANGLE(<existing parameters>, 228 uint memory, 229 uint64 offset, 230 bitfield createFlags, 231 bitfield usageFlags, 232 const void *imageCreateInfoPNext); 233 234 For each of the TexStorageMemFlags*ANGLE commands, move the description from 235 the corresponding TexStorageMem*EXT from EXT_external_objects under that 236 command and add the following language: 237 238 "The implementation should apply the same semantics to the internal 239 storage of the texture based on <createFlags>, <usageFlags> and 240 <imageCreateInfoPNext> as the corresonding VkImageCreateFlags, 241 VkImageUsageFlags and chained structs to VkImageCreateInfo would have 242 on a Vulkan image respectively. See tables 8.17 and 8.18 for the 243 mapping between the GL and Vulkan flags. It is undefined behavior if 244 the application provides create flags, usage flags or chained structs 245 that are not identical to those used to create the Vulkan image." 246 247 Table 8.17: Create flags and corresponding Vulkan Image Create Flags 248 249 | Create Flag | Equivalent Vulkan Create Flag | 250 +----------------------------------------------------+-----------------------------------------------------------+ 251 | CREATE_SPARSE_BINDING_BIT_ANGLE | VK_IMAGE_CREATE_SPARSE_BINDING_BIT | 252 | CREATE_SPARSE_RESIDENCY_BIT_ANGLE | VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT | 253 | CREATE_SPARSE_ALIASED_BIT_ANGLE | VK_IMAGE_CREATE_SPARSE_ALIASED_BIT | 254 | CREATE_MUTABLE_FORMAT_BIT_ANGLE | VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT | 255 | CREATE_CUBE_COMPATIBLE_BIT_ANGLE | VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT | 256 | CREATE_ALIAS_BIT_ANGLE | VK_IMAGE_CREATE_ALIAS_BIT | 257 | CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_ANGLE | VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT | 258 | CREATE_2D_ARRAY_COMPATIBLE_BIT_ANGLE | VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT | 259 | CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_ANGLE | VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT | 260 | CREATE_EXTENDED_USAGE_BIT_ANGLE | VK_IMAGE_CREATE_EXTENDED_USAGE_BIT | 261 | CREATE_PROTECTED_BIT_ANGLE | VK_IMAGE_CREATE_PROTECTED_BIT | 262 | CREATE_DISJOINT_BIT_ANGLE | VK_IMAGE_CREATE_DISJOINT_BIT | 263 | CREATE_CORNER_SAMPLED_BIT_ANGLE | VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV | 264 | CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_ANGLE | VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT | 265 | CREATE_SUBSAMPLED_BIT_ANGLE | VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT | 266 +----------------------------------------------------------------------------------------------------------------+ 267 268 Table 8.18: Usage flags and corresponding Vulkan Image Usage Flags 269 270 | Usage Flag | Equivalent Vulkan Usage Flag | 271 +------------------------------------------+---------------------------------------------+ 272 | USAGE_TRANSFER_SRC_BIT_ANGLE | VK_IMAGE_USAGE_TRANSFER_SRC_BIT | 273 | USAGE_TRANSFER_DST_BIT_ANGLE | VK_IMAGE_USAGE_TRANSFER_DST_BIT | 274 | USAGE_SAMPLED_BIT_ANGLE | VK_IMAGE_USAGE_SAMPLED_BIT | 275 | USAGE_STORAGE_BIT_ANGLE | VK_IMAGE_USAGE_STORAGE_BIT | 276 | USAGE_COLOR_ATTACHMENT_BIT_ANGLE | VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT | 277 | USAGE_DEPTH_STENCIL_ATTACHMENT_BIT_ANGLE | VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT | 278 | USAGE_TRANSIENT_ATTACHMENT_BIT_ANGLE | VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT | 279 | USAGE_INPUT_ATTACHMENT_BIT_ANGLE | VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT | 280 | USAGE_SHADING_RATE_IMAGE_BIT_ANGLE | VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV | 281 | USAGE_FRAGMENT_DENSITY_MAP_BIT_ANGLE | VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT | 282 +----------------------------------------------------------------------------------------+ 283 284 Add the following errors for each of the TexStorageMemFlags*ANGLE commands: 285 286 "An INVALID_VALUE error is generated if <createFlags> has a bit set 287 other than those specified in table 8.17." 288 289 "An INVALID_VALUE error is generated if <usageFlags> has a bit set 290 other than those specified in table 8.18." 291 292 For each of the TexStorageMem*EXT commands, change the description of 293 TexStorageMem*EXT and TextureStorageMem*EXT as such: 294 295 "Calling TexStorageMem*EXT is equivalent to calling 296 TexStorageMemFlags*ANGLE with 0 as <createFlags>, all 297 Vulkan-supported usage flags as <usageFlags>, even if there are no 298 corresponding GL flags specified in this extension, and NULL as 299 <imageCreateInfoPNext>." 300 301Issues 302 303 1) Can the GL and Vulkan create and usage flag values diverge? 304 305 RESOLVED: No. It is expected for the application to provide the flags 306 used to create the Vulkan image verbatim. 307 308 2) What if Vulkan adds new create and usage flags? 309 310 RESOLVED: If the implementation is too old to be aware of those flags, 311 the functions from GL_EXT_memory_object must be used instead. New flags 312 can be added through new extensions that build on this extension. 313 314 3) Should the GL implementation apply the same validation as Vulkan based 315 on the create and usage flags? 316 317 RESOLVED: No. The application has already created an image with these 318 flags in Vulkan, so the GL implementation can assume they are valid. 319 Validating this is expensive and unnecessary in almost all applications. 320 321 4) How can extension structs applied to VkImageCreateInfo be communicated 322 to the GL implementation? 323 324 RESOLVED: The chain of structs itself is directly passed to the 325 implementation. 326 327Revision History 328 329 Revision 2, 2021-11-10 (Shahbaz Youssefi) 330 - Added the imageCreateInfoPNext parameter. 331 332 Revision 1, 2020-08-03 (Shahbaz Youssefi) 333 - Initial draft based on EXT_external_objects. 334