mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-29 15:45:16 +00:00
7f7686d7f2
* Bump API patch number and header version number to 23 for this update.
Github Issues:
* Add explicit valid value attributes to pname:sType members in vk.xml
(public issue 34).
* Clarify usage of flink:vkGetInstanceProcAddr and
flink:vkGetDeviceProcAddr (public issue 225).
* Fix a copy-and-paste error in the description of
pname:pSwapchainImageCount saying that it was the count of ``format
pairs'' instead of ``swapchain images'' (public issue 292).
* flink:vkCmdExecuteCommandBuffers requires all command buffers to be
allocated from command pools created for the same queue family (public
issue 296).
* Remove bogus +optional+ attribute for
flink:vkEnumerateDeviceLayerProperties::pname:physicalDevice from vk.xml
(public issue 301).
* Clean up the <<resources-image-views-compatibility,image and image view
compatibility table>> reference and contents. Use full enumerant names.
Refer to pname:layerCount in the ``view parameters'' column instead of
pname:arrayLayers. Require N >= 1 for the cube array subview row, not
just arrayLayers >= 6 N (public issue 304).
* Modify description of <<resources-memory-aliasing,memory aliasing>> to
be consistent with the description of
<<resources-bufferimagegranularity,buffer image granularity>> (public
issue 307).
Internal Issues:
* Describe remaining +vk_platform.h+ macros in the <<boilerplate,API
Boilerplate>> appendix (internal issue 6).
* Clarify
<<features-features-robustBufferAccess,pname:robustBufferAccess>>
feature behavior; what memory can be accessed, how bounds checking is
performed, and allowing for vectorization (internal issue 332).
* Document markup for automatic extraction of reference pages from the
spec sources in the style guide (internal issue 395).
* Allow flink:vkCreateDisplayModeKHR to return
ename:VK_ERROR_INITIALIZAION_FAILED_KHR if the user requests mode
parameters that the specified display does not support (internal issue
411).
* Remove atomic counters (atomic_uint style) from KHR_vulkan_glsl, and
more clearly remove the subroutine keyword alongside it (internal issue
421).
* Clarify behavior of flink:vkCmdBindDescriptorSets for descriptor sets
not contained in the layout (internal issue 427).
Other Commits:
* Change the order in which members of sname:VkAttachmentDescription and
sname:VkPipelineInputAssemblyStateCreateInfo are described to match
their order in the structures.
187 lines
6.8 KiB
Plaintext
187 lines
6.8 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
|
|
|
|
* 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 Github issue 219.
|
|
* May 1, 2016 - Include feedback from public Github 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.
|