Skip to content
Permalink
Browse files

Change log for April 7, 2019 Vulkan 1.1.106 spec update:

  * Update release number to 106.

Public Issues:

  * Add searchbox and generate search index for the chunked HTML target.
    Note that doing this requires several new toolchain components to build
    the `chunked` target (public issue 578 / internal issue 1352).
  * Remove descriptions of flink:vkCreateSampler sampler constraints which
    were repeated in the valid usage statements (public pull request 648).
  * Fix sense of conditional around a valid usage statement in the
    <<copies>> chapter (public issue 942).

Internal Issues:

  * Add missing pname:extent.width and pname:extent.height valid usage
    statements for flink:vkCmdClearAttachments (internal issue 1583).
  * Fix some inconsistencies in structures and corresponding pname:sType
    enumerant names by renaming
    sname:VkPhysicalDeviceShaderDrawParameterFeatures ->
    slink:slink:VkPhysicalDeviceShaderDrawParametersFeatures;
    sname:VkPhysicalDeviceVariablePointerFeatures ->
    slink:VkPhysicalDeviceVariablePointerFeatures;
    sname:VkPhysicalDeviceVariablePointerFeaturesKHR ->
    slink:VkPhysicalDeviceVariablePointerFeaturesKHR;
    sname:VkPhysicalDeviceBufferAddressFeaturesEXT ->
    slink:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT;
    etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETER_FEATURES
    ->
    ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES;
    etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES ->
    ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES;
    etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES_KHR ->
    ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR;
    and etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_ADDRESS_FEATURES_EXT
    ->
    ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT.
    The old names are still available as aliases for backwards
    compatibility. This change required introducing valid XML markup which
    externally written XML processing scripts may need to be modified to
    accomodate, to support multiple aliases of a single command or token
    name (internal issue 1592).
  * Add slink:VkDevice as the first parameter to flink:vkSetLocalDimmingAMD
    (internal issue 1618).
  * Improve CI header compilation tests to test all Vulkan platform
    includes, using fake platform headers where needed, and change the
    `allchecks` Makefile target to use the more comprehensive
    `check_spec_links.py` script instead of the retired `checkinc` and
    `checklinks` targets.
  * Move descriptions of the ASTC compressed texture decode mode from the
    <<appendix-compressedtex-astc,appendix>> to the recently updated
    external Khronos Data Format Specification.
  * Fix minor markup and spelling issues in the `VK_NV_ray_tracing`
    extension.
  • Loading branch information...
oddhack committed Apr 8, 2019
1 parent 84fcf6f commit b1042a3204aba3319e2a9b42afa969789472a458
@@ -68,33 +68,18 @@ hpp-generate:
allow_failure: true

# Compile a simple test program that uses vulkan.h
# The fake platform headers in tests/ allow compiling with all Vulkan
# platforms at once.
h-compile:
stage: test
dependencies:
- spec-generate
before_script:
- apt-get update -qq
- apt-get install -y -qq gcc clang
- echo "#include <vulkan/vulkan.h>" > /tmp/htest.c
- echo "int main()" >> /tmp/htest.c
- echo "{" >> /tmp/htest.c
- echo " const VkInstanceCreateInfo instance_info = {" >> /tmp/htest.c
- echo " .sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO," >> /tmp/htest.c
- echo " .pNext = NULL," >> /tmp/htest.c
- echo " .flags = 0," >> /tmp/htest.c
- echo " .pApplicationInfo = NULL," >> /tmp/htest.c
- echo " .enabledLayerCount = 0," >> /tmp/htest.c
- echo " .ppEnabledLayerNames = NULL," >> /tmp/htest.c
- echo " .enabledExtensionCount = 0," >> /tmp/htest.c
- echo " .ppEnabledExtensionNames = NULL," >> /tmp/htest.c
- echo " };" >> /tmp/htest.c
- echo " VkInstance instance;" >> /tmp/htest.c
- echo " vkCreateInstance(&instance_info, NULL, &instance);" >> /tmp/htest.c
- echo " vkDestroyInstance(instance, NULL);" >>/tmp/htest.c
- echo "}" >> /tmp/htest.c
script:
- gcc -c -std=c11 -Iinclude -Wall -Wextra -Werror /tmp/htest.c
- clang -c -std=c11 -Iinclude -Wall -Wextra -Werror /tmp/htest.c
- gcc -c -std=c11 -Iinclude -Itests -Wall -Wextra -Werror tests/htest.c
- clang -c -std=c11 -Iinclude -Itests -Wall -Wextra -Werror tests/htest.c

