Skip to content
Permalink
Browse files

Change log for August 26, 2016 Vulkan 1.0.25 spec update:

  * Bump API patch number and header version number to 25 for this update.
  * Structurally change the specification so that multiple extensions are
    included in the +1.0+ git branch, and specifications will include or not
    include those extensions at build time based on options passed to the
    Makefile. See +doc/specs/vulkan/README.html+ and the ``Layers and
    Extensions'' section of the ``Vulkan Documentation and Extensions''
    document for more information on this change.
  * Register and publish new extensions in the single-branch form:
  ** +VK_NV_external_memory_capabilities+
  ** +VK_NV_external_memory+
  ** +VK_NV_external_memory_win32+
  ** +VK_NV_win32_keyed_mutex+

Github Issues:

  * Clarify description of GetInstanceProcAddr and GetDeviceProcAddr (public
    issue 212).
  * Add SPIR-V <<textures-operation-validation, instruction validation>> for
    single-sampled images (public issue 316).
  * Fix spelling of ``tesselation'' in a few places and note it as an
    exception to the American spelling rules convention (public issue
    327).
  * Fix Makefile to create output directory for ``styleguide''
    target (public issue 329).
  * Fix numerous minor issues with incorrectly tags on enumerant names and
    table titles (public issue 330).
  * Generate specversion.txt date in UTC time and RFC 2822 format
    (public issue 335).
  * Convert link to the SPIR-V Specification for
    flink:VkShaderModuleCreateInfo into an internal link to the normative
    reference (public issue 336).
  * Add ename:VK_ERROR_OUT_OF_MEMORY error code to
    flink:vkCreateDebugReportCallbackEXT (public issue 337).

Internal Issues:

  * Update style guide regarding use of code:NULL and dname:VK_NULL_HANDLE
    (internal issue 393).
  * Change the definition of latexmath:[$q$] in the
    <<textures-image-level-selection,texture image level selection>> section
    to be the index of the maximum defined level for the view, not the
    number of levels in the view (internal issue 406).
  * Allow developers to override dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE
    with their own binary-compatible definition (internal issue 439).
  * Fix +vk_platform.h+ conditional logic causing compile failure with some
    Android compilers (internal issue 441).
  * Implement the single-branch model as described above (internal issue
    461).

Other Issues:
  • Loading branch information...
oddhack committed Aug 28, 2016
1 parent 2dd2b35 commit 85184f305afe0f2e9e99cc9525e8ce25c32e74e0
Showing 793 changed files with 9,129 additions and 15,759 deletions.
@@ -32,6 +32,7 @@

# Python cache
__pycache__
.pyc

# Spec build temporary files and outputs
out/1.0*
@@ -1176,3 +1176,58 @@ Internal Issues:
* Clarify that command buffers and descriptor sets are allocated
rather than created. Also clarify when the recording state of a
command buffer is relevant (internal issue 434).

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

Change log for August 26, 2016 Vulkan 1.0.25 spec update:

* Bump API patch number and header version number to 25 for this update.
* Structurally change the specification so that multiple extensions are
included in the +1.0+ git branch, and specifications will include or not
include those extensions at build time based on options passed to the
Makefile. See +doc/specs/vulkan/README.html+ and the ``Layers and
Extensions'' section of the ``Vulkan Documentation and Extensions''
document for more information on this change.
* Register and publish new extensions in the single-branch form:
** +VK_NV_external_memory_capabilities+
** +VK_NV_external_memory+
** +VK_NV_external_memory_win32+
** +VK_NV_win32_keyed_mutex+

Github Issues:

* Clarify description of GetInstanceProcAddr and GetDeviceProcAddr (public
issue 212).
* Add SPIR-V <<textures-operation-validation, instruction validation>> for
single-sampled images (public issue 316).
* Fix spelling of ``tesselation'' in a few places and note it as an
exception to the American spelling rules convention (public issue
327).
* Fix Makefile to create output directory for ``styleguide''
target (public issue 329).
* Fix numerous minor issues with incorrectly tags on enumerant names and
table titles (public issue 330).
* Generate specversion.txt date in UTC time and RFC 2822 format
(public issue 335).
* Convert link to the SPIR-V Specification for
flink:VkShaderModuleCreateInfo into an internal link to the normative
reference (public issue 336).
* Add ename:VK_ERROR_OUT_OF_MEMORY error code to
flink:vkCreateDebugReportCallbackEXT (public issue 337).

