// Copyright (c) 2015-2018 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 <> 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`". [source,asciidoc] .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 <>. For example, if you wanted to say: A ename:VK_ERROR_DEVICE_LOST error the correct way to mark this up in asciidoc would be: [source,asciidoc] ---- 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 [source,asciidoc] ---- 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-arrays]] === Describing Properties of Array Elements Many Vulkan parameters are arrays, or pointers to arrays. When describing array elements, use the terminology "`each element`" when the description applies uniformly and independently to every element of the array. For example: [source,asciidoc] .Example Markup ---- * Each element of the pname:pCommandBuffers member of each element of pname:pSubmits must: be in the <>. ---- Use the terminology "`any element`" when the description is of zero or more elements of the array sharing a property. For example: [source,asciidoc] .Example Markup ---- * If any element of the pname:pCommandBuffers member of any element of pname:pSubmits was not recorded with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in the <>. ---- Never use the redundant terminology "`any *given* element`". [[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 + level of detail + level-of-detail| 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 | pname:pNext chain | pname:pNext-chain + pname:pNext extension chain | | general-purpose | general purpose| When used as an adjective | swapchain | swap chain | Exception due to heavy use in WSI extensions | happen-before + happen-after | happen before + happen after | As used in concurrent languages such as C++11, Java and OpenCL C. |==== ==== Words With "Pre-" Prefixes // also: premultiply preorder prerotation predefined 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. This list is not intended to be complete. [[writing-describing]] == Describing Commands and Parameters The <> 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; enumerated types specifying values or bitmasks which affect the operation of a command; or structures containing combinations of scalar types and objects. The templates and examples shown and annotated here are based on the <>. Do not vary from them without compelling need. Normative parts of the <> 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 `NULL` may: be used for pointer parameters and members and dispatchable object handles, and the reserved value dname:VK_NULL_HANDLE may: be used for non-dispatchable Vulkan 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 <> using <>. [[writing-latexmath]] == Math Markup There is a considerable amount of math in the documentation, ranging from simple arithmetic expressions to complicated conditionals. There are two ways of marking up math expressions, described below. === Asciidoc Math Markup Where possible, math is marked up using straight asciidoc features. For commonality with LaTeX math (see below), some common LaTeX operators and names are defined as asciidoc attributes using the same names, expanding to the corresponding Unicode entities. The complete set of these attributes is found in `config/attribs.txt`. .Spelling [width="100%",options="header",cols="20%,20%,60%"] |==== | Feature | Result | Sample Markup | Subscripts | [eq]#a~x~# | +++[eq]#a~x~#+++ | Superscripts | [eq]#-2^(b-1)^# | +++[eq]#-2^(b-1)^#+++ | Struct/parameter names as variables | [eq]#2^pname:bits^# | +++[eq]#2^pname:bits^#+++ | Greek Letters (selected) | [eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, {rho}, {tau}# | +++[eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, {rho}, {tau}#+++ | Fractions | [eq]#{onequarter} + {onehalf}# | +++[eq]#{onequarter} + {onehalf}#+++ | Closed Ranges | [eq]#[0,1]# | +++[eq]#[0,1]#+++ | Open Ranges | [eq]#[0,1)# | +++[eq]#[0,1)#+++ | Arithmetic and Relational Operators | [eq]#a {times} b#, [eq]#a {leq} b#, [eq]#a {neq} b#, [eq]#a {geq} b#, [eq]#{vert}x{vert}# | +++[eq]#a {times} b#+++, +++[eq]#a {leq} b#+++, +++[eq]#a {neq} b#+++, +++[eq]#a {geq} b#+++, +++[eq]#{vert}x{vert}#+++ | Floor | [eq]#{lfloor}w - {onehalf}{rfloor}# | +++[eq]#{lfloor}w - {onehalf}{rfloor}#+++ | Ceiling | [eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1# | +++[eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1#+++ | Logical and Set Operators | [eq]#{land} {lnot} {lor} {oplus} {elem}# | +++[eq]#{land} {lnot} {lor} {oplus} {elem}#+++ | Partial Derivatives | [eq]#{partial}r~x~ / {partial}x = 0# | +++[eq]#{partial}r~x~ / {partial}x = 0#+++ | Matrix/Vector Parameter Names | [eq]#**P** = t **P**~1~ + (1-t) **P**~2~# | +++[eq]#**P** = t **P**~1~ + (1-t) **P**~2~#+++ |==== === LaTeX Math Markup Math markup more complex than easily supported in straight asciidoc markup (examples found in the Vulkan Specification include matrices, tensors, summation notation, conditional assignments, and division of complex expressions) are marked up using LaTeX math notation, which is either passed through to the KaTeX in-browser rendering script for HTML outputs, or passed through asciidoctor-mathematical for PDF outputs. [NOTE] .Note ==== There are font and style differences between LaTeX and asciidoc math markup which lead to minor visual inconsistencies. We'll try to make this better over time, but it's not significant enough to be a big priority. ==== 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:[\frac{1 - \frac{x}{2}}{x - 1}] * latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2.] [source,asciidoc] .Example Markup ---- * latexmath:[[0,1\]] * latexmath:[\frac{1 - \frac{x}{2}}{x - 1}] * latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{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 `aligned` environment to delimit the expression. [latexmath] +++++++++++++++++++ \begin{aligned} c_{RGB} & = \begin{cases} \frac{c_{sRGB}}{12.92} & \text{for}\ c_{sRGB} \leq 0.04045 \\ \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \text{for}\ c_{sRGB} > 0.04045 \end{cases} \end{aligned} +++++++++++++++++++ [source,asciidoc] .Example Markup ---- [latexmath] +++++++++++++++++++ \begin{aligned} c_{RGB} & = \begin{cases} \frac{c_{sRGB}}{12.92} & \text{for}\ c_{sRGB} \leq 0.04045 \\ \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \text{for}\ c_{sRGB} > 0.04045 \end{cases} \end{aligned} +++++++++++++++++++ ---- [NOTE] .Note ==== The KaTeX processor used to render LaTeX math inside HTML documents does not support all features of LaTeX math. Similarly, the asciidoctor-mathematical processor does not support everything, though does have some support for AMSMath. Some workarounds we've had to make are: .LaTeX math replacements for KaTeX compatibility [width="70%",options="header",cols="20%,20%,60%"] |==== | Replace | With | Comments | `\begin{equation}` | _nothing_ | Unnecessary in blocks. Should not be used for inline. | `\end{equation}` | _nothing_ | Unnecessary in blocks. Should not be used for inline. | `\begin{align*}` | `\begin{aligned}` | | `\end{align*}` | `\end{aligned}` | | `\operatorname{foo}` | `\mathbin{foo}` | | `{\rm A}` | `\mathrm{A}` | | `\text{for }` | `\text{for}\ ` | Text ending in spaces is unpredictable - favour escaped spaces after text |==== See https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX for a list of currently supported LaTeX functionality in KaTeX. You can also use the live katex preview tool on the KaTeX website to double check support, without building the whole spec: https://khan.github.io/KaTeX/ See https://github.com/gjtorikian/mtex2MML/blob/master/SUPPORTED.md for the list of supported operations in the PDF build. \mathop in particular is not supported properly by the PDF build, but most other standard functionality is included. It is necessary to cross reference these two to make sure that support exists before using anything, but almost all standard functionality is supported for both. ==== This example is among the most complex expressions in the Vulkan specification: [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} +++++++++++++++++++ [source,asciidoc] .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-latexmath-in-table-cells]] === LaTeX Math in Table Cells To use `[latexmath]` or `latexmath{cl}` constructs inside table cells, the cell separator must be `a|` instead of just `|`: [source,asciidoc] .Example Markup ---- .Advanced Blend Overlap Modes [width="80%",options="header"] |==== | Overlap Mode | Weighting Equations | ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT a| [latexmath] ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ \begin{aligned} p_0(A_s,A_d) & = A_sA_d \\ p_1(A_s,A_d) & = A_s(1-A_d) \\ p_2(A_s,A_d) & = A_d(1-A_s) \\ \end{aligned} ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ---- [[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: [source,asciidoc] ---- 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 <> is a sample based on the <>, 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 // Three dashes are used here to allow the inner [source] block to show the // correct two dashes. [open,refpage='VkCreateCommandPool',desc='Create a new command pool object',type='protos'] -- To create a command pool, call: include::../api/protos/vkCreateCommandPool.txt[] [NOTE] .Guideline ==== Begin the command description with an open block delimiting the contents as a reference page. The open block contains several required attribute values, as described for <>. 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: // The 'subs=attributes+' and '{blank}--' are one way to allow the inner // [source] block to show the correct two dashes. See // http://discuss.asciidoctor.org/Another-markup-escaping-question-td5665.html [source,asciidoc,subs=attributes+] ---- [open,refpage='VkCreateCommandPool',desc='Create a new command pool object',type='protos'] {blank}-- 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 <> 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 ==== Some parameter and member validation language for commands and structures is _implicit_ (autogenerated from `vk.xml`), and included from the `../validity/` directories. All Vulkan command and structure language should include the autogenerated file at the end of their descriptions. It is harmless to include a nonexistent file, in the rare cases where no implicit validity language exists. [source,asciidoc,subs=attributes+] ---- \include::../validity/protos/vkCreateCommandPool.txt[] {blank}-- ---- End the open block surrounding the command description after the implicit validity include. All content within the block will be extracted for the corresponding reference page. [NOTE] .Guideline ==== Open blocks delimiting reference page content should not themselves contain section headers, as asciidoctor can't render such nested content correctly. Reference pages should in general be relatively short, so this limitation is not severe. ==== Structures and enumerations first used as parameters of a command are described next. ==== // Three dashes are used here to allow the inner [source] block to show the // correct two dashes. [open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] -- The sname:VkCommandPoolCreateInfo structure is defined as: include::../api/structs/VkCommandPoolCreateInfo.txt[] [NOTE] .Guideline ==== Begin the structure description with an open block delimiting the contents as a reference page, in the same fashion as described above for commands. The open block contains several required attribute values, as described for <>. 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: [source,asciidoc,subs=attributes+] ---- [open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] {blank}-- 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 bitmask of elink:VkCommandPoolCreateFlagBits indicating usage behavior for the pool and command buffers allocated from it. * pname:queueFamilyIndex designates a queue family as described in section <>. All command buffers allocated from this command pool must: be submitted on queues from the same queue 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. [source,asciidoc] ---- * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating usage behavior for the pool and command buffers allocated from it. * pname:queueFamilyIndex designates a queue family as described in section <>. All command buffers allocated from this command pool must: be submitted on queues from the same queue family. ---- These entries should be short and functional, without describing details of e.g. new enumerant values, function of individual parameter settings, etc. They can refer to other types using the appropriate *link: macros or to related sections of the specification using asciidoc xrefs. In rare cases, an 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: // @@@ Use VkCommandBufferInheritanceInfo:framebuffer for a current example instead ifdef::editing-notes[] [NOTE] .editing-note ==== This example is obsolete and incorrect. Use VkCommandBufferInheritanceInfo:framebuffer for a current example instead. ==== endif::editing-notes[] [source,asciidoc,subs=attributes+] ---- * pname:flags is a bitmask indicating usage behavior for the pool and command buffers allocated from it. Bits which can: be set include: + {blank}-- // refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool \include::../api/enums/VkCommandPoolCreateFlagBits.txt[] {blank}-- + ** 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. ---- ==== .Valid Usage **** * [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] pname:queueFamilyIndex must: be the index of a queue family available in the calling command's pname:device parameter **** [NOTE] .Guideline ==== In addition to implicit validity language, there may be additional validation language which is explicit. Such language is written in a separate block in the specification, _preceding_ the validity include. The fname:vkCreateCommandPool example above has no such explicit language, but this example does have explicit language. ==== include::../validity/structs/VkCommandPoolCreateInfo.txt[] -- [NOTE] .Guideline ==== Following the definition of structure members, add explicit validity language, following by including the implicit (automatically generated) validity language include for this structure: [source,asciidoc] ---- .Valid Usage **** * [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] pname:queueFamilyIndex must: be the index of a queue family available in the calling command's pname:device parameter **** \include::../validity/structs/VkCommandPoolCreateInfo.txt[] ---- Each explicit Valid Usage statement should be a single, self-contained assertion, possibly involving multiple subexpressions or parameters. For example, instead of writing "`width, height, and depth must: all be greater than zero`", write each condition as a separate statement. In contrast, "`width {times} height must: be less than 1024`" is a single assertion involving multiple parameters. Do not use "`unless`" to call out exceptions - always write valid usage statements of the form "`if _A_ then _B_`". This may result in harder to read statements in a few cases, but maintains consistency. In many cases, it may lead to a simpler VU statement, or splitting one large VU into multiple new ones. Do not use nested lists or other writing structure where Valid Usage statements are not self-contained. This would make it impossible to extract semantically meaningful descriptions for each assigned <>. Be clear on the distinction between a "`valid pointer`" and a "`pointer to a valid object`" when writing Valid Usage statements. See the "`Valid Usage`" section of the Vulkan Specification, and particularly the "`Valid Usage for Pointers`" section. Explicit Valid Usage statements must be assigned Valid Usage ID tags before publication. This process is described in the <> appendix, but is normally performed only when preparing to integrate functionality into the Vulkan Specification prior to publication. It is something authors of new functionality should be aware of, but are not themselves responsible for. For example, when writing the explicit pname:queueFamilyIndex statement shown above, the tag [source,asciidoc] ---- [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] ---- was inserted by a script, not the original author. ==== [[writing-empty-enumerations]] == Markup For Empty Enumerated Types Sometimes an enumerated type has all values defined by extensions, and each enumerated value defined by the type will be surrounded by an asciidoc conditional for the corresponding extension. When a specification is built without any of those extensions enabled, the type should still be included, even though it is empty. In this case, the enumerated value descriptions must be followed by one additional conditional section which is only included when *none* of the relevant extensions are enabled. For example, the relevant part of the elink:VkDescriptorSetLayoutCreateFlagBits description, whose only value is defined by an extension, will look like this: [source,asciidoc,subs=attributes+] ---- \include::../api/enums/VkDescriptorSetLayoutCreateFlagBits.txt[] \ifdef::VK_KHR_push_descriptor[] * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR specifies that descriptor sets must: not be allocated using this layout, and descriptors are instead pushed by flink:vkCmdPushDescriptorSetKHR. \endif::VK_KHR_push_descriptor[] \ifndef::VK_KHR_push_descriptor[] [NOTE] .Note ==== All bits for this type are defined by extensions, and none of those extensions are enabled in this build of the specification. ==== \endif::VK_KHR_push_descriptor[] ---- [[writing-refpages]] == Markup For Automatic Reference Page Extraction The Vulkan reference pages are (mostly) 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 an asciidoc `open` block surrounding markup describing that page, with attributes used to specify properties of the reference page. Additional heuristics and non-asciidoc tags, described below, are used to identify subsections of a reference page in some cases. In general the open block introduction will look like: [source,asciidoc] ---- [open,refpage='name',desc='short description',type='pagetype',xrefs='xrefs'] -- ---- Attributes which can be set on the block are: * *refpage* - the name of the reference page, e.g. the Vulkan interface (command, structure, enumerant, handle, etc.) name. This attribute is required. * *desc* - short description / summary of the page, used in the page title. This attribute is required. * *type* - type of the interface, which must match the directory name following `api/` in the interface `include::` line within the block, and must be one of `basetypes`, `defines`, `enums`, `flags`, `funcpointers`, `handles`, `protos`, or `structs`. This attribute is required. * *xrefs* - list of whitespace-separated names of other reference pages which should be added to the `See Also` section of this page. Most cross-references are automatically generated based on the immediate dependency information in `vk.xml`, but in some cases, such as referring between `*FlagBits` and `*Flags` types, this additional tagging is useful. This attribute is optional. Attributes of the open block must be written in this format, using single quotes as delimiters (even though asciidoc markup also allows double quotes), and escape single quotes in e.g. the *desc* attribute value with backquotes. After the open block is started, the following markup should be provided: * A single paragraph of text describing the definition of the interface. This paragraph is optional, but strongly recommended. * The `include` line for the interface, which must be consistent with the page name and type in the open block attributes. This paragraph is required. * 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. This list is required, unless the interface has nothing to describe, such as an empty structure or enumeration, or a function with no parameters. * Paragraphs of text making up the `Description` section of the ref page. This section is optional. 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: + [source,asciidoc] ---- // refBody ---- + * An explicit Valid Usage block. This block is required if the interface has such Valid Usage constraints. * The `include` line for the implicit valid usage block. This line is required for for commands and structures, but not for interfaces such as enumerated types, which do not have implicit valid usage blocks. * Finally, a two-dash asciidoc delimiter closing the open block: + [source,asciidoc] ---- -- ---- 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 (open block `refpage` attributes, interface `include` lines, and validity `include` lines) 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 - and the language will be structurally incorrect, as well. 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.