1Name 2 3 ARB_spirv_extensions 4 5Name String 6 7 GL_ARB_spirv_extensions 8 9Contact 10 11 Daniel Koch, NVIDIA Corporation (dkoch at nvidia.com) 12 13Contributors 14 15 Daniel Rakos, AMD 16 John Kessenich, Google 17 Members of the OpenGL Working Group 18 19Notice 20 21 Copyright (c) 2017-2018 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34Status 35 36 Complete 37 38Version 39 40 Last Modified Date: February 20, 2018 41 Revision: 9 42 43Number 44 45 ARB Extension #194 46 47Dependencies 48 49 This extensions is written against the OpenGL 4.5 Specification 50 (Core Profile - July 7, 2016) 51 52 This extension requires ARB_gl_spirv. 53 54 This extension interacts with ARB_shader_ballot and 55 SPV_KHR_shader_ballot. 56 57 This extension interacts with ARB_shader_draw_parameters and 58 SPV_KHR_shader_draw_parameters. 59 60 This extension interacts with ARB_shader_group_vote and 61 SPV_KHR_subgroup_vote. 62 63 This extension interacts with NV_stereo_view_rendering and 64 SPV_NV_stereo_view_rendering. 65 66 This extension interacts with NV_viewport_array2 and 67 SPV_NV_viewport_array2. 68 69 This extension interacts with ARB_shader_viewport_layer_array 70 and SPV_NV_viewport_array2. 71 72 This extension interacts with NV_geometry_shader_passthrough 73 and SPV_NV_geometry_shader_passthrough. 74 75 This extension interacts with NV_sample_mask_override_coverage 76 and SPV_NV_sample_mask_override_coverage. 77 78 This extension interacts with AMD_shader_explicit_vertex_parameter 79 and SPV_AMD_shader_explicit_vertex_parameter. 80 81 This extension interacts with AMD_gpu_shader_half_float 82 and SPV_AMD_gpu_shader_half_float. 83 84 This extension interacts with ARB_shader_atomic_counter_ops and 85 SPV_KHR_shader_atomic_counter_ops. 86 87 This extension interacts with ARB_post_depth_coverage, 88 EXT_post_depth_coverage and SPV_KHR_post_depth_coverage. 89 90 This extension interacts with SPV_KHR_storage_buffer_storage_class. 91 92Overview 93 94 ARB_gl_spirv added support for using SPIR-V modules in OpenGL. 95 However it only added support for SPIR-V 1.0 concepts that were part of 96 the OpenGL 4.5 Core Profile. 97 98 There are a great number of additional OpenGL ARB and vendor extensions 99 which add shading language concepts and since they were defined prior 100 to the existence of SPIR-V support in OpenGL they don't add SPIR-V support 101 for their additional features. Ideally GL_ARB_gl_spirv would have added 102 support for them, but as noted in Issue 27 of that extension, support for 103 them was left as a future exercise. 104 105 Now that at least some of that functionality has been defined via SPIR-V 106 extensions, there is currently no way for an OpenGL implementation to 107 advertise that is supports additional SPIR-V extensions. 108 109 This extension provides a mechanism for an implementation to advertise 110 which SPIR-V extensions it supports, and further provides a place where 111 the SPIR-V environment for those extensions can be documented for OpenGL. 112 113 It is expected that this document can be extended over time as SPIR-V 114 support for additional extensions is added. The mapping between GLSL and 115 SPIR-V concepts and any other pertinent information can be provided here 116 as interactions with the corresponding OpenGL and SPIR-V extensions. 117 118New Procedures and Functions 119 120 None 121 122New Tokens 123 124 Accepted by the <name> parameter of GetStringi: 125 126 SPIR_V_EXTENSIONS 0x9553 127 128 Accepted by the <pname> parameter of GetIntegerv: 129 130 NUM_SPIR_V_EXTENSIONS 0x9554 131 132Modifications to Chapter 7 of the OpenGL 4.5 (Core Profile) Specification 133(Programs and Shaders) 134 135 [[Modifications when SPV_KHR_storage_buffer_storage_class is supported]] 136 137 (replace section "7.6.2.spv SPIR-V Uniform Offsets and Strides" added by 138 ARB_gl_spirv with the following:) 139 140 "The SPIR-V decorations *GLSLShared* or *GLSLPacked* must not be used. 141 A variable in the *Uniform* or *StorageBuffer* Storage Class decorated 142 as a *Block* must be explicitly laid out using the *Offset*, 143 *ArrayStride*, and *MatrixStride* decorations. If the variable is in 144 the *Uniform* storage class decorated as a *BufferBlock* or in the 145 *StorageBuffer* storage class decorated as a *Block*, its offsets and 146 strides must not contradict std430 alignment and minimum offset 147 requirements. Otherwise, its offsets and strides must not contradict 148 std140 alignment and minimum offset requirements." 149 150 151Modifications to Chapter 22 of the OpenGL 4.5 (Core Profile) Specification 152(Context State Queries) 153 154 Additions to section 22.2 (Pointer, String, and Related Context Queries) 155 156 Add the following to the description of tokens accepted by 157 GetStringi: 158 159 "If <name> is SPIR_V_EXTENSIONS, the SPIR-V extension name 160 corresponding to the <index>th supported SPIR-V extension 161 (specified as the Name String in the corresponding SPIR-V 162 extension document) will be returned. <index> may range from zero 163 to the value of NUM_SPIR_V_EXTENSIONS minus one. The value of 164 NUM_SPIR_V_EXTENSIONS can be queried using the GetInteger 165 command. There is no defined relationship between any particular 166 extension name and the <index> values and a SPIR-V extension name 167 may correspond to a different <index> in different GL contexts 168 and/or implementations." 169 170 Modify the INVALID_ENUM error for the GetStringi command to be: 171 172 "An INVALID_ENUM error is generated if <name> is not EXTENSIONS, 173 SHADING_LANGUAGE_VERSION, or SPIR_V_EXTENSIONS." 174 175 176Modifications to Appendix A.spv of the OpenGL 4.5 (Core Profile) Specification 177(The OpenGL SPIR-V Execution Environment) [as added by GL_ARB_gl_spirv] 178 179 Additions to section A.spv.2 (Valid SPIR-V Built-In Variable Decorations) 180 181 Built-in Variable Decoration Minimum GL version (Extension) 182 ---------------------------- ----------------------------- 183 SubgroupEqMaskKHR (ARB_shader_ballot) 184 SubgroupGeMaskKHR (ARB_shader_ballot) 185 SubgroupGtMaskKHR (ARB_shader_ballot) 186 SubgroupLeMaskKHR (ARB_shader_ballot) 187 SubgroupLtMaskKHR (ARB_shader_ballot) 188 BaseVertex (ARB_shader_draw_parameters) 189 BaseInstance (ARB_shader_draw_parameters) 190 DrawIndex (ARB_shader_draw_parameters) 191 SecondaryPositionNV (NV_stereo_view_rendering) 192 SecondaryViewportMaskNV (NV_stereo_view_rendering) 193 ViewportMaskNV (NV_viewport_array2) 194 BaryCoordNoPerspAMD (AMD_shader_explicit_vertex_parameter) 195 BaryCoordNoPerspCentroidAMD (AMD_shader_explicit_vertex_parameter) 196 BaryCoordNoPerspSampleAMD (AMD_shader_explicit_vertex_parameter) 197 BaryCoordSmoothAMD (AMD_shader_explicit_vertex_parameter) 198 BaryCoordSmoothCentroidAMD (AMD_shader_explicit_vertex_parameter) 199 BaryCoordSmoothSampleAMD (AMD_shader_explicit_vertex_parameter) 200 BaryCoordPullModelAMD (AMD_shader_explicit_vertex_parameter) 201 202 Additions to section A.spv.3 (Valid SPIR-V Capabilities) 203 204 Implementations supporting ARB_shader_ballot and 205 SPV_KHR_shader_ballot must support the following operand declared 206 by OpCapability: 207 208 SubgroupBallotKHR 209 210 Implementations supporting ARB_shader_draw_parameters and 211 SPV_KHR_shader_draw_parameters must support the following operand 212 declared by OpCapability: 213 214 DrawParameters 215 216 Implementations supporting ARB_shader_group_vote and 217 SPV_KHR_subgroup_vote must support the following operand declared 218 by OpCapability: 219 220 SubgroupVoteKHR 221 222 Implementations supporting NV_stereo_view_rendering and 223 SPV_NV_stereo_view_rendering must support the following operand 224 declared by OpCapability: 225 226 ShaderStereoViewNV 227 228 Implementations supporting NV_viewport_array2 and 229 SPV_NV_viewport_array2 must support the following operands 230 declared by OpCapability: 231 232 ShaderViewportIndexLayerNV 233 ShaderViewportMaskNV 234 235 Implementations supporting ARB_shader_viewport_layer_array and 236 SPV_NV_viewport_array2 must support the following operands 237 declared by OpCapability: 238 239 ShaderViewportIndexLayerNV 240 241 Implementations supporting NV_geometry_shader_passthrough and 242 SPV_NV_geometry_shader_passthrough must support the following 243 operand declared by OpCapability: 244 245 GeometryShaderPassthroughNV 246 247 Implementations supporting NV_sample_mask_override_coverage and 248 SPV_NV_sample_mask_override_coverage must suport the following 249 operand declared by OpCapability: 250 251 SampleMaskOverrideCoverageNV 252 253 Implementations supporting AMD_gpu_shader_half_float and 254 SPV_AMD_gpu_shader_half_float must support the following operand 255 declared by OpCapability: 256 257 Float16 258 259 Implementations supporting ARB_shader_atomic_counter_ops and 260 SPV_KHR_shader_atomic_counter_ops must support the following 261 operand declared by OpCapability: 262 263 AtomicStorageOps 264 265 Implementations supporting ARB_post_depth_coverage 266 (or EXT_post_depth_coverage) and SPV_KHR_post_depth_coverage 267 must support the following operand declared by OpCapability: 268 269 SampleMaskPostDepthCoverage 270 271 Additions to section A.spv.4 (Validation rules) 272 273 [[Additions for SPV_NV_viewport_array2]] 274 275 * The code:ViewportRelativeNV decoration must: only be used on a variable 276 decorated with code:Layer in the vertex, tessellation evaluation, or 277 geometry shader stages. 278 * The code:ViewportRelativeNV decoration must: not be used unless a 279 variable decorated with one of code:ViewportIndex or 280 code:ViewportMaskNV is also statically used by the same 281 code:OpEntryPoint. 282 * The code:ViewportMaskNV and code:ViewportIndex decorations must: not 283 both be statically used by one or more code:OpEntryPoint's that form 284 the vertex processing stages of a graphics pipeline. 285 286 [[Additions for SPV_AMD_shader_explicit_vertex_parameter]] 287 288 * The code:CustomInterpAMD decoration must not be used on variables with 289 Storage Class other than *Input* or on variables used in the interface 290 of non-fragment shader entry points. 291 292 [[Modifications if SPV_KHR_storage_buffer_storage_class is supported]] 293 294 - Add *StorageBuffer* to the list of Storage Classes that are accepted. 295 296 (replace the following statement from ARB_gl_spirv) 297 298 - OpTypeRuntimeArray must only be used for the last member of an 299 OpTypeStruct in the Uniform Storage Class and is decorated as 300 BufferBlock. 301 302 (with the following:) 303 304 - OpTypeRuntimeArray must: only be used for the last member of an 305 OpTypeStruct that is in the StorageBuffer storage class 306 decorated as Block, or that is in the Uniform storage 307 class decorated as BufferBlock. 308 309 310New State 311 312Add the following rows to Table 23.56 (Implementation Dependent Version 313and Extensions support) 314 315Get Value Type Get Minimum Description Sec. 316 Command Value 317--------------------- ----- ----------- ------- ---------------- ---- 318SPIR_V_EXTENSIONS n x S GetStringi - Supported SPIR-V 22.2 319 extension names 320NUM_SPIR_V_EXTENSIONS Z+ GetIntegerv 0 No. of supported 22.2 321 SPIR-V extension 322 names 323 324 325Interactions with ARB_shader_ballot and SPV_KHR_shader_ballot: 326 327 When using these extensions the following GLSL -> SPIR-V mapping is used: 328 329 * in uint64_t gl_SubGroupEqMaskARB; -> SubgroupEqMaskKHR, 330 * in uint64_t gl_SubGroupGeMaskARB; -> SubgroupGeMaskKHR, 331 * in uint64_t gl_SubGroupGtMaskARB; -> SubgroupGtMaskKHR, 332 * in uint64_t gl_SubGroupLeMaskARB; -> SubgroupLeMaskKHR, 333 * in uint64_t gl_SubGroupLtMaskARB; -> SubgroupLtMaskKHR, 334 * in uint gl_SubGroupInvocationARB; -> SubgroupLocalInvocationId, 335 * uniform uint gl_SubGroupSizeARB; -> SubgroupSize, 336 * ballotARB() -> OpSubgroupBallotKHR, 337 * readFirstInvocationARB() -> OpSubgroupFirstInvocationKHR, and 338 * readInvocationARB() -> OpSubgroupReadInvocationKHR. 339 340Interactions with ARB_shader_draw_parameters and 341SPV_KHR_shader_draw_parameters: 342 343 When using these extensions the following GLSL -> SPIR-V mapping is used: 344 345 * in int gl_BaseInstanceARB; -> BaseInstance, 346 * in int gl_BaseVertexARB; -> BaseVertex, and 347 * in int gl_DrawIDARB; -> DrawIndex. 348 349Interactions with ARB_shader_group_vote and SPV_KHR_subgroup_vote: 350 351 When using these extensions the following GLSL -> SPIR-V mapping is used: 352 353 * anyInvocationARB() -> OpSubgroupAnyKHR, 354 * allInvocationsARB() -> OpSubgroupAllKHR, and 355 * allInvocationsEqualARB() -> OpSubgroupAllEqualKHR. 356 357Interactions with NV_stereo_view_rendering and SPV_NV_stereo_view_rendering: 358 359 When using these extensions the following GLSL -> SPIR-V mapping is used: 360 361 * highp vec4 gl_SecondaryPositionNV; -> SecondaryPositionNV, 362 * highp int gl_SecondaryViewportMaskNV[]; -> SecondaryViewportMaskNV, and 363 * layout (secondary_view_offset = n) -> SecondaryViewportRelativeNV. 364 365Interactions with NV_viewport_array2 and SPV_NV_viewport_array2: 366 367 When using these extensions the following GLSL -> SPIR-V mapping is used: 368 369 * highp int gl_ViewportMask[] -> ViewportMaskNV, and 370 * layout (viewport_relative) -> ViewportRelativeNV. 371 372Interactions with ARB_shader_viewport_layer_array and SPV_NV_viewport_array2: 373 374 When using these extensions, gl_Layer and gl_ViewportIndex can be written 375 from Vertex or Tessellation shaders. 376 377Interactions with NV_geometry_shader_passthrough and 378SPV_NV_geometry_shader_passthrough: 379 380 When using these extensions the following GLSL -> SPIR-V mapping is used: 381 382 * layout(passthrough) -> PassthroughNV. 383 384Interactions with NV_sample_mask_override_coverage and 385SPV_NV_sample_mask_override_coverage: 386 387 When using these extensions the following GLSL -> SPIR-V mapping is used: 388 389 * layout(override_coverage) -> OverrideCoverageNV. 390 391Interactions with AMD_shader_explicit_vertex_parameter and 392SPV_AMD_shader_explicit_vertex_parameter: 393 394 When using these extensions the following GLSL -> SPIR-V mapping is used: 395 396 * explicitInterpAMD -> ExplicitInterpAMD 397 * in vec2 gl_BaryCoordNoPerspAMD; -> BaryCoordNoPerspAMD 398 * in vec2 gl_BaryCoordNoPerspCentroidAMD; -> BaryCoordNoPerspCentroidAMD 399 * in vec2 gl_BaryCoordNoPerspSampleAMD; -> BaryCoordNoPerspSampleAMD 400 * in vec2 gl_BaryCoordSmoothAMD; -> BaryCoordSmoothAMD 401 * in vec2 gl_BaryCoordSmoothCentroidAMD; -> BaryCoordSmoothCentroidAMD 402 * in vec2 gl_BaryCoordSmoothSampleAMD; -> BaryCoordSmoothSampleAMD 403 * in vec3 gl_BaryCoordPullModelAMD; -> BaryCoordPullModelAMD 404 405Interactions with AMD_gpu_shader_half_float and SPV_AMD_gpu_shader_half_float: 406 407 When using these extensions, 16-bit floating-point types are permitted 408 for a number of additional data-types and built-in functions. 409 410Interactions with ARB_shader_atomic_counter_ops and 411SPV_KHR_shader_atomic_counter_ops: 412 413 When using these extensions the following GLSL -> SPIR-V mapping is used: 414 415 * uint atomicCounterAddARB() -> OpAtomicIAdd 416 * uint atomicCounterSubtractARB() -> OpAtomicISub 417 * uint atomicCounterMinARB() -> OpAtomicUMin 418 * uint atomicCounterMaxARB() -> OpAtomicUMax 419 * uint atomicCounterAndARB() -> OpAtomicAnd 420 * uint atomicCounterOrARB() -> OpAtomicOr 421 * uint atomicCounterXorARB() -> OpAtomicXor 422 * uint atomicCounterExchangeARB() -> OpAtomicExchange 423 * uint atomicCounterCompSwapARB() -> OpAtomicCompareExchange 424 425Interactions with ARB_post_depth_coverage or EXT_post_depth_coverage and 426SPV_KHR_post_depth_coverage: 427 428 When using these extensions the following GLSL -> SPIR-V mapping is used: 429 430 * layout(post_depth_coverage) -> PostDepthCoverage. 431 432Interactions with SPV_KHR_storage_buffer_storage_class: 433 434 When SPV_KHR_storage_buffer_storage class is supported, shader storage 435 buffer objects can be mapped to SPIR-V using the *StorageBuffer* storage 436 class and decorated as *Block*, which is considered equivalent (and 437 preferred to) declaring them with the *Uniform* storage class and 438 decorating them with the *BufferBlock* decoration: 439 440 buffer blockN { ... } ...; -> Uniform, with BufferBlock decoration 441 buffer blockN { ... } ...; -> StorageBuffer, with Block decoration (preferred) 442 443 If SPV_KHR_storage_buffer_storage_class is not supported, ignore all 444 references to the StorageBuffer storage class. 445 446Issues 447 4481. Where should we document environment interactions for new SPIR-V 449 extensions? 450 451 DISCUSSION. The environment interactions could be: 452 a) added to the corresponding (existing) GL extension? This means they 453 would be spread across all manner of documents and hard to find. 454 We would prefer to have them documented in few locations. 455 b) added to ARB_gl_spirv? This means ARB_gl_spirv would be an ever 456 growing document which is a bit strange as it gives no way to 457 advertise or enable the new functionality. Also that document effectively 458 corresponds go GL 4.5 level functionality and is going to be rolled 459 into OpenGL 4.6. 460 c) added to this extension? This document becomes the ever growing version 461 instead, and it does provide a query to be able to tell if new 462 functionality is supported by an implementation. 463 464 RESOLVED. Pick (c). New GL extensions should add their SPIR-V environment 465 restrictions for OpenGL to this document. It it is recommended to include a 466 pointer to this extension from the new GL extension. 467 4682. Does that mean we can add brand new SPIR-V functionality to GL just by 469 editing this extension? 470 471 RESOLVED. Only for shader functionality that already exists in OpenGL 472 by a previous extension. For completely new functionality it should be 473 done via a new API extension that adds any necessary API support as 474 well as defining the GLSL-version of the functionality. 475 4763. If a new GL extension is added that includes SPIR-V support via a 477 new SPIR-V extension does it's SPIR-V extension also get enumerated by 478 the SPIR_V_EXTENSIONS_ARB query?. 479 480 RESOLVED. Yes. It's good to include it for consistency. Any SPIR-V 481 functionality supported beyond the SPIR-V version that is required 482 for the GL API version should be enumerated. 483 4844. Does (3) mean that we should have a query for the version of SPIR-V 485 that is supported as well? 486 487 RESOLVED. No. With ARB_gl_spirv (and in OpenGL 4.6) OpenGL only supports 488 SPIR-V 1.0. If we want to support additional versions of SPIR-V we'll need 489 to update the SPIR-V environment which will require a new GL extension to 490 to do this. 491 492Revision History 493 494 Rev. Date Author Changes 495 ---- ----------- ------------ --------------------------------- 496 1 2017-01-22 dgkoch Initial revision 497 2 2017-04-08 dgkoch Add additional extensions and issues. 498 3 2017-04-21 dgkoch Assign tokens 499 4 2017-04-22 dgkoch Add SPV_KHR_shader_atomic_counter_ops 500 and add GLSL->SPIR-V mappings. 501 5 2017-04-24 dgkoch remove ARB suffixes and resolve issue 4. 502 6 2017-04-25 dgkoch Add SPV_KHR_post_depth_coverage. 503 7 2017-05-09 dgkoch fix typos. 504 8 2017-07-14 dgkoch Add SPV_KHR_storage_buffer_storage_class. 505 9 2018-02-20 dgkoch Update storage class whitelist to include 506 storage buffers (SPIR-V/issues/166) 507 508