480 lines
17 KiB
Plaintext
480 lines
17 KiB
Plaintext
[[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/
|
|
|
|
=== 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. For example:
|
|
|
|
*Correct:* color, signaled.
|
|
|
|
*Incorrect:* colour, signalled.
|
|
|
|
The following word is an exception to this convention, for historical
|
|
reasons:
|
|
|
|
.Spelling Exceptions
|
|
[width="100%",options="header",cols="20%,80%"]
|
|
|=====
|
|
| tessellation
|
|
|=====
|
|
|
|
|
|
=== Compound Words and Preferred Orthography
|
|
|
|
Unless there's longstanding precedent in computer science literature, don't
|
|
arbitrarily cram terms together. Note that this doesn't apply to parameter
|
|
names, where capitalization is used to distinguish words. For example, it's
|
|
proper to refer to the use of a pname:colorSpace member of a structure as a
|
|
'color space' value.
|
|
|
|
.Spelling
|
|
[width="100%",options="header"]
|
|
|=====
|
|
| Use Spelling | Instead Of | Comments
|
|
| bit plane | bitplane |
|
|
| color space | colorspace |
|
|
| double-buffer | doublebuffer |
|
|
| flat shading | flatshading |
|
|
| GitHub | Github | Site's preferred spelling
|
|
| LOD | lod | Acronym for ``Level Of Detail''
|
|
| mip level / layer / size / tail | miplevel / miplayer / mipsize / miptail | Probably ``mipmap *term*'' is better
|
|
|=====
|
|
|
|
The following compound words are exceptions to the compound word rule, for
|
|
historical reasons:
|
|
|
|
.Spelling Exceptions
|
|
[width="100%",options="header",cols="20%,80%"]
|
|
|=====
|
|
| mipmap
|
|
| swapchain
|
|
|=====
|
|
|
|
// also: premultiply preorder prerotation predefin
|
|
|
|
When use 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 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 API Specification>>. Do not vary from them without
|
|
compelling need.
|
|
|
|
Normative parts of the <<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 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 \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}
|
|
\]
|
|
+++++++++++++++++++
|
|
----
|
|
|
|
|
|
[[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 *perform 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 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 comment delimiting the language for
|
|
<<writing-refpages,automatic extraction into a 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 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.
|
|
* 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]*
|
|
----
|
|
|
|
All elements specifying an interface name (+refBegin+ 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.
|