mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-29 15:45:16 +00:00
f4c4113d07
* Bump API patch number and header version number to 21 for this update.
Github Issues:
* Clarify how <<features-supported-sample-counts,sample count queries>>
relate to the limits in slink:VkPhysicalDeviceLimits. (public issue
185).
* Clarify in the <<interfaces-iointerfaces,Shader Input and Output
Interfaces>> section that shader output variables have undefined values
until the shader writes to them (public issue 240).
* Specify the implicit value of image parameters that cannot be set in
slink:VkSwapchainCreateInfo::pname:flags, pname:imageType,
pname:mipLevels, pname:samples, pname:tiling, and pname:initialLayout
(public issue 243).
* Make use of code:NULL and code:VK_NULL_HANDLE consistent in the
VK_KHR_swapchain extension (public issue 276).
Internal Issues:
* Clarify that presenting an image to a display surface swapchain applies
the display surface's mode, and that destroying a display surface
swapchain may reset the display's mode, in the VK_KHR_display_swapchain
extension (internal issue 247).
* Better describe what a slink:VkSurfaceKHR is, and that creating one does
not set a mode, in the VK_KHR_display extension. This is a round-about
way of pointing out that mode setting is not covered by the extension,
but rather is performed as a side effect of presentation (internal issue
247).
* Add more valid usage statements to flink:vkQueuePresentKHR command when
the VK_KHR_display_swapchain extension is present (internal issue
247).
* Add more includes to the VK_KHR_swapchain extension to better document
interactions with VK_KHR_display_swapchain (internal issue 247).
* Clarify restrictions on location aliasing in the
<<fxvertex,Fixed-Function Vertex Processing>> section (internal issue
370).
* Add mathematical description of blitting to flink:vkCmdBlitImage, and
link it to the <<textures,Image Operations>> chapter. Use mathematical
notation for ranges of texel coordinates in the <<textures,Image
Operations>> chapter. Fixed miscellaneous validity statements for
flink:vkCmdBlit and slink:VkImageBlit (internal issue 382).
Other Commits:
* Added a valid usage rule to flink:VkGraphicsPipelineCreateInfo that the
ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST topology must only be used when
tessellation shaders are used.
* Expand the style guide into a formal "Procedures and Conventions"
document. Add a API Naming Conventions section, move most of the API
Specification Appendix C (Layers and Extensions) content into the new
document, and define the resulting procedures as mandatory (where
relevant). This more clearly separates use vs. specification of Vulkan
APIs.
* Update vk_platform.h to handle 32-bit ARMv8 binaries.
* Various minor cleanups to the Makefile and build process.
183 lines
6.6 KiB
Plaintext
183 lines
6.6 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 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.
|