# Compile a simple test program that uses vulkan.hpp
hpp-compile:
@@ -105,14 +90,7 @@ hpp-compile:
before_script:
- apt-get update -qq
- apt-get install -y -qq g++ clang
- echo "#include <vulkan/vulkan.hpp>" > /tmp/hpptest.cpp
- echo "int main()" >> /tmp/hpptest.cpp
- echo "{" >> /tmp/hpptest.cpp
- echo " auto const instance_info = vk::InstanceCreateInfo();" >> /tmp/hpptest.cpp
- echo " vk::Instance instance;" >> /tmp/hpptest.cpp
- echo " vk::createInstance(&instance_info, nullptr, &instance);" >> /tmp/hpptest.cpp
- echo "}" >> /tmp/hpptest.cpp
script:
- g++ -c -std=c++11 -Iinclude -IVulkan-Hpp -Wall -Wextra -Werror /tmp/hpptest.cpp
- clang++ -c -std=c++11 -Iinclude -IVulkan-Hpp -Wall -Wextra -Werror /tmp/hpptest.cpp
- g++ -c -std=c++11 -Iinclude -IVulkan-Hpp -Wall -Wextra -Werror tests/hpptest.cpp
- clang++ -c -std=c++11 -Iinclude -IVulkan-Hpp -Wall -Wextra -Werror tests/hpptest.cpp
allow_failure: true
@@ -34,7 +34,7 @@ which builds an HTML5 specification output.
$ make all

builds the spec targets `html`, `pdf`, `styleguide`, `registry`, `manhtml`,
`manpdf`, `manhtmlpages`, `checkinc`, and `checklinks`.
`manpdf`, `manhtmlpages`, and `allchecks`

[NOTE]
.Note
@@ -71,11 +71,8 @@ XML Registry schema document::
* `manpdf` -- Single-file PDF in `$(OUTDIR)/apispec.pdf`
* `manhtmlpages` -- File-per-entry-point HTML in `$(OUTDIR)/man/html/*`
<<validation-scripts,Validator output>>::
* `checkinc` -- List of commands, structs, etc.
missing from the API spec in `$(OUTDIR)/checks/notInSpec.txt`
* `checklinks` -- Validator script output for API spec in
`$(OUTDIR)/checks/specErrs.txt` and for reference pages in
`$(OUTDIR)/checks/manErrs.txt`
* None at present. The `allchecks` target writes to standard output unless
the underlying script is given additional options.
Valid usage database::
* `validusage` - json database of all valid usage statements in the
specification. Must be built with `./makeAllExts` (for now).
@@ -209,38 +206,14 @@ builds.
[[validation-scripts]]
=== Validation Scripts

[NOTE]
.Note
====
The validation scripts have not been kept up to date, and probably don't
work properly at present due to numerous changes in the macro and
conditional markup used in the specification sources.
====

There are several Makefile targets which look for inconsistencies and
missing material between the specification and ref pages, and the canonical
description of the API in `vk.xml` :

* `checkinc`
* `checklinks`
* `allchecks` - both `checkinc` and `checklinks`

They are necessarily heuristic since they're dealing with lots of
hand-written material.

The `checkinc` target uses Unix filters to determine which autogenerated API
include files are used (and not used) in the spec.
It generates `notInSpec.txt` report.
This contains a list of the include files which are *not* referenced
anywhere in the spec, and probably correspond to undocumented material in
the spec.

