219 lines
8.7 KiB
Plaintext
219 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.
|