mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 06:54:14 +00:00
0cc6bba634
* Bump API patch number and header version number to 61 for this update.
Github Issues:
* Provide alternate length attributes (altlen=) in the XML schema, for
those using length attributes to generate code instead of documentation
(public issue 555).
* Fix erroneous references to `latex:` being used for asciidoc math
markup, rather than `latexmath:` (public pull request 556).
* Add author ID to XML for Kazan software renderer (public pull request
557).
Internal Issues:
* Add the <<fundamentals-abi,Application Binary Interface>> section
describing platform ABI requirements and recommendations, add examples
of function and function pointer declarations to the
<<boilerplate-platform-specific-calling-conventions, Platform-Specific
Calling Conventions>> section, and remove related language that existed
elsewhere in the specification (internal issue 64).
* Describe where to document valid usage interactions of chained
structures in the style guide, and fix one case now appearing in
slink:VkBufferCreateInfo instead of the child
slink:VkDedicatedAllocationBufferCreateInfoNV structure (internal issue
715).
* Add example to the style guide of describing enumerated types which are
empty when the spec is built without relevant extensions enabled, and
apply it to existing examples for
elink:VkDescriptorSetLayoutCreateFlagBits and
elink:VkSubpassDescriptionFlagBits (internal issue 864).
* Add a note to the <<fundamentals-validusage-enums, Valid Usage for
Enumerated Types>> section that the special values suffixed with
etext:_BEGIN_RANGE, etext:_END_RANGE, etext:_RANGE_SIZE and
etext:_MAX_ENUM are not part of the API and should: not be used by
applications (internal issue 872).
* Added note to flink:vkCmdUpdateBuffers explaining the performance
penalty for copies done in this way, and why the upper copy limit is
what it is (internal issue 952).
* Update `VK_KHX_device_group` to split some functionality into the new
`VK_KHR_bind_memory2` extension, and rename that functionality (internal
issue 969).
* Remove *Status* fields from extension appendices, since they are by
definition published and complete by the time they reach the public
github repository (internal issue 973).
Other Issues:
* Update Data Format specification dependency to version 1.2 and change
references to DF sections accordingly.
* Update XML to make the pname:pAllocator parameter of
flink:vkRegisterDeviceEventEXT and flink:vkRegisterDisplayEventEXT in
the `VK_EXT_display_control` extension as optional.
New Extensions:
* `VK_KHR_bind_memory2`
* `VK_KHR_image_format_list`
* `VK_KHR_maintenance2`
* `VK_KHR_sampler_ycbcr_conversion`
222 lines
8.7 KiB
Plaintext
222 lines
8.7 KiB
Plaintext
// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[[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*, *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 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.
|
|
In cases where grammatically appropriate, the terms *recommend* or
|
|
*recommendation* may be used instead of *should*.
|
|
|
|
*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.2_,
|
|
https://www.khronos.org/registry/dataformat/specs/1.2/dataformat.1.2.html,
|
|
September, 2017.
|
|
|
|
// 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.
|