Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Change log for September 1, 2022 Vulkan 1.3.226 spec update: 
Public Issues:

  * Add missing SPV_KHR_ray_tracing storage class valid usage statement for
    code:ShaderRecordBufferKHR (public merge request 1895).
  * Add a NOTE to slink:VkAccelerationStructureCreateInfoKHR about
    ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR (public issue 1904).
  * Add a standalone SPIR-V valid usage statement for code:OpImageWrite
    component mismatch (public merge request 1916).
  * Generate the "`SPIRV Image Format`" and "`Plane Compatibility Format`"
    tables from `vk.xml` (public merge request 1922).
  * Add a NOTE to dlink:VK_USE_64_BIT_PTR_DEFINES to define its availability
    Vulkan headers starting with VK_HEADER_VERSION 174 (public merge request
    1918).

Internal Issues:

  * Update issue #2 in the apiext:VK_EXT_depth_range_unrestricted appendix
    to match core spec text (internal issue 2445).
  * Clarify <<shaders-interpolation-decorations, Interpolation decorations>>
    in pre-rasterization (internal issue 2721).
  * Relax implicit layer disabling requirements in slink:VkApplicationInfo
    (internal issue 2856).
  * Update <requires> `extension` attribute in XML to support multiple
    extensions with AND/OR connectives (internal issue 2922).
  * Update provisional video API queries for usage hint and optimized
    implementation settings (internal issue 2986).
  * Relax slink:VkImageViewCreateInfo valid usage statement 01584 to allow
    layers/levels for compressed format views of compressed format images
    (internal issue 3063).
  * Remove slink:VkImageViewCreateInfo valid usage statement 04739 (internal
    issue 3164).
  * Specify that addresses returned by flink:vkGetBufferDeviceAddress must
    satisfy the alignment requirements of the device (internal issue 3176).
  * Update makeSpec script to properly clean OUTDIR when it's explicitly
    specified (internal issue 3194).
  * Ensure that a mutable type list is provided in
    slink:VkDescriptorSetLayoutCreateInfo when required (internal issue
    3198).
  * Update clarity of the Khronos specification copyright statement
    regarding normative references to external specifications and the
    Khronos Intellectual Property Rights Policy (internal issue 3203).
  * Rename '.txt' -> '.adoc' for all asciidoctor markup files in the
    repository, and update scripts and tools to match (internal issue 3204)
  * Tag apiext:VK_ARM_rasterization_order_attachment_access as promoted to
    EXT in XML (internal merge request 5364)
  * Fix a typo in the "` Color Sample Coverage`" section (internal merge
    request 5367)
  * Fix apiext:VK_EXT_fragment_density_map2 appendix to include the correct
    extension interface information (internal merge request 5368)
  * Remove unwieldy and unnecessary list of copy functions from the
    introduction of the <<copies, Copy Commands>> chapter (merge request
    5373).
  * Move asciidoctor attributes enabling version and extension attributes
    into a generated file `specattribs.adoc` (internal merge request 5396).

New Extensions

  * apiext:VK_EXT_depth_clamp_01
  * apiext:VK_EXT_mesh_shader
  • Loading branch information
@oddhack
oddhack committed Sep 1, 2022
1 parent 7a60421 commit 135da3a
Show file tree
Hide file tree
Showing 82 changed files with 3,273 additions and 637 deletions.
2 changes: 1 addition & 1 deletion .reuse/dep5
View file
Expand Up @@ -2,7 +2,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: Vulkan-Docs
Source: https://github.com/KhronosGroup/Vulkan-Docs

