957 lines
33 KiB
Plaintext
957 lines
33 KiB
Plaintext
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
||
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
||
|
||
Vulkan Style Guide
|
||
==================
|
||
Jon Leech
|
||
include::../specversion.txt[]
|
||
:toc2:
|
||
:toclevels: 3
|
||
:max-width: 100
|
||
:numbered:
|
||
:doctype: book
|
||
:imagewidth: 800
|
||
:fullimagewidth: {svgpdf@pdf:scaledwidth="75%":width="800"}
|
||
:cl: :
|
||
|
||
:leveloffset: 1
|
||
|
||
// :icons:
|
||
// :toc-placement: manual
|
||
|
||
<<<<
|
||
|
||
include::../copyright.txt[]
|
||
|
||
<<<<
|
||
|
||
[[introduction]]
|
||
= Introduction
|
||
|
||
This is the Vulkan Documentation Style Guide, containing the collected
|
||
rules, guidelines, tricks, and tips for authors contributing to the Vulkan
|
||
API Specification (the _Specification_), reference pages, and other
|
||
documentation such as white papers and tutorials (if and when we have them).
|
||
These are collectively referred to as _Vulkan Documentation_ or just
|
||
_documentation_ below. The primary focus and inspiration is the
|
||
Specification, although all of the markup and most of the writing style is
|
||
equally applicable to the reference pages.
|
||
|
||
The primary purpose of the style guide is to achieve consistency of both
|
||
source and output documents. Consistency makes it easier for editors,
|
||
reviewers, and users of our documentation to understand and modify it. When
|
||
the style guide makes prescriptive statements, please follow them unless
|
||
there are compelling reasons not to. If you have a strong desire to change
|
||
these guidelines, you can try to make a case starting with the Specification
|
||
editors, and proceeding to the Vulkan Working Group if need be.
|
||
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
But be prepared to make the numerous merge requests applying those changes
|
||
to all parts of our documentation, if your change request is accepted!
|
||
====
|
||
|
||
The style guide is broken into two major sections:
|
||
|
||
* <<markup,Markup Style>> - how to write asciidoc 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>> - overall and fine-grained structure and
|
||
conventions, normative language use, API naming conventions, common
|
||
words and phrases to use (and those not to use), linking and
|
||
cross-referencing, etc.
|
||
|
||
|
||
[[introduction-asciidoc]]
|
||
== Asciidoc Markup
|
||
|
||
Vulkan Documentation is primarily written in Asciidoc, a form of text markup
|
||
language. Asciidoc is documented on its website at http://www.asciidoc.org/.
|
||
|
||
[[userguide]]
|
||
References to the Asciidoc User Guide are to sections in the document at
|
||
http://asciidoc.org/userguide.html .
|
||
|
||
Asciidoc packages are available for Linux, MacOS, and Microsoft Windows,
|
||
together with the other toolchain components required to generate output
|
||
documents corresponding to the markup. Note that we are currently using the
|
||
original _asciidoc_ tool. Other tools to process Asciidoc markup, such as
|
||
_asciidoctor_, are also available, but are not currently usable for our
|
||
documents. While asciidoctor supports the basic Asciidoc markup syntax, it
|
||
does not support asciidoc macros, which are used extensively in the
|
||
documentation. It is possible to move from asciidoc to asciidoctor, but this
|
||
will be a significant effort, taking place after Vulkan 1.0 is published.
|
||
|
||
This guide does not address the toolchain and build process, just source
|
||
documents.
|
||
|
||
|
||
[[markup]]
|
||
= Markup Style
|
||
|
||
This chapter demonstrates Asciidoc and Specification structure, including
|
||
text layout and markup style.
|
||
|
||
Chapters and sections follow a rigid template consisting of an optional
|
||
anchor (if other parts of the document cross-reference the section) followed
|
||
by a one line title (see section 11.2 of the <<userguide,User Guide>>) and a
|
||
blank line. The anchor is typically the base name of the file containing the
|
||
chapter, with a lowercased version of the section name following, with
|
||
spaces replaced by dashes.
|
||
|
||
Always use the one-line title form, with one to five = signs preceding the
|
||
chapter/section title. The two-line title form cannot be easily searched for
|
||
and often looks like other types of asciidoc delimiters.
|
||
|
||
Always precede the anchor by two blank lines (except at the beginning of a
|
||
file), and follow the title by a blank line, to set off sections visibly.
|
||
|
||
.Example Markup
|
||
----
|
||
[[markup]]
|
||
= Markup Style
|
||
|
||
|
||
[[markup-sample-section]]
|
||
== Sample Section
|
||
----
|
||
|
||
|
||
[[markup-sample-section]]
|
||
== Sample Section
|
||
|
||
This is a sample section of the Vulkan Specification, nested one level
|
||
inside a chapter. Sections can be nested up to level 5, although not all
|
||
levels are included in the Table of Contents.
|
||
|
||
|
||
[[markup-layout]]
|
||
== Layout, Line Lengths, and Lists
|
||
|
||
Asciidoc source should be text filled to 76 columns with hard line breaks.
|
||
Except when necessary for lists or other markup, text should begin at the
|
||
first column of each line (leading spaces are often semantically meaningful
|
||
in asciidoc markup).
|
||
|
||
UTF-8 characters outside the ASCII subset should be used sparingly, only
|
||
when needed for non-English names. Instead use asciidoc markup for special
|
||
characters, if required. For example, two hyphens produces an en-dash:
|
||
|
||
[NOTE]
|
||
.Example Markup
|
||
====
|
||
|
||
`An -- en-dash` -> An -- en-dash
|
||
====
|
||
|
||
As an exception, multiplication should be marked with the unicode
|
||
multiplication symbol ``×'' (and *not* an asterisk) when used in plain
|
||
text. In math sections, the same symbol should be referred to as `\times`.
|
||
In code sections, a conventional asterisk (`*`) should be used instead.
|
||
|
||
See chapter 10 of the <<userguide,User Guide>> for supported special
|
||
characters, as well as use of entity references.
|
||
|
||
Quotation marks should use the 66/99 convention. That is, double asymmetric
|
||
quotation marks, indicated by double back-ticks as opening marks and double
|
||
apostrophes as closing marks (\`\`like this''), which renders ``like this''.
|
||
|
||
_Never_ use hard tabs or trailing blanks.
|
||
|
||
* In some cases, limitations of asciidoc markup may result in lines that are
|
||
longer than 76 characters and cannot easily be shortened without
|
||
compromising the output documents.
|
||
|
||
|
||
[[markup-samplesection-lists]]
|
||
=== Lists
|
||
|
||
* Bullet lists are the preferred form of list, aside from glossary
|
||
definitions.
|
||
* Lists should have text indented by 4 spaces and the list item delimiter
|
||
(e.g. one or more asterisks, for bullet lists) indented by two spaces.
|
||
+
|
||
--
|
||
Note that continuation blocks for list items longer than one paragraph
|
||
cannot be indented, only the first paragraph.
|
||
|
||
In general, successive list items should not be separated by white space.
|
||
However, list continuation blocks must be followed by a blank line due to
|
||
limitations of the asciidoc parser.
|
||
--
|
||
|
||
* Indent bullet lists two spaces (to the bullet), 4 spaces (to the text,
|
||
if it extends over multiple lines). This lets us visually distinguish
|
||
lists from other kinds of markup.
|
||
** Nested lists should align the leftmost list item delimiter (bullet,
|
||
etc.) with the parent delimiter.
|
||
|
||
.Example Markup
|
||
----
|
||
* This is the first item in a bullet list.
|
||
* The second item is described with two paragraphs. The second
|
||
paragraph is in a continuation block:
|
||
+
|
||
--
|
||
This is the second paragraph.
|
||
--
|
||
|
||
** This is a nested list item for the second item. Since it
|
||
follows a continuation block, it must be separated by a
|
||
blank line from that block.
|
||
----
|
||
|
||
|
||
[[markup-samplesection-anchors]]
|
||
=== Anchors and Cross-references
|
||
|
||
In general, chapters and sections should always have anchors, following the
|
||
naming convention <<markup,discussed above>>. Anchors to other sections of
|
||
the document may be inserted as needed. In addition, the autogenerated
|
||
include files defining commands, structures, enumerations and flags all
|
||
define anchors whose name is the name of the command or type being defined,
|
||
so it's easy to link to a (for example) a command name such as
|
||
<<vkCreateCommandPool>>.
|
||
|
||
If you want a cross-reference to an anchor to appear as something other than
|
||
the raw anchor name, always make sure to include that text as part of the
|
||
cross-reference. There are several different toolchains followed for various
|
||
forms of asciidoc output, and not all of them treat anchors without alt-text
|
||
the same way.
|
||
|
||
.Example Markup
|
||
----
|
||
In general, chapters and sections should always have anchors,
|
||
following the naming convention <<markup,discussed above>>.
|
||
Link to a command name such as <<vkCreateCommandPool>>.
|
||
----
|
||
|
||
|
||
[[markup-markup]]
|
||
== Markup Macros and Normative Terminology
|
||
|
||
This section discusses Asciidoc macros used in the document. In addition to
|
||
the macros defined by asciidoc itself, additional macros are defined by the
|
||
Specification and Reference Page configuration files.
|
||
|
||
|
||
=== API Markup Macros
|
||
|
||
These macros must: be used to tag command, structure, enumeration,
|
||
enumerant, and other Vulkan-specific names so they can be rendered in a
|
||
distinctive fashion, link to definitions of those names, and be easily
|
||
searched for in the source documents. The validation scripts (`make
|
||
allchecks` output) also rely on these macros being used consistently and
|
||
correctly. The API markup macros, with examples of their use, are in the
|
||
following table:
|
||
|
||
.API Markup Macros
|
||
[width="100%",options="header",cols="20%,80%"]
|
||
|=====
|
||
| Macro Name | Usage and Meaning
|
||
| flink{cl} | Generates a cross-reference or link to the definition of
|
||
the command name in the macro argument. Example:
|
||
flink{cl}vkCreateCommandPool -> flink:vkCreateCommandPool.
|
||
| fname{cl} | Formats the macro argument like flink{cl}. Does not
|
||
generate a cross-reference. Example:
|
||
fname{cl}vkCreateCommandPool -> fname:vkCreateCommandPool.
|
||
The flink{cl} macro is preferred.
|
||
| ftext{cl} | Formats the macro argument like fname{cl}. May contain
|
||
asterisks for wildcards. Not validated. Example:
|
||
ftext{cl}vkCmd* -> ftext:vkCmd*.
|
||
|
||
Only use ftext{cl} when it is necessary to describe
|
||
something that should be rendered like a command name,
|
||
but is not actually one (e.g. is a wildcard or subset of
|
||
an actual command name).
|
||
| slink{cl} | Generates a cross-reference or link to the definition
|
||
of the structure in the macro argument. Example:
|
||
slink{cl}VkCommandPoolCreateInfo ->
|
||
slink:VkCommandPoolCreateInfo.
|
||
| sname{cl} | Formats the macro argument like slink{cl}. Does not
|
||
generate a cross-reference. May also be an abstract
|
||
structure name. Examples: sname{cl}VkCommandPoolCreateInfo
|
||
-> sname:VkCommandPoolCreateInfo, sname{cl}VK_NULL_HANDLE
|
||
-> sname:VK_NULL_HANDLE. The slink{cl} macro is preferred.
|
||
| stext{cl} | Formats the macro argument like sname{cl}. May contain
|
||
asterisks for wildcards. Not validated. Example:
|
||
stext{cl}Vk*CreateInfo -> stext:Vk*CreateInfo.
|
||
|
||
Only use stext{cl} when it is necessary to describe
|
||
something that should be rendered like a structure name,
|
||
but is not actually one (e.g. is a wildcard or subset of
|
||
an actual structure name).
|
||
| elink{cl} | Formats the macro argument as a Vulkan enumerantion
|
||
name and links to the definition of that enumeration type.
|
||
Example: ename{cl}VkResult -> ename:VkResult.
|
||
| ename{cl} | Formats the macro argument as a Vulkan enumerant name.
|
||
Example: ename{cl}VK_EVENT_SET -> ename:VK_EVENT_SET.
|
||
| etext{cl} | Formats the macro argument like ename{cl}. Not validated.
|
||
Examples: etext{cl}_RANGE_SIZE -> etext:_RANGE_SIZE,
|
||
etext{cl}VK_IMAGE_CREATE_SPARSE_* ->
|
||
etext:VK_IMAGE_CREATE_SPARSE_*
|
||
|
||
Only use stext{cl} when it is necessary to describe
|
||
something that should be rendered like a enumerant name,
|
||
but is not actually one (e.g. is a wildcard or subset of
|
||
an actual enumerant name).
|
||
| pname{cl} | Formats the macro argument as a Vulkan parameter or
|
||
structure member name. Example: pname{cl}device ->
|
||
pname:device.
|
||
| ptext{cl} | Formats the macro argument like pname{cl}. May contain
|
||
asterisks for wildcards. Not validated. Example:
|
||
ptext{cl}sparseResidency* -> ptext:sparseResidency*.
|
||
|
||
Only use ptext{cl} when it is necessary to describe
|
||
something that should be rendered like a parameter name,
|
||
but is not actually one (e.g. is a wildcard or subset of
|
||
an actual parameter name).
|
||
| tlink{cl} | Generates a cross-reference or link to the definition
|
||
of the Vulkan type in the macro argument. Example:
|
||
tlink{cl}PFN_vkAllocationFunction ->
|
||
tlink:PFN_vkAllocationFunction. This is only used for
|
||
function pointer types at present.
|
||
| tname{cl} | Formats the macro argument like tlink{cl}. Does not
|
||
generate a cross-reference. Example:
|
||
tname{cl}PFN_vkAllocationFunction ->
|
||
tname:PFN_vkAllocationFunction. The tlink{cl} macro is
|
||
preferred.
|
||
| basetype{cl} | Formats the macro argument like a basic scalar type
|
||
or API handle name. Not validated. Examples:
|
||
basetype{cl}uint32_t -> basetype:uint32_t,
|
||
basetype{cl}VkDeviceSize -> basetype:VkDeviceSize.
|
||
| code{cl} | Formats the macro argument as a code sample. Primarily
|
||
used for SPIR-V keywords. Examples: code{cl}ClipDistance
|
||
-> code:ClipDistance, code{cl}NULL -> code:NULL.
|
||
|=====
|
||
|
||
|
||
==== Other Markup
|
||
|
||
Uses of standard Asciidoc markup are less common. Occasional asterisk markup
|
||
is used for *emphasis*. Backtick markup is sometimes used for the C `NULL`
|
||
macro, but the code{cl} macro should be used for code:NULL instead.
|
||
|
||
.Example Markup
|
||
----
|
||
*emphasis*
|
||
`NULL`
|
||
code:NULL
|
||
----
|
||
|
||
|
||
==== Glossary Terms
|
||
|
||
_Glossary terms_ are currently marked up using underscore markup where they
|
||
are defined in the documents, as well as being added to the formal Glossary
|
||
appendix in the Specification. However, we will probably change to using
|
||
custom macros soon, to enable linkage between the glossary appendix and
|
||
definitions in the spec body.
|
||
|
||
.Example Markup
|
||
----
|
||
_Glossary terms_
|
||
----
|
||
|
||
|
||
=== Normative Terminology
|
||
|
||
Normative terminology is precisely defined in section 1.3 of the Vulkan API
|
||
Specification, and is used to visually tag terms which express mandatory and
|
||
optional behavior of Vulkan implementations, and of applications using
|
||
Vulkan.
|
||
|
||
Whenever one of these terms appears in the Specification, it must: be tagged
|
||
using the macros, to indicate that its use has been carefully considered and
|
||
is consistent with the definitions in section 1.3. This is extremely
|
||
important for determining IP that is in and out of Scope during Ratification
|
||
reviews. The normative terminology macros are defined in the following
|
||
table:
|
||
|
||
.Normative Terminology Macros
|
||
[width="100%",options="header"]
|
||
|=====
|
||
| Macro Name | Meaning
|
||
| can{cl} | can:
|
||
| cannot{cl} | cannot:
|
||
| may{cl} | may:
|
||
| maynot{cl} | maynot:
|
||
| must{cl} | must:
|
||
| mustnot{cl} | mustnot:
|
||
| optional{cl} | optional:
|
||
| optionally{cl} | optionally:
|
||
| recommend{cl} | recommend:
|
||
| required{cl} | required:
|
||
| should{cl} | should:
|
||
| shouldnot{cl} | shouldnot:
|
||
|=====
|
||
|
||
Because asciidoc macro names cannot contain spaces, macros which correspond
|
||
to multiple words (maynot{cl}, mustnot{cl}, and shouldnot{cl}) drop those
|
||
spaces. Also note that the macros are lower-case only, so language should be
|
||
written such that these terms do not appear at the beginning of a sentence
|
||
(if really necessary, additional capitalized macros could be added).
|
||
|
||
|
||
==== Optional Behavior
|
||
|
||
If a described behavior of the implementation is not necessary for
|
||
conformance, use the terms _may:_ or _optional:_ to describe it.
|
||
|
||
If a described usage pattern by the application is allowed but
|
||
not necessary, use the term _can:_ to describe it.
|
||
|
||
|
||
==== Optional Functionality
|
||
|
||
If functionality (rather than behavior) is optional, it should be
|
||
described as
|
||
|
||
.Example Markup
|
||
----
|
||
not required:
|
||
----
|
||
|
||
Implementations are not mandated to support functionality which is not
|
||
required:, but if they do, they must: behave as described by the
|
||
Specification. The term _functionality_ includes API features, extensions,
|
||
and layers.
|
||
|
||
|
||
[[markup-informative]]
|
||
== Informative, Editing and Implementor's Notes
|
||
|
||
There are several possible types of notes. Depending on the type of output,
|
||
they are rendered in different styles, but always include a note title, and
|
||
are usually set off in a box or with an icon. While asciidoc supports a wide
|
||
set of _admonition paragraphs_ such as TIP, IMPORTANT, WARNING, and CAUTION,
|
||
we always use the NOTE form, augmented by a note title. Each type of note is
|
||
discussed below.
|
||
|
||
|
||
[[markup-informative-notes]]
|
||
=== Informative Notes
|
||
|
||
Informative notes always appear as part of the document, but are considered
|
||
non-normative. They usually describe usage advice for applications, and are
|
||
always given the title _Note_, as in the following example:
|
||
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
This is an informative note.
|
||
====
|
||
|
||
.Example Markup
|
||
----
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
This is an informative note.
|
||
====
|
||
----
|
||
|
||
If an entire chapter or section is considered informative, it should begin
|
||
with the sentence:
|
||
|
||
.Example Markup
|
||
----
|
||
This chapter/section is Informative.
|
||
----
|
||
|
||
|
||
=== Editing Notes
|
||
|
||
Editing notes only appear in internal (non-published) versions of documents,
|
||
via asciidoc conditionals, and should be removed from the source before
|
||
pushing content to a canonical (master or per-extension) public repository.
|
||
They usually tag places where an outstanding bug or Gitlab/Github issue is
|
||
being worked, and are always given the title _editing-note_, as in the
|
||
following example:
|
||
|
||
ifdef::editing-notes[]
|
||
[NOTE]
|
||
.editing-note
|
||
====
|
||
This is an editing note, marked up as follows:
|
||
====
|
||
endif::editing-notes[]
|
||
|
||
.Example Markup
|
||
----
|
||
\ifdef::editing-notes[]
|
||
[NOTE]
|
||
.editing-note
|
||
====
|
||
Contents of an editing note go here. It is good practice to include a
|
||
bug/issue number, or link to the bug/issue, in the editing note.
|
||
====
|
||
\endif::editing-notes[]
|
||
----
|
||
|
||
|
||
=== Implementor's Notes
|
||
|
||
Implementor's notes may or may not appear in published versions of
|
||
documents, via asciidoc conditionals. They describe suggested approaches or
|
||
guidelines for people writing Vulkan implementations, and are rare because
|
||
the hardware being targeted varies so widely. They are always given the
|
||
title _Implementor's Note_, as in the following example:
|
||
|
||
ifdef::implementation-guide[]
|
||
.Implementor's Note
|
||
====
|
||
This is an implementor's note, marked up as follows:
|
||
====
|
||
endif::implementation-guide[]
|
||
|
||
.Example Markup
|
||
----
|
||
\ifdef::implementation-guide[]
|
||
.Implementor's Note
|
||
====
|
||
Contents of an implementor's note go here.
|
||
====
|
||
\endif::implementation-guide[]
|
||
----
|
||
|
||
|
||
== Word Choices
|
||
|
||
There are a variety of common terms that have several equivalent word
|
||
choices. Always use the words in the first column instead of the alternate
|
||
terms. This list may not be comprehensive; when in doubt, be guided by the
|
||
existing API Specification.
|
||
|
||
.Word Choices
|
||
[width="100%",options="header"]
|
||
|=====
|
||
| Use This | Instead Of | Comments
|
||
| allocate | create
|
||
| When describing objects or memory resulting from
|
||
ftext:vkAllocate* commands.
|
||
| application | client |
|
||
| command | function
|
||
| Except when talking about function pointers returned by
|
||
ftext:vkGet*ProcAddr commands.
|
||
| create | allocate
|
||
| When describing objects resulting from ftext:vkCreate*
|
||
commands.
|
||
| depth/stencil | packed (interleaved, combined, _other prefix_)
|
||
depth/stencil, depth-stencil, DepthStencil, etc.
|
||
| Combined format implicit in the name.
|
||
| device | GPU
|
||
| Implementations on non-GPU devices are possible.
|
||
| host endianness | platform endianness |
|
||
| implementation| system |
|
||
| it is | it's | In general, avoid contractions.
|
||
| member | field |
|
||
| pname:parameter are/is
|
||
| pname:parameter specifies (denotes, indicates)
|
||
| In rare cases when _are_ or _if_ are not grammatically
|
||
appropriate, _specifies_ may be used instead.
|
||
| begins / begun | starts / started | For ftext:vkBegin* - also see ``finish''
|
||
| finishes / finished | ends / ended | For ftext:vkEnd* - also see ``begins''
|
||
| used | referenced | When describing attachments specified in a
|
||
subpass description.
|
||
| statically used | referenced | When describing resources or push constants
|
||
accessed by shader code
|
||
| a more specific term | referenced | For all other situations.
|
||
| component | channel | Specifically this refers to color channels/components
|
||
|=====
|
||
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
The ``begin/start'' and ``end/finish'' distinction is still being sorted out.
|
||
See Gitlab issue #61.
|
||
====
|
||
|
||
|
||
=== Terms to Avoid
|
||
|
||
Don't describe anything in the documentation using vague or wishy-washy
|
||
terms. Our goal is to precisely describe behavior of implementations.
|
||
|
||
The normative terms may:, optional:, and should: are available when
|
||
implementations may make choices of behavior, but when such choices are
|
||
allowed, each choice still must: have well-defined behavior.
|
||
|
||
.Terms to Avoid
|
||
[width="100%",options="header"]
|
||
|=====
|
||
| Bad Term | Comments
|
||
| expect | And variants such as _expected_
|
||
| likely | And variants such as _will likely_
|
||
| allowed, could, generally, might, probably, perhaps
|
||
| And all other such terms of choice. Use _may:_ or _can:_
|
||
depending on the context.
|
||
| may: or maynot: | Just use _may:_.
|
||
|=====
|
||
|
||
|
||
[[writingstyle]]
|
||
= Writing Style
|
||
|
||
|
||
[[writingstyle-misc]]
|
||
== Miscellaneous Grammar, Spelling, and Punctuation Issues
|
||
|
||
=== Use the Oxford Comma (Serial Comma)
|
||
|
||
When writing a sentence listing a series of items, include a comma before
|
||
the ``and'' separating the last item.
|
||
|
||
*Correct:* The red, green, blue, and alpha components.
|
||
|
||
*Incorrect:* The red, green, blue and alpha components.
|
||
|
||
Also see http://blog.oxforddictionaries.com/2011/06/oxford-comma/
|
||
|
||
=== Numbers in Text
|
||
|
||
When describing the need for a small number of objects, smaller than ten, spell
|
||
the number out (e.g. ``one''). If you are describing a literal value that is a
|
||
small number, you may use a numeric value (e.g. ``1'').
|
||
|
||
For example, instead of writing that a bitfield ``contains 1 or more bits'',
|
||
write that it ``contains one or more bits''. A counter example is that it is okay
|
||
to write ``For non-stereoscopic-3D applications, this value is 1.''
|
||
|
||
|
||
[[writingstyle-describing]]
|
||
== Describing Commands and Parameters
|
||
|
||
The Specification describes API commands followed by descriptions of their
|
||
parameters, which are usually simple scalar types, handles or pointers to
|
||
Vulkan objects or arrays of objects, or structures containing combinations
|
||
of scalar types and objects. The templates and examples shown and annotated
|
||
here are based on the Specification. Do not vary from them without
|
||
compelling need.
|
||
|
||
Normative parts of the Specification should describe _what_ something does,
|
||
rather than _how_ or _why_ an application would want to use it.
|
||
|
||
[NOTE]
|
||
.Guideline
|
||
====
|
||
As a simple example, say
|
||
|
||
``To create a command pool, call fname:vkCreateCommandPool''
|
||
|
||
rather than
|
||
|
||
``You/The application/The user can create a command pool by calling
|
||
fname:vkCreateCommandPool''.
|
||
|
||
====
|
||
|
||
Explanations of _why_ and _how_ should largely be confined to reference
|
||
documentation, sample code, tutorials, and other such documents. Occasional
|
||
non-normative explanations can be included in the Specification using
|
||
<<markup-informative-notes,informative notes>>.
|
||
|
||
|
||
[[writingstyle-latexmath]]
|
||
== LaTeX Math Markup
|
||
|
||
There is a considerable amount of math in the documentation, ranging from
|
||
simple arithmetic expressions to complicated conditionals. For the most
|
||
part, math is marked up using LaTeX math notation, which is either passed
|
||
through to the Mathjax browser renderer for HTML outputs, or passed through
|
||
to LaTeX for PDF outputs. For some very simple math expressions, asciidoc
|
||
markup can be used.
|
||
|
||
[NOTE]
|
||
.Note
|
||
====
|
||
We still haven't got the latexmath vs. asciidoc font situation sorted out
|
||
for all target output forms, so there can be some visual inconsistencies.
|
||
====
|
||
|
||
While LaTeX math macros, including the amsmath package, are supported,
|
||
general LaTeX constructs are not.
|
||
|
||
_Inline math_ is encoded using the latexmath{cl} macro. For example:
|
||
|
||
* latexmath:[$[0,1\]$]
|
||
* latexmath:[$x \cdot 0 = 0 \cdot x = 0$]
|
||
* latexmath:[${\textbf c} = t {\textbf c}_1 + (1-t){\textbf c}_2. $]
|
||
|
||
.Example Markup
|
||
----
|
||
latexmath:[$[0,1\]$]
|
||
latexmath:[$x \cdot 0 = 0 \cdot x = 0$]
|
||
latexmath:[${\textbf c} = t {\textbf c}_1 + (1-t){\textbf c}_2. $]
|
||
----
|
||
|
||
Note the escaped bracket in markup for the first expression, which is
|
||
necessary to work around asciidoc macro parsing:
|
||
|
||
|
||
_Block math_ is used for more complex equations. This example uses the
|
||
amsmath `align*` macros to delimit the expression:
|
||
|
||
[latexmath]
|
||
+++++++++++++++++++
|
||
\begin{align*}
|
||
c_{RGB} & =
|
||
\begin{cases}
|
||
\frac{c_{sRGB}}{12.92} & \textrm{for } c_{sRGB} \leq 0.04045 \\
|
||
\left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \textrm{for } c_{sRGB} > 0.04045
|
||
\end{cases}
|
||
\end{align*}
|
||
+++++++++++++++++++
|
||
|
||
.Example Markup
|
||
----
|
||
[latexmath]
|
||
+++++++++++++++++++
|
||
\begin{align*}
|
||
c_{RGB} & =
|
||
\begin{cases}
|
||
\frac{c_{sRGB}}{12.92} & \textrm{for } c_{sRGB} \leq 0.04045 \\
|
||
\left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \textrm{for } c_{sRGB} > 0.04045
|
||
\end{cases}
|
||
\end{align*}
|
||
+++++++++++++++++++
|
||
----
|
||
|
||
This example uses normal LaTeX math brackets to delimit the expression:
|
||
|
||
[latexmath]
|
||
+++++++++++++++++++
|
||
\[
|
||
V =
|
||
\begin{cases}
|
||
(-1)^S \times 0.0, & E = 0, M = 0 \\
|
||
(-1)^S \times 2^{-14} \times { M \over 2^{10} },
|
||
& E = 0, M \neq 0 \\
|
||
(-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) },
|
||
& 0 < E < 31 \\
|
||
(-1)^S \times Inf, & E = 31, M = 0 \\
|
||
NaN, & E = 31, M \neq 0
|
||
\end{cases}
|
||
\]
|
||
+++++++++++++++++++
|
||
|
||
.Example Markup
|
||
----
|
||
[latexmath]
|
||
+++++++++++++++++++
|
||
\[
|
||
V =
|
||
\begin{cases}
|
||
(-1)^S \times 0.0, & E = 0, M = 0 \\
|
||
(-1)^S \times 2^{-14} \times { M \over 2^{10} },
|
||
& E = 0, M \neq 0 \\
|
||
(-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) },
|
||
& 0 < E < 31 \\
|
||
(-1)^S \times Inf, & E = 31, M = 0 \\
|
||
NaN, & E = 31, M \neq 0
|
||
\end{cases}
|
||
\]
|
||
+++++++++++++++++++
|
||
----
|
||
|
||
|
||
[[writingstyle-example]]
|
||
== An Example Command Description
|
||
|
||
The <<sample-command,next section>> is a sample based on the Specification,
|
||
and describes a command in enough detail to see the different usage patterns
|
||
and layout / markup used. Informative notes discussing markup and guidelines
|
||
are interspersed with the example description to explain how and why it
|
||
looks as it does.
|
||
|
||
|
||
[[sample-command]]
|
||
== Sample Command Description: Creating Command Pools
|
||
|
||
To create a command pool, call:
|
||
|
||
[NOTE]
|
||
.Guideline
|
||
====
|
||
Use a short, active sentence when describing what commands do, instead of
|
||
more passive phrasing like ``A command pool is created by calling:'' or ``The
|
||
application may create a command pool by calling:''.
|
||
====
|
||
|
||
include::../protos/vkCreateCommandPool.txt[]
|
||
|
||
[NOTE]
|
||
.Guideline
|
||
====
|
||
After the description, include the autogenerated prototype for the command
|
||
from the `../protos/` directory:
|
||
|
||
include::../protos/vkCreateCommandPool.txt[]
|
||
|
||
Note that each autogenerated command, enumeration, flag, or structure
|
||
definition include file also defines a corresponding asciidoc anchor which
|
||
is the base name of the file. In this case, the anchor is named
|
||
`vkCreateCommandPool`.
|
||
====
|
||
|
||
* pname:device is the logical device that the command pool is created on.
|
||
* pname:pCreateInfo points to an instance of the
|
||
slink:VkCommandPoolCreateInfo structure containing information used to
|
||
create the command pool.
|
||
* pname:pAllocator controls host memory allocation as described in the
|
||
<<memory-allocation, Memory Allocation>> chapter.
|
||
* pname:pCommandPool points to a handle in which the created command pool
|
||
object is returned.
|
||
|
||
[NOTE]
|
||
.Guideline
|
||
====
|
||
Each command parameter is described in a separate bullet list entry,
|
||
followed by validity rules, then detailed descriptions of any new
|
||
structures, flags, or enumerations introduced by this command.
|
||
|
||
Each parameter should appear as a separate bullet list item beginning with
|
||
the parameter name, in the same order as parameters appear in the command.
|
||
This aids in extracting short descriptions of parameters for inclusion in
|
||
annotated headers and similar documentation. Make sure to tag each parameter
|
||
with the pname{cl} macro.
|
||
|
||
Strive for compact notation, and in particular always try to use the
|
||
phrasing ``pname{cl}param _is_'' rather than wordier forms such as
|
||
``pname{cl}param _specifies_'' or ``The pname{cl}param parameter specifies''. In
|
||
general there is no need to describe a parameter which is a Vulkan object
|
||
handle *as* a handle; for example, say ``pname{cl}device is the logical
|
||
device'' rather than ``pname{cl}device is a handle to the logical device''. An
|
||
exception is object creation functions, where a pointer to a handle of the
|
||
proper type is used to return the newly created object.
|
||
====
|
||
|
||
include::../validity/protos/vkCreateCommandPool.txt[]
|
||
|
||
[NOTE]
|
||
.Guideline
|
||
====
|
||
Parameter and member validation language for commands and structures is also
|
||
autogenerated from vk.xml, and included from the `../validity/` directories:
|
||
|
||
include::../validity/protos/vkCreateCommandPool.txt[]
|
||
====
|
||
|
||
The sname:VkCommandPoolCreateInfo structure is defined as follows:
|
||
|
||
include::../structs/VkCommandPoolCreateInfo.txt[]
|
||
|
||
[NOTE]
|
||
.Guideline
|
||
====
|
||
Structures and enumerations first used as parameters of a command are
|
||
described next, by including the autogenerated interface file for that
|
||
structure or enumeration:
|
||
|
||
include::../structs/VkCommandPoolCreateInfo.txt[]
|
||
|
||
====
|
||
|
||
* pname:sType is the type of this structure.
|
||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||
* pname:flags is a combination of bitfield flags indicating usage behavior
|
||
for the pool and command buffers allocated from it. Possible values
|
||
include:
|
||
+
|
||
--
|
||
include::../enums/VkCommandPoolCreateFlagBits.txt[]
|
||
|
||
** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers
|
||
allocated from the pool will be short-lived.
|
||
** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether
|
||
command buffers allocated from the pool can: be individually reset.
|
||
--
|
||
* pname:queueFamilyIndex designates a queue family. Command buffers in
|
||
this command pool must: be submitted on queues from the same family.
|
||
|
||
[NOTE]
|
||
.Guideline
|
||
====
|
||
Each structure member is described in a separate bullet list entry. For the
|
||
stext:Vk*CreateInfo structures in particular, there is standard boilerplate
|
||
for the pname:sType and pname:pNext members, followed by the members
|
||
specific to the structure.
|
||
|
||
----
|
||
* pname:sType is the type of this structure.
|
||
* pname:pNext is `NULL` or a pointer to an
|
||
extension-specific structure.
|
||
----
|
||
|
||
In some cases, such as when the type of a member is itself a new type, the
|
||
entry will cover multiple paragraphs. In these cases the normal list nesting
|
||
and indentation guidelines cannot be applied due to limitations of the
|
||
asciidoc parser. It is usually best to append a block following the first
|
||
paragraph of such a list item:
|
||
|
||
----
|
||
* pname:flags is a combination of bitfield flags
|
||
indicating usage behavior for the pool and
|
||
command buffers allocated from it. Possible
|
||
values include:
|
||
+
|
||
--
|
||
\include::../enums/VkCommandPoolCreateFlagBits.txt[]
|
||
|
||
** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT
|
||
indicates that command buffers allocated
|
||
from the pool will be short-lived.
|
||
** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT
|
||
controls whether command buffers allocated from
|
||
the pool can: be individually reset.
|
||
--
|
||
----
|
||
====
|
||
|
||
include::../validity/structs/VkCommandPoolCreateInfo.txt[]
|
||
|
||
[NOTE]
|
||
.Guideline
|
||
====
|
||
Following the definition of structure members, include the validity language
|
||
for this structure:
|
||
|
||
include::../validity/structs/VkCommandPoolCreateInfo.txt[]
|
||
====
|
||
|
||
|
||
// = API Naming Conventions
|
||
//
|
||
// It's not clear these belong in this document. They are currently
|
||
// captured in the member Wiki under API_Design/Cleanup
|
||
//
|
||
// If they do go here, we would discuss naming conventions starting with
|
||
// prefixes, camelCase, suffixes for size and arrayness, choice of names for
|
||
// similar parameters, templates for CreateInfo structs, parameter naming &
|
||
// ordering (especially length/array pointer pairs), etc.
|
||
|
||
|
||
= To Be Done
|
||
|
||
* Something about Image formats
|
||
* Something about validation scripts
|
||
* Something about pictures
|
||
* Glossary lists
|
||
* New param/enum macros
|
||
|
||
= Revision History
|
||
|
||
* February 16, 2016 - Place asciidoc conversion post-release.
|
||
* February 9, 2016 - Added quotation mark convention.
|
||
* February 1, 2016 - add the Oxford Comma section and issue resolution.
|
||
* January 26, 2016 - add bullet-list style description of command parameters.
|
||
* January 11, 2016 - add ``Numbers in Text'' section from WSI work.
|
||
* December 16, 2015 - Make ``begin / end'' preferred terms to ``start /
|
||
finish''.
|
||
* December 15, 2015 - Make ``implementation'' preferred term instead of
|
||
``system''.
|
||
* December 13, 2015 - Add tlink{cl}/tname{cl} macros for function pointer
|
||
types.
|
||
* December 10, 2015 - Initial release for feedback.
|