Skip to content

Commit

Permalink
Change log for March 18, 2019 Vulkan 1.1.104 spec update:
Browse files Browse the repository at this point in the history
  * Update release number to 104.

Public Issues:

  * Remove the incorrect line from "`Initial`" to "`Invalid`" state in the
    <<commandbuffer-lifecycle-diagram, Lifecycle of a command buffer>>
    diagram (public issue 881).
  * Add Fuchsia platform to <<boilerplate-wsi-header-table, Window System
    Extensions and Headers>> table (public pull request 933).
  * Change the type of
    slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress from
    basetype:VkDeviceSize to basetype:VkDeviceAddress. These are both
    typedefs of code:uint64_t, so it is an ABI-compatible change (public
    issue 934).

Internal Issues:

  * Remove generated header files and update the CI tests to build a copy of
    the headers for use by the hpp-generate / hpp-compile CI stages. Targets
    to generate the headers will not be removed, but keeping these generated
    files in the repository increased the frequency of conflicts between
    branches when merging to master (internal issue 745).
  * Reword "`undefined: behavior if *action*" to "`must: not do *action*`"
    in the places the old terminology was used, and add a new
    <<writing-undefined, Describing Undefined Behavior>> section of the
    style guide to explain how to write such language in the future
    (internal issue 1579).
  * Move almost all Python scripts into the toplevel `scripts/` directory.
    Apply extensive internal edits to clean up and simplify the scripts, and
    try to follow PEP8 guidelines. Generalize the scripts with the use of a
    Conventions object controlling many aspects of output generation, to
    enable their use in other Khronos projects with similar requirements.
    Autogenerate extension interface refpages (these are experimental and
    may be retired going forward).

New Extensions:

  * `VK_AMD_display_native_hdr`
  * `VK_EXT_full_screen_exclusive` (internal issue 1439)
  * `VK_EXT_host_query_reset`
  * `VK_EXT_pipeline_creation_feedback` (internal issue 1560)
  * `VK_KHR_surface_protected_capabilities` (internal issue 1520)
  • Loading branch information