Internal Issues:

* Update style guide regarding use of code:NULL and dname:VK_NULL_HANDLE
(internal issue 393).
* Change the definition of latexmath:[$q$] in the
<<textures-image-level-selection,texture image level selection>> section
to be the index of the maximum defined level for the view, not the
number of levels in the view (internal issue 406).
* Allow developers to override dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE
with their own binary-compatible definition (internal issue 439).
* Fix +vk_platform.h+ conditional logic causing compile failure with some
Android compilers (internal issue 441).
* Implement the single-branch model as described above (internal issue
461).

Other Issues:
@@ -5,6 +5,21 @@ This repository contains formal documentation of the Vulkan API. This
includes the main API Specification, the reference (man) pages, the XML API
Registry, and related tools and scripts.

Single-Branch Model
-------------------

As of the 1.0.25 release, we have switch to a new 'single-branch' model in
which all extensions are included in the source of the 1.0 branch of the
Specification, and can be configured in or out of the build using Makefile
options.

The single-branch model seems to be working for all the spec builds,
although there are probably a few issues we haven't caught yet. The ref page
build needs some additional work, as genRef.py is creating reference pages
for all interfaces, not just those for the API and extensions being built,
and we'll get to that within a week or two. The validation scripts also need
to be tweaked further for the single-branch model.

Repository Structure
--------------------

@@ -17,12 +32,7 @@ doc/specs/ Main documentation tree
chapters/ Chapters - one file each
config/ asciidoc configuration
images/ Images (figures, diagrams, icons)
man/ Reference (manual) pages for API
enums/ Includeable snippets for enumerations from vk.xml
flags/ Includeable snippets for flags from vk.xml
protos/ Includeable snippets for prototypes from vk.xml
structs/ Includeable snippets for structures from vk.xml
validity/ Includeable validity language from vk.xml
man/ Reference (manual) pages for API, mostly extracted from the spec source
misc/ Related specifications (GL_KHR_vulkan_glsl)
src/spec/ XML API Registry (vk.xml) and related scripts
src/vulkan/ Vulkan headers, generated from the Registry
@@ -58,9 +68,9 @@ There are several make targets in doc/specs/vulkan :
The outputs will be written to $(OUTDIR), which defaults to out/ at the root
of the checked-out git repository.

To build PDF outputs (make pdf, make manpdf), you need a2x (part of the
asciidoc) package, dblatex and a LaTeX processor. The PDF builds are
currently configured to use a2x to go from asciidoc markdown to docbook, and
To build PDF outputs (make pdf, make manpdf), you need
dblatex and a LaTeX processor. The PDF builds are
currently configured to use asciidoc to go from asciidoc markdown to docbook, and
then run the result through dblatex to go from there to LaTeX and then
through your LaTeX processor to PDF.

@@ -100,9 +110,11 @@ Generating Headers and Related Files

The header file (src/vulkan/vulkan.h) and many parts of the specification
and reference page documents are generated from descriptions in the XML API
Registry (src/spec/vk.xml). All the generated files are checked into the
repository, and should not be modified directly. If you change vk.xml,
you can regenerated these files by going to src/spec and running:
Registry (src/spec/vk.xml). The generated files, with the exception
of vulkan.h, are not checked into the repository. If you change vk.xml, you
can regenerate the header by going to src/spec and running:

* make clobber install

* make clobber (get rid of all old generated files)
* make full_install (regenerate all the files)
The other generated files are built as required via dependencies in
doc/specs/vulkan/Makefile .
@@ -3,24 +3,42 @@

# Vulkan Specification makefile
#
# Default targets:
# - XHTML, XHTML chunked, and PDF specs ('allspecs')
# - HTML single-document reference pages ('manhtml' and 'manpdf')
# - HTML separate reference pages ('manpages' and 'manhtmlpages')
# - Validator scripts ('allchecks')
# To build the specification and reference pages with optional
# extensions included, set the $(EXTENSIONS) variable on the make
# command line to a space-separated list of extension names. The
# VK_KHR_sampler_mirror_clamp_to_edge extension which is a required part
# of Vulkan 1.0, is always included. $(EXTENSIONS) is converted into
# asciidoc and generator script arguments $(EXTATTRIBS) and
# $(EXTOPTIONS).

