mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-21 02:28:07 +00:00
ce60b9c887
* Vulkan 1.1 initial release. Bump API patch number and header version
number to 70 for this update. The patch number will be used for both
Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment
continuously from the previous Vulkan 1.0.69 update.
NOTE: We are not publishing an updated 1.0.70 specification, or 1.1
reference pages, along with 1.1.70. There are still minor issues to work
out with those build targets. However, we will soon generate all three
types of documents as part of the regular spec update cycle.
NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the
current specification in the `master` branch. The `1.0` branch is out of
date and will not be maintained, since we will be generating both 1.1
and 1.0 specifications from the `master` branch in the future.
Github Issues:
* Clarify how mapped memory ranges are flushed in
flink:vkFlushMappedMemoryRanges (public issue 127).
* Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a
list of tasks that each command performs, rather than necessarily being
discrete pieces of hardware that one task flows through. Add a
"`synchronization command`" pipeline type which all synchronization
command execute (it's just TOP + BOTTOM), with an explanatory note
(public issue 554).
Internal Issues:
* Regenerate all images used in the spec in Inkscape with a consistent
look-and-feel, and adjust image size attributes so they're all legible,
and not too large with respect to the spec body text (internal issue
701).
* Document in the <<extensions,extensions>> appendix and in the style
guide that `KHX` extensions are no longer supported or used in the
Vulkan 1.1 timeframe (internal issue 714).
* Remove the leftover equations_temp directory after PDF build completes
(internal issue 925).
* Update the <<credits, Credits (Informative)>> appendix to include
contributors to Vulkan 1.1, and to list them according to the API
version(s) they contributed to (internal issue 987).
* Add a NOTE to the introduction explaining that interfaces defined by
extensions which were promoted to Vulkan 1.1 are now expressed as
aliases of the Vulkan 1.1 type (internal issue 991).
* Instrument spec source conditionals so spec can be built with 1.1
features, extensions promoted to 1.1, or both (internal issues 992,
998).
* Modify the XML schema and tools to support explicit aliasing of types,
structures, and commands, and use this to express the promotion of 1.0
extensions to 1.1 core features, by making the extension interfaces
aliases of the core features they were promoted to. Mark up promoted
interfaces to allow still generating 1.0 + extension specifications
(internal issue 991).
* Platform names, along with corresponding preprocessor symbols to enable
extensions specific to those platforms, are now reserved in vk.xml using
the <platform> tag. Update the registry schema and schema specification
to match (internal issue 1011).
* Updated the <<textures-texel-replacement, Texel Replacement>> section to
clarify that reads from invalid texels for image resources result in
undefined values (internal issue 1014).
* Modify description of patch version so it continues to increment across
minor version changes (internal issue 1033).
* Clarify and unify language describing physical device-level core and
extension functionality in the <<fundamentals-validusage-extensions,
Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid
Usage for Newer Core Versions>>, <<initialization-functionpointers
Command Function Pointers>>, <<initialization-phys-dev-extensions,
Extending Physical Device From Device Extensions>>
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> sections and for
flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that
instance-level functionality is tied to the loader, and independent of
the ICD; physical device-level functionality is tied to the ICD, and
associated with device extensions; physical devices are treated more
uniformly between core and extensions; and instance and physical
versions can be different (internal issue 1048).
* Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>>
section to clarify the ability for pending command buffers to transition
to the invalid state after submission, and add a command buffer
lifecycle diagram (internal issue 1050).
* Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters
are ignored when push descriptors are not supported (internal issue
1054).
* Specify that flink:vkCreateImage will return an error if the image is
too large, in a NOTE in the slink:VkImageFormatProperties description
(internal issue 1078).
* Remove near-duplicate NOTEs about when to query function pointers
dynamically in the <<initialization, Initialization>> chapter and
replace by extending the NOTE in the <<fundamentals-abi, Application
Binary Interface>> section (internal issue 1085).
* Restore missing references to "`Sparse Resource Features`" in the
flink:VkBufferCreateFlagBits description (internal issue 1086).
* Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl`
specification, the <<descriptorsets, Resource Descriptors>> section and
its subsections, and the <<interfaces-resources-descset, Descriptor Set
Interface>> for consistency, reduction of duplicate information, and
removal of GLSL correspondance/examples (internal issue 1090).
* Correctly describe code:PrimitiveId as an Input for tessellation control
and evaluation shaders, not an Output (internal issue 1109).
* Relax the requirements on chroma offsets for nearest filtering in
<<textures-implict-reconstruction, Implicit Reconstruction>> (internal
issue 1116).
Other Issues:
* Clarify the intended relationship between specification language and
certain terms defined in the Khronos Intellectual Property Rights
policy. Specific changes include:
** Rewrote IP/Copyright preamble and introduction to better agree with
normative language both as laid out in the introduction, and the
Khronos IPR policy.
** Added notion of fully informative sections, which are now tagged with
"`(Informative)`" in their titles.
** Removed non-normative uses of the phrase "`not required`"
** Clarified the distinction between terms "`optional`" and "`not
required:`" as they relate to the IPR Policy, and updated specification
text to use terms consistent with the intent.
** Reduced additions to RFC 2119, and ensured the specification agreed
with the leaner language.
** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from
normative text.
** Moved several paragraphs that should not have been normative to
informative notes.
** Clarified a number of definitions in the Glossary.
** Updated the document writing guide to match new terminology changes.
* Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire,
application memory lifetime>> language that that for objects other than
descriptor sets, a slink:VkDescriptorSetLayout object used in the
creation of another object (such as slink:VkPipelineLayout or
slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation
of that object and can be safely destroyed afterwards.
* Updated the <<textures-scale-factor, Scale Factor Operation>> section to
use the ratio of anisotropy, rather than the integer sample rate, to
perform the LOD calculation. The spec still allows use of the sample
rate as the value used to calculate the LOD, but no longer requires it.
* Update `vulkan_ext.c` to include all platform-related definitions from
the Vulkan platform headers, following the split of the headers into
platform-specific and non-platform-specific files.
* Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter
which accidentally duplicated an anchor in the pipelines chapter. There
were no reference to this anchor, fortunately.
* Add valid usage statement for slink:VkWriteDescriptorSet and
slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout
used to allocate the source and destination sets must not have been
destroyed at the time flink:vkUpdateDescriptorSets is called.
* Document mapping of subgroup barrier functions to SPIR-V, and clarify a
place where subgroupBarrier sounds like it's execution-only in the
standalone `GL_KHR_shader_subgroup` specification.
* Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with
the default Arial font family replaced by the sans-serif Noto font
family.
* Numerous minor updates to README.adoc, build scripts, Makefiles, and
registry and style guide specifications to support Vulkan 1.1 outputs,
use them as defaults, and remove mention of `KHX` extensions, which are
no longer supported.
New Extensions:
* `VK_EXT_vertex_attrib_divisor`
238 lines
9.8 KiB
Plaintext
238 lines
9.8 KiB
Plaintext
// Copyright (c) 2014-2018 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*, *required*, *should*, *recommend*, *may*, and
|
|
*optional* in this document are to be interpreted as described in RFC 2119
|
|
and by the Vulkan 1.1 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.1.70 - A Specification_,
|
|
https://www.khronos.org/registry/vulkan/, 2018-03-07
|
|
|
|
Version 1.1.70 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
|
|
|
|
// Appendices are included below
|
|
include::style/vuid.txt[]
|
|
|
|
|
|
= Revision History
|
|
|
|
* 2018-03-07 - Updated for Vulkan 1.1 release.
|
|
* 2018-01-10 - Move details of mandated extension compatibility from the
|
|
<<extensions-rules, General Rules/Guidelines>> section into the
|
|
Fundamentals section of the API Specification, where they are changed
|
|
slightly to allow explicit incompatibilies (public issue 638).
|
|
* 2017-10-27 - Add language about proper use of "`valid pointer`" and
|
|
"`pointer to valid object`" for valid usage statements, in the
|
|
<<sample-command, Sample Command Description>> section (related to public
|
|
pull request 547).
|
|
* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells,
|
|
LaTeX Math in Table Cells>> (internal issue 908).
|
|
* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX`
|
|
extensions>> (public issues 536, 580)..
|
|
* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and
|
|
`any`>> to refer to properties of elments of arrays (internal issue 884).
|
|
* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and
|
|
Extension pname:pNext Chains>> language specifying where to describe
|
|
interactions of structures in a pname:pNext chain (internal issue 715).
|
|
* 2017-09-10 - Add example of marking up an enumerated type all of whose
|
|
values are defined by extensions (internal issue 864).
|
|
* 2017-08-25 - Add language to the <<extensions,API Versions, Extensions,
|
|
and Layers>> chapter describing how to write new API versions (internal
|
|
issue 892).
|
|
* 2017-06-12 - Add sections describing when to use the
|
|
<<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text,
|
|
*text{cl}>> markup macros instead of the *link{cl} macros, and clarify
|
|
that slink{cl} should be used for handle as well as structure names
|
|
(internal issue 886).
|
|
* 2017-05-08 - Add appendix describing <<appendix-vuid, Valid Usage ID
|
|
Tags>> and how they're generated.
|
|
* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension
|
|
Structure Names>>.
|
|
* 2017-02-11 - Finish transitioning to asciidoctor markup.
|
|
* 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.
|