mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-29 15:45:16 +00:00
eaea7d2709
* Bump API patch number and header version number to 26 for this update.
Github Issues:
* Bring sample code in the +VK_KHR_surface+ and +VK_KHR_swapchain+
extension summary appendices up to date, and note they will be replaced
with pointers to the LunarG SDK examples in the future (public issue
279).
* Add a new <<fundamentals-commandsyntax-results-lifetime,Lifetime of
Retrieved Results>> section specifying that ftext:vkGet* and
ftext:VkEnumerate* results are invariant unless otherwise specified, and
specify behavior for individual commands which are not invariant (public
issue 280).
* Remove conflicting definition of
slink:VkDisplayPlaneCapabilitiesKHR::pname:maxSrcPosition and clean up
language of the remaining definition (public issue 351).
* Fix many minor spelling errors and add rules to the style guide to
prevent recurrences (public issue 352).
Internal Issues:
* Remove redundant descriptions of the etext:VK_USE_PLATFORM_* macros from
the <<wsi,Window System Integration>> chapter in favor of the
description in the <<boilerplate-wsi-header,Window System-Specific
Header Control>> appendix (internal issue 6).
* Replace misleading 'can: be destroyed when not X' with more correct
'must: not be destroyed while X' in the
<<fundamentals-objectmodel-lifetime,Object Lifetime>> section. Disallow
destroying a pipeline layout while a command buffer using it is
recording (internal issue 241).
* Clarify that ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT is valid for
all images used as attachments in elink:VkImageUsageFlagBits and the
slink:VkImageLayout validity language (internal issue 320).
* Note that <<extended-functionality-layers,Layers>> may wrap object
handles, but that this is a generally discouraged. A link to additional
information in the documentation for layer authors is provided (issue
398)
* Replace the mustnot: and shouldnot: macros with equivalent must: not and
should: not to get rid of non-English words while still highlighting
normative language (internal issue 407).
* Disallow creating multisampled images with
ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT in the slink:VkImageLayout
validity language and the <<features-supported-sample-counts,Supported
Sample Counts>> section (internal issue 445).
* Fix typo so that flink:vkCmdDrawIndexedIndirect is defined in terms of
flink:vkCmdDrawIndexed rather than flink:vkCmdDrawIndirect (internal
issue 446).
* Reorganize the per-extension information sections to all be in the
<<extensions,Layers & Extensions>> appendix. Also fix a typo in
+VK_IMG_filter_cubic+ which incorrectly identified it as a +KHR+
extension (internal issue 461).
Other Issues:
* Use asciidoc markup instead of latexmath to simplify diagrams in the
<<features-formats-non-packed,byte mapping tables>> for color formats.
* Fix a markup problem with the wildcarded enumerant names in a NOTE in
the <<textures-texel-replacement,Texel Replacement>> section.
* Fix missing attributes in the XML interface for
elink:VkExternalMemoryHandleTypeFlagBitsNV and
elink:VkExternalMemoryFeatureFlagBitsNV (KhronosGroup/Vulkan-Hpp issue
#25)
* Cleanup reference page builds so only core pages are built for releases.
193 lines
7.2 KiB
Plaintext
193 lines
7.2 KiB
Plaintext
// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
Vulkan Documentation and Extensions: Procedures and Conventions
|
|
===============================================================
|
|
Jon Leech, Tobias Hector
|
|
include::specversion.txt[]
|
|
:toc2:
|
|
:toclevels: 3
|
|
:max-width: 100
|
|
:numbered:
|
|
:doctype: book
|
|
:imagewidth: 800
|
|
:fullimagewidth: {svgpdf@pdf:scaledwidth="75%":width="800"}
|
|
:cl: :
|
|
|
|
:leveloffset: 1
|
|
|
|
// :icons:
|
|
// :toc-placement: manual
|
|
|
|
<<<<
|
|
|
|
include::copyright-ccby.txt[]
|
|
|
|
<<<<
|
|
|
|
[[introduction]]
|
|
= Introduction
|
|
|
|
This document contains required procedures and conventions when writing specifications for
|
|
new Vulkan APIs, extensions and layers, or related Khronos documentation
|
|
such as white papers and tutorials; or contributing to existing Vulkan
|
|
specifications. These are collectively referred to as _Vulkan Documentation_
|
|
or just _documentation_ below. The primary focus is the API Specification
|
|
and API extensions, although all of the markup and most of the writing style
|
|
is equally applicable to other documentation.
|
|
|
|
The primary purpose is to achieve consistency across the
|
|
API, as well as across all of our source and output documents. Consistency
|
|
makes it easier for developers, editors, reviewers, and users
|
|
of our documentation to understand and modify it.
|
|
|
|
This document is now formally voted on and approved
|
|
by the Vulkan Working Group. This means that unless explicitly stated
|
|
otherwise, the procedures and conventions must be followed
|
|
If you have a strong desire to modify the procedures and conventions,
|
|
such changes must be made through the normal
|
|
Vulkan Working Group processes.
|
|
|
|
|
|
[[introduction-terminology]]
|
|
== Terminology
|
|
|
|
The key words *must*, *must not*, *required*, *shall*, *shall not*,
|
|
*should*, *should not*, *recommend*, *may*, and *optional* in this document
|
|
are to be interpreted as described in RFC 2119 and by the
|
|
Vulkan 1.0 Specification in the ``Terminology'' section.
|
|
|
|
|
|
[[introduction-structure]]
|
|
== Document Structure
|
|
|
|
The style guide is broken into four sections:
|
|
|
|
* <<naming,API Naming Conventions>> - the required rules for choosing names
|
|
of Vulkan identifiers of all types.
|
|
* <<extensions,Extensions and Layers>> - the required procedures
|
|
for creating formal Vulkan extensions and layers.
|
|
* <<markup,Markup Style>> - the required and recommended markup style for
|
|
writing asciidoc and XML source that
|
|
follows consistent formatting and layout guidelines, tags special terms
|
|
and phrases for proper processing by the spec generation tools, etc.
|
|
* <<writing,Writing Style>> - the required and recommended writing style
|
|
for overall and fine-grained structure and
|
|
conventions, normative language use, API naming conventions, common
|
|
words and phrases to use and to avoid, linking and
|
|
cross-referencing, etc.
|
|
|
|
|
|
[[introduction-asciidoc]]
|
|
== Asciidoc Markup
|
|
|
|
Vulkan Documentation is primarily written in Asciidoc, a form of text markup
|
|
language. Asciidoc is documented on its website at http://www.asciidoc.org/.
|
|
|
|
[[userguide]]
|
|
References to the Asciidoc User Guide are to sections in the document at
|
|
http://asciidoc.org/userguide.html .
|
|
|
|
Asciidoc packages are available for Linux, MacOS, and Microsoft Windows,
|
|
together with the other toolchain components required to generate output
|
|
documents corresponding to the markup.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
We are currently using the
|
|
original _asciidoc_ tool. Other tools to process Asciidoc markup, such as
|
|
_asciidoctor_, are also available, but are not currently usable for our
|
|
documents. While asciidoctor supports the basic Asciidoc markup syntax, it
|
|
does not support asciidoc macros, which are used extensively in the
|
|
documentation. We expect to transition from asciidoc to asciidoctor
|
|
eventually. There may be minor effects on markup and if so, we will
|
|
document them at the time of the transition.
|
|
====
|
|
|
|
The asciidoc toolchain and build process are not addressed by this
|
|
document, which concentrates solely on source documents.
|
|
|
|
|
|
[[introduction-normative]]
|
|
== Normative References
|
|
|
|
Normative references are references to external documents or resources to
|
|
which documentation authors must comply.
|
|
|
|
[[KhronosGroup/Vulkan-Docs]]:: Khronos Vulkan Working Group,
|
|
+KhronosGroup/Vulkan-Docs+ project on GitHub,
|
|
https://github.com/KhronosGroup/Vulkan-Docs,
|
|
July 5, 2016.
|
|
|
|
[[Vulkan API Specification]]:: Vulkan Working Group,
|
|
_Vulkan 1.0.19 - A Specification_,
|
|
https://www.khronos.org/registry/vulkan/,
|
|
July 1, 2016.
|
|
|
|
Version 1.0.19 is the latest patch release of the Vulkan API Specification as of the
|
|
time this reference was created, but that Specification is frequently
|
|
updated with minor bugfixes and clarifications. When a more recent patch
|
|
release is made, it becomes the normative reference for the API.
|
|
|
|
|
|
// Chapters of the text are included below
|
|
|
|
include::style/naming.txt[]
|
|
|
|
include::style/extensions.txt[]
|
|
|
|
include::style/markup.txt[]
|
|
|
|
include::style/writing.txt[]
|
|
|
|
|
|
= Still To Be Done
|
|
|
|
* Something about Image formats
|
|
* Something about validation scripts
|
|
* Something about pictures
|
|
* Glossary lists
|
|
* New param/enum macros
|
|
|
|
= Revision History
|
|
|
|
* August 30, 2016 - remove mustnot{cl} and shouldnot{cl} macro definitions,
|
|
which are no longer used in the Specification (internal issue 407).
|
|
* August 29, 2016 - Add spelling and compound word rules (public issue 352).
|
|
* August 23, 2016 - Modify description of specifying extensions in the
|
|
<<extensions,Layers and Extensions>> chapter to refer to the new
|
|
single-branch model for extensions (internal issue 397).
|
|
* July 26, 2016 - Add section describing <<writing-refpages,markup for
|
|
automatic reference page extraction>>.
|
|
* July 18, 2016 - Add examples of function-parameter and structure-member
|
|
markup (based on public issue 286).
|
|
* July 11, 2016 - Change the document title.
|
|
* July 7, 2016 - Rename document, change license to CC BY, clarify required
|
|
and recommended actions, and reserve use of ``normative'' for the
|
|
Specifications.
|
|
* June 26, 2016 - Move Layers and Extensions chapter from Appendix C of the
|
|
Vulkan API Specification and merge content with the naming guide. Put
|
|
extension and naming chapters into their own source files.
|
|
* June 20, 2016 - Add API naming guide.
|
|
* May 22, 2016 - Add markup and image creation rules, after fixing missing
|
|
figure captions for public issue 219.
|
|
* May 1, 2016 - Include feedback from public issues 120 and 190. Use
|
|
consistent conventions for defining structures. Use American rather than
|
|
British spelling conventions.
|
|
* March 12, 2016 - Recommend against "the value of".
|
|
* February 26, 2016 - Replace use of the "maynot{cl}" macro with "may{cl} not".
|
|
* February 16, 2016 - Place asciidoc conversion post-release.
|
|
* February 9, 2016 - Added quotation mark convention.
|
|
* February 1, 2016 - add the Oxford Comma section and issue resolution.
|
|
* January 26, 2016 - add bullet-list style description of command parameters.
|
|
* January 11, 2016 - add ``Numbers in Text'' section from WSI work.
|
|
* December 16, 2015 - Make ``begin / end'' preferred terms to ``start /
|
|
finish''.
|
|
* December 15, 2015 - Make ``implementation'' preferred term instead of
|
|
``system''.
|
|
* December 13, 2015 - Add tlink{cl}/tname{cl} macros for function pointer
|
|
types.
|
|
* December 10, 2015 - Initial release for feedback.
|