1// Copyright 2015-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[writing]] 6= Writing Style 7 8New specification language should, whenever possible, closely follow related 9examples in the existing specification documents. 10 11Whenever possible follow existing API design patterns. 12Some specific patterns to follow (this list is very incomplete) include: 13 14 * Behavior of queries which return arrays of unknown length (see e.g. 15 `vkEnumeratePhysicalDevices`). 16 * Behavior of creation commands which create multiple objects at once (see 17 e.g. `vkCreateGraphicsPipelines`). 18 19 20[[writing-misc]] 21== Miscellaneous Grammar, Spelling, and Punctuation Issues 22 23=== Use the Oxford Comma (Serial Comma) 24 25When writing a sentence listing a series of items, include a comma before 26the "`and`" separating the last item. 27 28*Correct:* The red, green, blue, and alpha components. 29 30*Incorrect:* The red, green, blue and alpha components. 31 32Also see this 33link:https://blog.oxforddictionaries.com/2015/01/21/video-oxford-comma/[video 34discussion of the Oxford comma] provided by the Oxford Dictionary. 35 36 37[[writing-titlecase]] 38=== Use AP Title Case for Chapter and Section Titles 39 40Here is a link:https://titlecaseconverter.com/rules/[summary] of the rules: 41 42 * Capitalize the first word and the last word of the title. 43 * Capitalize the principal words. 44 * Capitalize "`to`" in infinitives. 45 * Capitalize all words of four letters or more. 46 * Do not capitalize articles, conjunctions, and prepositions of three 47 letters or fewer. 48 49[NOTE] 50.Note 51==== 52The actual AP style guide is behind a paywall. 53The summary here is from a commercial website. 54==== 55 56 57=== Date Format 58 59Whenever possible, write dates in the <<iso-8601,ISO 8601>> format: 60YYYY-MM-DD. 61 62If needed for consistency with existing dates, e.g. in appendix changelogs, 63you can also write "`Month DD, YYYY`" where "`Month`" is the English name of 64the month. 65 66Never use ambiguous formats such as "`09/12/16`". 67 68[source,asciidoc] 69.Example Markup 70---- 71 * 2016-09-12 72 * September 12, 2016 73---- 74 75 76[[writing-misc-a-an]] 77=== A/An and Markup Macros 78 79Use "`a`" and "`an`" 80link:https://www.grammar.com/a-vs-an-when-to-use/[correctly], based on the 81*sound* of the letter beginning the following word. 82 83It is easy to get this wrong when talking about Vulkan API names tagged with 84the <<markup-macros,markup macros>>. 85For example, if you wanted to say: 86 87A ename:VK_ERROR_DEVICE_LOST error 88 89the correct way to mark this up in asciidoctor would be: 90 91[source,asciidoc] 92---- 93A ename:VK_ERROR_DEVICE_LOST error 94---- 95 96However, on first glance at this it *appears* wrong, because the "`word`" 97following "`a`" is the macro name, "`ename{cl}`". 98That starts with a vowel, so the temptation is to say 99 100[source,asciidoc] 101---- 102An ename:VK_ERROR_DEVICE_LOST error may occur. 103---- 104 105What matters here is how the *output* document is formatted. 106 107 108=== Numbers in Text 109 110When describing the need for a small number of objects, smaller than ten, 111spell the number out (e.g. "`one`"). 112If you are describing a literal value that is a small number, you may use a 113numeric value (e.g. "`1`"). 114 115For example, instead of writing that a bitmask "`contains 1 or more bits`", 116write that it "`contains one or more bits`". 117A counter example is that it is okay to write "`For non-stereoscopic-3D 118applications, this value is 1.`" 119 120 121[[writing-conventions]] 122=== Use American Spelling Conventions 123 124In case of conflict, use American rather than British spelling conventions, 125except for noted exceptions in the table below. 126 127.Spelling 128[width="60%",options="header"] 129|==== 130| Use Spelling | Instead Of | Comments 131| color | colour | 132| signaled | signalled | 133| tessellation | tesselation | Historical exception 134|==== 135 136[NOTE] 137.Note 138==== 139There are a few exceptions to `color` in the Vulkan Video extensions, such 140as ename:VK_VIDEO_ENCODE_H264_CAPABILITY_SEPARATE_COLOUR_PLANE_BIT_EXT. 141This is for because those extensions refer to externally defined video 142compression standards and headers using that spelling. 143==== 144 145 146[[writing-inclusivity]] 147=== Use Inclusive Language 148 149The Vulkan Working Group has begun to apply the 150link:https://www.khronos.org/about/inclusive-language[Khronos Inclusive 151Language] list to our specifications and other documents. 152The Khronos Inclusive Language list contains terms to avoid due to their use 153in discriminatory contexts that make people uncomfortable, or cause 154division. 155 156We are working through the Vulkan Specification repository to make 157appropriate changes, and enhancing the repository continuous integration 158scripts to report questionable terminology usage. 159This process will take some time. 160 161Some files in the repository are incorporated unmodified from external 162projects we do not control, and which may not comply with the Inclusive 163Language list. 164We will ask those projects to update their terminology usage, but cannot 165control their choices. 166 167 168[[writing-pointers-instances]] 169=== Describing Pointers, Handles, Structures, and Arrays 170 171When describing pointer parameters or members, use "`is a pointer to`" 172rather than more informal phrasing such as "`points to`". 173 174When describing individual structures, use "`VkStructname structure`" rather 175than longer phrasing such as "`instance of the VkStructname structure`" or 176"`structure of type VkStructname`". 177 178When describing array parameters or members, use "`is a pointer to an array 179of`" rather than "`is an array of`" unless it is a structure member that is 180a fixed-size array. 181Reference the dynamic size of the array that is pointed to (usually another 182structure member), or the static size for fixed-size arrays, in the 183description. 184 185When describing pointers which may be `NULL`, use "`is `NULL` or a pointer 186to`" rather than "`is an optional pointer`". 187The same principle applies when describing a handle which may be 188dname:VK_NULL_HANDLE. 189"`Optional pointer/handle`" are not well-defined terms in the Specification. 190 191[source,asciidoc] 192.Example Markup 193---- 194 * pname:pInfo is a pointer to a slink:VkDebugUtilsLabelEXT structure 195 specifying the parameters of the label to insert. 196 * pname:pBindInfos is a pointer to an array of pname:bindInfoCount 197 slink:VkBindBufferMemoryInfo structures describing buffers and memory to 198 bind. 199 * pname:pStrides is `NULL` or a pointer to an array 200 of buffer strides. 201 * pname:image is dlink:VK_NULL_HANDLE or a handle of an image which this 202 memory will be bound to. 203---- 204 205 206[[writing-arrays]] 207=== Describing Properties of Array Elements 208 209Many Vulkan parameters are arrays, or pointers to arrays. 210When describing array elements, use the terminology "`each element`" when 211the description applies uniformly and independently to every element of the 212array. 213For example: 214 215[source,asciidoc] 216.Example Markup 217---- 218 * Each element of the pname:pCommandBuffers member of each element of 219 pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or 220 executable state>>. 221---- 222 223Use the terminology "`any element`" when the description is of zero or more 224elements of the array sharing a property. 225For example: 226 227[source,asciidoc] 228.Example Markup 229---- 230 * If any element of the pname:pCommandBuffers member of any element 231 of pname:pSubmits was not recorded with the 232 ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in 233 the <<commandbuffers-lifecycle, pending state>>. 234---- 235 236Never use the redundant terminology "`any *given* element`". 237 238 239[[writing-compound-words]] 240=== Compound Words and Preferred Orthography 241 242Unless there is longstanding precedent in computer science literature, or 243the word is a <<spelling-exception-table, noted exception>>, do not 244arbitrarily combine terms together with hyphens, or as a single compound 245word without hyphens. 246 247This does not apply to parameter names in the API, where capitalization is 248used to distinguish words. 249For example, it is proper to refer to the use of a pname:colorSpace member 250of a structure as a "`color space`" value. 251 252.Spelling 253[width="70%",options="header",cols="20%,20%,60%"] 254|==== 255| Use Spelling | Instead Of | Comments 256| bit plane | bitplane | 257| compile time | compile-time | Per Wikipedia "`compile time`" 258| color space | colorspace | 259| cube map | cubemap | 260| double-buffer | doublebuffer | 261| entry point | entry-point, + 262 entrypoint 263 | Except if needed to disambiguate from surrounding terms 264| flat shading | flatshading | 265| GitHub | Github | Site's preferred spelling 266| indirect (drawing/dispatching) command 267 | indirect command (draw/dispatch) 268 | Even though related commands are named 269 ftext:vk*Draw*Indirect 270| LOD | lod, + 271 level of detail, + 272 level-of-detail| Acronym for "`Level of Detail`" 273| mip level + 274 mip layer + 275 mip size + 276 mip tail 277 | miplevel + 278 miplayer + 279 mipsize + 280 miptail | "`mipmap *term*`" may be used in time 281| render pass | renderpass | 282| reuse | re-use | 283| side effect | side-effect | 284| use case | use-case | 285|==== 286 287[[spelling-exception-table]] 288.Spelling Exceptions 289[width="70%",options="header",cols="20%,20%,60%"] 290|==== 291| general-purpose 292 | general purpose| When used as an adjective 293| happen-before + 294 happen-after | happen before + 295 happen after | As used in concurrent languages such as 296 C++11, Java and OpenCL C. 297| implementation-dependent 298 | implementation dependent 299 | When used as an adjective 300| mipmap | mip map | Exception for historical reasons 301| pname:pNext chain 302 | pname:pNext-chain, + 303 pname:pNext extension chain 304 | 305| swapchain | swap chain | Exception due to heavy use in WSI extensions 306|==== 307 308[NOTE] 309.Note 310==== 311These examples are not complete, and will be added to over time when there 312is reason to. 313 314Different sources and individuals can and do reasonably disagree with regard 315to some of the examples. 316==== 317 318 319==== Words With "Pre-" Prefixes 320 321// also: premultiply preorder prerotation predefined 322 323When using the prefix "`pre`" to indicate "`prior to`", such as in the words 324"`preinitialized`", "`preprocess`", and "`pretransform`", do not separate 325the prefix from the word with a hyphen. 326This list is not intended to be complete. 327 328 329[[writing-references]] 330=== References 331 332When citing external references, use the appropriate <<acm-references, 333Association for Computing Machinery Citation Style>>. 334Most citations in our specifications should follow the _For an online 335document/WWW resource_ style, using the actual date on the document being 336referenced rather than the document retrieval date. 337See the <<vulkan-spec, Vulkan API Specification>> citation in this document 338for an example. 339 340 341[[writing-undefined]] 342== Describing Undefined Behavior 343 344When describing undefined behavior that results only in the values of 345specified variables, or the contents of specified memory, becoming undefined 346or implementation-defined, use the undefined{cl} macro to indicate that each 347use of the term "`undefined`" has been carefully considered and accurately 348represents the degree of undefined behavior allowed. 349 350The word "`undefined`" should not be used without the trailing {cl}. 351This is enforced by internal CI tests. 352 353The undefined{cl} macro does not result in visible markup in the output 354document, and is not itself a normative term. 355The macro is simply markup to help ensure that use of the word has been 356consciously chosen. 357 358When describing more general types of undefined behavior (up to and 359including termination of the application), do *not* use the term 360"`undefined`". 361Instead, specify that the application must{cl} not create circumstances that 362would lead to such behavior. 363Such statements should be written as valid usage statements, if possible. 364 365 366[[writing-describing]] 367== Describing Commands and Parameters 368 369The <<vulkan-spec,Vulkan API Specification>> describes API commands followed 370by descriptions of their parameters, which are usually simple scalar types, 371handles or pointers to Vulkan objects or arrays of objects; enumerated types 372specifying values or bitmasks which affect the operation of a command; or 373structures containing combinations of scalar types and objects. 374The templates and examples shown and annotated here are based on the 375<<vulkan-spec,Vulkan API Specification>>. 376Do not vary from them without compelling need. 377 378Normative parts of the <<vulkan-spec,Vulkan API Specification>> should 379describe _what_ something does, rather than _how_ or _why_ an application 380would want to use it. 381 382When explicitly allowed by the Specification, the reserved value `NULL` may: 383be used for pointer parameters and members and dispatchable object handles, 384and the reserved value dname:VK_NULL_HANDLE may: be used for 385non-dispatchable Vulkan object handle parameters and members. 386Otherwise, pointers and handles must: refer to valid memory and valid Vulkan 387objects, respectively. 388 389 390[NOTE] 391.Guideline 392==== 393As a simple example, say 394 395"`To create a command pool, call fname:vkCreateCommandPool`" 396 397rather than 398 399"`You/The application/The user can create a command pool by calling 400fname:vkCreateCommandPool`". 401==== 402 403Explanations of _why_ and _how_ should largely be confined to reference 404documentation, sample code, tutorials, and other such documents. 405Occasional non-normative explanations can be included in the 406<<vulkan-spec,Vulkan API Specification>> using 407<<markup-informative-notes,informative notes>>. 408 409 410[[writing-describing-errors]] 411=== Commands Which Return Error Codes 412 413Commands which return elink:VkResult values must list all possible error 414codes for the command in the `errorcodes` XML attribute for the command. 415Almost all such commands may return the ename:VK_ERROR_OUT_OF_HOST_MEMORY 416error code. 417Any exceptions to this rule should be carefully considered by the 418specification author, and a rationale for this anomalous behavior may be 419provided in a NOTE or in the Issues section of the extension appendix 420corresponding to the new command. 421 422See the "`Return Codes`" section of the <<vulkan-spec,Vulkan API 423Specification>> for additional information. 424 425 426[[writing-describing-layers]] 427== Extensions and Grouping Related Language 428 429Language specifying behavior of a command or structure that does not 430originate in an extension should be placed in a single contiguous region of 431the specification. 432 433When defining a new command or structure from an extension that introduces 434additional behavior or options, do not insert such new language in a way 435that "`orphans`" part of an existing description by splitting up the 436existing language. 437 438This constraint does not apply to enumerated types. 439Language for new enumerants defined by extensions should be added to the 440existing enumerant definition, <<extensions-documenting-extensions, 441protected by asciidoctor conditionals>> for the new extension. 442 443[NOTE] 444.Guideline 445==== 446Specification language should be structured, whenever possible, so it fits 447into a single open block defining a <<writing-refpages, reference page>>. 448==== 449 450 451[[writing-math]] 452== Math Markup 453 454There is a considerable amount of math in the documentation, ranging from 455simple arithmetic expressions to complicated conditionals. 456There are two ways of marking up math expressions, described below. 457 458 459=== Asciidoc Math Markup 460 461Where possible, math is marked up using straight asciidoctor features. 462For commonality with LaTeX math (see below), some common LaTeX operators and 463names are defined as asciidoctor attributes using the same names, expanding 464to the corresponding Unicode entities. 465The complete set of these attributes is found in `config/attribs.adoc`. 466 467.Spelling 468[width="100%",options="header",cols="20%,20%,60%"] 469|==== 470| Feature | Result | Sample Markup 471 472| Subscripts 473| [eq]#a~x~# 474| +++[eq]#a~x~#+++ 475 476| Superscripts 477| [eq]#-2^(b-1)^# 478| +++[eq]#-2^(b-1)^#+++ 479 480| Struct/parameter names as variables 481| [eq]#2^pname:bits^# 482| +++[eq]#2^pname:bits^#+++ 483 484| Greek Letters (selected) 485| [eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, 486 {rho}, {tau}# 487| +++[eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, 488 {rho}, {tau}#+++ 489 490| Fractions 491| [eq]#{onequarter} {plus} {onehalf}# 492| +++[eq]#{onequarter} {plus} {onehalf}#+++ 493 494| Closed Ranges 495| [eq]#[0,1]# 496| +++[eq]#[0,1]#+++ 497 498| Open Ranges 499| [eq]#[0,1)# 500| +++[eq]#[0,1)#+++ 501 502| Arithmetic and Relational Operators 503| [eq]#a {times} b#, [eq]#a {leq} b#, [eq]#a {neq} b#, [eq]#a {geq} b#, [eq]#{vert}x{vert}# 504| +++[eq]#a {times} b#+++, +++[eq]#a {leq} b#+++, +++[eq]#a {neq} b#+++, +++[eq]#a {geq} b#+++, +++[eq]#{vert}x{vert}#+++ 505 506| Floor 507| [eq]#{lfloor}w - {onehalf}{rfloor}# 508| +++[eq]#{lfloor}w - {onehalf}{rfloor}#+++ 509 510| Ceiling 511| [eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} {plus} 1# 512| +++[eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} {plus} 1#+++ 513 514| Logical and Set Operators 515| [eq]#{land} {lnot} {lor} {oplus} {elem}# 516| +++[eq]#{land} {lnot} {lor} {oplus} {elem}#+++ 517 518| Partial Derivatives 519| [eq]#{partial}r~x~ / {partial}x = 0# 520| +++[eq]#{partial}r~x~ / {partial}x = 0#+++ 521 522| Matrix/Vector Parameter Names 523| [eq]#**P** = t **P**~1~ {plus} (1-t) **P**~2~# 524| +++[eq]#**P** = t **P**~1~ {plus} (1-t) **P**~2~#+++ 525 526|==== 527 528 529[[writing-math-latexmath]] 530=== LaTeX Math Markup 531 532Math markup more complex than easily supported in straight asciidoctor 533markup (examples found in the Vulkan Specification include matrices, 534tensors, summation notation, conditional assignments, and division of 535complex expressions) are marked up using LaTeX math notation, which is 536either passed through to the KaTeX in-browser rendering script for HTML 537outputs, or passed through asciidoctor-mathematical for PDF outputs. 538 539[NOTE] 540.Note 541==== 542There are font and style differences between LaTeX and asciidoctor math 543markup which lead to minor visual inconsistencies. 544We will try to make this better over time, but it is not significant enough 545to be a big priority. 546==== 547 548While LaTeX math macros, including the amsmath package, are supported, 549general LaTeX constructs are not. 550 551_Inline math_ is encoded using the latexmath{cl} macro. 552For example: 553 554 * latexmath:[[0,1\]] 555 * latexmath:[\frac{1 - \frac{x}{2}}{x - 1}] 556 * latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2.] 557 558[source,asciidoc] 559.Example Markup 560---- 561 * latexmath:[[0,1\]] 562 * latexmath:[\frac{1 - \frac{x}{2}}{x - 1}] 563 * latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2. ] 564---- 565 566Note the escaped bracket in markup for the first expression, which is 567necessary to work around asciidoctor macro parsing. 568 569_Block math_ is used for more complex equations. 570This example uses the `aligned` environment to delimit the expression. 571 572[latexmath] 573+++++++++++++++++++ 574\begin{aligned} 575c_{RGB} & = 576 \begin{cases} 577 \frac{c_{sRGB}}{12.92} & \text{for}\ c_{sRGB} \leq 0.04045 \\ 578 \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \text{for}\ c_{sRGB} > 0.04045 579 \end{cases} 580\end{aligned} 581+++++++++++++++++++ 582 583[source,asciidoc] 584.Example Markup 585---- 586[latexmath] 587+++++++++++++++++++ 588\begin{aligned} 589c_{RGB} & = 590 \begin{cases} 591 \frac{c_{sRGB}}{12.92} & \text{for}\ c_{sRGB} \leq 0.04045 \\ 592 \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \text{for}\ c_{sRGB} > 0.04045 593 \end{cases} 594\end{aligned} 595+++++++++++++++++++ 596---- 597 598[NOTE] 599.Note 600==== 601The KaTeX processor used to render LaTeX math inside HTML documents does not 602support all features of LaTeX math. 603 604Similarly, the asciidoctor-mathematical processor does not support 605everything, though does have some support for AMSMath. 606 607Some workarounds we use are: 608 609.LaTeX math replacements for KaTeX compatibility 610[width="70%",options="header",cols="20%,20%,60%"] 611|==== 612| Replace | With | Comments 613| `++\begin{equation}++`, + 614 `++\end{equation}++` | _nothing_ | Unnecessary in blocks. Should not be used for inline. 615| `\begin{align*}` | `++\begin{aligned}++` | 616| `\end{align*}` | `++\end{aligned}++` | 617| `++\operatorname{foo}++` | `++\mathbin{foo}++` | 618| `{\rm A}` | `++\mathrm{A}++` | 619| `\text{for }` | `\text{++for++}\` | Text ending in spaces is unpredictable - favour escaped spaces after text 620|==== 621 622The KaTeX repository provides a 623link:https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX[list of 624currently supported LaTeX functionality]. 625You can also use the link:https://khan.github.io/KaTeX/[live katex preview 626tool] on the KaTeX website to double check support, without building the 627whole specification. 628 629Note that we use a locally-cached copy of KaTeX which may lag the latest 630published version on the website. 631As of April 2021, we are using v0.11.1. 632 633See the mtex2MML repository for a 634link:https://github.com/gjtorikian/mtex2MML/blob/master/SUPPORTED.md[list of 635supported operations in the PDF build]. 636In particular, `\mathop` is not supported properly, but most other standard 637functionality is included. 638 639It is necessary to cross reference these two to make sure that support 640exists before using anything, but almost all standard functionality is 641supported for both. 642==== 643 644This example is among the most complex expressions in the Vulkan 645specification: 646 647[latexmath] 648+++++++++++++++++++ 649V = 650 \begin{cases} 651 (-1)^S \times 0.0, & E = 0, M = 0 \\ 652 (-1)^S \times 2^{-14} \times { M \over 2^{10} }, 653 & E = 0, M \neq 0 \\ 654 (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) }, 655 & 0 < E < 31 \\ 656 (-1)^S \times Inf, & E = 31, M = 0 \\ 657 NaN, & E = 31, M \neq 0 658 \end{cases} 659+++++++++++++++++++ 660 661[source,asciidoc] 662.Example Markup 663---- 664[latexmath] 665+++++++++++++++++++ 666V = 667 \begin{cases} 668 (-1)^S \times 0.0, & E = 0, M = 0 \\ 669 (-1)^S \times 2^{-14} \times { M \over 2^{10} }, 670 & E = 0, M \neq 0 \\ 671 (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) }, 672 & 0 < E < 31 \\ 673 (-1)^S \times Inf, & E = 31, M = 0 \\ 674 NaN, & E = 31, M \neq 0 675 \end{cases} 676+++++++++++++++++++ 677---- 678 679 680[[writing-latexmath-in-table-cells]] 681=== LaTeX Math in Table Cells 682 683To use `[latexmath]` or `latexmath{cl}` constructs inside table cells, the 684cell separator must be `a|` instead of just `|`: 685 686[source,asciidoc] 687.Example Markup 688---- 689.Advanced Blend Overlap Modes 690[width="80%",options="header"] 691|==== 692| Overlap Mode | Weighting Equations 693| ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT a| 694[latexmath] 695++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 696 \begin{aligned} 697 p_0(A_s,A_d) & = A_sA_d \\ 698 p_1(A_s,A_d) & = A_s(1-A_d) \\ 699 p_2(A_s,A_d) & = A_d(1-A_s) \\ 700 \end{aligned} 701++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 702|==== 703---- 704 705 706[[writing-pNext-chain]] 707== Describing Extending Structure Chains 708 709When describing an extending structure which is passed to an existing 710command by including it in the pname:pNext chain of a structure parameter of 711that command, introduce the structure description in this fashion: 712 713[source,asciidoc] 714---- 715When *performing an operation described by the extending structure*, add 716a slink:VkExtensionStructNameID structure to the pname:pNext chain of the 717slink:VkBaseExtensionStructName structure passed to the 718flink:vkBaseFunctionName command *saying what the extending structure 719does*. 720---- 721 722When describing properties of a structure included in a pname:pNext chain, 723refer to that structure as "`included in the pname:pNext chain`" rather than 724`"present in`" or other similar terms, in this fashion: 725 726[source,asciidoc] 727---- 728If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2 729structure, then pname:pEnabledFeatures must: be `NULL` 730---- 731 732 733[[writing-example]] 734== Example Command, Structure, and Enumerant Descriptions 735 736The <<sample-command,next section>> is a sample based on the 737<<vulkan-spec,Vulkan API Specification>>, and describes a command and 738related structures and enumerated types in enough detail to see the 739different usage patterns and layout / markup used. 740Informative notes discussing markup and guidelines are interspersed with the 741example description to explain how and why it looks as it does. 742 743 744[[sample-command]] 745== Sample Command Description: Creating Command Pools 746 747[open,refpage='vkCreateCommandPool',desc='Create a new command pool object',type='protos'] 748-- 749To create a command pool, call: 750 751include::{generated}/api/protos/vkCreateCommandPool.adoc[] 752 753[NOTE] 754.Guideline 755==== 756Begin the command description with an open block delimiting the contents as 757a reference page. 758The open block contains several required attribute values, as described for 759<<writing-refpages, automatic extraction into a reference page>>. 760 761Use a short, active sentence when describing what commands do, instead of 762more passive phrasing like "`A command pool is created by calling:`" or 763"`The application may create a command pool by calling:`". 764 765After the description, include the autogenerated prototype for the command 766from the `\{generated}/api/protos/` directory: 767 768// The 'subs=attributes+' and '{blank}--' are one way to allow the inner 769// [source] block to show the correct two dashes. See 770// https://discuss.asciidoctor.org/Another-markup-escaping-question-td5665.html 771 772[source,asciidoc,subs=attributes+] 773---- 774[open,refpage='vkCreateCommandPool',desc='Create a new command pool object',type='protos'] 775{blank}-- 776To create a command pool, call: 777 778\include::\{generated}/api/protos/vkCreateCommandPool.adoc[] 779---- 780 781Note that each autogenerated command, enumeration, flag, or structure 782definition include file also defines a corresponding asciidoctor anchor 783which is the base name of the file. 784In this case, the anchor is named `vkCreateCommandPool`. 785==== 786 787 * pname:device is the logical device that the command pool is created on. 788 * pname:pCreateInfo is a pointer to a slink:VkCommandPoolCreateInfo 789 structure specifying the state of the command pool object. 790 * pname:pAllocator controls host memory allocation as described in the 791 <<memory-allocation, Memory Allocation>> chapter. 792 * pname:pCommandPool is a pointer to a slink:VkCommandPool handle in which 793 the created pool is returned. 794 795[NOTE] 796.Guideline 797==== 798Describe each command parameter in a separate bullet list item. 799in the same order that parameters appear in the command. 800 801Each description must begin with the parameter name. 802This aids in extracting short descriptions of parameters for inclusion in 803annotated headers and similar documentation. 804Make sure to tag each parameter with the pname{cl} macro. 805 806Strive for compact notation, and in particular always try to use the 807phrasing "`pname{cl}param _is_`" rather than wordier forms such as 808"`pname{cl}param _specifies_`" or "`The pname{cl}param parameter 809specifies`". 810In general there is no need to describe a parameter which is a Vulkan object 811handle *as* a handle; for example, say "`pname{cl}device is the logical 812device`" rather than "`pname{cl}device is a handle to the logical device`". 813An exception is object creation functions, where a pointer to a handle of 814the proper type is used to return the newly created object. 815==== 816 817This is a general description of creating a command pool. 818 819.Valid Usage 820**** 821 * [[VUID-vkCreateCommandPool-queueFamilyIndex-01937]] 822 pname:pCreateInfo->queueFamilyIndex must: be the index of a queue family 823 available in the logical device pname:device 824**** 825 826include::{generated}/validity/protos/vkCreateCommandPool.adoc[] 827-- 828 829[NOTE] 830.Guideline 831==== 832If there is a general description of the command, add it following the 833parameter descriptions: 834 835[source,asciidoc,subs=attributes+] 836---- 837This is a general description of creating a command pool. 838---- 839 840If there are _explicit_ valid usage statements for the command, add them in 841their own valid usage block: 842 843[source,asciidoc,subs=attributes+] 844---- 845.Valid Usage 846**** 847 * [[VUID-vkCreateCommandPool-queueFamilyIndex-01937]] 848 pname:pCreateInfo->queueFamilyIndex must: be the index of a queue family 849 available in the logical device pname:device 850**** 851---- 852 853Although a valid usage ID is shown in the rendered example above, do not 854specify the ID when initially writing the statement, as 855<<sample-writing-explicit-vu, described below>>. 856VUIDs are normally assigned immediately prior to publication. 857 858Some parameter and member validation language for commands and structures is 859_implicit_ (autogenerated from `vk.xml`), and included from the 860`\{generated}/validity/` directories. 861All Vulkan command and structure language should include the autogenerated 862file at the end of their descriptions. 863It is harmless to include a nonexistent file, in the rare cases where no 864implicit validity language exists. 865 866[source,asciidoc,subs=attributes+] 867---- 868\include::\{generated}/validity/protos/vkCreateCommandPool.adoc[] 869{blank}-- 870---- 871 872Close the open block surrounding the command description after the implicit 873validity include. 874All content within the block will be extracted for the corresponding 875reference page. 876 877Open blocks delimiting reference page content should not themselves contain 878section headers, as asciidoctor cannot render such nested content correctly. 879Reference pages should in general be relatively short, so this limitation is 880not severe. 881 882Structures and enumerations first introduced as parameters of a command are 883described next. 884==== 885 886[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] 887-- 888The sname:VkCommandPoolCreateInfo structure is defined as: 889 890include::{generated}/api/structs/VkCommandPoolCreateInfo.adoc[] 891 892[NOTE] 893.Guideline 894==== 895Begin the structure description with an open block delimiting the contents 896as a reference page, in the same fashion as described above for commands. 897The open block contains several required attribute values, as described for 898<<writing-refpages, automatic extraction into a reference page>>. 899 900Use a short, active paragraph to introduce the structure, usually just "`The 901sname:VkStructureName structure is defined as:`". 902 903After the description, include the autogenerated definition for the 904structure from the `\{generated}/api/structs/` directory: 905 906[source,asciidoc,subs=attributes+] 907---- 908[open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] 909{blank}-- 910 911The sname:VkCommandPoolCreateInfo structure is defined as: 912 913\include::\{generated}/api/structs/VkCommandPoolCreateInfo.adoc[] 914---- 915==== 916 917 * pname:sType is a elink:VkStructureType value identifying this structure. 918 * pname:pNext is `NULL` or a pointer to a structure extending this 919 structure. 920+ 921-- 922This demonstrates how to create a continuation paragraph in a member 923description. 924This paragraph is not present in the actual specification the example is 925based on. 926-- 927 * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating 928 usage behavior for the pool and command buffers allocated from it. 929 * pname:queueFamilyIndex designates a queue family as described in section 930 <<devsandqueues-queueprops,Queue Family Properties>>. 931 All command buffers allocated from this command pool must: be submitted 932 on queues from the same queue family. 933 934[NOTE] 935.Guideline 936==== 937Each structure member is described in a separate bullet list item. 938For structures with pname:sType and pname:pNext members, there is standard 939boilerplate for their descriptions. 940Descriptions of other members of the structure follow. 941 942[source,asciidoc,subs=attributes+] 943---- 944 * pname:sType is a elink:VkStructureType value identifying this structure. 945 * pname:pNext is `NULL` or a pointer to a structure extending this 946 structure. 947+ 948{blank}-- 949This demonstrates how to create a continuation paragraph in a member 950description. 951This paragraph is not present in the actual specification the example is 952based on. 953{blank}-- 954 * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating 955 usage behavior for the pool and command buffers allocated from it. 956 * pname:queueFamilyIndex designates a queue family as described in section 957 <<devsandqueues-queueprops,Queue Family Properties>>. 958 All command buffers allocated from this command pool must: be submitted 959 on queues from the same queue family. 960---- 961 962These entries should be short and functional, without describing details of 963e.g. new enumerant values, function of individual parameter settings, etc. 964They can refer to other types using the appropriate *link: macros or to 965related sections of the specification using asciidoctor xrefs. 966 967In rare cases, a member description will cover multiple paragraphs. 968In these cases the normal list nesting and indentation guidelines cannot be 969applied due to limitations of the asciidoctor parser. 970It is usually best to append a continuation block following the first 971paragraph of such a list item, as shown for pname:pNext above. 972 973Add general descriptions of the structure, if any, following the member 974descriptions. 975No general description is shown in this example. 976==== 977 978.Valid Usage 979**** 980ifdef::VK_VERSION_1_1[] 981 * [[VUID-VkCommandPoolCreateInfo-flags-02860]] 982 If the <<features-protectedMemory, pname:protectedMemory>> feature is 983 not enabled, the ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of 984 pname:flags must: not be set 985endif::VK_VERSION_1_1[] 986**** 987 988include::{generated}/validity/structs/VkCommandPoolCreateInfo.adoc[] 989-- 990 991[NOTE] 992.Guideline 993==== 994Add explicit valid usage statements (if any) and the implicit autovalidity 995include in the same fashion as described for commands above, then close the 996open block. 997 998[source,asciidoc,subs=attributes+] 999---- 1000.Valid Usage 1001**** 1002ifdef::VK_VERSION_1_1[] 1003 * [[VUID-VkCommandPoolCreateInfo-flags-02860]] 1004 If the <<features-protectedMemory, pname:protectedMemory>> feature is 1005 not enabled, the ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT bit of 1006 pname:flags must: not be set 1007endif::VK_VERSION_1_1[] 1008**** 1009 1010\include::\{generated}/validity/structs/VkCommandPoolCreateInfo.adoc[] 1011{blank}-- 1012---- 1013==== 1014 1015[open,refpage='VkCommandPoolCreateFlagBits',desc='Bitmask specifying usage behavior for a command pool',type='enums'] 1016-- 1017Bits which can: be set in slink:VkCommandPoolCreateInfo::pname:flags to 1018specify usage behavior for a command pool are: 1019 1020include::{generated}/api/enums/VkCommandPoolCreateFlagBits.adoc[] 1021 1022[NOTE] 1023.Guideline 1024==== 1025Begin an enumerated type description with an open block delimiting the 1026contents as a reference page, in the same fashion as described above for 1027commands and structures. 1028 1029Use boilerplate language similar to that above to introduce the type. 1030 1031[source,asciidoc,subs=attributes+] 1032---- 1033[open,refpage='VkCommandPoolCreateFlagBits',desc='Bitmask specifying usage behavior for a command pool',type='enums'] 1034{blank}-- 1035Bits which can: be set in slink:VkCommandPoolCreateInfo::pname:flags to 1036specify usage behavior for a command pool are: 1037 1038\include::\{generated}/api/enums/VkCommandPoolCreateFlagBits.adoc[] 1039---- 1040==== 1041 1042 * ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT specifies that command 1043 buffers allocated from the pool will be short-lived, meaning that they 1044 will be reset or freed in a relatively short timeframe. 1045 This flag may: be used by the implementation to control memory 1046 allocation behavior within the pool. 1047ifdef::VK_VERSION_1_1[] 1048 * ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT specifies that command 1049 buffers allocated from the pool are protected command buffers. 1050endif::VK_VERSION_1_1[] 1051-- 1052 1053[NOTE] 1054.Guideline 1055==== 1056Each enumerant in the enumerated type is described in a separate bullet list 1057item. 1058Make sure to protect enumerants added to the type by extensions or future 1059core versions with asciidoctor conditionals. 1060Close the open block after all enumerants are described. 1061 1062[source,asciidoc,subs=attributes+] 1063---- 1064 * ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT specifies that command 1065 buffers allocated from the pool will be short-lived, meaning that they 1066 will be reset or freed in a relatively short timeframe. 1067 This flag may: be used by the implementation to control memory 1068 allocation behavior within the pool. 1069\ifdef::VK_VERSION_1_1[] 1070 * ename:VK_COMMAND_POOL_CREATE_PROTECTED_BIT specifies that command 1071 buffers allocated from the pool are protected command buffers. 1072\endif::VK_VERSION_1_1[] 1073{blank}-- 1074---- 1075==== 1076 1077 1078[[sample-writing-explicit-vu]] 1079== Writing Explicit Valid Usage Statements 1080 1081Explicit valid usage statements must be written at a point that all 1082information needed to evaluate them is known. 1083In particular, if validity of structure parameters depends on other 1084parameters of a command that structure is passed to, such valid usage 1085statements must be written for the command, rather than the structure. 1086 1087Each explicit valid usage statement should be a single, self-contained 1088assertion, possibly involving multiple subexpressions or parameters. 1089For example, instead of writing "`width, height, and depth must: all be 1090greater than zero`", write each condition as a separate statement. 1091In contrast, "`width {times} height must: be less than 1024`" is a single 1092assertion involving multiple parameters. 1093 1094Do not use "`unless`" to call out exceptions - always write valid usage 1095statements of the form "`if _A_ then _B_`". 1096This may result in harder to read statements in a few cases, but maintains 1097consistency. 1098In many cases, it may lead to a simpler VU statement, or splitting one large 1099VU into multiple new ones. 1100 1101A valid usage statement may used nested bullet lists or other asciidoc 1102markup. 1103 1104Be clear on the distinction between a "`valid pointer`" and a "`pointer to a 1105valid object`" when writing valid usage statements. 1106See the "`Valid Usage`" section of the Vulkan Specification, and 1107particularly the "`Valid Usage for Pointers`" section. 1108 1109When clauses in valid usage statements apply only when specific extensions 1110and/or core API versions are enabled at runtime, use appropriate asciidoctor 1111conditionals around such clauses. 1112 1113[NOTE] 1114==== 1115Prior to specification update 1.3.255, there were stronger restrictions on 1116placement of asciidoctor conditionals that have been relaxed, allowing 1117writing such valid usage statements in a more natural manner and with less 1118duplication of language. 1119==== 1120 1121Explicit valid usage statements must be assigned Valid Usage ID tags before 1122publication. 1123This process is described in the <<vuid, Valid Usage ID Tags>> appendix, but 1124is normally performed only when preparing to integrate functionality into 1125the Vulkan Specification prior to publication. 1126It is something authors of new functionality should be aware of, but are not 1127themselves responsible for. 1128For example, when writing the explicit 1129flink:vkCreateCommandPool::pname:queueFamilyIndex valid usage statement 1130shown above, the tag 1131 1132[source,asciidoc,subs=attributes+] 1133---- 1134[[VUID-vkCreateCommandPool-queueFamilyIndex-01937]] 1135---- 1136 1137was inserted by a script, not the original author. 1138 1139[NOTE] 1140.Guideline 1141==== 1142If the same set of valid usage statements are going to be common to multiple 1143commands or structures, these should be extracted into a separate file under 1144`chapters/commonvalidity/`. 1145The file name should be short but to the point (e.g. `draw_common.adoc`), 1146and then the file can be included in the relevant API features using 1147standard include syntax: 1148 1149[source,asciidoc,subs=attributes+] 1150---- 1151.Valid Usage 1152**** 1153\include::\{chapters}/commonvalidity/draw_common.adoc[] 1154\include::\{chapters}/commonvalidity/draw_vertex_binding.adoc[] 1155 * [[VUID-vkCmdDrawIndirectByteCountEXT-transformFeedback-02287]] 1156 sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:transformFeedback 1157 must: be enabled 1158**** 1159---- 1160 1161Common VU includes should appear before individual VUs for consistency. 1162 1163The file itself should be structured with the comment `// Common Valid 1164Usage` used as a delimiter at the start and end of the file, with a comment 1165describing in more detail where these are included, and then the valid usage 1166statement bullets outside of a valid usage block. 1167For example: 1168 1169[source,asciidoc] 1170---- 1171// Common Valid Usage 1172// Common to drawing commands that consume vertex binding state 1173 * All vertex input bindings accessed via vertex input variables declared 1174 in the vertex shader entry point's interface must: have valid buffers 1175 bound 1176 * For a given vertex buffer binding, any attribute data fetched must: be 1177 entirely contained within the corresponding vertex buffer binding, as 1178 described in <<fxvertex-input>> 1179// Common Valid Usage 1180---- 1181 1182Finally, the original feature section needs to define the `:refpage:` 1183attribute to match the name of the feature, as this is used to correctly 1184generate links to expanded common valid usage statements in the built 1185specification. 1186 1187[source,asciidoc] 1188---- 1189[open,refpage='vkCmdDrawIndirectByteCountEXT',desc='Draw primitives where the vertex count is derived from the counter byte value in the counter buffer',type='protos'] 1190-- 1191:refpage: vkCmdDrawIndirectByteCountEXT 1192---- 1193 1194In general, this methodology should be preferred over any other method of 1195consolidation - e.g. calling out a block of common valid usage statements, 1196or referencing the valid usage statements of another command. 1197However, for cases where the boilerplate of setting this up creates more 1198text than a simple copy paste (e.g. only two commands consume a single 1199valid usage statement), the original VUs can be left intact. 1200==== 1201 1202 1203[[writing-empty-enumerations]] 1204== Markup for Empty Enumerated Types 1205 1206Sometimes an enumerated type has all values defined by extensions, and each 1207enumerated value defined by the type will be surrounded by an asciidoctor 1208conditional for the corresponding extension. 1209When a specification is built without any of those extensions enabled, the 1210type should still be included, even though it is empty. 1211In this case, the enumerated value descriptions must be followed by one 1212additional conditional section which is only included when *none* of the 1213relevant extensions are enabled. 1214 1215For example, the relevant part of the 1216ename:VkDescriptorSetLayoutCreateFlagBits description, whose only value is 1217defined by an extension, will look like this: 1218 1219[source,asciidoc,subs=attributes+] 1220---- 1221\include::\{generated}/api/enums/VkDescriptorSetLayoutCreateFlagBits.adoc[] 1222 1223\ifdef::VK_KHR_push_descriptor[] 1224 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR specifies 1225 that descriptor sets must: not be allocated using this layout, and 1226 descriptors are instead pushed by flink:vkCmdPushDescriptorSetKHR. 1227\endif::VK_KHR_push_descriptor[] 1228 1229\ifndef::VK_KHR_push_descriptor[] 1230[NOTE] 1231.Note 1232==== 1233All bits for this type are defined by extensions, and none of those 1234extensions are enabled in this build of the specification. 1235==== 1236\endif::VK_KHR_push_descriptor[] 1237---- 1238 1239 1240[[writing-refpages]] 1241== Markup for Automatic Reference Page Extraction 1242 1243The Vulkan reference pages are (mostly) extracted from corresponding 1244sections of the API Specification. 1245This requires that the markup and writing conventions described above be 1246adhered to rigidly. 1247 1248The extraction scripts for a given page rely on the existence of an 1249asciidoctor `open` block surrounding markup describing that page, with 1250attributes used to specify properties of the reference page. 1251Additional heuristics and non-asciidoctor tags, described below, are used to 1252identify subsections of a reference page in some cases. 1253 1254In general the open block introduction will look like: 1255 1256[source,asciidoc] 1257---- 1258[open,refpage='name',desc='short description',type='pagetype',alias='alias',anchor='anchor',xrefs='xrefs'] 1259-- 1260---- 1261 1262Attributes which can be set on the block are: 1263 1264 * *refpage* - the name of the reference page, e.g. the Vulkan interface 1265 (command, structure, enumerant, handle, etc.) name. This attribute is 1266 required. 1267 * *desc* - short description / summary of the page, used in the page 1268 title. 1269 This attribute is required. 1270 * *type* - type of the interface, which must match the directory name 1271 following `api/` in the interface `include::` line within the block, and 1272 must be one of `basetypes`, `defines`, `enums`, `flags`, `funcpointers`, 1273 `handles`, `protos`, or `structs`; or the non-API block types `feature`, 1274 `freeform`. or `spirv`. 1275 This attribute is required. 1276 * *alias* - list of comma-separated names of other API entities which this 1277 refpage also describes. This is used when an API is promoted and the 1278 refpage block describes both the old and promoted APIs. 1279 This attribute is optional. 1280 * *anchor* - anchor name at which this reference page is fully described 1281 in the API specification document. 1282 This attribute is optional except for the non-API block types, which do 1283 not correspond to Vulkan APIs. 1284 * *xrefs* - list of whitespace-separated names of other reference pages 1285 which should be added to the `See Also` section of this page. 1286 Most cross-references are automatically generated based on the immediate 1287 dependency information in `vk.xml`, but in some cases, such as referring 1288 between `*FlagBits` and `*Flags` types, this additional tagging is 1289 useful. 1290 This attribute is optional. 1291 1292Attributes of the open block must be written in this format, using single 1293quotes as delimiters (even though asciidoctor markup also allows double 1294quotes), and escape single quotes in e.g. the *desc* attribute value with 1295backquotes. 1296 1297After the open block is started, the following markup should be provided: 1298 1299 * A single paragraph of text describing the definition of the interface. 1300 This paragraph is optional, but strongly recommended. 1301 * The `include` line for the interface, which must be consistent with the 1302 page name and type in the open block attributes. 1303 This paragraph is required. 1304 * A bullet list describing function parameters, structure members, 1305 enumerants in an enumerated type, etc. 1306 This list should contain no empty lines, as the extraction script 1307 classifies the uninterrupted block of text following the `include` 1308 directive as the `Parameters` or `Members` section of the ref page. 1309 This list is required, unless the interface has nothing to describe, 1310 such as an empty structure or enumeration, or a function with no 1311 parameters. 1312 * Paragraphs of text making up the `Description` section of the ref page. 1313 This section is optional. 1314 If it is necessary due to constraints of asciidoctor markup to have an 1315 empty line in the bullet list section, add a `// refBody` comment 1316 immediately following the bullet list and preceding this section: 1317+ 1318[source,asciidoc] 1319---- 1320// refBody 1321---- 1322+ 1323There are no examples of this usage in the Vulkan 1.2.192 Specification, 1324but it has been needed in the past and may again in the future. 1325+ 1326 * An explicit valid usage block. 1327 This block is required if the interface has such valid usage 1328 constraints. 1329 * The `include` line for the implicit valid usage block. 1330 This line is required for commands and structures, but not for 1331 interfaces such as enumerated types, which do not have implicit valid 1332 usage blocks. 1333 * Finally, a two-dash asciidoctor delimiter closing the open block: 1334+ 1335[source,asciidoc] 1336---- 1337-- 1338---- 1339 1340All elements specifying an interface name (open block `refpage` attributes, 1341interface `include` lines, and validity `include` lines) must use the same 1342interface name, if present. 1343Otherwise the extraction script is either unable to extract that page, or 1344will extract the wrong text - and the language will be structurally 1345incorrect, as well. 1346The extraction process is somewhat fragile, so care should be taken and the 1347results of reference page extraction verified after making changes to that 1348portion of the specification source. 1349 1350Content that should only appear in reference pages, such as 1351developer-oriented guidelines for reference pages describing extensions, may 1352be conditionally included in the specification as follows: 1353 1354[source,asciidoc,subs=attributes+] 1355---- 1356\ifdef::isrefpage[] 1357 1358=== Refpage-Only Section 1359 1360*This section will appear only when generating an extension refpage, 1361but not in the specification extensions appendix.* 1362 1363\endif::isrefpage[] 1364---- 1365