382 lines
18 KiB
Plaintext
382 lines
18 KiB
Plaintext
// Copyright 2014-2021 The Khronos Group Inc.
|
|
//
|
|
// SPDX-License-Identifier: CC-BY-4.0
|
|
|
|
= Vulkan^®^ Documentation and Extensions: Procedures and Conventions
|
|
Jon Leech, Tobias Hector
|
|
:data-uri:
|
|
:icons: font
|
|
:toc2:
|
|
:toclevels: 3
|
|
:numbered:
|
|
:source-highlighter: rouge
|
|
:rouge-style: github
|
|
:doctype: book
|
|
:imagewidth: 800
|
|
:fullimagewidth: width="800"
|
|
:cl: :
|
|
|
|
// Various special / math symbols. This is easier to edit with than Unicode.
|
|
include::{config}/attribs.txt[]
|
|
|
|
// Where the current Asciidoctor documentation is found.
|
|
:docguide: https://docs.asciidoctor.org/asciidoc/latest
|
|
|
|
:leveloffset: 1
|
|
|
|
<<<<
|
|
|
|
include::{config}/copyright-ccby.txt[]
|
|
|
|
<<<<
|
|
|
|
[[introduction]]
|
|
= Introduction
|
|
|
|
This document contains required procedures and conventions when writing
|
|
specifications for new Vulkan APIs, extensions and layers, or related
|
|
Khronos^{reg}^ documentation such as white papers and tutorials; or
|
|
contributing to existing Vulkan specifications.
|
|
These are collectively referred to as _Vulkan Documentation_ or just
|
|
_documentation_ below.
|
|
The primary focus is the API Specification and API extensions, although all
|
|
of the markup and most of the writing style is equally applicable to other
|
|
documentation.
|
|
|
|
The primary purpose is to achieve consistency across the API, as well as
|
|
across all of our source and output documents.
|
|
Consistency makes it easier for developers, editors, reviewers, and users of
|
|
our documentation to understand and modify it.
|
|
|
|
This document is now formally voted on and approved by the Vulkan Working
|
|
Group.
|
|
This means that unless explicitly stated otherwise, the procedures and
|
|
conventions must be followed.
|
|
If you have a strong desire to modify the procedures and conventions, such
|
|
changes must be made through the normal Vulkan Working Group processes.
|
|
|
|
|
|
[[introduction-terminology]]
|
|
== Terminology
|
|
|
|
The key words *must*, *required*, *should*, *recommend*, *may*, and
|
|
*optional* in this document are to be interpreted as described in RFC 2119
|
|
and by the Vulkan Specification in the "`Terminology`" section.
|
|
|
|
|
|
[[introduction-structure]]
|
|
== Document Structure
|
|
|
|
The style guide is broken into four sections:
|
|
|
|
* <<naming,API Naming Conventions>> - the required rules for choosing
|
|
names of Vulkan identifiers of all types.
|
|
* <<extensions,Extensions and Layers>> - the required procedures for
|
|
creating formal Vulkan extensions and layers.
|
|
* <<markup,Markup Style>> - the required and recommended markup style for
|
|
writing asciidoctor and XML source that follows consistent formatting
|
|
and layout guidelines, tags special terms and phrases for proper
|
|
processing by the spec generation tools, etc.
|
|
* <<writing,Writing Style>> - the required and recommended writing style
|
|
for overall and fine-grained structure and conventions, normative
|
|
language use, API naming conventions, common words and phrases to use
|
|
and to avoid, linking and cross-referencing, etc.
|
|
|
|
|
|
[[introduction-asciidoc]]
|
|
== Asciidoctor Markup
|
|
|
|
Vulkan Documentation is primarily written in Asciidoctor, a text markup
|
|
language.
|
|
We use the command-line asciidoctor client that is actively maintained by
|
|
asciidoctor, which is documented on its website at https://asciidoctor.org.
|
|
|
|
References to the Asciidoctor User Manual are to sections in the document at
|
|
https://asciidoctor.org/docs/user-manual/.
|
|
|
|
Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is
|
|
available for Linux, MacOS, and Microsoft Windows.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
There are other implementations of asciidoctor, such as AsciidoctorJ
|
|
(https://github.com/asciidoctor/asciidoctorj) and asciidoctor.js
|
|
(https://github.com/asciidoctor/asciidoctor.js).
|
|
In particular, GitHub and GitLab both have preview renderers for .adoc or
|
|
.asciidoc files in repositories, and live preview extensions exist for
|
|
Chrome and Firefox.
|
|
|
|
However, because of the use of custom Ruby macros in the Vulkan
|
|
Specification toolchain, and the high complexity of the documents and
|
|
toolchain used to generate it, these web tools cannot currently render the
|
|
Specification from source.
|
|
Instead, we generate HTML and PDF versions of the Specification and publish
|
|
them on the Khronos website.
|
|
|
|
The Asciidoctor toolchain and build process are not addressed by this
|
|
document, which concentrates solely on source documents.
|
|
====
|
|
|
|
|
|
[[introduction-normative]]
|
|
== Normative References
|
|
|
|
Normative references are references to external documents or resources to
|
|
which documentation authors must comply.
|
|
|
|
[[acm-references]]
|
|
Association for Computing Machinery.
|
|
_Citation Style and Reference Formats_.
|
|
Retrieved July 27, 2019.
|
|
https://www.acm.org/publications/authors/reference-formatting .
|
|
|
|
[[iso-8601]]
|
|
International Organization for Standardization.
|
|
_Data elements and interchange formats -- Information interchange --
|
|
Representation of dates and times_ (2004-12-01).
|
|
https://www.iso.org/standard/40874.html .
|
|
Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples.
|
|
|
|
[[vulkan-docs]]
|
|
Khronos Vulkan Working Group.
|
|
`KhronosGroup/Vulkan-Docs` project on GitHub (July 5, 2016).
|
|
https://github.com/KhronosGroup/Vulkan-Docs .
|
|
|
|
[[vulkan-spec]]
|
|
Khronos Vulkan Working Group.
|
|
_Vulkan 1.1.116 - A Specification_ (July 20, 2019).
|
|
https://www.khronos.org/registry/vulkan/ .
|
|
|
|
Version 1.1.116 is the latest patch release of the Vulkan API Specification
|
|
as of the time this reference was created, but that Specification is
|
|
frequently updated with minor bugfixes and clarifications.
|
|
When a more recent patch release is made, it becomes the normative reference
|
|
for the API.
|
|
|
|
|
|
// Chapters of the text are included below
|
|
|
|
include::style/naming.txt[]
|
|
|
|
include::style/extensions.txt[]
|
|
|
|
include::style/markup.txt[]
|
|
|
|
include::style/writing.txt[]
|
|
|
|
include::style/misc.txt[]
|
|
|
|
// Appendices are included below
|
|
include::style/vuid.txt[]
|
|
|
|
|
|
= Revision History
|
|
|
|
* 2021-11-04 - Remove backquote markup around recommended use of the
|
|
`apiext:` macro, since that macro now styles the extension name argument
|
|
itself.
|
|
* 2021-10-29 - add "`render pass" to the <<writing-compound-words, Compound
|
|
Words and Preferred Orthography>> section.
|
|
* 2021-10-04 - Update the <<extensions-documenting-extensions, Changes for
|
|
New Extensions>> section to require use of the `apiext:` macro for links
|
|
to extension names (internal issue 2831).
|
|
* 2021-09-12 - Add a new subsection with more details on using
|
|
tilde-delimited source blocks <<markup-blocks-source, inside reference
|
|
page open blocks>>, and rewrite the <<sample-command, Sample Command
|
|
Description>> section to follow current phrasing and markup patterns
|
|
(internal issue 2040).
|
|
* 2021-09-09 - Add the <<markup-italicized-enumerant-names, Italicized
|
|
Enumerant Names>> section to clarify how to write wildcard enumerant names
|
|
with imbedded italicized text.
|
|
* 2021-09-06 - Add the <<writing-inclusivity, Use Inclusive Language>>
|
|
section based on the Khronos Inclusive Language list (internal issue
|
|
2293).
|
|
* 2021-09-06 - add "`cube map`" to the <<writing-compound-words, Compound
|
|
Words and Preferred Orthography>> section (internal merge request 4794).
|
|
* 2021-07-20 - Add additional contraction examples to the table in the
|
|
<<markup-avoid-contractions, Avoid Abbreviations and Contractions>>
|
|
section.
|
|
* 2021-05-31 - Add "`implementation-dependent`" as an exception in the
|
|
<<writing-compound-words, Compound Words and Preferred Orthography>>
|
|
section (internal merge request 4611).
|
|
* 2021-05-24 - Add escapes to prevent expansion of attribute names in a few
|
|
places where markup examples are given.
|
|
* 2021-05-22 - Expand the <<markup-avoid-contractions, markup rules>> to
|
|
include avoiding abbreviations, as well as contractions.
|
|
* 2021-05-07 - Add <<markup-word-choices, preferred way to write
|
|
"`drawing/dispatching command">>.
|
|
* 2021-04-28 - Add <<markup-word-choices, disambiguations for
|
|
"`executable`">>.
|
|
* 2021-04-28 - Add <<writing-pointers-instances, usage for pointers and
|
|
handles>> which may be `NULL` or dname:VK_NULL_HANDLE, respectively
|
|
(internal issue 2662).
|
|
* 2021-04-14 - Add "`side effect`" and "`reuse`" as
|
|
<<writing-compound-words, preferred orthography>> (public issue 1484).
|
|
* 2021-03-31 - Update description of the code{cl} macro in the
|
|
<<markup-macros-api, API Markup Macros>> section to match current
|
|
behavior.
|
|
* 2021-03-21 - Note that the <<extensions-reserving-bitmask-values same bit
|
|
should be reserved>> for the same purpose in comparable 32- and 64-bit
|
|
bitmask types (internal issue 2565).
|
|
* 2020-09-14 - Change <<markup-informative-notes, Informative Sections and
|
|
Notes>> section to track actual usage and update the description of the
|
|
undefined{cl} macro to further clarify its purpose and uses (internal
|
|
issue 2195).
|
|
* 2020-08-16 - Add "`reference monitor`" to the preferred
|
|
<<markup-word-choices, Word Choices>> (internal issue 2291).
|
|
* 2020-08-10 - Add a <<writing-describing-errors, Commands which Return
|
|
Error Codes>> section to guide authors of new commands (internal issue
|
|
2290).
|
|
* 2020-07-28 - Add a <<markup-copyrights, Copyrights and Licenses>> section
|
|
describing how to properly attribute this information.
|
|
* 2020-06-23 - Update the <<extensions-documenting-extensions, Changes for
|
|
New Extensions>> section to recommend placing most extension language
|
|
inline in existing specification source files, rather than in separate
|
|
files, and to base extension revision numbers at `1` starting with initial
|
|
public release (public issue 1263).
|
|
* 2020-04-29 - Expand use of `basetype` macros to include external API
|
|
types.
|
|
* 2020-03-16 - Add documentation of writing links to extension appendices in
|
|
the <<extensions-documenting-extensions, Changes for New Extensions>>
|
|
section and document the apiext{cl} and reflink{cl} macros in the
|
|
<<markup-macros-api, API Markup Macros>> section.
|
|
Improve documentation of writing <<writing-refpages, Markup For Automatic
|
|
Reference Page Extraction>> including how to mark up content in the
|
|
Specification source so it only appears in generated reference pages;
|
|
however, this section is still out of date (internal issue 1999).
|
|
* 2020-03-11 - Specify in the <<sample-command, Sample Command Description>>
|
|
section that a valid usage statement must be defined at the place (command
|
|
or structure specification) that all information need to evaluate the
|
|
statement is known.
|
|
Update the description of <<appendix-vuid-creating, Creating VUID tags>>
|
|
to match the current scripts.
|
|
Use the term "`asciidoctor`" instead of "`asciidoc`" everywhere.
|
|
Note in the <<introduction-asciidoc, Asciidoctor Markup>> section that the
|
|
Specification can only be built using the command-line asciidoctor client,
|
|
not by asciidoctor web clients.
|
|
* 2020-02-22 - Document that it is no longer needed to escape C arrows in
|
|
macros.
|
|
* 2019-12-15 - Add a markup section on <<markup-macros-prime-symbols, Prime
|
|
Symbols>> (internal issue 1110).
|
|
* 2019-11-27 - Expand the <<writing-pNext-chain, Describing Extension
|
|
Structure Chains>> section and make all spec language consistent with it
|
|
(internal issue 1814).
|
|
* 2019-09-09 - Define markup for nested structure members in the
|
|
<<markup-macros-api, API Markup Macros>> section (internal issue 1765).
|
|
* 2019-09-08 - Add language to the end of the
|
|
<<extensions-documenting-extensions, Changes for New Extensions>> section
|
|
describing how to mark up asciidoctor conditionals (internal issue 1808).
|
|
* 2019-08-25 - Add the <<markup-indentation-equations, Indentation of
|
|
Equations>> section (internal issue 1793).
|
|
* 2019-08-25 - Add the <<writing-describing-layers, Extensions and Grouping
|
|
Related Language>> section (internal issue 979) and the
|
|
<<markup-minimize-indentation, Minimize Indentation>> section (internal
|
|
issue 747).
|
|
Disallow use of standalone `+` except in latexmath and source blocks, in
|
|
the <<markup-layout, Asciidoc Markup And Text Layout>> section (internal
|
|
issue 736).
|
|
* 2019-08-19 - Add the <<writing-pointers-instances, Describing Pointers and
|
|
Instances>> section (internal issue 1553).
|
|
* 2019-08-13 - Add a NOTE to the <<appendix-vuid-format, Format of VUID
|
|
Tags>> appendix specifying allowed characters in VUID tags (based on
|
|
discussion for internal merge request 3239).
|
|
* 2019-07-27 - Add the <<writing-references, References>> section and
|
|
rewrite external references accordingly.
|
|
* 2019-05-09 - Specify rules for defining <<extensions-new-flags-types, new
|
|
flags and bitmask types>> (internal issue 1649).
|
|
* 2019-01-06 - Add details on <<extensions-reserving-bitmask-values,
|
|
Reserving Bitmask Values>> (internal issue 1411).
|
|
* 2018-11-19 - Add details to the <<extensions-documenting-extensions,
|
|
Changes for New Extensions>> section including the new "`Description`"
|
|
section, and other standard parts of extension appendices.
|
|
* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images,
|
|
Figures>> section (public pull request 734).
|
|
* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined
|
|
Behavior>> (as part of the fixes for public issue 379), and describing why
|
|
the undefined{cl} macro should always be used.
|
|
* 2018-07-08 - Remove requirement to explicitly include extension appendices
|
|
in the <<extensions-documenting-extensions, Changes for New Extensions>>
|
|
section.
|
|
* 2018-06-25 - Modify the process for <<extensions-vendor-id, Registering a
|
|
Vendor ID with Khronos>> to define vendor ID values as part of an
|
|
enumerated type.
|
|
* 2018-03-07 - Updated for Vulkan 1.1 release.
|
|
* 2018-01-10 - Move details of mandated extension compatibility from the
|
|
<<extensions-rules, General Rules/Guidelines>> section into the
|
|
Fundamentals section of the API Specification, where they are changed
|
|
slightly to allow explicit incompatibilies (public issue 638).
|
|
* 2017-10-27 - Add language about proper use of "`valid pointer`" and
|
|
"`pointer to valid object`" for valid usage statements, in the
|
|
<<sample-command, Sample Command Description>> section (related to public
|
|
pull request 547).
|
|
* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells,
|
|
LaTeX Math in Table Cells>> (internal issue 908).
|
|
* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX`
|
|
extensions>> (public issues 536, 580).
|
|
* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and
|
|
`any`>> to refer to properties of elments of arrays (internal issue 884).
|
|
* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and
|
|
Extension pname:pNext Chains>> language specifying where to describe
|
|
interactions of structures in a pname:pNext chain (internal issue 715).
|
|
* 2017-09-10 - Add example of marking up an enumerated type all of whose
|
|
values are defined by extensions (internal issue 864).
|
|
* 2017-08-25 - Add language to the <<extensions,API Versions, Extensions,
|
|
and Layers>> chapter describing how to write new API versions (internal
|
|
issue 892).
|
|
* 2017-06-12 - Add sections describing when to use the
|
|
<<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text,
|
|
*text{cl}>> markup macros instead of the *link{cl} macros, and clarify
|
|
that slink{cl} should be used for handle as well as structure names
|
|
(internal issue 886).
|
|
* 2017-05-08 - Add appendix describing <<appendix-vuid, Valid Usage ID
|
|
Tags>> and how they're generated.
|
|
* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension
|
|
Structure Names>>.
|
|
* 2017-02-11 - Finish transitioning to asciidoctor markup.
|
|
* 2016-09-28 - Add asciidoc math markup guidelines.
|
|
* 2016-09-16 - Make style guide markup more consistent with its own
|
|
recommendations.
|
|
Simplify some tables of preferred terms.
|
|
Add sections on block and table markup.
|
|
* 2016-09-12 - Describe writing and markup style for labelled lists.
|
|
Require use of the ISO 8601 date format except in rare legacy cases.
|
|
Expand the description of <<markup-layout,Line Lengths>> and add a
|
|
description of markup for <<markup-footnotes,Footnotes>>.
|
|
* 2016-09-08 - Add a writing section about proper use of
|
|
<<writing-misc-a-an,"`a`" and "`an`">> (internal issue 432).
|
|
* 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions, which
|
|
are no longer used in the Specification (internal issue 407).
|
|
* 2016-08-29 - Add spelling and compound word rules (public issue 352).
|
|
* 2016-08-23 - Modify description of specifying extensions in the
|
|
<<extensions,Layers and Extensions>> chapter to refer to the new
|
|
single-branch model for extensions (internal issue 397).
|
|
* 2016-07-26 - Add section describing <<writing-refpages,markup for
|
|
automatic reference page extraction>>.
|
|
* 2016-07-18 - Add examples of function-parameter and structure-member
|
|
markup (based on public issue 286).
|
|
* 2016-07-11 - Change the document title.
|
|
* 2016-07-07 - Rename document, change license to CC BY, clarify required
|
|
and recommended actions, and reserve use of "`normative`" for the
|
|
Specifications.
|
|
* 2016-06-26 - Move Layers and Extensions chapter from Appendix C of the
|
|
Vulkan API Specification and merge content with the naming guide.
|
|
Put extension and naming chapters into their own source files.
|
|
* 2016-06-20 - Add API naming guide.
|
|
* 2016-05-22 - Add markup and image creation rules, after fixing missing
|
|
figure captions for public issue 219.
|
|
* 2016-05-01 - Include feedback from public issues 120 and 190.
|
|
Use consistent conventions for defining structures.
|
|
Use American rather than British spelling conventions.
|
|
* 2016-03-12 - Recommend against "the value of".
|
|
* 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not".
|
|
* 2016-02-16 - Place asciidoc conversion post-release.
|
|
* 2016-02-09 - Added quotation mark convention.
|
|
* 2016-02-01 - Add the Oxford Comma section and issue resolution.
|
|
* 2016-01-26 - Add bullet-list style description of command parameters.
|
|
* 2016-01-11 - Add "`Numbers in Text`" section from WSI work.
|
|
* 2015-12-16 - Make "`begin / end`" preferred terms to "`start / finish`".
|
|
* 2015-12-15 - Make "`implementation`" preferred term instead of "`system`".
|
|
* 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer types.
|
|
* 2015-12-10 - Initial release for feedback.
|