Skip to content

Commit

Permalink
Change log for September 5, 2017 Vulkan 1.0.60 spec update:
Browse files Browse the repository at this point in the history
  * Bump API patch number and header version number to 60 for this update.

Github Issues:

  * Document that <<queries-timestamps, Timestamp Queries>> can only be
    meaningfully compared when they are written from the same queue (public
    issue 216).
  * Document that the `<extension>` tag `type` attribute is required for
    non-disabled extensions (derived from, but does not close public issue
    354).
  * Clean up registry schema length attribute descriptions to be consistent
    and correct (public issue 555).

Internal Issues:

  * Replace as much of the hand-written extension appendix metadata as
    possible with asciidoc includes generated from corresponding attributes
    of +vk.xml+, and enhance the style guide to match. This avoids
    inconsistencies between +vk.xml+ and the appendices, and produces a more
    uniform style (internal issue 137).
  * Remove the generated extDependency.{py,sh} files from the tree and
    create them dynamically on demand instead, reducing merge conflicts
    (internal issue 713).
  * Add a prototype tool for generating in-place difference markup for
    sections guarded by asciidoc conditionals, and new syntax for open
    blocks to support it (internal issue 833).
  * Remove unnecessary restriction of etext:*SYNC_FD_BIT_KHR external handle
    types to the same physical device in the
    slink:VkPhysicalDeviceIDPropertiesKHR,
    flink:VkImportMemoryWin32HandleInfoKHR,
    slink:VkImportFenceWin32HandleInfoKHR, slink:VkImportFenceFdInfoKHR,
    slink:VkImportSemaphoreWin32HandleInfoKHR,
    slink:VkImportSemaphoreFdInfoKHR
    <<external-memory-handle-types-compatibility, External memory handle
    types compatibility>>, <<external-semaphore-handle-types-compatibility,
    External semaphore handle types compatibility>>, and
    <<external-fence-handle-types-compatibility, External fence handle types
    compatibility>> sections (internal issue 956).

Other Issues:

  * Remove dependency of +VK_KHX_device_group+ on +VK_KHR_swapchain+ (there
    is an interaction, but not a strict dependency), and add a new
    `extension` attribute to the `<require` XML tag to allow classifying a
    subset of interfaces of an extension as requiring another extension.
    Update the registry schema and documentation accordingly.

New Extensions:

  * `VK_AMD_shader_fragment_mask` (and related `GL_AMD_shader_fragment_mask`
    GLSL extension)
  * `VK_EXT_sample_locations`
  * `VK_EXT_validation_cache`
  • Loading branch information
oddhack committed Sep 4, 2017
1 parent bbb637d commit df88ded
Show file tree
Hide file tree
Showing 141 changed files with 3,016 additions and 1,829 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ __pycache__
doc/specs/vulkan/api
doc/specs/vulkan/hostsynctable
doc/specs/vulkan/validity
doc/specs/vulkan/appendices/meta

# Files generated by extraction from spec source
doc/specs/vulkan/man/PFN*.txt
Expand Down
134 changes: 134 additions & 0 deletions doc/specs/misc/GL_AMD_shader_fragment_mask.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
Name

AMD_shader_fragment_mask

Name Strings

GL_AMD_shader_fragment_mask

Contact

Aaron Hagan, AMD (aaron.hagan 'at' amd.com)

Contributors

Aaron Hagan, AMD
Timothy Lottes, AMD
Daniel Rakos, AMD

Status

Pending

Version

Last Modified Date: 08/07/2017
Author Revision: 2

Number

TBD

Dependencies

This extension is written against the OpenGL Shading Language
Specification, Version 4.50.

Overview

This extension introduces new GLSL built-in functions enabling more
efficient read access to fragment mask compressed multisampled color
images. Implementations supporting this extension can avoid storing
identical sample color values inside a single pixel. This is achieved
by introducing the concept of color fragments and fragment masks.

Color fragments are storage units inside a single pixel of a multisampled
color image that can hold a unique color value. Each pixel then has a
fragment mask which contains per sample indices that map a given color
sample to a particular color fragment.

This extension enables fetching the fragment mask and individual color
fragments from a multisampled color image.

IP Status

None.

New Procedures and Functions

None.

New Tokens

None.

Modifications to the OpenGL Shading Language Specification, Version 4.50

Including the following line in a shader can be used to control the
language features described in this extension:

#extension GL_AMD_shader_fmask : <behavior>

where <behavior> is as specified in section 3.3.

New preprocessor #defines are added to the OpenGL Shading Language:

