mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-23 03:28:19 +00:00
1f875738fd
* Bump API patch number and header version number to 6 for this
update.
Github Issues:
* Define 'invocation group' for compute and graphics shaders. Cleanup
definition and use of 'workgroup', and add glossary entries (public
issue 1).
* Various minor editorial fixes (public issue 33).
* Clarify locations for block members in the
<<interfaces-iointerfaces-locations,Location Assignment>>
section (public issue 45).
* Editorial fixes for <<commandbuffer-allocation,Command Buffer
Allocation>> section (public issues 54, 59).
* Clarify behavior of depth test in the <<fragops-depth,Depth
Test>> section (public issues 80, 81).
* Remove discussion of return codes from
flink:vkGetPhysicalDeviceSparseImageFormatProperties and
flink:vkGetImageSparseMemoryRequirements, which don't return values
(public issue 82).
* Allow flink:vkCmdDrawIndirect and flink:vkCmdDrawIndexedIndirect
pname:drawCount of 0, as well as 1, when the multiDrawIndirect
feature is not supported (public issue 88).
* Remove confusing wording in the <<features-limits,Limits>>
section describing the slink:VkPhysicalDeviceLimits
pname:minTexelBufferOffsetAlignment,
pname:minUniformBufferOffsetAlignment, and
pname:minStorageBufferOffsetAlignment members as both minimums and
maximums (public issue 91).
* Clarified that only the RGB components should be affected in places
where sRGB is referred to in the spec, such as ASTC formats. Minor
re-wording to avoid "color space" when actively incorrect, now that
we refer to the Data Format Spec which actually makes a distinction
between color space and transfer function (public issue 94).
* Treat pname:pPropertyCount == 0 consistently in
flink:vkEnumerateInstanceLayerProperties and
flink:vkEnumerateDeviceLayerProperties (public issue 99)
* Cleanup minor editorial issues in chapters 14-17 (public issue 100).
* Clarify definition of flink:vkEnumerateInstanceExtensionProperties
and flink:vkEnumerateDeviceExtensionProperties (public issue 101).
* Define the flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties pname:pLayerName
parameter to be a pointer to a null-terminated UTF-8 string (public
issue 101).
* Rearrange "Missing information" references in mandatory format
tables (public issue 101).
* Clarify that the enumerated extensions returned by
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties will only include
extensions provided by the platform or extensions implemented in
implicitly enabled layers (public issue 101).
* Miscellaneous editorial fixes. Include the Vulkan spec patch number
in the PDF title. Fix label on <<fig-non-strict-lines,Non
strict lines>> diagram. Use more easily distinguished symbols in
tables in the <<features-required-format-support,Required
Format Support>> section. Don't require FQDNs used as layer names be
encoded in lower case if not possible, in the
<<extensions-naming-conventions, Extension and Layer Naming
Conventions>> section (public issues 101, 119, 121).
Internal Issues:
* Fixed excessive spacing in tables in XHTML (internal issue 18).
* Clarify that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
applies to secondary command buffers. Previously spec only referred
to the members of pname:pCommandBuffers being affected by this bit.
Added a separate slink:VkSubmitInfo Valid Usage restriction
specifying that ename:VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT
also applies to any secondary command buffers that are recorded into
the primary command buffers in pname:pCommandBuffers (internal issue
106).
* Clarify that slink:VkDeviceCreateInfo::pname:pEnabledFeatures can be
NULL (internal issue 117).
* Remove "the value of" where it is redundant (e.g. speaking of an API
parameter, struct member, or SPIR-V variable, but not when speaking
of color components) (internal issue 175).
* Forced patch version to always be 0 in the header. Add a
"VK_API_VERSION_<major>_<minor>" macro for people to use to do the
right thing. Add a VK_HEADER_VERSION which captures the header
release number independent of the spec patch number (internal issue
176).
* Correct description of
slink:VkPipelineShaderStageCreateInfo::pname:pName to "a pointer to
a null-terminated UTF-8 string" (internal issue #197).
Other Commits:
* Updated DataFormat spec reference to the new date for revision 5 of
that spec.
* Fixed KEEP option (to retain LaTeX intermediate files) in the
Makefile to be included when edited there, as well as set on the
command line.
* Reserve and add "VK_IMG_filter_cubic" to the registry, and implement
script functionality to add and remove validity from existing
functions. Includes schema and readme changes.
* Update GL_KHR_vulkan_glsl so push_constants do not have descriptor
sets.
197 lines
8.2 KiB
Plaintext
197 lines
8.2 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 ``{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.
|