The `checklinks` target validates the various internal tagged links in the
man pages and spec (e.g. the `fname:vkFuncBlah`, `sname:VkStructBlah`, etc.)
against the canonical description of the API in `vk.xml`.
It generates two output files, `manErrs.txt` and `specErrs.txt`, which
report problematic tags and the filenames/lines on which those tags were
found.
The `allchecks` Makefile target runs a Python script that looks for markup
errors, missing interfaces, macro misuse, and inconsistencies in the
specification text.
This script is necessarily heuristic, since it's dealing with lots of
hand-written material, but it identifies many problems and can suggest
solutions.
This script is also run as part of the CI tests in the internal Khronos
gitlab repository.


[[macros]]
@@ -415,6 +388,7 @@ Fences are used with the +++<<vkQueueSubmit>>+++ command...

// editing-note: why would I though. There are xlink: macros for that.


[[depends]]
== Software Dependencies

@@ -440,6 +414,24 @@ work at least as well.
This is for the PDF build, and it can still progress without it.
Ghostscript is used to optimize the size of the PDF, so it will be order
of magnitude smaller if it is included.
* The following dependencies are required only if building the
`chunked` target (chunked HTML output).
** Node (`nodejs`, version: 8.11.1)
*** Node Package Manager (`npm`, version: 5.8.0), for installing Lunr
** Lunr (`lunr`, version: 2.3.6), installed with npm.
One of the lunr files, `lunr.js`, is also incorporated into this
repository under `config/chunkindex/lunr.js`, so it will always be
available at spec load time. It is possible that there will be
incompatibilities between the installed version of lunr used to build
the index, and the copy of `lunr.js` included with the repository. If
so, update the repository copy of the file from your lunr distribution,
or install the specific lunr version 2.3.6 corresponding to the
repository copy.
*** Ensure that the installed `lunr` package is found by `node` at
runtime. This may require setting the environment variable NODE_PATH
to the path where `lunr` is installed. This path will probably be
`/usr/lib/node_modules`, if you install `nodejs` and `npm` from
deb.nodesource.com .

The following Ruby Gems and platform package dependencies must also be
installed.
@@ -752,7 +744,7 @@ gem clean


[[depends-chunker]]
=== Asciidoctor-chunker
=== Asciidoctor-chunker and Index Generation

To generate the `chunked` HTML target, you must install
https://github.com/wshito/asciidoctor-chunker[`asciidoctor-chunker`] and
@@ -767,6 +759,18 @@ Note that both Roswell and asciidoctor-chunker are installed outside the
scope of the Vulkan Specification repository (in system directories, and
in your home directory, respectively).

You must also install these Javascript dependencies to generate the
index, partly as system packages, and partly with npm. Note that npm is not
packaged for Debian 9, thus it's installed from deb.nodesource.com following
https://linuxize.com/post/how-to-install-node-js-on-debian-9/

----
curl -sL https://deb.nodesource.com/setup_8.x | sudo bash -
# nodejs also installs npm
sudo apt install nodejs
sudo npm install -g lunr@2.3.6
setenv NODE_PATH /usr/lib/node_modules
----

[[troubleshooting]]
== Troubleshooting
@@ -8,6 +8,64 @@ public pull requests that have been accepted.

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

Change log for April 7, 2019 Vulkan 1.1.106 spec update:

* Update release number to 106.

Public Issues:

* Add searchbox and generate search index for the chunked HTML target.
Note that doing this requires several new toolchain components to build
the `chunked` target (public issue 578 / internal issue 1352).
* Remove descriptions of flink:vkCreateSampler sampler constraints which
were repeated in the valid usage statements (public pull request 648).
* Fix sense of conditional around a valid usage statement in the
<<copies>> chapter (public issue 942).

Internal Issues:

* Add missing pname:extent.width and pname:extent.height valid usage
statements for flink:vkCmdClearAttachments (internal issue 1583).
* Fix some inconsistencies in structures and corresponding pname:sType
enumerant names by renaming
sname:VkPhysicalDeviceShaderDrawParameterFeatures ->
slink:slink:VkPhysicalDeviceShaderDrawParametersFeatures;
sname:VkPhysicalDeviceVariablePointerFeatures ->
slink:VkPhysicalDeviceVariablePointerFeatures;
sname:VkPhysicalDeviceVariablePointerFeaturesKHR ->
slink:VkPhysicalDeviceVariablePointerFeaturesKHR;
sname:VkPhysicalDeviceBufferAddressFeaturesEXT ->
slink:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT;
etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETER_FEATURES
->
ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_DRAW_PARAMETERS_FEATURES;
etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES ->
ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES;
etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTER_FEATURES_KHR ->
ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VARIABLE_POINTERS_FEATURES_KHR;
and etext:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_ADDRESS_FEATURES_EXT
->
ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT.
The old names are still available as aliases for backwards
compatibility. This change required introducing valid XML markup which
externally written XML processing scripts may need to be modified to
accomodate, to support multiple aliases of a single command or token
name (internal issue 1592).
* Add slink:VkDevice as the first parameter to flink:vkSetLocalDimmingAMD
(internal issue 1618).
* Improve CI header compilation tests to test all Vulkan platform
includes, using fake platform headers where needed, and change the
`allchecks` Makefile target to use the more comprehensive
`check_spec_links.py` script instead of the retired `checkinc` and
`checklinks` targets.
* Move descriptions of the ASTC compressed texture decode mode from the
<<appendix-compressedtex-astc,appendix>> to the recently updated
external Khronos Data Format Specification.
* Fix minor markup and spelling issues in the `VK_NV_ray_tracing`
extension.

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

Change log for March 19, 2019 Vulkan 1.1.105 spec update (GDC edition):

* Update release number to 105.
@@ -59,8 +59,7 @@ IMAGEOPTS = inline
# manhtml - HTML5 single-page reference guide
# manpdf - PDF reference guide
# manhtmlpages - HTML5 separate per-feature reference pages
# checkinc - validator script for asciidoc include files
# checklinks - validator script for asciidoc xrefs
# allchecks - Python sanity checker for script markup and macro use

all: alldocs allchecks

@@ -70,14 +69,18 @@ allspecs: html pdf styleguide registry

allman: manhtml manpdf manhtmlpages

allchecks: checkinc checklinks
allchecks:
$(PYTHON) $(SCRIPTS)/check_spec_links.py -Werror

# Note that the := assignments below are immediate, not deferred, and
# are therefore order-dependent in the Makefile

QUIET ?= @
PYTHON ?= python3
ASCIIDOC ?= asciidoctor
RUBY = ruby
NODEJS = node
PATCH = patch
RM = rm -f
RMRF = rm -rf
MKDIR = mkdir -p
@@ -118,7 +121,7 @@ VERBOSE =
# ADOCOPTS options for asciidoc->HTML5 output

NOTEOPTS = -a editing-notes -a implementation-guide
PATCHVERSION = 105
PATCHVERSION = 106
ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS)))
SPECREVISION = 1.1.$(PATCHVERSION)
else
@@ -203,10 +206,22 @@ $(OUTDIR)/$(KATEXDIR)/README.md: katex/README.md
ROSWELL = ros
ROSWELLOPTS ?= dynamic-space-size=4000
CHUNKER = $(HOME)/common-lisp/asciidoctor-chunker/roswell/asciidoctor-chunker.ros