Files: images/*.svg config/chunkindex/custom.patch config/CI/contractions*
Files: images/*.svg config/chunkindex/custom.patch config/CI/contractions* config/CI/txt-files-allowed
Copyright: 2015-2022 The Khronos Group Inc.
License: CC-BY-4.0

Expand Down
64 changes: 64 additions & 0 deletions ChangeLog.adoc
View file
Expand Up @@ -11,6 +11,70 @@ public pull requests that have been accepted.

-----------------------------------------------------

Change log for September 1, 2022 Vulkan 1.3.226 spec update:

Public Issues:

* Add missing SPV_KHR_ray_tracing storage class valid usage statement for
code:ShaderRecordBufferKHR (public merge request 1895).
* Add a NOTE to slink:VkAccelerationStructureCreateInfoKHR about
ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR (public issue 1904).
* Add a standalone SPIR-V valid usage statement for code:OpImageWrite
component mismatch (public merge request 1916).
* Generate the "`SPIRV Image Format`" and "`Plane Compatibility Format`"
tables from `vk.xml` (public merge request 1922).
* Add a NOTE to dlink:VK_USE_64_BIT_PTR_DEFINES to define its availability
Vulkan headers starting with VK_HEADER_VERSION 174 (public merge request
1918).

Internal Issues:

* Update issue #2 in the apiext:VK_EXT_depth_range_unrestricted appendix
to match core spec text (internal issue 2445).
* Clarify <<shaders-interpolation-decorations, Interpolation decorations>>
in pre-rasterization (internal issue 2721).
* Relax implicit layer disabling requirements in slink:VkApplicationInfo
(internal issue 2856).
* Update <requires> `extension` attribute in XML to support multiple
extensions with AND/OR connectives (internal issue 2922).
* Update provisional video API queries for usage hint and optimized
implementation settings (internal issue 2986).
* Relax slink:VkImageViewCreateInfo valid usage statement 01584 to allow
layers/levels for compressed format views of compressed format images
(internal issue 3063).
* Remove slink:VkImageViewCreateInfo valid usage statement 04739 (internal
issue 3164).
* Specify that addresses returned by flink:vkGetBufferDeviceAddress must
satisfy the alignment requirements of the device (internal issue 3176).
* Update makeSpec script to properly clean OUTDIR when it's explicitly
specified (internal issue 3194).
* Ensure that a mutable type list is provided in
slink:VkDescriptorSetLayoutCreateInfo when required (internal issue
3198).
* Update clarity of the Khronos specification copyright statement
regarding normative references to external specifications and the
Khronos Intellectual Property Rights Policy (internal issue 3203).
* Rename '.txt' -> '.adoc' for all asciidoctor markup files in the
repository, and update scripts and tools to match (internal issue 3204)
* Tag apiext:VK_ARM_rasterization_order_attachment_access as promoted to
EXT in XML (internal merge request 5364)
* Fix a typo in the "` Color Sample Coverage`" section (internal merge
request 5367)
* Fix apiext:VK_EXT_fragment_density_map2 appendix to include the correct
extension interface information (internal merge request 5368)
* Remove unwieldy and unnecessary list of copy functions from the
introduction of the <<copies, Copy Commands>> chapter (merge request
5373).
* Move asciidoctor attributes enabling version and extension attributes
into a generated file `specattribs.adoc` (internal merge request 5396).

New Extensions

* apiext:VK_EXT_depth_clamp_01
* apiext:VK_EXT_mesh_shader

-----------------------------------------------------

Change log for August 18, 2022 Vulkan 1.3.225 spec update:

* Update release number to 225 for this update.
Expand Down
106 changes: 62 additions & 44 deletions LICENSES/LicenseRef-KhronosSpecCopyright.adoc
View file
Expand Up @@ -5,64 +5,82 @@ proprietary to Khronos. Except as described by these terms, it or any
components may not be reproduced, republished, distributed, transmitted,
displayed, broadcast or otherwise exploited in any manner without the
express prior written permission of Khronos.

Khronos grants a conditional copyright license to use and reproduce the
unmodified Specification for any purpose, without fee or royalty, EXCEPT no
licenses to any patent, trademark or other intellectual property rights are
granted under these terms.
granted under these terms. Parties desiring to implement the Specification
and make use of Khronos trademarks in relation to that implementation, and
receive reciprocal patent license protection under the Khronos IP Policy
must become Adopters and confirm the implementation as conformant under the
process defined by Khronos for this Specification; see
https://www.khronos.org/adopters.

Khronos makes no, and expressly disclaims any, representations or
warranties, express or implied, regarding this Specification, including,
without limitation: merchantability, fitness for a particular purpose,
non-infringement of any intellectual property, correctness, accuracy,
completeness, timeliness, and reliability.
Under no circumstances will Khronos, or any of its Promoters, Contributors
or Members, or their respective partners, officers, directors, employees,
agents or representatives be liable for any damages, whether direct,
indirect, special or consequential damages for lost revenues, lost profits,
or otherwise, arising from or in connection with these materials.
completeness, timeliness, and reliability. Under no circumstances will
Khronos, or any of its Promoters, Contributors or Members, or their
respective partners, officers, directors, employees, agents or
representatives be liable for any damages, whether direct, indirect, special
or consequential damages for lost revenues, lost profits, or otherwise,
arising from or in connection with these materials.

This Specification has been created under the Khronos Intellectual Property
Rights Policy, which is Attachment A of the Khronos Group Membership
Agreement available at https://www.khronos.org/files/member_agreement.pdf, and which
defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'.
Parties desiring to implement the Specification and make use of Khronos trademarks
in relation to that implementation, and receive reciprocal patent license protection
under the Khronos Intellectual Property Rights Policy must become Adopters and
confirm the implementation as conformant under the process defined by Khronos for
this Specification; see https://www.khronos.org/adopters.
Agreement available at https://www.khronos.org/files/member_agreement.pdf.

// "Successor Specification" section

This Specification contains substantially unmodified functionality from, and
is a successor to, Khronos specifications including OpenGL, OpenGL ES and
OpenCL.

// End "Successor Specification" section

// "Normative Wording" section

This Specification contains substantially unmodified functionality from, and is a
successor to, Khronos specifications including OpenGL, OpenGL ES and OpenCL.
The Khronos Intellectual Property Rights defines the terms 'Scope',
'Compliant Portion', and 'Necessary Patent Claims'.

Some parts of this Specification are purely informative and so are EXCLUDED from
the Scope of this Specification. The <<introduction-conventions>> section of the
<<introduction>> defines how these parts of the Specification are identified.

Where this Specification uses <<introduction-technical-terminology,technical
terminology>>, defined in the <<glossary>> or otherwise, that refer to
enabling technologies that are not expressly set forth in this
Specification, those enabling technologies are EXCLUDED from the Scope of
this Specification.
For clarity, enabling technologies not disclosed with particularity in this
Specification (e.g. semiconductor manufacturing technology, hardware
architecture, processor architecture or microarchitecture, memory
architecture, compiler technology, object oriented technology, basic
operating system technology, compression technology, algorithms, and so on)
are NOT to be considered expressly set forth; only those application program
interfaces and data structures disclosed with particularity are included in
the Scope of this Specification.

For purposes of the Khronos Intellectual Property Rights Policy as it relates
to the definition of Necessary Patent Claims, all recommended or optional
features, behaviors and functionality set forth in this Specification, if
implemented, are considered to be included as Compliant Portions.

Where this Specification includes <<introduction-normative-references,
normative references to external documents>>, only the specifically
identified sections of those external documents are INCLUDED in the Scope of
this Specification. If not created by Khronos, those external documents may
contain contributions from non-members of Khronos not covered by the Khronos
Intellectual Property Rights Policy.
terminology>>, defined in the <<glossary, Glossary>> or otherwise, that
refer to enabling technologies that are not expressly set
forth in this Specification, those enabling technologies are EXCLUDED from
the Scope of this Specification. For clarity, enabling technologies not
disclosed with particularity in this Specification (e.g. semiconductor
manufacturing technology, hardware architecture, processor architecture or
microarchitecture, memory architecture, compiler technology, object oriented
technology, basic operating system technology, compression technology,
algorithms, and so on) are NOT to be considered expressly set forth; only
those application program interfaces and data structures disclosed with
particularity are included in the Scope of this Specification.

For purposes of the Khronos Intellectual Property Rights Policy as it
relates to the definition of Necessary Patent Claims, all recommended or
optional features, behaviors and functionality set forth in this
Specification, if implemented, are considered to be included as Compliant
Portions.

// End "Normative Wording" section

// "External References" section

Where this Specification identifies specific sections of external
references, only those specifically identified sections define
<<introduction-normative-references, normative>>
functionality. The Khronos Intellectual Property Rights Policy excludes
external references to materials and associated enabling technology not
created by Khronos from the Scope of this specification, and any licenses
that may be required to implement such referenced materials and associated
technologies must be obtained separately and may involve royalty payments.

// End "External References" section

ifndef::ratified_core_spec[]
This document contains extensions which are not ratified by Khronos, and as
Expand All @@ -75,9 +93,9 @@ https://registry.khronos.org/vulkan/specs/1.2-khr-extensions/html/vkspec.html
(core with KHR extensions).
endif::ratified_core_spec[]

Vulkan and Khronos are registered trademarks of The Khronos Group Inc.
ASTC is a trademark of ARM Holdings PLC; OpenCL is a trademark of Apple
Inc.; and OpenGL and OpenGL ES are registered trademarks of Hewlett Packard
Enterprise, all used under license by Khronos. All other product names,
Khronos and Vulkan are registered trademarks of The Khronos Group Inc.
OpenCL is a trademark of Apple Inc.; and OpenGL and OpenGL ES are registered
trademarks of Hewlett Packard Enterprise, all used under license by Khronos.
ASTC is a trademark of ARM Holdings PLC. All other product names,
trademarks, and/or company names are used solely for identification and
belong to their respective owners.
37 changes: 20 additions & 17 deletions Makefile
View file
Expand Up @@ -8,26 +8,24 @@
# $(VERSIONS) variable on the make command line to a space-separated
# list of version names (e.g. VK_VERSION_1_3) *including all previous
# versions of the API* (e.g. VK_VERSION_1_1 must also include
# VK_VERSION_1_0). $(VERSIONS) is converted into asciidoc and generator
# script arguments $(VERSIONATTRIBS) and $(VERSIONOPTIONS)
# VK_VERSION_1_0). $(VERSIONS) is converted into generator
# script arguments $(VERSIONOPTIONS) and into $(ATTRIBFILE)
#
# To build the specification / reference pages (refpages) with optional
# extensions included, set the $(EXTENSIONS) variable on the make
# command line to a space-separated list of extension names.
# $(EXTENSIONS) is converted into asciidoc and generator script
# arguments $(EXTATTRIBS) and $(EXTOPTIONS).
# $(EXTENSIONS) is converted into generator script
# arguments $(EXTOPTIONS) and into $(ATTRIBFILE)

# If a recipe fails, delete its target file. Without this cleanup, the leftover
# file from the failed recipe can falsely satisfy dependencies on subsequent
# runs of `make`.
.DELETE_ON_ERROR:

VERSIONS := VK_VERSION_1_0 VK_VERSION_1_1 VK_VERSION_1_2 VK_VERSION_1_3
VERSIONATTRIBS := $(foreach version,$(VERSIONS),-a $(version))
VERSIONOPTIONS := $(foreach version,$(VERSIONS),-feature $(version))

EXTS := $(sort $(EXTENSIONS) $(DIFFEXTENSIONS))
EXTATTRIBS := $(foreach ext,$(EXTS),-a $(ext))
EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext))

# APITITLE can be set to extra text to append to the document title,
Expand Down Expand Up @@ -70,7 +68,7 @@ check-contractions:
fi

# Look for typos and suggest fixes
CODESPELL = codespell --config config/CI/codespellrc
CODESPELL = codespell --config config/CI/codespellrc -S '*.js'
check-spelling:
if ! $(CODESPELL) > /dev/null ; then \
echo "Found probable misspellings. Corrections can be added to config/CI/codespell-allowed:" ; \
Expand Down Expand Up @@ -106,7 +104,7 @@ check-undefined:
$(SCRIPTS)/ci/check_undefined

# Look for '.txt' files, which should almost all be .adoc now
CHECK_TXTFILES = find . -name '*.txt' | egrep -v '^\./LICENSES/'
CHECK_TXTFILES = find . -name '*.txt' | egrep -v -E -f config/CI/txt-files-allowed
check-txtfiles:
if test `$(CHECK_TXTFILES) | wc -l` != 0 ; then \
echo "*.txt files found that are not allowed (use .adoc):" ; \
Expand Down Expand Up @@ -156,17 +154,13 @@ VERBOSE =
# NOTEOPTS sets options controlling which NOTEs are generated
# PATCHVERSION must equal VK_HEADER_VERSION from vk.xml
# ATTRIBOPTS sets the API revision and enables KaTeX generation
# VERSIONATTRIBS sets attributes for enabled API versions (set above
# based on $(VERSIONS))
# EXTATTRIBS sets attributes for enabled extensions (set above based on
# $(EXTENSIONS))
# EXTRAATTRIBS sets additional attributes, if passed to make
# ADOCMISCOPTS miscellaneous options controlling error behavior, etc.
# ADOCEXTS asciidoctor extensions to load
# ADOCOPTS options for asciidoc->HTML5 output

NOTEOPTS = -a editing-notes -a implementation-guide
PATCHVERSION = 225
PATCHVERSION = 226

ifneq (,$(findstring VK_VERSION_1_3,$(VERSIONS)))
SPECMINOR = 3
Expand Down Expand Up @@ -219,8 +213,6 @@ ATTRIBOPTS = -a revnumber="$(SPECREVISION)" \
-a images=$(IMAGEPATH) \
-a generated=$(GENERATED) \
-a refprefix \
$(VERSIONATTRIBS) \
$(EXTATTRIBS) \
$(EXTRAATTRIBS)
ADOCMISCOPTS = --failure-level ERROR
# Non target-specific Asciidoctor extensions and options
Expand Down Expand Up @@ -293,8 +285,9 @@ INTERFACEDEPEND = $(INTERFACEPATH)/timeMarker
SPIRVCAPDEPEND = $(SPIRVCAPPATH)/timeMarker
FORMATSDEPEND = $(FORMATSPATH)/timeMarker
RUBYDEPEND = $(RBAPIMAP)
ATTRIBFILE = $(GENERATED)/specattribs.adoc
# All generated dependencies
GENDEPENDS = $(APIDEPEND) $(VALIDITYDEPEND) $(HOSTSYNCDEPEND) $(METADEPEND) $(INTERFACEDEPEND) $(SPIRVCAPDEPEND) $(FORMATSDEPEND) $(RUBYDEPEND)
GENDEPENDS = $(APIDEPEND) $(VALIDITYDEPEND) $(HOSTSYNCDEPEND) $(METADEPEND) $(INTERFACEDEPEND) $(SPIRVCAPDEPEND) $(FORMATSDEPEND) $(RUBYDEPEND) $(ATTRIBFILE)
# All non-format-specific dependencies
COMMONDOCS = $(SPECFILES) $(GENDEPENDS)

Expand Down Expand Up @@ -461,7 +454,8 @@ CLEAN_GEN_PATHS = \
$(GENERATED)/__pycache__ \
$(PDFMATHDIR) \
$(PYAPIMAP) \
$(RBAPIMAP)
$(RBAPIMAP) \
$(ATTRIBFILE)

clean_generated:
$(QUIET)$(RMRF) $(CLEAN_GEN_PATHS)
Expand Down Expand Up @@ -652,5 +646,14 @@ $(FORMATSDEPEND): $(VKXML) $(GENVK)
$(QUIET)$(MKDIR) $(FORMATSPATH)
$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(FORMATSPATH) formatsinc

# This generates a single file containing asciidoc attributes for each
# core version and extension in the spec being built.
attribs: $(ATTRIBFILE)

$(ATTRIBFILE):
for attrib in $(VERSIONS) $(EXTS) ; do \
echo ":$${attrib}:" ; \
done > $@

# Debugging aid - generate all files from registry XML
generated: $(PYAPIMAP) $(GENDEPENDS)
29 changes: 29 additions & 0 deletions appendices/VK_EXT_depth_clamp_zero_one.adoc
View file
@@ -0,0 +1,29 @@
// Copyright 2017-2022 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_EXT_depth_clamp_zero_one.adoc[]

=== Other Extension Metadata

*Last Modified Date*::
2021-07-29
*Contributors*::
- Graeme Leese, Broadcom

=== Description

This extension gives defined behavior to fragment depth values which end up
outside the conventional [0, 1] range.
It can be used to ensure portability in edge cases of features like
depthBias.
The particular behavior is chosen to match OpenGL to aid porting or
emulation.

include::{generated}/interfaces/VK_EXT_depth_clamp_zero_one.adoc[]


=== Version History

* Revision 1, 2021-07-29 (Graeme Leese)
** Internal revisions
7 changes: 4 additions & 3 deletions appendices/VK_EXT_depth_range_unrestricted.adoc
View file
Expand Up @@ -43,9 +43,10 @@ the `0.0` to `1.0` range.
2) What happens if a resulting depth fragment is outside of the `0.0` to
`1.0` range and the depth buffer is fixed-point rather than floating-point?

*RESOLVED*: This situation can also arise without this extension (when fragment
shaders replace depth values, for example), and this extension does not change
the behaviour, which is defined in the <<fragops-depth,Depth Test>> section of the Fragment Operations chapter.
*RESOLVED*: This situation can also arise without this extension (when
fragment shaders replace depth values, for example), and this extension does
not change the behaviour, which is defined in the <<fragops-depth,Depth
Test>> section of the Fragment Operations chapter.

=== Version History

Expand Down

0 comments on commit 135da3a

Please sign in to comment.