mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-19 09:47:19 +00:00
eb9997129d
* Bump API patch number and header version number to 18 for this
update.
Github Issues:
* Added "queue operation" terminology, and modified spec to actually
use this terminology (public issue 155). The act of submitting a
piece of work to a queue now generates "operations" for the queue to
execute, including operations to wait on/signal semaphores and
fences. Synchronization waits on these operations, making execution
dependency chains more obvious for semaphores and fences (though
additional work is still needed here). These changes include:
** Overview of "queue submission" commands in chapter
<<devsandqueues-submission>>.
** Updated descriptions for fence and semaphore waits and signals in
the synchronization chapter <<synchronization-semaphores-waiting>>,
<<synchronization-semaphores-signaling>> and
<<synchronization-fences-waiting>>.
** Clarifications to semaphore and fence operation within queue
submission functions.
** New glossary terms.
** Moved device idle and queue wait idle to synchronization chapter in
order to describe them in terms of other synchronization
primitives.
** Clarifications to semaphore and fence operation allowed removal of
the "implicit ordering guarantees" section, as this information is
now wholly covered where these primitives are described.
*** The "host writes" section of this is still there for now - in its
own section. This could probably be merged into other sections
later.
*** Modified fundamentals chapter on queue ordering to make sense in
context of the new changes, and avoid duplication.
<<fundamentals-queueoperation>>
* Added "aspect" and "component" definitions to the glossary, and made
sure these terms are referenced correctly (public issue 163).
* Update valid usage for ftext:vkGet*ProcAddr to only include
conditions that must be met to get a valid result. In particular,
it's okay to call flink:vkGetDeviceProcAddr with any string and will
get a code:NULL if that string is not a core Vulkan function or an
enabled extension function (addresses but does not fully close
public issue 214).
* Change the WSI extension dependencies to refer to version 1.0 of the
Vulkan API, instead of the pre-1.0-release internal revisions
numbers (public issue 238).
* Specified that <<interfaces-fragmentoutput,undeclared fragment
shader outputs>> result in undefined values input to the blending
unit or color attachment (public issue 240).
Internal Issues:
* Better documented that the registry XML "optional" tag for values
only applies when that value is the size of an array (internal issue
335).
* Add a stronger definition for the valid usages of
VkSpecializationMapEntry.size in the
<<pipelines-specialization-constants,Specialization Constants>>
section (internal issue 345).
* Change code:OpName to code:OpDecorate (along with appropriate
syntax) for vertex shader built-ins (internal issue 368).
* Add missing ref pages (those which are not currently stubs) to
apispec.txt for the single-page version of the ref pages (internal
issue 378).
Other Commits:
* Fix example in the <<descriptorsets,Descriptor Sets>> section to use
M, N, and I, describing set, binding, and index, consistently
throughout the example code.
292 lines
11 KiB
Makefile
292 lines
11 KiB
Makefile
# Copyright (c) 2014-2016 The Khronos Group Inc.
|
|
# Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
# Vulkan Specification makefile
|
|
#
|
|
# Default targets:
|
|
# - XHTML, XHTML chunked, and PDF specs ('allspecs')
|
|
# - HTML single-document reference pages ('manhtml' and 'manpdf')
|
|
# - HTML and nroff separate reference pages ('manpages' and 'manhtmlpages')
|
|
# - Validator scripts ('allchecks')
|
|
#
|
|
# 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.
|
|
|
|
all: alldocs allchecks
|
|
|
|
alldocs: allspecs allman
|
|
|
|
allspecs: xhtml chunked pdf
|
|
|
|
allman: manhtml manpdf manpages manhtmlpages
|
|
|
|
allchecks: checkinc checklinks
|
|
|
|
# Note that the := assignments below are immediate, not deferred, and
|
|
# are therefore order-dependent in the Makefile
|
|
|
|
QUIET?=@
|
|
ASCIIDOC ?= asciidoc.py
|
|
A2X ?= a2x.py
|
|
DBLATEX ?= dblatex
|
|
# DBLATEXPREFIX can be overriden by setting it as an environment variable,
|
|
# if not installed in the standard location on your distribution
|
|
DBLATEXPREFIX ?= /etc/asciidoc/dblatex
|
|
RM=rm -f
|
|
RMRF=rm -rf
|
|
MKDIR=mkdir -p
|
|
CP=cp
|
|
ECHO:=echo
|
|
# Target directories for output files
|
|
# HTMLDIR - 'html' target
|
|
# XHTMLDIR - 'xhtml' target
|
|
# PDFDIR - 'pdf' target
|
|
# CHECKDIR - 'allchecks' target
|
|
OUTDIR := ../../../out/1.0
|
|
HTMLDIR := $(OUTDIR)/html
|
|
XHTMLDIR := $(OUTDIR)/xhtml
|
|
PDFDIR := $(OUTDIR)/pdf
|
|
CHECKDIR := $(OUTDIR)/checks
|
|
# Images used in the API spec
|
|
IMAGEPATH :=images
|
|
ICONPATH :=$(IMAGEPATH)/icons
|
|
PDFXSL :=config/vkspec-dblatex.xsl
|
|
PDFSTY :=config/vkspec-dblatex.sty
|
|
PYTHON ?= python3
|
|
|
|
# Set VERBOSE to -v to see what asciidoc is doing.
|
|
# Set KEEP to -d to retain intermediate dblatex files
|
|
VERBOSE =
|
|
KEEP =
|
|
|
|
# asciidoc / a2x 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
|
|
# VKCONF contains Vulkan-specific Asciidoc macros
|
|
# ADOCOPTS options for asciidoc->HTML output
|
|
# ADOCPDFOPTS options for asciidoc->PDF output via dblatex (not using a2x)
|
|
# A2XOPTS options for a2x->{HTML,PDF} output
|
|
XMLLINT = --no-xmllint
|
|
NOTEOPTS = -a editing-notes -a implementation-guide
|
|
ATTRIBOPTS = -a apirevision="$(SPECREVISION)" -a mathjax
|
|
VKCONF = config/vkspec.conf
|
|
ADOCOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-asciidoc.conf \
|
|
-f $(VKCONF) $(VERBOSE)
|
|
ADOCPDFOPTS= $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-docbook.conf \
|
|
-f $(VKCONF) $(VERBOSE)
|
|
A2XOPTS = $(ATTRIBOPTS) $(NOTEOPTS) \
|
|
--asciidoc-opts="-f config/mathjax-docbook.conf -f $(VKCONF)" \
|
|
--xsltproc-opts="--param generate.consistent.ids 1" \
|
|
$(XMLLINT) $(VERBOSE) --icons
|
|
|
|
# XSL customizing Asciibook XSL to pass through equations and add
|
|
# MathJax. This varies depending on target type.
|
|
XHTMLXSL = config/docbook-xsl/xhtml.xsl
|
|
CHUNKEDXSL = config/docbook-xsl/chunked.xsl
|
|
|
|
# dblatex options passed two ways, directly to dblatex and via a2x.
|
|
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)
|
|
|
|
.PHONY: directories
|
|
|
|
ICONFILES := \
|
|
$(ICONPATH)/caution.png \
|
|
$(ICONPATH)/example.png \
|
|
$(ICONPATH)/home.png \
|
|
$(ICONPATH)/important.png \
|
|
$(ICONPATH)/next.png \
|
|
$(ICONPATH)/note.png \
|
|
$(ICONPATH)/prev.png \
|
|
$(ICONPATH)/tip.png \
|
|
$(ICONPATH)/up.png \
|
|
$(ICONPATH)/warning.png
|
|
PNGFILES := $(ICONFILES) $(wildcard $(IMAGEPATH)/*.png)
|
|
# This is a horrible hack to avoid pulling in vulkantexture0.svg
|
|
SVGFILES := $(wildcard $(IMAGEPATH)/[A-Za-uw-z]*.svg)
|
|
PDFFILES := $(SVGFILES:.svg=.pdf)
|
|
# Some random directories and files that need to be copied into spec
|
|
# output directory
|
|
WEBIMAGES := $(SVGFILES:%=$(HTMLDIR)/%) $(PNGFILES:%=$(HTMLDIR)/%)
|
|
# File suffix for image targets for HTML and PDF Builds - Asciidoc {svgtype} attribute
|
|
SVGTYPEHTML := svg
|
|
SVGTYPEPDF := pdf
|
|
# Main (root) asciidoc spec source file
|
|
TOPDOC := vkspec.txt
|
|
# Included chapters of the API spec
|
|
CHAPTERS := $(wildcard chapters/[A-Za-z]*.txt appendices/[A-Za-z]*.txt)
|
|
INCLUDES := $(wildcard protos/*.txt structs/*.txt flags/*.txt enums/*.txt funcpointers/*.txt validity/structs/*.txt validity/protos/*.txt)
|
|
# All non-format-specific dependencies
|
|
COMMONDOCS := $(CHAPTERS) $(INCLUDES)
|
|
# A generated included file with the spec version, date, and git commit
|
|
SPECVERSION = specversion.txt
|
|
SPECREVISION = 1.0.18
|
|
SPECREMARK =
|
|
|
|
# Spec targets
|
|
# There is some complexity to try and avoid short virtual targets like 'html'
|
|
# causing specs to *always* be regenerated.
|
|
|
|
html: $(HTMLDIR)/vkspec.html $(TOPDOC) $(COMMONDOCS) $(WEBIMAGES)
|
|
|
|
$(HTMLDIR)/vkspec.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) $(WEBIMAGES)
|
|
$(QUIET)if test ! -d $(HTMLDIR) ; then $(MKDIR) $(HTMLDIR) ; fi
|
|
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) -o $(HTMLDIR)/vkspec.html -a svgpdf=$(SVGTYPEHTML) $(TOPDOC)
|
|
|
|
xhtml: $(XHTMLDIR)/vkspec.html $(TOPDOC) $(COMMONDOCS)
|
|
|
|
$(XHTMLDIR)/vkspec.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
|
|
$(QUIET)if test ! -d $(XHTMLDIR) ; then $(MKDIR) $(XHTMLDIR) ; fi
|
|
$(QUIET)$(A2X) $(A2XOPTS) -f xhtml $(TOPDOC) \
|
|
--xsl-file=$(XHTMLXSL) \
|
|
-a toc2 -a toclevels=2 --destination-dir=$(XHTMLDIR) \
|
|
-a svgpdf=$(SVGTYPEHTML)
|
|
|
|
chunked: $(OUTDIR)/vkspec.chunked/index.html $(TOPDOC) $(COMMONDOCS)
|
|
|
|
$(OUTDIR)/vkspec.chunked/index.html: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS)
|
|
$(QUIET)if test ! -d $(OUTDIR)/chunked ; then $(MKDIR) $(OUTDIR) ; fi
|
|
$(QUIET)$(A2X) $(A2XOPTS) -f chunked $(TOPDOC) \
|
|
--xsl-file=$(CHUNKEDXSL) \
|
|
-a toc2 -a toclevels=2 --destination-dir=$(OUTDIR) \
|
|
-a svgpdf=$(SVGTYPEHTML)
|
|
|
|
pdf: $(PDFDIR)/vkspec.pdf
|
|
|
|
$(PDFDIR)/vkspec.pdf: $(PDFXSL) $(PDFSTY) $(PDFDIR)/vkspec.xml
|
|
$(QUIET)$(DBLATEX) -b pdftex $(DBLATEXOPTS) \
|
|
-p "$(DBLATEXPREFIX)/asciidoc-dblatex.xsl" \
|
|
-p $(PDFXSL) -s $(PDFSTY) \
|
|
$(PDFDIR)/vkspec.xml -O $(PDFDIR)
|
|
|
|
$(PDFDIR)/vkspec.xml: $(VKCONF) $(SPECVERSION) $(TOPDOC) $(COMMONDOCS) $(PDFDIR) $(PDFFILES)
|
|
$(QUIET)$(ASCIIDOC) --backend docbook $(ADOCPDFOPTS) \
|
|
-a a2x-format=pdf -a svgpdf=pdf \
|
|
--out-file $(PDFDIR)/vkspec.xml $(TOPDOC)
|
|
|
|
$(PDFDIR):
|
|
$(QUIET)if test ! -d $(PDFDIR) ; then $(MKDIR) $(PDFDIR) ; fi
|
|
|
|
# Generate Asciidoc attributes for spec version / date
|
|
GITHEAD := ../../../.git/logs/HEAD
|
|
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" >> $@
|
|
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,
|
|
# but that's likely to lead to merge conflicts. Just regenerate
|
|
# when pushing a new spec for review to the sandbox.
|
|
# The dependency on HEAD is per the suggestion in
|
|
# http://neugierig.org/software/blog/2014/11/binary-revisions.html
|
|
$(SPECVERSION): $(GITHEAD)
|
|
$(QUIET)echo ":revnumber: $(SPECREVISION)" > $@
|
|
$(QUIET)echo ":revdate: " `date` >> $@
|
|
$(QUIET)echo ":revremark: $(SPECREMARK) from git branch:" \
|
|
`git symbolic-ref --short HEAD` \
|
|
"commit:" `git log -1 --format="%H"` >> $@
|
|
endif
|
|
|
|
styleguide: $(OUTDIR)/styleguide.html
|
|
|
|
STYLESRC = style/styleguide.txt
|
|
$(OUTDIR)/styleguide.html: $(VKCONF) $(SPECVERSION) $(STYLESRC)
|
|
$(QUIET)$(ASCIIDOC) -b html5 $(ADOCOPTS) \
|
|
-o $(OUTDIR)/styleguide.html -a svgpdf=$(SVGTYPEHTML) \
|
|
$(STYLESRC)
|
|
|
|
clean: clean_html clean_pdf clean_chunked clean_checks clean_dirt
|
|
|
|
clean_html:
|
|
$(QUIET)$(RMRF) $(HTMLDIR) $(XHTMLDIR)
|
|
$(QUIET)$(RM) $(OUTDIR)/apispec.html
|
|
|
|
clean_pdf:
|
|
$(QUIET)$(RM) $(PDFDIR)/vkspec.pdf $(PDFDIR)/vkspec.xml $(OUTDIR)/apispec.pdf
|
|
|
|
clean_chunked:
|
|
$(QUIET)$(RMRF) $(OUTDIR)/vkspec.chunked
|
|
|
|
clean_checks:
|
|
$(QUIET)$(RMRF) $(CHECKDIR)
|
|
|
|
clean_dirt:
|
|
$(QUIET)$(RM) $(DIRT)
|
|
|
|
# Man page targets for individual pages
|
|
MANDIR:=man
|
|
-include man/manpages.mak
|
|
|
|
# Man page targets for HTML and PDF single-file documents
|
|
|
|
manpdf: $(OUTDIR)/apispec.pdf
|
|
|
|
manhtml: $(OUTDIR)/apispec.html
|
|
|
|
$(OUTDIR)/apispec.pdf: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(PDFXSL)
|
|
$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
|
|
$(QUIET)$(A2X) -f pdf $(A2XDBLATEXOPTS) $(A2XOPTS) --icons man/apispec.txt --destination-dir=$(OUTDIR)
|
|
|
|
$(OUTDIR)/apispec.html: $(CONFFILE) man/apispec.txt $(MANSOURCES) $(SVGFILES)
|
|
$(QUIET)if test ! -d $(OUTDIR) ; then $(MKDIR) $(OUTDIR) ; fi
|
|
$(QUIET)$(ASCIIDOC) $(ADOCOPTS) -d book -b html --out-file=$(OUTDIR)/apispec.html man/apispec.txt
|
|
|
|
$(HTMLDIR)/images/%: images/%
|
|
$(QUIET)$(MKDIR) $(@D)
|
|
$(QUIET)$(CP) $< $@
|
|
|
|
# Automated (though heuristic) checks of consistency in the spec and
|
|
# ref page sources
|
|
|
|
# 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)ls $(INCLUDES) | sort > $(ACTUAL)
|
|
$(QUIET)cat $(CHAPTERS) | \
|
|
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:
|
|
$(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 man/[Vv][Kk]*.txt > $(CHECKDIR)/manErrs.txt
|
|
$(QUIET)$(PYTHON) checkLinks.py -follow $(CHAPTERS) > $(CHECKDIR)/specErrs.txt
|
|
|
|
# README file with build instructions
|
|
README.html: README.txt
|
|
$(ASCIIDOC) -b html5 README.txt
|