oddhack committed Mar 17, 2019
1 parent 8cc971f commit 476e3f4
Show file tree
Hide file tree
Showing 98 changed files with 4,109 additions and 12,081 deletions.
14 changes: 9 additions & 5 deletions .gitlab-ci.yml
Expand Up @@ -5,7 +5,7 @@ spec-generate:
stage: build
before_script:
- apt-get update -qq
- apt-get install -y -qq gcc git python3 python3-termcolor python3-pytest ruby
- apt-get install -y -qq gcc git python3 python3-termcolor python3-pytest ruby jing
- apt-get install -y -qq cmake bison flex libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev libpango1.0-dev ttf-lyx
# Force-install an older version of i18n so the 1.5.2 version, which
# won't work with ruby 2.1, doesn't abort the CI job when installing
Expand All @@ -14,17 +14,19 @@ spec-generate:
- gem install asciidoctor asciidoctor-mathematical coderay json-schema
script:
# Internal self-test of the check_spec_links script
- ( cd xml && py.test-3 )
- ( cd scripts && py.test-3 test*.py )
- mkdir -p out/checks
- xml/check_spec_links.py --html=out/checks/problems.html > /dev/null || true
- scripts/check_spec_links.py --html=out/checks/problems.html > /dev/null || true
# Breaking the build if # of errors increases. We should manually ratchet ignore_count down as errors get fixed.
# If there are unfixable errors, add '--ignore_count #' where '#' is the
# number of them. This is a slightly crude way of enforcing "don't add
# errors" but simpler than the alternatives (running against master,
# diff, etc)
- xml/check_spec_links.py -Werror --ignore_count 0
- scripts/check_spec_links.py -Werror --ignore_count 0
# Build the actual spec
- ./makeAllExts QUIET= -j${nproc} -Otarget checkinc checklinks validusage html styleguide registry manhtmlpages
- ./makeAllExts QUIET= -j${nproc} -Otarget validusage html styleguide registry manhtmlpages
# Build headers, for use by all later stages
- ( cd xml && make validate test install )
artifacts:
when: always
paths:
Expand All @@ -48,6 +50,8 @@ hpp-generate:
- git submodule update --init --recursive -- tinyxml2
- rm -rf Vulkan-Docs
- cp -r "${SPEC_DIR}" Vulkan-Docs
# Copy Vulkan C headers into subdir copy used by Vulkan-Hpp
- cp -p ${SPEC_DIR}/include/vulkan/*.h Vulkan-Docs/include/vulkan/
script:
- cd /tmp/Vulkan-Hpp
- cmake -H. -Bbuild
Expand Down
47 changes: 47 additions & 0 deletions ChangeLog.txt
Expand Up @@ -8,6 +8,53 @@ public pull requests that have been accepted.

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

Change log for March 18, 2019 Vulkan 1.1.104 spec update:

* Update release number to 104.

Public Issues:

* Remove the incorrect line from "`Initial`" to "`Invalid`" state in the
<<commandbuffer-lifecycle-diagram, Lifecycle of a command buffer>>
diagram (public issue 881).
* Add Fuchsia platform to <<boilerplate-wsi-header-table, Window System
Extensions and Headers>> table (public pull request 933).
* Change the type of
slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress from
basetype:VkDeviceSize to basetype:VkDeviceAddress. These are both
typedefs of code:uint64_t, so it is an ABI-compatible change (public
issue 934).

Internal Issues:

* Remove generated header files and update the CI tests to build a copy of
the headers for use by the hpp-generate / hpp-compile CI stages. Targets
to generate the headers will not be removed, but keeping these generated
files in the repository increased the frequency of conflicts between
branches when merging to master (internal issue 745).
* Reword "`undefined: behavior if *action*" to "`must: not do *action*`"
in the places the old terminology was used, and add a new
<<writing-undefined, Describing Undefined Behavior>> section of the
style guide to explain how to write such language in the future
(internal issue 1579).
* Move almost all Python scripts into the toplevel `scripts/` directory.
Apply extensive internal edits to clean up and simplify the scripts, and
try to follow PEP8 guidelines. Generalize the scripts with the use of a
Conventions object controlling many aspects of output generation, to
enable their use in other Khronos projects with similar requirements.
Autogenerate extension interface refpages (these are experimental and
may be retired going forward).

New Extensions:

* `VK_AMD_display_native_hdr`
* `VK_EXT_full_screen_exclusive` (internal issue 1439)
* `VK_EXT_host_query_reset`
* `VK_EXT_pipeline_creation_feedback` (internal issue 1560)
* `VK_KHR_surface_protected_capabilities` (internal issue 1520)

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

Change log for March 11, 2019 Vulkan 1.1.103 spec update:

* Update release number to 103.
Expand Down
74 changes: 17 additions & 57 deletions Makefile
Expand Up @@ -85,6 +85,9 @@ CP = cp
ECHO = echo
GS_EXISTS := $(shell command -v gs 2> /dev/null)

# Path to Python scripts used in generation
SCRIPTS = scripts

# Target directories for output files
# HTMLDIR - 'html' target
# PDFDIR - 'pdf' target
Expand Down Expand Up @@ -115,7 +118,7 @@ VERBOSE =
# ADOCOPTS options for asciidoc->HTML5 output

NOTEOPTS = -a editing-notes -a implementation-guide
PATCHVERSION = 103
PATCHVERSION = 104
ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS)))
SPECREVISION = 1.1.$(PATCHVERSION)
else
Expand Down Expand Up @@ -264,7 +267,7 @@ $(OUTDIR)/registry.html: $(REGSRC)


# Reflow text in spec sources
REFLOW = reflow.py
REFLOW = $(SCRIPTS)/reflow.py
REFLOWOPTS = -overwrite

reflow:
Expand All @@ -290,8 +293,9 @@ clean_checks:
$(QUIET)$(RMRF) $(CHECKDIR)

clean_generated:
$(QUIET)$(RMRF) api/* hostsynctable/* validity/* $(METADIR)/* vkapi.py
$(QUIET)$(RM) config/extDependency.stamp config/extDependency.pyc config/extDependency.sh config/extDependency.py
$(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)$(RMRF) $(PDFMATHDIR)

Expand Down Expand Up @@ -327,9 +331,10 @@ MANCOPYRIGHT = $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt
#
# Should pass in $(EXTOPTIONS) to determine which pages to generate.
# For now, all core and extension ref pages are extracted by genRef.py.
GENREF = $(SCRIPTS)/genRef.py
LOGFILE = man/logfile
man/apispec.txt: $(SPECFILES) genRef.py reflib.py vkapi.py
$(PYTHON) genRef.py -log $(LOGFILE) $(SPECFILES)
man/apispec.txt: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(SCRIPTS)/vkapi.py
$(PYTHON) $(GENREF) -log $(LOGFILE) $(SPECFILES)

# These targets are HTML5 ref pages
#
Expand Down Expand Up @@ -377,53 +382,8 @@ $(OUTDIR)/apispec.html: $(SPECVERSION) man/apispec.txt $(MANCOPYRIGHT) $(SVGFILE
$(QUIET)$(MKDIR) $(OUTDIR)
$(QUIET)$(ASCIIDOC) -b html5 -a html_spec_relative='html/vkspec.html' $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ man/apispec.txt

# Automated (though heuristic) checks of consistency in the spec and
# ref page sources.
# These are way out of date WRT current spec markup, and probably won't
# work properly.

# Validate includes in spec source vs. includes actually in the tree
# Generates file in $(CHECKDIR)
# $(NOTINSPEC) notInSpec.txt - include files only found in XML, not in spec
# Intermediate files removed after the run
# $(ACTUAL) - include files generated from vk.xml
# $(INSPEC) - include files referenced from the spec (not ref page) source
# Other files which could be generated but are basically useless
# include files only found in the spec source - comm -13 $(ACTUAL) $(INSPEC)
# include files both existing and referenced by the spec - comm -12 $(ACTUAL) $(INSPEC)
INCFILES = $(CHECKDIR)/incfiles
ACTUAL = $(CHECKDIR)/actual
INSPEC = $(CHECKDIR)/inspec
NOTINSPEC = $(CHECKDIR)/notInSpec.txt
checkinc:
$(QUIET)if test ! -d $(CHECKDIR) ; then $(MKDIR) $(CHECKDIR) ; fi
$(QUIET)find api validity hostsynctable -name '*.txt' | sort > $(ACTUAL)
$(QUIET)cat $(SPECFILES) | \
egrep '^include::\.\./' | tr -d '[]' | \
sed -e 's#^include::\.\./##g' | sort > $(INCFILES)
$(QUIET)echo "List of API include files repeatedly included in the API specification" > $(NOTINSPEC)
$(QUIET)echo "----------------------------------------------------------------------" >> $(NOTINSPEC)
$(QUIET)uniq -d $(INCFILES) >> $(NOTINSPEC)
$(QUIET)(echo ; echo "List of API include files not referenced in the API specification") >> $(NOTINSPEC)
$(QUIET)echo "-----------------------------------------------------------------" >> $(NOTINSPEC)
$(QUIET)comm -23 $(ACTUAL) $(INCFILES) >> $(NOTINSPEC)
$(QUIET)echo "Include files not found in the spec source are in $(CHECKDIR)/notInSpec.txt"
$(QUIET)$(RM) $(INCFILES) $(ACTUAL) $(INSPEC)

# Validate link tags in spec and ref page sources against vk.xml
# (represented in vkapi.py, which is autogenerated along with the
# headers and ref page includes).
# Generates files in $(CHECKDIR):
# specErrs.txt - errors & warnings in API spec
# manErrs.txt - errors & warnings in man pages
checklinks: man/apispec.txt generated
$(QUIET)if test ! -d $(CHECKDIR) ; then $(MKDIR) $(CHECKDIR) ; fi
$(QUIET)echo "Generating link checks for spec (specErrs.txt) and man pages (manErrs.txt)"
$(QUIET)$(PYTHON) checkLinks.py -follow $(SPECFILES) > $(CHECKDIR)/specErrs.txt
$(QUIET)$(PYTHON) checkLinks.py -follow man/[Vv][Kk]*.txt > $(CHECKDIR)/manErrs.txt

# Targets generated from the XML and registry processing scripts
# vkapi.py - Python encoding of the registry
# $(SCRIPTS)/vkapi.py - Python encoding of the registry
# 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
Expand All @@ -440,12 +400,12 @@ checklinks: man/apispec.txt generated

REGISTRY = xml
VKXML = $(REGISTRY)/vk.xml
GENVK = $(REGISTRY)/genvk.py
GENVK = $(SCRIPTS)/genvk.py
GENVKOPTS = $(VERSIONOPTIONS) $(EXTOPTIONS) $(GENVKEXTRA) -registry $(VKXML)
GENVKEXTRA =

vkapi.py: $(VKXML) $(GENVK)
$(PYTHON) $(GENVK) $(GENVKOPTS) -o . vkapi.py
$(SCRIPTS)/vkapi.py: $(VKXML) $(GENVK)
$(PYTHON) $(GENVK) $(GENVKOPTS) -o scripts vkapi.py

apiinc: api/timeMarker

Expand Down Expand Up @@ -475,15 +435,15 @@ $(METADIR)/timeMarker: $(VKXML) $(GENVK)
# 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 $(GENDEPENDS)
generated: $(SCRIPTS)/vkapi.py $(GENDEPENDS)

# 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
DEPSCRIPT = $(SCRIPTS)/extDependency.py
config/extDependency.stamp: $(VKXML) $(DEPSCRIPT)
$(QUIET)$(PYTHON) $(DEPSCRIPT) -registry $(VKXML) \
-outscript config/extDependency.sh \
Expand Down
33 changes: 11 additions & 22 deletions README.adoc
Expand Up @@ -8,21 +8,22 @@ This repository contains sources for the formal documentation of the Vulkan
API. This includes:

[options="compact"]
* the Vulkan API Specification
* specification of Vulkan Extensions
* the reference ("`man`") pages
* the XML API Registry (also mirrored at
* The Vulkan API Specification
* Specification of Vulkan extensions
* API reference ("`man`") pages
* The XML API Registry (also mirrored at
https://github.com/KhronosGroup/Vulkan-Headers)
* Vulkan header files (also mirrored at
https://github.com/KhronosGroup/Vulkan-Headers)
* related tools and scripts.
* Related tools and scripts.

The authoritative public repository is located at
https://github.com/KhronosGroup/Vulkan-Docs/.
It hosts public Issue tracker, and accepts patches (Pull Requests) from the
general public.
It hosts a public Issue tracker, and outside developers can file proposed
patches (Pull Requests) against the Specification, subject to approval
by Khronos.

If in doubt where to submit your Issue consult the
If in doubt where to submit your Issue, consult the
https://github.com/KhronosGroup/Vulkan-Ecosystem repo.


Expand All @@ -32,14 +33,6 @@ Everything is now maintained in the `master` branch of the repository.
From this branch it is possible to generate both Vulkan 1.1 and Vulkan 1.0
Specifications, as well as specifications for any set of Extensions.

[NOTE]
====
Old revisions of the repository maintained the Vulkan 1.0 Specification in
the `1.0` branch, and extensions in the `1.0-VK_EXTENSION_NAME`.
These branches are now **obsolete**, and contain only very old versions of
the Specification (and extensions).
====


== Directory Structure

Expand All @@ -59,16 +52,12 @@ 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/ Related scripts (but many scripts are still in the root or xml/ directory)
src/ext_loader/ Extension loader library (deprecated)
scripts/ Helper scripts used in specification, header, and reference page generation
style/ Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
xml/ XML API Registry (vk.xml) and related scripts
xml/ XML API Registry (vk.xml)
registry.txt Sources for documentation of the vk.xml format
```

This structure was adopted following 1.1.70 spec update.
There may be additional cleanup and simplification in the future.


== Building the Specification and Reference Pages

Expand Down
62 changes: 62 additions & 0 deletions appendices/VK_AMD_display_native_hdr.txt
@@ -0,0 +1,62 @@
include::meta/VK_AMD_display_native_hdr.txt[]

*Last Modified Date*::
2018-12-18
*IP Status*::
No known IP claims.
*Contributors*::
- Matthaeus G. Chajdas, AMD
- Aaron Hagan, AMD
- Aric Cyr, AMD
- Timothy Lottes, AMD
- Derrick Owens, AMD
- Daniel Rakos, AMD

This extension introduces the following display native HDR features to
Vulkan:

* A new elink:VkColorSpaceKHR enum for setting the native display
colorspace.
For example, this color space would be set by the swapchain to use the
native color space in Freesync2 displays.

* Local dimming control

=== New Object Types

None.

=== New Enum Constants

* Extending elink:VkStructureType:
** ename:VK_STRUCTURE_TYPE_DISPLAY_NATIVE_HDR_SURFACE_CAPABILITIES_AMD
** ename:VK_STRUCTURE_TYPE_SWAPCHAIN_DISPLAY_NATIVE_HDR_CREATE_INFO_AMD

* Extending elink:VkColorSpaceKHR:
** ename:VK_COLOR_SPACE_DISPLAY_NATIVE_AMD

=== New Enums

None.

=== New Structures

* slink:VkDisplayNativeHdrSurfaceCapabilitiesAMD
* slink:VkSwapchainDisplayNativeHdrCreateInfoAMD

=== New Functions

* flink:vkSetLocalDimmingAMD

=== Issues

None.

=== Examples

None.

=== Version History

* Revision 1, 2018-12-18 (Daniel Rakos)
- Initial revision

0 comments on commit 476e3f4

Please sign in to comment.