mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-27 14:45:55 +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.
219 lines
8.6 KiB
Plaintext
219 lines
8.6 KiB
Plaintext
// Copyright (c) 2015-2017 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[introduction]]
|
|
= Introduction
|
|
|
|
This chapter is Informative except for the sections on Terminology and
|
|
Normative References.
|
|
|
|
This document, referred to as the "`Vulkan Specification`" or just the
|
|
"`Specification`" hereafter, describes the Vulkan graphics system: what it
|
|
is, how it acts, and what is required to implement it.
|
|
We assume that the reader has at least a rudimentary understanding of
|
|
computer graphics.
|
|
This means familiarity with the essentials of computer graphics algorithms
|
|
and terminology as well as with modern GPUs (Graphic Processing Units).
|
|
|
|
The canonical version of the Specification is available in the official
|
|
Vulkan Registry, located at URL
|
|
|
|
http://www.khronos.org/registry/vulkan/
|
|
|
|
|
|
[[introduction-whatis]]
|
|
== What is the Vulkan Graphics System?
|
|
|
|
Vulkan is an API (Application Programming Interface) for graphics and
|
|
compute hardware.
|
|
The API consists of many commands that allow a programmer to specify shader
|
|
programs, compute kernels, objects, and operations involved in producing
|
|
high-quality graphical images, specifically color images of
|
|
three-dimensional objects.
|
|
|
|
|
|
[[introduction-programmer]]
|
|
=== The Programmer's View of Vulkan
|
|
|
|
To the programmer, Vulkan is a set of commands that allow the specification
|
|
of _shader programs_ or _shaders_, _kernels_, data used by kernels or
|
|
shaders, and state controlling aspects of Vulkan outside of shader
|
|
execution.
|
|
Typically, the data represents geometry in two or three dimensions and
|
|
texture images, while the shaders and kernels control the processing of the
|
|
data, rasterization of the geometry, and the lighting and shading of
|
|
_fragments_ generated by rasterization, resulting in the rendering of
|
|
geometry into the framebuffer.
|
|
|
|
A typical Vulkan program begins with platform-specific calls to open a
|
|
window or otherwise prepare a display device onto which the program will
|
|
draw.
|
|
Then, calls are made to open _queues_ to which _command buffers_ are
|
|
submitted.
|
|
The command buffers contain lists of commands which will be executed by the
|
|
underlying hardware.
|
|
The application can: also allocate device memory, associate _resources_ with
|
|
memory and refer to these resources from within command buffers.
|
|
Drawing commands cause application-defined shader programs to be invoked,
|
|
which can: then consume the data in the resources and use them to produce
|
|
graphical images.
|
|
To display the resulting images, further platform-specific commands are made
|
|
to transfer the resulting image to a display device or window.
|
|
|
|
|
|
[[introduction-implementor]]
|
|
=== The Implementor's View of Vulkan
|
|
|
|
To the implementor, Vulkan is a set of commands that allow the construction
|
|
and submission of command buffers to a device.
|
|
Modern devices accelerate virtually all Vulkan operations, storing data and
|
|
framebuffer images in high-speed memory and executing shaders in dedicated
|
|
GPU processing resources.
|
|
|
|
The implementor's task is to provide a software library on the host which
|
|
implements the Vulkan API, while mapping the work for each Vulkan command to
|
|
the graphics hardware as appropriate for the capabilities of the device.
|
|
|
|
|
|
[[introduction-ourview]]
|
|
=== Our View of Vulkan
|
|
|
|
We view Vulkan as a pipeline having some programmable stages and some
|
|
state-driven fixed-function stages that are invoked by a set of specific
|
|
drawing operations.
|
|
We expect this model to result in a specification that satisfies the needs
|
|
of both programmers and implementors.
|
|
It does not, however, necessarily provide a model for implementation.
|
|
An implementation must: produce results conforming to those produced by the
|
|
specified methods, but may: carry out particular computations in ways that
|
|
are more efficient than the one specified.
|
|
|
|
|
|
[[introduction-bugs]]
|
|
== Filing Bug Reports
|
|
|
|
Issues with and bug reports on the Vulkan Specification and the API Registry
|
|
can: be filed in the Khronos Vulkan GitHub repository, located at URL
|
|
|
|
http://github.com/KhronosGroup/Vulkan-Docs
|
|
|
|
Please tag issues with appropriate labels, such as "`Specification`", "`Ref
|
|
Pages`" or "`Registry`", to help us triage and assign them appropriately.
|
|
Unfortunately, GitHub does not currently let users who do not have write
|
|
access to the repository set GitHub labels on issues.
|
|
In the meantime, they can: be added to the title line of the issue set in
|
|
brackets, e.g. ''[Specification]''.
|
|
|
|
|
|
[[introduction-terminology]]
|
|
== Terminology
|
|
|
|
The key words *must*, *required*, *shall* *should*, *recommend*, *may*, and
|
|
*optional* in this document are to be interpreted as described in RFC 2119:
|
|
|
|
http://www.ietf.org/rfc/rfc2119.txt
|
|
|
|
*must*::
|
|
When used alone, this word, or the term *required*, means that the
|
|
definition is an absolute requirement of the specification.
|
|
When followed by *not* ("`must: not`" ), the phrase means that the
|
|
definition is an absolute prohibition of the specification.
|
|
|
|
*should*::
|
|
When used alone, this word, or the adjective *recommended*, means that there
|
|
may exist valid reasons in particular circumstances to ignore a particular
|
|
item, but the full implications must be understood and carefully weighed
|
|
before choosing a different course.
|
|
When followed by *not* ("`should: not`"), the phrase means that there may
|
|
exist valid reasons in particular circumstances when the particular behavior
|
|
is acceptable or even useful, but the full implications should: be
|
|
understood and the case carefully weighed before implementing any behavior
|
|
described with this label.
|
|
|
|
*may*::
|
|
This word, or the adjective *optional*, means that an item is truly
|
|
optional.
|
|
One vendor may choose to include the item because a particular marketplace
|
|
requires it or because the vendor feels that it enhances the product while
|
|
another vendor may omit the same item.
|
|
An implementation which does not include a particular option must be
|
|
prepared to interoperate with another implementation which does include the
|
|
option, though perhaps with reduced functionality.
|
|
In the same vein an implementation which does include a particular option
|
|
must be prepared to interoperate with another implementation which does not
|
|
include the option (except, of course, for the feature the option provides).
|
|
|
|
The additional terms *can* and *cannot* are to be interpreted as follows:
|
|
|
|
*can*::
|
|
This word means that the particular behavior described is a valid choice for
|
|
an application, and is never used to refer to implementation behavior.
|
|
|
|
*cannot*::
|
|
This word means that the particular behavior described is not achievable by
|
|
an application.
|
|
For example, an entry point does not exist, or shader code is not capable of
|
|
expressing an operation.
|
|
|
|
[NOTE]
|
|
.Note
|
|
==================
|
|
There is an important distinction between *cannot* and *must not*, as used
|
|
in this Specification.
|
|
*Cannot* means something the application literally is unable to express or
|
|
accomplish through the API, while *must not* means something that the
|
|
application is capable of expressing through the API, but that the
|
|
consequences of doing so are undefined and potentially unrecoverable for the
|
|
implementation.
|
|
==================
|
|
|
|
ifdef::editing-notes[]
|
|
[NOTE]
|
|
.editing-note
|
|
====
|
|
TODO (Jon) - We might need to augment the RFC 2119 definition of *must not*
|
|
to include some of the previous note, since at present it is defined solely
|
|
in terms of implementation behavior.
|
|
See Gitlab issue #9.
|
|
====
|
|
endif::editing-notes[]
|
|
|
|
|
|
[[introduction-normative]]
|
|
== Normative References
|
|
|
|
Normative references are references to external documents or resources to
|
|
which implementers of Vulkan must: comply.
|
|
|
|
[[ieee-754]]
|
|
_IEEE Standard for Floating-Point Arithmetic_, IEEE Std 754-2008,
|
|
http://dx.doi.org/10.1109/IEEESTD.2008.4610935, August, 2008.
|
|
|
|
[[data-format]] A.
|
|
Garrard, _Khronos Data Format Specification, version 1.1_,
|
|
https://www.khronos.org/registry/dataformat/specs/1.1/dataformat.1.1.html,
|
|
June, 2016.
|
|
|
|
// If the author name is placed on a standalone line, we see the mysterious
|
|
// asciidoc error 'list item index: expected 2 got 10'. Apparently the 'A.'
|
|
// of the previous paragraph and the 'J.' of this one get misinterpreted.
|
|
|
|
[[spirv-extended]] J.
|
|
Kessenich, _SPIR-V Extended Instructions for GLSL, Version 1.00_,
|
|
https://www.khronos.org/registry/spir-v/, February 10, 2016.
|
|
|
|
[[spirv-spec]] J.
|
|
Kessenich and B.
|
|
Ouriel, _The Khronos SPIR-V Specification, Version 1.00_,
|
|
https://www.khronos.org/registry/spir-v/, February 10, 2016.
|
|
|
|
[[vulkan-styleguide]] J.
|
|
Leech and T.
|
|
Hector, _Vulkan Documentation and Extensions: Procedures and Conventions_,
|
|
https://www.khronos.org/registry/vulkan/, July 11, 2016
|
|
|
|
[[LoaderAndValidationLayers]]
|
|
_Vulkan Loader Specification and Architecture Overview_,
|
|
https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/loader/LoaderAndLayerInterface.md,
|
|
August, 2016.
|