Vulkan-Docs/doc/specs/vulkan/chapters/introduction.txt

// 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

https://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.