#define GL_AMD_shader_fragement_mask 1

Additions to Chapter 8 of the OpenGL Shading Language (GLSL) Specification,
version 4.30 (Built-in functions)

Add to the table of functions 8.9.2, "Texel Lookup Functions", p. 164

+-----------------------------------+-------------------------------------+
| Syntax | Description |
+-----------------------------------+-------------------------------------+
| uint fragmentMaskFetchAMD( | Returns the fragment mask from a |
| gsampler2DMS sampler, | multisampled color image. The |
| ivec2 P) | fragment mask is a single uint where|
| | each subsequent 4 bit specifies the |
| uint fragmentMaskFetchAMD( | color fragment index corresponding |
| gsampler2DMSArray sampler, | to the color sample, starting from |
| ivec3 P) | the least significant bit. |
| | |
| uint fragmentMaskFetchAMD( | |
| gsubpassInputMS subpass) | |
+-----------------------------------+-------------------------------------+
| gvec4 fragmentFetchAMD( | Fetches a color fragment with a |
| gsampler2DMS sampler, | correspoding fragment mask value. |
| ivec2 P, | |
| uint fragIndex) | |
| | |
| gvec4 fragmentFetchAMD( | |
| gsampler2DMSArray sampler, | |
| ivec3 P, | |
| uint fragIndex)| |
| | |
| gvec4 fragmentFetchAMD( | |
| gsubpassInputMS subpass, | |
| uint fragIndex) | |
+-----------------------------------+-------------------------------------+


Additions to the AGL/GLX/WGL Specifications

None.

GLX Protocol

None.

Errors

None.

Issues


Revision History

Rev. Date Author Changes
---- ---------- -------- -----------------------------------------------
2 08/07/2017 ahagan Cleanup and prepared for posting.

1 04/24/2017 ahagan Initial draft.
37 changes: 29 additions & 8 deletions doc/specs/vulkan/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
# asciidoc and generator script arguments $(EXTATTRIBS) and
# $(EXTOPTIONS).

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

Expand Down Expand Up @@ -87,7 +87,7 @@ VERBOSE =
# $(EXTENSIONS))
# ADOCOPTS options for asciidoc->HTML5 output
NOTEOPTS = -a editing-notes -a implementation-guide
SPECREVISION = 1.0.59
SPECREVISION = 1.0.60
# Spell out RFC2822 format as not all date commands support -R
SPECDATE = $(shell echo `date -u "+%a, %d %b %Y %T %z"`)

Expand All @@ -114,7 +114,7 @@ ATTRIBOPTS = -a revnumber="$(SPECREVISION)" \
-a stem=latexmath \
$(EXTATTRIBS)

ADOCEXTS = -r $(CURDIR)/config/vulkan-macros.rb
ADOCEXTS = -r $(CURDIR)/config/vulkan-macros.rb -r $(CURDIR)/config/tilde_open_block.rb
ADOCOPTS = -d book $(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)

