blob: 287ba47a0622d4692a155bb7306992a1f9f42301 [file] [log] [blame]
Name String
Daniel Koch, NVIDIA Corporation (dkoch at
Daniel Rakos, AMD
John Kessenich, Google
Members of the OpenGL Working Group
Copyright (c) 2017-2018 The Khronos Group Inc. Copyright terms at
Specification Update Policy
Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
Last Modified Date: February 20, 2018
Revision: 9
ARB Extension #194
This extensions is written against the OpenGL 4.5 Specification
(Core Profile - July 7, 2016)
This extension requires ARB_gl_spirv.
This extension interacts with ARB_shader_ballot and
This extension interacts with ARB_shader_draw_parameters and
This extension interacts with ARB_shader_group_vote and
This extension interacts with NV_stereo_view_rendering and
This extension interacts with NV_viewport_array2 and
This extension interacts with ARB_shader_viewport_layer_array
and SPV_NV_viewport_array2.
This extension interacts with NV_geometry_shader_passthrough
and SPV_NV_geometry_shader_passthrough.
This extension interacts with NV_sample_mask_override_coverage
and SPV_NV_sample_mask_override_coverage.
This extension interacts with AMD_shader_explicit_vertex_parameter
and SPV_AMD_shader_explicit_vertex_parameter.
This extension interacts with AMD_gpu_shader_half_float
and SPV_AMD_gpu_shader_half_float.
This extension interacts with ARB_shader_atomic_counter_ops and
This extension interacts with ARB_post_depth_coverage,
EXT_post_depth_coverage and SPV_KHR_post_depth_coverage.
This extension interacts with SPV_KHR_storage_buffer_storage_class.
ARB_gl_spirv added support for using SPIR-V modules in OpenGL.
However it only added support for SPIR-V 1.0 concepts that were part of
the OpenGL 4.5 Core Profile.
There are a great number of additional OpenGL ARB and vendor extensions
which add shading language concepts and since they were defined prior
to the existence of SPIR-V support in OpenGL they don't add SPIR-V support
for their additional features. Ideally GL_ARB_gl_spirv would have added
support for them, but as noted in Issue 27 of that extension, support for
them was left as a future exercise.
Now that at least some of that functionality has been defined via SPIR-V
extensions, there is currently no way for an OpenGL implementation to
advertise that is supports additional SPIR-V extensions.
This extension provides a mechanism for an implementation to advertise
which SPIR-V extensions it supports, and further provides a place where
the SPIR-V environment for those extensions can be documented for OpenGL.
It is expected that this document can be extended over time as SPIR-V
support for additional extensions is added. The mapping between GLSL and
SPIR-V concepts and any other pertinent information can be provided here
as interactions with the corresponding OpenGL and SPIR-V extensions.
New Procedures and Functions
New Tokens
Accepted by the <name> parameter of GetStringi:
Accepted by the <pname> parameter of GetIntegerv:
Modifications to Chapter 7 of the OpenGL 4.5 (Core Profile) Specification
(Programs and Shaders)
[[Modifications when SPV_KHR_storage_buffer_storage_class is supported]]
(replace section "7.6.2.spv SPIR-V Uniform Offsets and Strides" added by
ARB_gl_spirv with the following:)
"The SPIR-V decorations *GLSLShared* or *GLSLPacked* must not be used.
A variable in the *Uniform* or *StorageBuffer* Storage Class decorated
as a *Block* must be explicitly laid out using the *Offset*,
*ArrayStride*, and *MatrixStride* decorations. If the variable is in
the *Uniform* storage class decorated as a *BufferBlock* or in the
*StorageBuffer* storage class decorated as a *Block*, its offsets and
strides must not contradict std430 alignment and minimum offset
requirements. Otherwise, its offsets and strides must not contradict
std140 alignment and minimum offset requirements."
Modifications to Chapter 22 of the OpenGL 4.5 (Core Profile) Specification
(Context State Queries)
Additions to section 22.2 (Pointer, String, and Related Context Queries)
Add the following to the description of tokens accepted by
"If <name> is SPIR_V_EXTENSIONS, the SPIR-V extension name
corresponding to the <index>th supported SPIR-V extension
(specified as the Name String in the corresponding SPIR-V
extension document) will be returned. <index> may range from zero
to the value of NUM_SPIR_V_EXTENSIONS minus one. The value of
NUM_SPIR_V_EXTENSIONS can be queried using the GetInteger
command. There is no defined relationship between any particular
extension name and the <index> values and a SPIR-V extension name
may correspond to a different <index> in different GL contexts
and/or implementations."
Modify the INVALID_ENUM error for the GetStringi command to be:
"An INVALID_ENUM error is generated if <name> is not EXTENSIONS,
Modifications to Appendix A.spv of the OpenGL 4.5 (Core Profile) Specification
(The OpenGL SPIR-V Execution Environment) [as added by GL_ARB_gl_spirv]
Additions to section A.spv.2 (Valid SPIR-V Built-In Variable Decorations)
Built-in Variable Decoration Minimum GL version (Extension)
---------------------------- -----------------------------
SubgroupEqMaskKHR (ARB_shader_ballot)
SubgroupGeMaskKHR (ARB_shader_ballot)
SubgroupGtMaskKHR (ARB_shader_ballot)
SubgroupLeMaskKHR (ARB_shader_ballot)
SubgroupLtMaskKHR (ARB_shader_ballot)
BaseVertex (ARB_shader_draw_parameters)
BaseInstance (ARB_shader_draw_parameters)
DrawIndex (ARB_shader_draw_parameters)
SecondaryPositionNV (NV_stereo_view_rendering)
SecondaryViewportMaskNV (NV_stereo_view_rendering)
ViewportMaskNV (NV_viewport_array2)
BaryCoordNoPerspAMD (AMD_shader_explicit_vertex_parameter)
BaryCoordNoPerspCentroidAMD (AMD_shader_explicit_vertex_parameter)
BaryCoordNoPerspSampleAMD (AMD_shader_explicit_vertex_parameter)
BaryCoordSmoothAMD (AMD_shader_explicit_vertex_parameter)
BaryCoordSmoothCentroidAMD (AMD_shader_explicit_vertex_parameter)
BaryCoordSmoothSampleAMD (AMD_shader_explicit_vertex_parameter)
BaryCoordPullModelAMD (AMD_shader_explicit_vertex_parameter)
Additions to section A.spv.3 (Valid SPIR-V Capabilities)
Implementations supporting ARB_shader_ballot and
SPV_KHR_shader_ballot must support the following operand declared
by OpCapability:
Implementations supporting ARB_shader_draw_parameters and
SPV_KHR_shader_draw_parameters must support the following operand
declared by OpCapability:
Implementations supporting ARB_shader_group_vote and
SPV_KHR_subgroup_vote must support the following operand declared
by OpCapability:
Implementations supporting NV_stereo_view_rendering and
SPV_NV_stereo_view_rendering must support the following operand
declared by OpCapability:
Implementations supporting NV_viewport_array2 and
SPV_NV_viewport_array2 must support the following operands
declared by OpCapability:
Implementations supporting ARB_shader_viewport_layer_array and
SPV_NV_viewport_array2 must support the following operands
declared by OpCapability:
Implementations supporting NV_geometry_shader_passthrough and
SPV_NV_geometry_shader_passthrough must support the following
operand declared by OpCapability:
Implementations supporting NV_sample_mask_override_coverage and
SPV_NV_sample_mask_override_coverage must suport the following
operand declared by OpCapability:
Implementations supporting AMD_gpu_shader_half_float and
SPV_AMD_gpu_shader_half_float must support the following operand
declared by OpCapability:
Implementations supporting ARB_shader_atomic_counter_ops and
SPV_KHR_shader_atomic_counter_ops must support the following
operand declared by OpCapability:
Implementations supporting ARB_post_depth_coverage
(or EXT_post_depth_coverage) and SPV_KHR_post_depth_coverage
must support the following operand declared by OpCapability:
Additions to section A.spv.4 (Validation rules)
[[Additions for SPV_NV_viewport_array2]]
* The code:ViewportRelativeNV decoration must: only be used on a variable
decorated with code:Layer in the vertex, tessellation evaluation, or
geometry shader stages.
* The code:ViewportRelativeNV decoration must: not be used unless a
variable decorated with one of code:ViewportIndex or
code:ViewportMaskNV is also statically used by the same
* The code:ViewportMaskNV and code:ViewportIndex decorations must: not
both be statically used by one or more code:OpEntryPoint's that form
the vertex processing stages of a graphics pipeline.
[[Additions for SPV_AMD_shader_explicit_vertex_parameter]]
* The code:CustomInterpAMD decoration must not be used on variables with
Storage Class other than *Input* or on variables used in the interface
of non-fragment shader entry points.
[[Modifications if SPV_KHR_storage_buffer_storage_class is supported]]
- Add *StorageBuffer* to the list of Storage Classes that are accepted.
(replace the following statement from ARB_gl_spirv)
- OpTypeRuntimeArray must only be used for the last member of an
OpTypeStruct in the Uniform Storage Class and is decorated as
(with the following:)
- OpTypeRuntimeArray must: only be used for the last member of an
OpTypeStruct that is in the StorageBuffer storage class
decorated as Block, or that is in the Uniform storage
class decorated as BufferBlock.
New State
Add the following rows to Table 23.56 (Implementation Dependent Version
and Extensions support)
Get Value Type Get Minimum Description Sec.
Command Value
--------------------- ----- ----------- ------- ---------------- ----
SPIR_V_EXTENSIONS n x S GetStringi - Supported SPIR-V 22.2
extension names
NUM_SPIR_V_EXTENSIONS Z+ GetIntegerv 0 No. of supported 22.2
SPIR-V extension
Interactions with ARB_shader_ballot and SPV_KHR_shader_ballot:
When using these extensions the following GLSL -> SPIR-V mapping is used:
* in uint64_t gl_SubGroupEqMaskARB; -> SubgroupEqMaskKHR,
* in uint64_t gl_SubGroupGeMaskARB; -> SubgroupGeMaskKHR,
* in uint64_t gl_SubGroupGtMaskARB; -> SubgroupGtMaskKHR,
* in uint64_t gl_SubGroupLeMaskARB; -> SubgroupLeMaskKHR,
* in uint64_t gl_SubGroupLtMaskARB; -> SubgroupLtMaskKHR,
* in uint gl_SubGroupInvocationARB; -> SubgroupLocalInvocationId,
* uniform uint gl_SubGroupSizeARB; -> SubgroupSize,
* ballotARB() -> OpSubgroupBallotKHR,
* readFirstInvocationARB() -> OpSubgroupFirstInvocationKHR, and
* readInvocationARB() -> OpSubgroupReadInvocationKHR.
Interactions with ARB_shader_draw_parameters and
When using these extensions the following GLSL -> SPIR-V mapping is used:
* in int gl_BaseInstanceARB; -> BaseInstance,
* in int gl_BaseVertexARB; -> BaseVertex, and
* in int gl_DrawIDARB; -> DrawIndex.
Interactions with ARB_shader_group_vote and SPV_KHR_subgroup_vote:
When using these extensions the following GLSL -> SPIR-V mapping is used:
* anyInvocationARB() -> OpSubgroupAnyKHR,
* allInvocationsARB() -> OpSubgroupAllKHR, and
* allInvocationsEqualARB() -> OpSubgroupAllEqualKHR.
Interactions with NV_stereo_view_rendering and SPV_NV_stereo_view_rendering:
When using these extensions the following GLSL -> SPIR-V mapping is used:
* highp vec4 gl_SecondaryPositionNV; -> SecondaryPositionNV,
* highp int gl_SecondaryViewportMaskNV[]; -> SecondaryViewportMaskNV, and
* layout (secondary_view_offset = n) -> SecondaryViewportRelativeNV.
Interactions with NV_viewport_array2 and SPV_NV_viewport_array2:
When using these extensions the following GLSL -> SPIR-V mapping is used:
* highp int gl_ViewportMask[] -> ViewportMaskNV, and
* layout (viewport_relative) -> ViewportRelativeNV.
Interactions with ARB_shader_viewport_layer_array and SPV_NV_viewport_array2:
When using these extensions, gl_Layer and gl_ViewportIndex can be written
from Vertex or Tessellation shaders.
Interactions with NV_geometry_shader_passthrough and
When using these extensions the following GLSL -> SPIR-V mapping is used:
* layout(passthrough) -> PassthroughNV.
Interactions with NV_sample_mask_override_coverage and
When using these extensions the following GLSL -> SPIR-V mapping is used:
* layout(override_coverage) -> OverrideCoverageNV.
Interactions with AMD_shader_explicit_vertex_parameter and
When using these extensions the following GLSL -> SPIR-V mapping is used:
* explicitInterpAMD -> ExplicitInterpAMD
* in vec2 gl_BaryCoordNoPerspAMD; -> BaryCoordNoPerspAMD
* in vec2 gl_BaryCoordNoPerspCentroidAMD; -> BaryCoordNoPerspCentroidAMD
* in vec2 gl_BaryCoordNoPerspSampleAMD; -> BaryCoordNoPerspSampleAMD
* in vec2 gl_BaryCoordSmoothAMD; -> BaryCoordSmoothAMD
* in vec2 gl_BaryCoordSmoothCentroidAMD; -> BaryCoordSmoothCentroidAMD
* in vec2 gl_BaryCoordSmoothSampleAMD; -> BaryCoordSmoothSampleAMD
* in vec3 gl_BaryCoordPullModelAMD; -> BaryCoordPullModelAMD
Interactions with AMD_gpu_shader_half_float and SPV_AMD_gpu_shader_half_float:
When using these extensions, 16-bit floating-point types are permitted
for a number of additional data-types and built-in functions.
Interactions with ARB_shader_atomic_counter_ops and
When using these extensions the following GLSL -> SPIR-V mapping is used:
* uint atomicCounterAddARB() -> OpAtomicIAdd
* uint atomicCounterSubtractARB() -> OpAtomicISub
* uint atomicCounterMinARB() -> OpAtomicUMin
* uint atomicCounterMaxARB() -> OpAtomicUMax
* uint atomicCounterAndARB() -> OpAtomicAnd
* uint atomicCounterOrARB() -> OpAtomicOr
* uint atomicCounterXorARB() -> OpAtomicXor
* uint atomicCounterExchangeARB() -> OpAtomicExchange
* uint atomicCounterCompSwapARB() -> OpAtomicCompareExchange
Interactions with ARB_post_depth_coverage or EXT_post_depth_coverage and
When using these extensions the following GLSL -> SPIR-V mapping is used:
* layout(post_depth_coverage) -> PostDepthCoverage.
Interactions with SPV_KHR_storage_buffer_storage_class:
When SPV_KHR_storage_buffer_storage class is supported, shader storage
buffer objects can be mapped to SPIR-V using the *StorageBuffer* storage
class and decorated as *Block*, which is considered equivalent (and
preferred to) declaring them with the *Uniform* storage class and
decorating them with the *BufferBlock* decoration:
buffer blockN { ... } ...; -> Uniform, with BufferBlock decoration
buffer blockN { ... } ...; -> StorageBuffer, with Block decoration (preferred)
If SPV_KHR_storage_buffer_storage_class is not supported, ignore all
references to the StorageBuffer storage class.
1. Where should we document environment interactions for new SPIR-V
DISCUSSION. The environment interactions could be:
a) added to the corresponding (existing) GL extension? This means they
would be spread across all manner of documents and hard to find.
We would prefer to have them documented in few locations.
b) added to ARB_gl_spirv? This means ARB_gl_spirv would be an ever
growing document which is a bit strange as it gives no way to
advertise or enable the new functionality. Also that document effectively
corresponds go GL 4.5 level functionality and is going to be rolled
into OpenGL 4.6.
c) added to this extension? This document becomes the ever growing version
instead, and it does provide a query to be able to tell if new
functionality is supported by an implementation.
RESOLVED. Pick (c). New GL extensions should add their SPIR-V environment
restrictions for OpenGL to this document. It it is recommended to include a
pointer to this extension from the new GL extension.
2. Does that mean we can add brand new SPIR-V functionality to GL just by
editing this extension?
RESOLVED. Only for shader functionality that already exists in OpenGL
by a previous extension. For completely new functionality it should be
done via a new API extension that adds any necessary API support as
well as defining the GLSL-version of the functionality.
3. If a new GL extension is added that includes SPIR-V support via a
new SPIR-V extension does it's SPIR-V extension also get enumerated by
RESOLVED. Yes. It's good to include it for consistency. Any SPIR-V
functionality supported beyond the SPIR-V version that is required
for the GL API version should be enumerated.
4. Does (3) mean that we should have a query for the version of SPIR-V
that is supported as well?
RESOLVED. No. With ARB_gl_spirv (and in OpenGL 4.6) OpenGL only supports
SPIR-V 1.0. If we want to support additional versions of SPIR-V we'll need
to update the SPIR-V environment which will require a new GL extension to
to do this.
Revision History
Rev. Date Author Changes
---- ----------- ------------ ---------------------------------
1 2017-01-22 dgkoch Initial revision
2 2017-04-08 dgkoch Add additional extensions and issues.
3 2017-04-21 dgkoch Assign tokens
4 2017-04-22 dgkoch Add SPV_KHR_shader_atomic_counter_ops
and add GLSL->SPIR-V mappings.
5 2017-04-24 dgkoch remove ARB suffixes and resolve issue 4.
6 2017-04-25 dgkoch Add SPV_KHR_post_depth_coverage.
7 2017-05-09 dgkoch fix typos.
8 2017-07-14 dgkoch Add SPV_KHR_storage_buffer_storage_class.
9 2018-02-20 dgkoch Update storage class whitelist to include
storage buffers (SPIR-V/issues/166)