mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-29 15:45:16 +00:00
82e0f83d43
* Bump API patch number and header version number to 40 for this update.
* There is a major build change in this release. We are now using the
Ruby-based ``asciidoctor'' implementation, rather than the Python-based
``asciidoc'' implementation, to process the specification. While the
actual specification markup changes were minimal, this requires a new
set of build tools and a very different installation process, especially
because we now use an experimental direct-to-PDF backend for Asciidoctor
instead of Docbook->dblatex->PDF. It is no longer possible to build the
Specification using asciidoc. See doc/specs/vulkan/README.adoc
for some guidance on installing the new toolchain components.
* There are some minor rendering issues in the PDF output due to teething
problems with the asciidoctor toolchain, especially with mathematical
equations. We are aware of these and working on them.
Github Issues:
* Updated sample code for the <<sparsememory-examples-basic,sparse
resource binding example>> (public issue 97).
* Modify line and point clipping behavior in the
<<vertexpostproc-clipping, Primitive Clipping>> section to allow for
pop-free behavior. The ability to check for which behavior is
implemented may be added a future feature or extension (public issue
113).
* Unify the discussions of implicit ordering throughout the spec, in
particular in the new sections <<drawing-primitive-order, Primitive
Order>>, <<primrast-order, Rasterization Order>>, and
<<synchronization-implicit, Implicit Synchronization Guarantees>>; the
discussion of <<synchronization-submission-order, submission order>>;
and references elsewhere to these sections (public issue 133).
* Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>>
language and introduce the term ``identically defined'' (public issue
164).
* Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to
reuse the object type enum from +VK_EXT_debug_report+, and moves the
definition of that enum into +VK_EXT_debug_report+ where it should be
(public issue 409).
* Remove redundant valid usage statement from slink:VkImageBlit (public
issue 421).
* Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a
specialization constant (public issue 424).
* Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue
426).
* Correct typo in New Objects list for <<VK_EXT_debug_report>> (public
issue 447).
Internal Issues:
* Moved to asciidoctor for spec builds (internal issue 121).
* Update style guide to describe where to put new extensions-specific
asciidoc files, and what to name them (internal issue 626).
* Add src/spec/indexExt.py to autogenerate registry index entries linking
into the 1.0-extensions specification, instead of maintaining the index
manually. (internal issue 642).
* Autogenerate extension dependencies and lists of all extensions and all
KHR extensions from the "supported" attributes in +vk.xml+. Execute
+make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported
extension is added to vk.xml, to regenerate the dependency script. The
consequence is that specifying a single extension to the +makeExt+
script will automatically enable all extensions it depends on as well,
and that the +makeAllExts+ and +makeKHR+ scripts do not need to be
updated when a new extension is supported (internal issue 648).
* Put extension appendices all at the same asciidoc section level, so KHR
WSI extensions show up in the HTML index (internal issue 648).
Other Issues:
* Imbed images in the generated HTML specs instead of loading them from
the images/ directory.
* Fix missing EXT in extension name
(ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME).
* Add new +VK_EXT_SMPTE_2086_metadata+ extension.
* In the <<platformCreateSurface_xlib,Xlib Surface>> section of the
+VK_KHR_xlib_surface+ specification, add language warning users that
they always need to call code:XinitThreads.
* Use the term "presentable image" (rather than "swapchain image")
consistently in +VK_KHR_swapchain+ and related extensions, and add a
glossary term defining it.
* Relocate the valid usage for samples of
flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo
to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR
structure.
202 lines
7.8 KiB
Plaintext
202 lines
7.8 KiB
Plaintext
// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
= Vulkan^(R)^ Documentation and Extensions: Procedures and Conventions
|
|
Jon Leech, Tobias Hector
|
|
:data-uri:
|
|
:icons: font
|
|
:toc2:
|
|
:toclevels: 3
|
|
:max-width: 100
|
|
:numbered:
|
|
:doctype: book
|
|
:imagewidth: 800
|
|
:fullimagewidth: width="800"
|
|
:cl: :
|
|
|
|
// Various special / math symbols. This is easier to edit with than Unicode.
|
|
include::config/attribs.txt[]
|
|
|
|
:leveloffset: 1
|
|
|
|
<<<<
|
|
|
|
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.
|
|
Specifically we're using the version of Asciidoc that is actively maintained
|
|
by asciidoctor, which is documented on its website at
|
|
http://www.asciidoctor.org/.
|
|
|
|
References to the Asciidoctor User Manual are to sections in the document at
|
|
http://asciidoctor.org/docs/user-manual/.
|
|
|
|
Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is
|
|
available for Linux, MacOS, and Microsoft Windows.
|
|
Multiple preview tools also exist for the language, primarily using
|
|
AsciidoctorJ (https://github.com/asciidoctor/asciidoctorj) or asciidoctor.js
|
|
(https://github.com/asciidoctor/asciidoctor.js).
|
|
In particular, GitHub and GitLab both have asciidoc previews for .adoc or
|
|
.asciidoc files in repositories, and live preview extensions exist for
|
|
Chrome and Firefox.
|
|
|
|
The Asciidoctor 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-28 - Add asciidoc math markup guidelines.
|
|
* 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.
|