status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-01-26 06:09:22 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/README.adoc
Jon Leech 1ca0ea1ef0 Change log for July 22, 2016 Vulkan 1.0.22 spec update: 
* Bump API patch number and header version number to 22 for this update.

Github Issues:

  * Translate the subpass self-dependency language into concrete
    validity statements, and added a validity statement about the
    restrictions on layout parameters (public issue 267).
  * Add validity requirement that
    slink:VkAttachmentDescription::pname:finalLayout and
    slink:VkAttachmentReference::pname:layout must not be
    ename:VK_IMAGE_LAYOUT_UNDEFINED or
    ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
  * Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
    layouts are used. Make language consistent with other attachment
    arrays (public issue 270).
  * Changed 64-bit definition for
    dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
    +vk.xml+ and the resulting +vulkan.h+ (public issue 282).
  * Add missing error return code for
    flink:vkEnumerateInstanceExtensionProperties and
    flink:vkEnumerateDeviceExtensionProperties (public issue 285)
  * Fix several cases of stext::VkStructName.memberName markup to
    stext::VkStructName::pname:memberName, to match other usage in the
    spec, and describe this markup in the style guide (public issue
    286).
  * Modified validity language generation script to avoid redundant
    common ancestor language if covered by generic parent language, and
    used `Both' instead of `Each' when appropriate (public issue 288).

Internal Issues:

  * Add language about behavior of flink:vkAllocateDescriptorSets when
    allocation fails due to fragmentation, a new error
    ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
    (internal issue 309).
  * For the features of code:PointSize, code:ClipDistance, and
    code:CullDistance, the SPIR-V capability is required to be declared
    on use (read or write) rather than on decoration (internal issue
    359).
  * Have desktop versions of GLSL respect precision qualification
    (code:mediump and code:lowp) when compiling for Vulkan. These will
    get translated to SPIR-V's code:RelaxedPrecision decoration as they
    do with OpenGL ES versions of GLSL (ESSL). The default precision of
    all types is code:highp when using a desktop version (internal issue
    360).
  * Add validity statement for slink:VkImageCreateInfo specifying that
    multisampled images must be two-dimensional, optimally tiled, and
    with a single mipmap level (internal issue 369).
  * Add validity statements to slink:VkImageViewCreateInfo disallowing
    creation of images or image views with no supported features. Made
    some slink:VkImageViewCreateInfo validity statements more precise
    and consistent. Added a Note to the <<features,features>> chapter
    about formats with no features (internal issue 371).
  * Remove +manpages+ from default build targets. Nroff outputs
    containing imbedded latexmath will not render properly. Fixing this
    is a lot of work for limited use cases (internal issue 401).

Other Commits:

  * Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
    statement to be based on attachment indices rather than the number
    of cleared attachments
    (Vulkan-LoaderAndValidationLayers/issues/601).
  * Convert registry documentation from LaTeX to asciidoc source and
    rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
  * Fix lack of Oxford commas in validity language.
  * Lots of cleanup of generator scripts and Makefiles to move extension
    list for generator into the script arguments instead of the body of
    genvk.py, and express better dependencies between XML, scripts, and
    generated files.
2016-07-23 03:15:48 -07:00

357 lines
13 KiB
Plaintext
Raw Blame History