CHUNKINDEX = $(CURDIR)/config/chunkindex
# Only the $(ROSWELL) step is required unless the search index is to be
# generated and incorporated into the chunked spec.
#
# Dropped $(QUIET) for now
# Should set NODE_PATH=/usr/local/lib/node_modules or wherever, outside Makefile
# Copying chunked.js into target avoids a warning from the chunker
chunked: $(HTMLDIR)/vkspec.html $(SPECSRC) $(COMMONDOCS)
$(QUIET)$(PATCH) $(HTMLDIR)/vkspec.html -o $(HTMLDIR)/prechunked.html $(CHUNKINDEX)/custom.patch
$(QUIET)$(CP) $(CHUNKINDEX)/chunked.css $(CHUNKINDEX)/chunked.js \
$(CHUNKINDEX)/lunr.js $(HTMLDIR)
$(QUIET)$(ROSWELL) $(ROSWELLOPTS) $(CHUNKER) \
$(HTMLDIR)/vkspec.html -o $(HTMLDIR)
$(HTMLDIR)/prechunked.html -o $(HTMLDIR)
$(QUIET)$(RM) prechunked.html
$(QUIET)$(RUBY) $(CHUNKINDEX)/generate-index.rb $(HTMLDIR)/chap*html | \
$(NODEJS) $(CHUNKINDEX)/build-index.js > $(HTMLDIR)/search.index.js

html: $(HTMLDIR)/vkspec.html $(SPECSRC) $(COMMONDOCS)

@@ -292,11 +307,12 @@ clean_man:
clean_checks:
$(QUIET)$(RMRF) $(CHECKDIR)

MANTRASH = $(filter-out $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt,$(wildcard $(MANDIR)/*.txt)) $(LOGFILE)
clean_generated:
$(QUIET)$(RMRF) api/* hostsynctable/* validity/* $(METADIR)/*
$(QUIET)$(RMRF) include/vulkan/vulkan_*.h $(SCRIPTS)/vkapi.py
$(QUIET)$(RM) config/extDependency.*
$(QUIET)$(RM) man/apispec.txt $(LOGFILE) man/[Vv][Kk]*.txt man/PFN*.txt
$(QUIET)$(RM) $(MANTRASH)
$(QUIET)$(RMRF) $(PDFMATHDIR)

clean_validusage:
@@ -47,9 +47,8 @@ ChangeLog.txt Change log summary for each public spec update
Makefile, make* Makefile and helper build scripts (see BUILD.adoc)
appendices/ Specification appendices
chapters/ Specification chapters
config/ Asciidoctor configuration
config/ Asciidoctor configuration, CSS, and index generator
images/ Images (figures, diagrams, icons)
include/vulkan/ Vulkan headers, generated from the Registry
man/ Reference (man) pages for the API; mostly extracted from the spec source
out/ Default directory for the generated documents
scripts/ Helper scripts used in specification, header, and reference page generation
@@ -74,10 +73,9 @@ See link:xml/README.adoc[xml/README.adoc].
The header files (`include/vulkan/vulkan*.h`) and many parts of the
specification and reference page documents are generated from descriptions
in the XML API Registry (`xml/vk.xml`).
The generated files (with the exception of header files) are not checked
into the repository.
If you change `vk.xml`, you can regenerate the header by going into `xml/`
and running:
The generated files are not checked into the repository.
If you change `vk.xml`, you can regenerate the headers by going into
`xml/` and running:

$ make clean install

@@ -29,7 +29,7 @@ None
=== New Enum Constants

* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_ADDRESS_FEATURES_EXT
** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_BUFFER_DEVICE_ADDRESS_FEATURES_EXT
** ename:VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO_EXT
** ename:VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_CREATE_INFO_EXT

@@ -48,7 +48,7 @@ None

=== New Structures

* slink:VkPhysicalDeviceBufferAddressFeaturesEXT
* slink:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT
* slink:VkBufferDeviceAddressInfoEXT
* slink:VkBufferDeviceAddressCreateInfoEXT

@@ -33,6 +33,7 @@ ifdef::VK_VERSION_1_1[]
* Extending elink:VkDescriptorUpdateTemplateType
** ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
endif::VK_VERSION_1_1[]

=== New Enums

None.
@@ -42,7 +42,7 @@ The second, code:VariablePointers, is optional.

=== New Structures

* slink:VkPhysicalDeviceVariablePointerFeaturesKHR
* slink:VkPhysicalDeviceVariablePointersFeaturesKHR

=== New SPIR-V Capabilities

0 comments on commit b1042a3

Please sign in to comment.
You can’t perform that action at this time.