EXTS := $(sort VK_KHR_sampler_mirror_clamp_to_edge $(EXTENSIONS))
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,
# normally used when building with extensions included.
APITITLE =

# The default 'all' target builds the following sub-targets:
# xhtml - XHTML single-page API specification
# pdf - PDF single-page API specification
# styleguide - HTML single-page "Documentation and Extensions" guide
# manhtml - XHTML single-page reference guide
# manpdf - PDF reference guide
# manhtmlpages - XHTML separate per-feature reference pages
# checkinc - validator script for asciidoc include files
# checklinks - validator script for asciidoc xrefs
#
# The 'html' target is deprecated but still supported, for now. It uses
# a different toolchain than XHTML/PDF outputs, isn't quite compatible,
# and will not be published, but is faster to generate for quick tests.
#
# Other targets:
# - Nroff (Unix 'man' format) separate reference pages ('manpages').
# The following targets are supported, but not invoked by default:
# html - HTML5 single-page API specification
# chunked - XHTML chunked (page per section) API specification
# manpages - nroff Unix 'man' format separate per-feature reference pages

all: alldocs allchecks

alldocs: allspecs allman

allspecs: xhtml chunked pdf styleguide
allspecs: xhtml pdf styleguide

allman: manhtml manpdf manhtmlpages

@@ -32,7 +50,6 @@ allchecks: checkinc checklinks
QUIET ?= @
PYTHON ?= python3
ASCIIDOC ?= asciidoc.py
A2X ?= a2x.py
DBLATEX ?= dblatex
XSLTPROC ?= xsltproc
# DBLATEXPREFIX can be overriden by setting it as an environment variable,
@@ -68,28 +85,27 @@ PDFSTY :=config/vkspec-dblatex.sty
VERBOSE =
KEEP =

# asciidoc / a2x attributes to set.
# asciidoc attributes to set.
# XMLLINT normally unset - to detect problems with intermediate files
# NOTEOPTS sets options controlling which NOTEs are generated
# ATTRIBOPTS sets the api revision and enables MathJax generation
# EXTATTRIBS sets attributes for enabled extensions (set above based on
# $(EXTENSIONS))
# CONFIG Vulkan-specific Asciidoc macros. File used depends on target.
# ADOCOPTS options for asciidoc->HTML output
# ADOCDBOPTS options for asciidoc->XHTML or PDF output via docbook (not using a2x)
# A2XOPTS options for a2x->{HTML,PDF} output
# ADOCDBOPTS options for asciidoc->XHTML or PDF output via docbook
XMLLINT = --no-xmllint
NOTEOPTS = -a editing-notes -a implementation-guide
ATTRIBOPTS = -a apirevision="$(SPECREVISION)" -a mathjax
ATTRIBOPTS = -a apirevision="$(SPECREVISION)" \
-a apititle="$(APITITLE)" \
-a mathjax $(EXTATTRIBS)
CONFIG = config/vkspec.conf
ADOCOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-asciidoc.conf \
-f $(CONFIG) $(VERBOSE)
ADOCDBOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-docbook.conf \
-f $(CONFIG) $(VERBOSE)
A2XOPTS = $(ATTRIBOPTS) $(NOTEOPTS) \
--asciidoc-opts="-f config/mathjax-docbook.conf -f $(CONFIG)" \
--xsltproc-opts="--param generate.consistent.ids 1" \
$(XMLLINT) $(VERBOSE) --icons

# All the options except the first are taken from a2x
# All the options except the first are taken from a2x defaults
XSLTOPTS = \
--param generate.consistent.ids 1 \
--stringparam callout.graphics 1 \
@@ -103,9 +119,8 @@ XHTMLXSL = config/docbook-xsl/xhtml.xsl
CHUNKXSL = config/docbook-xsl/chunked.xsl
MANPAGEXSL = config/docbook-xsl/manpage.xsl

# dblatex options passed two ways, directly to dblatex and via a2x.
# dblatex options, passed directly to dblatex
DBLATEXOPTS := $(KEEP) -V -T db2latex -I. -I images -I images/icons -s $(DBLATEXPREFIX)/asciidoc-dblatex.sty
A2XDBLATEXOPTS := --dblatex-opts='$(DBLATEXOPTS)'