= Vulkan Specification Build Instructions and Notes =
* <<intro,Introduction>>
* <<building,Building the spec>>
* <<macros,Our asciidoc macros>>
* <<refpages,Reference Pages>>
* <<styles,Our stylesheets>>
* <<equations,Imbedding equations>>
* <<anchors,Anchors and xrefs>>
* <<depends,Software dependencies>> (general and platform-specific)
* <<history,Revision history>>
[[intro]]
== Introduction ==
This README describes important stuff for getting the Vulkan API
specification and reference pages building properly.
[[building]]
== Building The Spec ==
Assuming you have all the right tools installed (see <<depends,Software
Dependencies>> below), go to
+...path-to-git-repo/vulkan/doc/specs/vulkan+ .
If the default values of ASCIIDOC and A2X are not correct for the
+asciidoc+ and +a2x+ scripts on your platform, change them via
environment variables, command line options, or by modifying the
+Makefile+. The default script names have +.py+ suffixes. These suffixes
should be removed for Linux platforms, and possibly for other
non-Windows environments.
$ make all
or equivalently:
$ make xhtml chunked pdf manhtml manpdf manhtmlpages checkinc checklinks
This will generate a variety of targets under +$(OUTDIR)+ (by default,
+../../../out/1.0+). The checked-in file +$(OUTDIR)/index.html+ links to
them all, or they can individually be found as follows:
* API spec:
** +xhtml+ - Single-file XHTML in +$(OUTDIR)/xhtml/vkspec.html+
** +chunked+ - Chunked HTML in +$(OUTDIR)/vkspec.chunked/index.html+
** +pdf+ - PDF in +$(OUTDIR)/pdf/vkspec.pdf+
* Reference pages:
** +manhtml+ - Single-file HTML in +$(OUTDIR)/apispec.html+
** +manpdf+ - Single-file PDF in +$(OUTDIR)/apispec.html+
** +manhtmlpages+ - File-per-entry-point HTML in +$(OUTDIR)/man/html/*+
* 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+
Once you have the basic build working, an appropriate parallelization
option to make, such as
$ make -j 8
will significantly speed up the reference page builds.
If your asciidoc installation does not put the stylesheets and xsl files in
the standard +/etc/asciidoc/dblatex+ directory, set the environment variable
+DBLATEXPREFIX+ to the path to that directory (the one containing the
+asciidoc-dblatex.xsl+ and +asciidoc-dblatex.sty+ files installed with
asciidoc).
The +manpages+ target is deprecated, as the resulting Unix man pages have
issues with content like embedded latexmath: constructs, but is still
available for third parties wishing to generate them:
* +manpages+ - File-per-entry-point nroff source in +$(OUTDIR)/man/3/*+
[[building-test]]
=== Alternate and Test Builds ===
If you are just testing asciidoc formatting, macros, stylesheets, etc.,
we suggest editing +vkspec.txt+ to comment out most of the chapter
includes.
In addition to the XHTML and PDF targets, there is also a single-file HTML5
target, +html+, which generates output directly from asciidoc without going
through Docbook. This is somewhat quicker to generate, but formatting and
section numbers aren't consistent with the other builds and it is not for
publication - just testing. The +html+ target will generate the file
+$(OUTDIR)/html/vkspec.html+ .
=== Rebuilding The Generated Images ===
There are some images in the +images/+ directory which are maintained in one
format but need to be converted to another format for corresponding types of
output. Most are SVG converted to PDF, some are PPT converted to PDF
converted to SVG. SVG and PDF forms are needed for the HTML and PDF output
formats, respectively.
These files are not automatically converted by the Makefile. Instead, all
output forms required are checked into +images/+ . On the rare occasions that
someone changes a source document and needs to regenerate the other forms:
cd images
make
[[macros]]
== Our Asciidoc Macros ==
We use a bunch of custom macros in the reference pages and API spec asciidoc
sources. The validator scripts rely on these macros as part of their sanity
checks, and you should use the macros whenever referring to an API command,
struct, token, or enum name, so the documents are semantically tagged and
more easily verifiable.
The supported macros are defined in +config/vkspec.conf+ (for the API spec)
and +config/manpages.conf+ (for the reference pages).
The tags used are described in the style guide (+styleguide.txt+).
We will eventually tool up the spec and ref pages to the point that anywhere
there's a type or token referred to, clicking on (or perhaps hovering over)
it in the HTML view and be taken to the definition of that type/token. That
will take some more plumbing work to tag the stuff in the autogenerated
include files, and do something sensible in the spec (e.g. resolve links to
internal references).
Most of these macros deeply need more intuitive names.
[[refpages]]
== Reference Pages ==
Prior to the 1.0.20 update of the API spec, the reference pages in +man/+
were handwritten, incomplete, and often way out of date with respect to the
spec.
Our initial effort to address this was to tag the API spec to help identify
boundaries of language talking about different commands, structures,
enumerants, and other types, then use a set of Python scripts to
automatically extract that language into the corresponding ref page. Pages
without corresponding content in the API spec are generated automatically,
when possible.
This has generated a semantically complete set of ref pages. Although they
are still far from ideal, they now fully document the API, and will stay in
sync with it. A significant drawback of this approach is that the only place
ref pages for extension interfaces can be generated is inside the
corresponding extension branches.
If for some reason you want to regenerate the ref pages from scratch
yourself, you can do so by
$ rm man/apispec.txt
$ make apispec.txt
The +genRef.py+ script will generate many warnings, but most are just
reminders that some pages are automatically generated. If everything is
working correctly, all the +man/*.txt+ files will be regenerated, but their
contents will not change.
[[styles]]
== Our stylesheets ==
NOTE: Section mostly TBD.
This branch introduces a Vulkan-specific XHTML CSS stylesheet in
+config/vkspec-xhtml.css+ . It started as a clone of the default
Asciidoc stylesheet, but added some new features. Similar CSS in
+config/vkman.css+ is used for the reference pages.
=== Marking Changes ===
There is the start of support for marking added, removed, and changed text
in the spec body. Currently this is supported *only* in the XHTML targets
(+xhtml+ and +chunked+), and *only* for paragraphs and spans of words.
Added, removed, and changed material is marked with the asciidoc *roles*
named _added_, _removed_, and _changed_ respectively. They can be used to
mark an entire paragraph, as follows:
[role="change"]
This paragraph shows change markings.
Or a few words in a sentence, as follows:
This sentence contains [added]#some added words# and [removed]#some
removed words#.
The formatting of these roles text depends on the stylesheet. Currently it
all three roles are red text, and the "removed" role is also strike-through
text.
We don't use this capability yet; it's just a proof of concept. It would
be a huge amount of work to insert this markup automatically for each
spec update, and it would be very difficult to do automatically based on
git diffs.
=== Marking Normative Language ===
There is support for marking normative language in the document. Currently
this is supported *only* in the XHTML targets (+xhtml+ and +chunked+).
Normative language is marked with the asciidoc *role* named _normative_.
It can be used to mark entire paragraphs or spans of words, in the
same fashion as change markings (described above). In addition, the
normative terminology macros, such as must: and may: and cannot:,
always use this role.
The formatting of normative language depends on the stylesheet. Currently it
just comes out in purple. We may add a way to disable this formatting at
build time.
[[equations]]
== Imbedding Equations
Equations should be written using the latexmath: inline and block macros.
The contents of the latexmath: blocks should be LaTeX math notation,
surrounded by appropriate delimiters - pass:[$$], +++\[\\]+++, pass:[\(\)],
or pass:[\begin{env}/\end{env}] math environments such as pass:[{equation*}]
or pass:[{align*}].
The asciidoc macros and configuration files, as well as the dblatex
customization layers, have been modified significantly so that LaTeX math is
passed through unmodified to all HTML output forms (using the MathJax engine
for real-time rendering of equations) and to dblatex for PDF output.
The following caveats apply:
* The special characters +<+ , +>+ , and +&+ can currently be used only in
+++[latexmath]+++ block macros, not in +++latexmath:[]+++ inline macros.
Instead use +\lt+ for +<+ and +\gt+ for +>+. +&+ is an alignment construct
for multiline equations, and should only appear in block macros anyway.
* AMSmath environments (e.g. pass:[\begin{equation*}], pass:[{align*}],
etc.) can be used, to the extent MathJax supports them.
* When using AMSmath environments, do *not* also surround the equation block
with +++\[\\]+++ brackets. That is not legal LaTeX math and will break the
PDF build. It is good practice to make sure all spec targets build
properly before proposing a merge to master.
* Arbitrary LaTeX constructs cannot be used with MathJax. It is an equation
renderer, not an full LaTeX engine. So imbedding stuff like \Large or
pass:[\hbox{\tt\small VK\_FOO}] does not work in any of the HTML backends
and should be avoided.
[[anchors]]
== Asciidoc Anchors And Xrefs
In the API spec, sections can have anchors (labels) applied with the
following syntax. In general the anchor should immediately precede the
chapter or section title and should use the form
'+++[[chapter-section-label]]+++'. For example,
For example, in chapter +synchronization.txt+:
++++
[[synchronization-primitives]]
Synchronization Primitives
++++
Cross-references to those anchors can then be generated with, for example,
++++
See the <<synchronization-primitives>> section for discussion
of fences, semaphores, and events.
++++
You can also add anchors on arbitrary paragraphs, using a similar naming
scheme.
Anything whose definition comes from one of the autogenerated API include
files (+.txt+ files in the directories +basetypes+, +enums+, +flags+,
+funcpointers+, +handles+, +protos+, and +structs+) has a corresponding
anchor whose name is the name of the function, struct, etc. being defined.
Therefore you can say something like:
Fences are used with the +++<<vkQueueSubmit>>+++ command...
[[depends]]
== Software Dependencies ==
This section describes the software components used by the Vulkan spec
toolchain. under the <<depends-general,General Dependencies>> below, then
describes specific considerations for Windows environments using Cygin under
<<depends-cygwin,Cygwin Dependencies>>
[[depends-general]]
=== General Dependencies ===
These are versions of required tools in one of the editors' development
environment (Debian 8, shown as Debian package names). Earlier versions
*may* work but unless they are verified by someone else, there's no way to
know that. Later versions should work.
- GNU make (make version: 4.0.8-1; older versions probably OK)
- Asciidoc / a2x (asciidoc version: 8.6.9-3)
- Python 3 (python, version: 3.4.2)
- Git command-line client (git, version: 2.1.4)
Only needed if regenerating specversion.txt. Any version supporting the
operations
-- +git symbolic-ref --short HEAD+ and
-- +git log -1 --format="%H"+ should work).
- Docbook LaTeX toolchain (dblatex, version: 0.3.5-2)
- Source code highlighter (source-highlight, version: 3.1.7-1+b1)
- LaTeX distribution (texlive, version: 2014.20141024-2)
[[depends-cygin]]
=== Cygwin Dependencies ===
The cygwin installer is at http://www.cygwin.org. Use the 64-bit version,
because the 32-bit version does not include the latest version of asciidoc
required for this project.
Required Cygwin packages (current version):
* Devel/make (4.1-1)
* Python/python (2.7.10-1) - Needed for asciidoc toolchain
* Python/python3 (3.4.3-1)
* Python/python3-lxml (3.4.4-1) - Needed for generating vulkan.h
* Text/asciidoc (8.6.8-1)
* Text/dblatex (0.3.4-1)
* Text/source-highlight (3.1.8-1)
Optional Cygwin packages (current version):
* Devel/gcc-core (4.9.3-1) - Needed for validating generated headers
* Devel/gcc-g++ (4.9.3-1) - Needed for validating generated headers
* Devel/git (2.5.1-1) - Needed for updating specversion.txt
[[history]]
== Revision History
* 2016/07/10 - Update for current state of spec and ref page generation.
* 2015/11/11 - Add new can: etc. macros and DBLATEXPREFIX variable.
* 2015/09/21 - Convert document to asciidoc and rename to README.md
in the hope the gitlab browser will render it in some fashion.
* 2015/09/21 - Add descriptions of LaTeX+MathJax math support for all
output formats.
* 2015/09/02 - Added Cygwin package info
* 2015/09/02 - Initial version documenting macros, required toolchain
components and versions, etc.
Reference in New Issue View Git Blame Copy Permalink