mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-29 15:45:16 +00:00
ef053e7c82
* Bump API patch number and header version number to 27 for this update.
Github Issues:
* Weaken flink:vkGetPipelineCacheData invariance conditions; previous
conditions were stronger than agreed and can't be guaranteed (public
issue 280).
* Add link to "Vulkan Loader Specification and Architecture Overview"
document to Normative References section (public issue 359).
Internal Issues:
* Be more clear in the <<interfaces-resources-layout-std140, uniform
buffer layout>> section that block offsets can be out of order
(internal issue 396).
* Document that extension authors should add support for their extensions
to the validation layers (internal issue 398).
* Clarify that the valid range of depth clear values should be limited
to the 0..1 range and that copies to depth aspect must also be in this
range (internal issue 412).
* Specify ``a'' vs. ``an'' use in the style guide (internal issue 432).
* Increase the maximum pname:nonCoherentAtomSize value in the
<<features-limits-required,Required Limits>> section from 128 to 256
(internal issue 435).
* Fix vk_platform.h for compiler errors on some Android platforms
(internal issue 441).
* Clarify that slink:VkPhysicalDeviceFeatures::pname:pEnabledFeatures ==
`NULL` disables all features, including the "required" feature
pname:robustBufferAccess (internal issue 479).
Other Issues:
* Expand style guide and make it more self-consistent.
* Use ISO 8601 date format everywhere.
* Emphasise the correct way of using
slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount.
* Added +VK_EXT_validation_flags+ extension for validation flag mechanism.
* Fix an <<credits,author credit>> to include their current employer.
211 lines
7.8 KiB
Plaintext
211 lines
7.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.
|
|
|
|
[[iso-8601]]
|
|
International Organization for Standardization,
|
|
_Data elements and interchange formats -- Information interchange --
|
|
Representation of dates and times_,
|
|
http://www.iso.org/iso/catalogue_detail?csnumber=40874,
|
|
2004-12-01.
|
|
Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples.
|
|
|
|
[[vulkan-docs]]
|
|
Khronos Vulkan Working Group,
|
|
+KhronosGroup/Vulkan-Docs+ project on GitHub,
|
|
https://github.com/KhronosGroup/Vulkan-Docs,
|
|
2016-07-05.
|
|
|
|
[[vulkan-spec]]
|
|
Vulkan Working Group,
|
|
_Vulkan 1.0.27 - A Specification_,
|
|
https://www.khronos.org/registry/vulkan/,
|
|
2016-09-16
|
|
|
|
Version 1.0.27 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
|
|
|
|
* 2016-09-16 - Make style guide markup more consistent with its own
|
|
recommendations. Simplify some tables of preferred terms. Add sections on
|
|
block and table markup.
|
|
* 2016-09-12 - Describe writing and markup style for labelled lists. Require
|
|
use of the ISO 8601 date format except in rare legacy cases. Expand the
|
|
description of <<markup-layout,Line Lengths>> and add a description
|
|
of markup for <<markup-footnotes,Footnotes>>.
|
|
* 2016-09-08 - Add a writing section about proper use of
|
|
<<writing-misc-a-an,``a'' and ``an''>> (internal issue 432).
|
|
* 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions,
|
|
which are no longer used in the Specification (internal issue 407).
|
|
* 2016-08-29 - Add spelling and compound word rules (public issue 352).
|
|
* 2016-08-23 - 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).
|
|
* 2016-07-26 - Add section describing <<writing-refpages,markup for
|
|
automatic reference page extraction>>.
|
|
* 2016-07-18 - Add examples of function-parameter and structure-member
|
|
markup (based on public issue 286).
|
|
* 2016-07-11 - Change the document title.
|
|
* 2016-07-07 - Rename document, change license to CC BY, clarify required
|
|
and recommended actions, and reserve use of ``normative'' for the
|
|
Specifications.
|
|
* 2016-06-26 - 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.
|
|
* 2016-06-20 - Add API naming guide.
|
|
* 2016-05-22 - Add markup and image creation rules, after fixing missing
|
|
figure captions for public issue 219.
|
|
* 2016-05-01 - Include feedback from public issues 120 and 190. Use
|
|
consistent conventions for defining structures. Use American rather than
|
|
British spelling conventions.
|
|
* 2016-03-12 - Recommend against "the value of".
|
|
* 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not".
|
|
* 2016-02-16 - Place asciidoc conversion post-release.
|
|
* 2016-02-09 - Added quotation mark convention.
|
|
* 2016-02-01 - Add the Oxford Comma section and issue resolution.
|
|
* 2016-01-26 - Add bullet-list style description of command parameters.
|
|
* 2016-01-11 - Add ``Numbers in Text'' section from WSI work.
|
|
* 2015-12-16 - Make ``begin / end'' preferred terms to ``start /
|
|
finish''.
|
|
* 2015-12-15 - Make ``implementation'' preferred term instead of
|
|
``system''.
|
|
* 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer
|
|
types.
|
|
* 2015-12-10 - Initial release for feedback.
|