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