# Misc. files to clean up (see 'checkinc' target below)
DIRT = $(SPECVERSION)
@@ -123,18 +138,18 @@ PDFFILES := $(SVGFILES:.svg=.pdf)
# File suffix for image targets for HTML and PDF Builds - Asciidoc {svgtype} attribute
SVGTYPEHTML := svg
SVGTYPEPDF := pdf
# Main (root) asciidoc spec source file
# Top-level spec source file
TOPDOC := vkspec.txt
# Files making up sections of the API spec. The wildcard expression
# should work in extension branches to pull in those files as well.
CHAPTERS := $(wildcard chapters/[A-Za-z]*.txt appendices/[A-Za-z]*.txt chapters/*/[A-Za-z]*.txt appendices/*/[A-Za-z]*.txt)
CHAPTERS = $(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
# All non-format-specific dependencies
COMMONDOCS = $(CHAPTERS) $(GENINCLUDE) $(GENDEPENDS)
# A generated included file with the spec version, date, and git commit
# A generated included file containing the spec version, date, and git commit
SPECVERSION = specversion.txt
SPECREVISION = 1.0.24
SPECREVISION = 1.0.25
SPECREMARK =

# Spec targets
@@ -197,12 +212,13 @@ $(PDFDIR)/vkspec.pdf: $(CONFIG) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) $(PDFFILE

# Generate Asciidoc attributes for spec version / date
GITHEAD := ../../../.git/logs/HEAD
DATE := `date -R -u`
ifeq ($(wildcard $(GITHEAD)),)
# If GITHEAD does not exist, don't include branch info.
$(SPECVERSION):
$(QUIET)echo ":revnumber: $(SPECREVISION)" > $@
$(QUIET)echo ":revdate: " `date` >> $@
$(QUIET)echo ":revremark: Git branch information not available" >> $@
$(QUIET)echo ":revdate: " $(DATE) >> $@
$(QUIET)echo ":revremark: $(SPECREMARK) Git branch information not available" >> $@
else
# Could use `git log -1 --format="%cd"` to get branch commit date
# This used to be a dependency in the spec html/chunked/pdf targets,
@@ -212,7 +228,7 @@ else
# http://neugierig.org/software/blog/2014/11/binary-revisions.html
$(SPECVERSION): $(GITHEAD)
$(QUIET)echo ":revnumber: $(SPECREVISION)" > $@
$(QUIET)echo ":revdate: " `date` >> $@
$(QUIET)echo ":revdate: " $(DATE) >> $@
$(QUIET)echo ":revremark: $(SPECREMARK) from git branch:" \
`git symbolic-ref --short HEAD` \
"commit:" `git log -1 --format="%H"` >> $@
@@ -224,6 +240,7 @@ STYLEFILES = $(wildcard style/[A-Za-z]*.txt)
styleguide: $(OUTDIR)/styleguide.html

$(OUTDIR)/styleguide.html: $(CONFIG) $(SPECVERSION) $(STYLESRC) $(STYLEFILES) $(GENINCLUDE) $(GENDEPENDS)
$(QUIET)$(MKDIR) $(OUTDIR)
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) \
-o $@ -a svgpdf=$(SVGTYPEHTML) \
$(STYLESRC)
@@ -379,16 +396,13 @@ checklinks: vkapi.py
# hostsynctable/timeMarker - proxy for host sync table include files under hostsynctable/*.txt
# validity/timeMarker - proxy for API validity include files under validity/*/*.txt
#
# EXTLIST specifies the extensions that will be included in these
# targets. This will differ in different extension branches, although
# all will include the VK_KHR_sampler_mirror_clamp_to_edge extension.
# Each extension should be specified as a separate -extension option.
# $(EXTOPTIONS) specifies the extensions which are included in these
# targets, and is set above based on $(EXTENSIONS).

EXTLIST = -extension VK_KHR_sampler_mirror_clamp_to_edge
REGISTRY = ../../../src/spec
VKXML = $(REGISTRY)/vk.xml
GENVK = $(REGISTRY)/genvk.py
GENVKOPTS= $(EXTLIST) -registry $(VKXML)
GENVKOPTS= $(EXTOPTIONS) -registry $(VKXML)

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

0 comments on commit 85184f3

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