202 lines
8.3 KiB
Plaintext
202 lines
8.3 KiB
Plaintext
// Copyright (c) 2015-2016 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 the
|
|
scope of shaders. 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*, *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:
|
|
|
|
http://www.ietf.org/rfc/rfc2119.txt
|
|
|
|
*must*:: This word, or the terms *required* or *shall*, mean that the
|
|
definition is an absolute requirement of the specification.
|
|
|
|
*must not*:: This phrase, or the phrase *shall not*, means that the
|
|
definition is an absolute prohibition of the specification.
|
|
|
|
*should*:: 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.
|
|
|
|
*should not*:: This phrase, or the phrase *not recommended*, 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.
|
|
|
|
[[Khronos Data Format Specification]]:: A. Garrard, _Khronos Data Format
|
|
Specification, version 1.1_,
|
|
https://www.khronos.org/registry/dataformat/specs/1.1/dataformat.1.1.html,
|
|
March 9, 2016.
|
|
|
|
[[Khronos SPIR-V Extended Instructions for GLSL Specification]]:: J.
|
|
Kessenich, _SPIR-V Extended Instructions for GLSL, Version 1.00_,
|
|
https://www.khronos.org/registry/spir-v/,
|
|
February 10, 2016.
|
|
|
|
[[Khronos SPIR-V Specification]]:: 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
|