562 lines
19 KiB
Plaintext
562 lines
19 KiB
Plaintext
// Copyright (c) 2015-2016 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[[writing]]
|
|
= Writing Style
|
|
|
|
|
|
[[writing-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/
|
|
|
|
|
|
=== Date Format
|
|
|
|
Whenever possible, write dates in the <<iso-8601,ISO 8601>> format:
|
|
YYYY-MM-DD.
|
|
|
|
If needed for consistency with existing dates, e.g.
|
|
in appendix changelogs, you can also write ``Month DD, YYYY'' where
|
|
``Month'' is the English name of the month.
|
|
|
|
Never use ambigious formats such as ``09/12/16''.
|
|
|
|
.Example Markup
|
|
----
|
|
* 2016-09-12
|
|
* September 12, 2016
|
|
----
|
|
|
|
|
|
[[writing-misc-a-an]]
|
|
=== A/An and Markup Macros
|
|
|
|
Use ``a'' and ``an'' http://www.grammar.com/a-vs-an-when-to-use/[correctly],
|
|
based on the *sound* of the letter beginning the following word.
|
|
|
|
It is easy to get this wrong when talking about Vulkan API names tagged with
|
|
the <<markup-macros,markup macros>>.
|
|
For example, if you wanted to say:
|
|
|
|
A VK_ERROR_DEVICE_LOST error
|
|
|
|
the correct way to mark this up in asciidoc would be:
|
|
|
|
A ename:VK_ERROR_DEVICE_LOST error
|
|
|
|
However, on first glance at this it *appears* wrong, because the ``word''
|
|
following ``a'' is the macro name, ``ename{cl}''.
|
|
That starts with a vowel, so the temptation is to say
|
|
|
|
An ename:VK_ERROR_DEVICE_LOST error may occur.
|
|
|
|
What matters here is how the *output* document is formatted.
|
|
|
|
|
|
=== 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 bitmask ``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.''
|
|
|
|
|
|
=== Use American Spelling Conventions
|
|
|
|
In case of conflict, use American rather than British spelling conventions,
|
|
except for noted exceptions in the table below.
|
|
|
|
.Spelling
|
|
[width="60%",options="header"]
|
|
|====
|
|
| Use Spelling | Instead Of | Comments
|
|
| color | colour |
|
|
| signaled | signalled |
|
|
| tessellation | tesselation | Historical exception
|
|
|====
|
|
|
|
|
|
[[writing-compound-words]]
|
|
=== Compound Words and Preferred Orthography
|
|
|
|
Unless there is longstanding precedent in computer science literature, or
|
|
the word is a noted exception in the table below, do not arbitrarily cram
|
|
terms together.
|
|
|
|
This does not apply to parameter names in the API, where capitalization is
|
|
used to distinguish words.
|
|
For example, it is proper to refer to the use of a pname:colorSpace member
|
|
of a structure as a ``color space'' value.
|
|
|
|
.Spelling
|
|
[width="70%",options="header",cols="20%,20%,60%"]
|
|
|====
|
|
| Use Spelling | Instead Of | Comments
|
|
| bit plane | bitplane |
|
|
| compile time | compile-time | Per Wikipedia ``compile time''
|
|
| color space | colorspace |
|
|
| double-buffer | doublebuffer |
|
|
| entry point | entry-point
|
|
| Except if needed to disambiguate from surrounding terms
|
|
| flat shading | flatshading |
|
|
| GitHub | Github | Site's preferred spelling
|
|
| LOD | lod | Acronym for ``Level Of Detail''
|
|
| mip level +
|
|
mip layer +
|
|
mip size +
|
|
mip tail
|
|
| miplevel +
|
|
miplayer +
|
|
mipsize +
|
|
miptail | ``mipmap *term*'' may be used in time
|
|
3+h| Exceptions
|
|
| mipmap | mip map | Exception for historical reasons
|
|
| swapchain | swap chain | Exception due to heavy use in WSI extensions
|
|
|====
|
|
|
|
==== Words With "Pre-" Prefixes
|
|
|
|
// also: premultiply preorder prerotation predefin
|
|
|
|
When using the prefix ``pre'' to indicate ``prior to'', such as in the words
|
|
``preinitialized'', ``preprocess'', and ``pretransform'', do not separate
|
|
the prefix from the word with a hyphen.
|
|
|
|
|
|
[[writing-describing]]
|
|
== Describing Commands and Parameters
|
|
|
|
The <<vulkan-spec,Vulkan API 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
|
|
<<vulkan-spec,Vulkan API Specification>>.
|
|
Do not vary from them without compelling need.
|
|
|
|
Normative parts of the <<vulkan-spec,Vulkan API Specification>> should
|
|
describe _what_ something does, rather than _how_ or _why_ an application
|
|
would want to use it.
|
|
|
|
When explicitly allowed by the Specification, the reserved value code:NULL
|
|
may: be used for Vulkan dispatchable objects, pointer parameters and
|
|
members, and the reserved value dname:VK_NULL_HANDLE may: be used for Vulkan
|
|
non-dispatchable object handle parameters and members.
|
|
Otherwise, pointers and handles must: refer to valid memory and valid Vulkan
|
|
objects, respectively.
|
|
|
|
|
|
[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
|
|
<<vulkan-spec,Vulkan API Specification>> using
|
|
<<markup-informative-notes,informative notes>>.
|
|
|
|
|
|
[[writing-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 do not have 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 \times 0 = 0 \times x = 0$]
|
|
* latexmath:[${\textbf c} = t {\textbf c}_1 + (1-t){\textbf c}_2.
|
|
$]
|
|
|
|
.Example Markup
|
|
----
|
|
latexmath:[$[0,1\]$]
|
|
latexmath:[$x \times 0 = 0 \times 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}
|
|
\]
|
|
+++++++++++++++++++
|
|
----
|
|
|
|
|
|
[[writing-pNext-chain]]
|
|
== Describing Extension Structure Chains
|
|
|
|
When describing an extension structure which is passed to an existing
|
|
command by placing it in the pname:pNext chain of a structure parameter of
|
|
that command, introduce the structure description in this fashion:
|
|
|
|
When *performing an operation described by the extension struct*, add
|
|
the slink:VkExtensionStructNameID to the pname:pNext chain of the
|
|
slink:VkBaseExtensionStructName structure passed to the
|
|
flink:vkBaseFunctionName command *saying what the extension struct
|
|
does*.
|
|
|
|
|
|
[[writing-example]]
|
|
== An Example Command Description
|
|
|
|
The <<sample-command,next section>> is a sample based on the
|
|
<<vulkan-spec,Vulkan API 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
|
|
|
|
// refBegin vkCreateCommandPool Create a new command pool object
|
|
|
|
To create a command pool, call:
|
|
|
|
include::../api/protos/vkCreateCommandPool.txt[]
|
|
|
|
[NOTE]
|
|
.Guideline
|
|
====
|
|
Begin the command description with a comment delimiting the language for
|
|
<<writing-refpages,automatic extraction into a reference page>>.
|
|
|
|
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:''.
|
|
|
|
After the description, include the autogenerated prototype for the command
|
|
from the `../protos/` directory:
|
|
|
|
// refBegin vkCreateCommandPool Create a new command pool object
|
|
|
|
To create a command pool, call:
|
|
|
|
include::../api/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[]
|
|
|
|
Structures and enumerations first used as parameters of a command are
|
|
described next.
|
|
====
|
|
|
|
// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of a newly created command pool
|
|
|
|
The sname:VkCommandPoolCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkCommandPoolCreateInfo.txt[]
|
|
|
|
[NOTE]
|
|
.Guideline
|
|
====
|
|
Begin the structure description with a +refBegin+ comment delimiting the
|
|
language for <<writing-refpages,automatic extraction into a reference page>>
|
|
and including a summary line for the reference page.
|
|
|
|
Use a short, active paragraph to introduce the structure, usually just ``The
|
|
sname:VkStructureName structure is defined as:''.
|
|
|
|
After the description, include the autogenerated definition for the
|
|
structure from the `../structs/` directory:
|
|
|
|
// refBegin VkCommandPoolCreateInfo - Structure specifying parameters of
|
|
a newly created command pool
|
|
|
|
The sname:VkCommandPoolCreateInfo structure is defined as:
|
|
|
|
include::../api/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 bitmask flags indicating usage behavior
|
|
for the pool and command buffers allocated from it.
|
|
Possible values include:
|
|
+
|
|
--
|
|
// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool
|
|
include::../api/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 continuation block following the first
|
|
paragraph of such a list item:
|
|
|
|
----
|
|
* pname:flags is a bitmask indicating usage behavior for the pool and
|
|
command buffers allocated from it. Bits which can: be set include:
|
|
+
|
|
--
|
|
// refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool
|
|
\include::../api/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[]
|
|
====
|
|
|
|
|
|
[[writing-refpages]]
|
|
== Markup For Automatic Reference Page Extraction
|
|
|
|
The Vulkan reference pages are (mostly) being extracted from corresponding
|
|
sections of the API Specification.
|
|
This requires that the markup and writing conventions described above be
|
|
adhered to rigidly.
|
|
|
|
The extraction scripts for a given page rely on the existence of the
|
|
asciidoc +include+ of the autogenerated definition of that command,
|
|
structure, or other API interface element.
|
|
Various heuristics are used to determine which text to extract for that
|
|
page; the general model is:
|
|
|
|
* Optional (but usually specified) comment line specifying the interface
|
|
name and the short description used in the title of the corresponding
|
|
ref page:
|
|
+
|
|
----
|
|
// refBegin name - description
|
|
----
|
|
+
|
|
* A paragraph of text introducing the definition of the interface.
|
|
If the +refBegin+ comment does not exist, this paragraph must be
|
|
present.
|
|
* The +include+ line for the interface, which must be consistent with the
|
|
interface name in the comment line.
|
|
* A bullet list describing function parameters, structure members,
|
|
enumerants in an enumerated type, etc.
|
|
This list should contain no empty lines, as the extraction script
|
|
classifies the uninterrupted block of text following the +include+
|
|
directive as the +Parameters+ or +Members+ section of the ref page.
|
|
* Optional paragraphs of text making up the +Description+ section of the
|
|
ref page.
|
|
If it is necessary due to constraints of asciidoc markup to have an
|
|
empty line in the bullet list section^1^, add a +refBody+ comment
|
|
immediately following the bullet list and preceding this section:
|
|
+
|
|
----
|
|
// refBody name
|
|
----
|
|
+
|
|
* The +include+ line for the validity statement of commands and
|
|
structures.
|
|
Other interfaces such as enumerated types do not have validity
|
|
statements.
|
|
* Comment line specifying the end of the extracted text for the reference
|
|
page and optional page names to link to in the +See Also+ section of the
|
|
page.
|
|
If the validity +include+ is not present, this line must be present:
|
|
+
|
|
----
|
|
// refEnd name [seeAlsoNames]*
|
|
----
|
|
|
|
1::
|
|
The only example of such markup in the 1.0.28 Vulkan Specification
|
|
source is the stext:VkPhysicalDeviceLimits structure description.
|
|
|
|
All elements specifying an interface name (+refBegin+, +refBody+, and
|
|
+refEnd+ comments, interface +include+ line, and validity +include+ line)
|
|
must use the same interface name, if present.
|
|
Otherwise the extraction script is either unable to extract that page, or
|
|
will extract the wrong text.
|
|
The extraction process is somewhat fragile, so care should be taken and the
|
|
results of reference page extraction verified after making changes to that
|
|
portion of the specification source.
|