ADOCHTMLEXTS = -r $(CURDIR)/config/katex_replace.rb
Expand Down Expand Up @@ -143,7 +143,10 @@ SPECSRC := vkspec.txt
# should work in extension branches to pull in those files as well.
SPECFILES = $(wildcard chapters/[A-Za-z]*.txt appendices/[A-Za-z]*.txt chapters/*/[A-Za-z]*.txt appendices/*/[A-Za-z]*.txt)
GENINCLUDE = $(wildcard api/*/[A-Za-z]*.txt validity/*/[A-Za-z]*.txt hostsynctable/*.txt)
GENDEPENDS = api/timeMarker validity/timeMarker hostsynctable/timeMarker
# Shorthand for where the extension appendix generated files go
METADIR = appendices/meta
# Generated dependencies of the spec
GENDEPENDS = api/timeMarker validity/timeMarker hostsynctable/timeMarker $(METADIR)/timeMarker
# All non-format-specific dependencies
COMMONDOCS = $(SPECFILES) $(GENINCLUDE) $(GENDEPENDS)

Expand All @@ -166,6 +169,12 @@ $(HTMLDIR)/vkspec.html: KATEXDIR = ../katex
$(HTMLDIR)/vkspec.html: $(SPECSRC) $(COMMONDOCS) katexinst
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ $(SPECSRC)

diff_html: $(HTMLDIR)/diff.html $(SPECSRC) $(COMMONDOCS)

$(HTMLDIR)/diff.html: KATEXDIR = ../katex
$(HTMLDIR)/diff.html: $(SPECSRC) $(COMMONDOCS) katexinst
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) -a diff_extensions="$(DIFFEXTENSIONS)" -r $(CURDIR)/config/extension-highlighter.rb --trace -o $@ $(SPECSRC)

pdf: $(PDFDIR)/vkspec.pdf $(SPECSRC) $(COMMONDOCS)

$(PDFDIR)/vkspec.pdf: $(SPECSRC) $(COMMONDOCS)
Expand Down Expand Up @@ -238,7 +247,8 @@ clean_checks:
$(QUIET)$(RMRF) $(CHECKDIR)

clean_generated:
$(QUIET)$(RMRF) api/* hostsynctable/* validity/* vkapi.py
$(QUIET)$(RMRF) api/* hostsynctable/* validity/* $(METADIR)/* vkapi.py
$(QUIET)$(RM) config/extDependency.stamp config/extDependency.pyc config/extDependency.sh config/extDependency.py
$(QUIET)$(RM) man/apispec.txt $(LOGFILE) man/[Vv][Kk]*.txt man/PFN*.txt
$(QUIET)$(RMRF) $(PDFMATHDIR)

Expand Down Expand Up @@ -363,6 +373,7 @@ checklinks: vkapi.py
# api/timeMarker - proxy for 'apiincludes' - API include files under api/*/*.txt
# hostsynctable/timeMarker - proxy for host sync table include files under hostsynctable/*.txt
# validity/timeMarker - proxy for API validity include files under validity/*/*.txt
# appendices/meta/timeMarker - proxy for extension appendix metadata include files under appendices/*.txt
#
# $(EXTOPTIONS) specifies the extensions which are included in these
# targets, and is set above based on $(EXTENSIONS).
Expand Down Expand Up @@ -393,17 +404,27 @@ validity/timeMarker: $(VKXML) $(GENVK)
$(QUIET)$(MKDIR) validity
$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o validity validinc

extinc: $(METADIR)/timeMarker

$(METADIR)/timeMarker: $(VKXML) $(GENVK)
$(QUIET)$(MKDIR) $(METADIR)
$(QUIET)$(PYTHON) $(GENVK) $(GENVKOPTS) -o $(METADIR) extinc

# Debugging aid - generate all files from registry XML
# This leaves out config/extDependency.sh intentionally as it only
# needs to be updated when the extension dependencies in vk.xml change.

generated: vkapi.py api/timeMarker hostsynctable/timeMarker validity/timeMarker
generated: vkapi.py api/timeMarker hostsynctable/timeMarker validity/timeMarker $(METADIR)/timeMarker

# Extension dependencies derived from vk.xml
# Both Bash and Python versions are generated

config/extDependency.sh: config/extDependency.stamp
config/extDependency.py: config/extDependency.stamp

DEPSCRIPT = $(REGISTRY)/extDependency.py
config/extDependency.sh: $(VKXML) $(DEPSCRIPT)
$(PYTHON) $(DEPSCRIPT) -registry $(VKXML) \
config/extDependency.stamp: $(VKXML) $(DEPSCRIPT)
$(QUIET)$(PYTHON) $(DEPSCRIPT) -registry $(VKXML) \
-outscript config/extDependency.sh \
-outpy config/extDependency.py
$(QUIET)touch $@
51 changes: 36 additions & 15 deletions doc/specs/vulkan/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ targets, or they can individually be found as follows:
** `pdf` - PDF in `$(OUTDIR)/pdf/vkspec.pdf`
* "`Vulkan Documentation and Extensions`" guide:
** `styleguide` - Single-file HTML5 in `$(OUTDIR)/styleguide.html`
* Diff spec:
** `diff_html` - Single-file HTML5 in `$(OUTDIR)/html/diff.html`
* Reference pages:
** `manhtml` - Single-file HTML in `$(OUTDIR)/apispec.html`
** `manpdf` - Single-file PDF in `$(OUTDIR)/apispec.html`
Expand Down Expand Up @@ -76,15 +78,16 @@ as described below
[[building-extensions]]
=== Building With Extensions Included

We now use a "`single-branch model`", where extensions are included in the
same `1.0` branch as the core Specification, instead of the older model
where each extension lived in a separate Git branch.
Whether a given extension is generated in the output depends on asciidoc and
generator script options being specified.
Extensions are defined in the same source as the core Specification, but
are only conditionally included in the output.
Asciidoctor http://asciidoctor.org/docs/user-manual/#attributes[attributes]
of the same name as the extension are used to define whether the extension
is included or not - defining such an attribute will cause the output to
include the text for that extension.

The extensions included are those specified as a space-separated list of
extension names (e.g. `VK_KHR_surface`) in the Makefile variable
`$(EXTENSIONS)`, normally set on the make command line.
When building the specification, the extensions included are those specified
as a space-separated list of extension names (e.g. `VK_KHR_surface`) in the
Makefile variable `$(EXTENSIONS)`, normally set on the make command line.
When changing the list of extensions, it is critical to remove all generated
files using the `clean_generated` Makefile target, as the contents of
generated files depends on `$(EXTENSIONS)`.
Expand All @@ -101,20 +104,38 @@ or more specified targets for specified extensions:
Khronox Experimental (`VK_KHX_*`) extensions enabled.
Usage is `makeKHRAndKHX target(s)`.

Before using these scripts, if you have changed `src/spec/vk.xml` since
checking out your repository, first

$ make config/extDependency.sh

to rebuild extension dependencies.

The Makefile variable `$(APITITLE)` defines an additional string which is
appended to the specification title.
When building with extensions enabled, this should be set to something like
`(with extension VK_extension_name)`.
The `makeExt`, `makeKHR`, and `makeKHRAndKHX` scripts already do this.


[[building-diff]]
==== Building A Highlighted Extension Diff

The "diff_html" target in the makefile can be used to generate a version of
the specification which highlights changes made to the specification by the
inclusion of a particular set of extensions.

Extensions in the "EXTENSIONS" attribute defines the base extensions to be
enabled by the specification, and these will not be highlighted in the
output.
Extensions in the "DIFFEXTENSIONS" attribute defines the set of extensions
whose changes to the text will be highlighted when they are enabled.
Any extensions in both environment variables will be treated as if they were
only included in DIFFEXTENSIONS.
The DIFFEXTENSIONS environment variable can be used alongside the make*
scripts in this repository.

In the resulting html document, content that has been added by one of the
extensions will be highlighted with a lime background, and content that was
removed will be highlighted with a pink background.
Each section has an anchor of "#differenceN", with an arrow (=>) at the end
of each section which links to the next difference section.
The first diff section is "difference1".


[[building-test]]
=== Alternate and Test Builds

Expand Down
16 changes: 1 addition & 15 deletions doc/specs/vulkan/appendices/VK_AMD_draw_indirect_count.txt
Original file line number Diff line number Diff line change
@@ -1,30 +1,16 @@
[[VK_AMD_draw_indirect_count]]
== VK_AMD_draw_indirect_count
include::meta/VK_AMD_draw_indirect_count.txt[]

*Name String*::
+VK_AMD_draw_indirect_count+
*Extension Type*::
Device extension
*Registered Extension Number*::
34
*Last Modified Date*::
2016-08-23
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0 of the Vulkan API.
*Contributors*::
- Matthaeus G.
Chajdas, AMD
- Derrick Owens, AMD
- Graham Sellers, AMD
- Daniel Rakos, AMD
- Dominik Witczak, AMD
*Contacts*::
- Matthaeus G.
Chajdas, AMD (matthaeus.chajdas@amd.com)

This extension allows an application to source the number of draw calls for
indirect draw calls from a buffer.
Expand Down
26 changes: 11 additions & 15 deletions doc/specs/vulkan/appendices/VK_AMD_gcn_shader.txt
Original file line number Diff line number Diff line change
@@ -1,31 +1,27 @@
[[VK_AMD_gcn_shader]]
== VK_AMD_gcn_shader
include::meta/VK_AMD_gcn_shader.txt[]

*Name String*::
+VK_AMD_gcn_shader+
*Extension Type*::
Device extension
*Registered Extension Number*::
26
*Last Modified Date*::
2016-05-30
*Revision*::
1
*IP Status*::
No known IP claims.
*Dependencies*::
- This extension is written against version 1.0.15 of the Vulkan API.
*Contributors*::
- Dominik Witczak, AMD
- Daniel Rakos, AMD
- Rex Xu, AMD
- Graham Sellers, AMD
*Contacts*::
- Dominik Witczak, AMD (dominik.witczak@amd.com)

This extension adds support for the following SPIR-V extension in Vulkan:

* +SPV_AMD_gcn_shader+
* https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_gcn_shader.html[+SPV_AMD_gcn_shader+]

ifdef::editing-notes[]
[NOTE]
.editing-note
==================
Shouldn't the SPV extension be in the Interactions and External Dependencies
block?
==================
endif::editing-notes[]

=== Version History

Expand Down
Loading

0 comments on commit df88ded

Please sign in to comment.