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

// 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 ``{apiname} Specification'' or just the
``Specification'' hereafter, describes the {apiname} 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
{apiname} Registry, located at URL

http://www.khronos.org/registry/vulkan/


[[introduction-whatis]]
== What is the {apiname} Graphics System?

{apiname} 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 {apiname}

To the programmer, {apiname} 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 {apiname} 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 {apiname} 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 {apiname}

To the implementor, {apiname} is a set of commands that allow the
construction and submission of command buffers to a device. Modern devices
accelerate virtually all {apiname} 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 {apiname} API, while mapping the work for each {apiname}
command to the graphics hardware as appropriate for the capabilities of the
device.


[[introduction-ourview]]
=== Our View of {apiname}

We view {apiname} 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 {apiname} 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 {apiname} 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.