mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-05 02:53:57 +00:00
eaea7d2709
* Bump API patch number and header version number to 26 for this update.
Github Issues:
* Bring sample code in the +VK_KHR_surface+ and +VK_KHR_swapchain+
extension summary appendices up to date, and note they will be replaced
with pointers to the LunarG SDK examples in the future (public issue
279).
* Add a new <<fundamentals-commandsyntax-results-lifetime,Lifetime of
Retrieved Results>> section specifying that ftext:vkGet* and
ftext:VkEnumerate* results are invariant unless otherwise specified, and
specify behavior for individual commands which are not invariant (public
issue 280).
* Remove conflicting definition of
slink:VkDisplayPlaneCapabilitiesKHR::pname:maxSrcPosition and clean up
language of the remaining definition (public issue 351).
* Fix many minor spelling errors and add rules to the style guide to
prevent recurrences (public issue 352).
Internal Issues:
* Remove redundant descriptions of the etext:VK_USE_PLATFORM_* macros from
the <<wsi,Window System Integration>> chapter in favor of the
description in the <<boilerplate-wsi-header,Window System-Specific
Header Control>> appendix (internal issue 6).
* Replace misleading 'can: be destroyed when not X' with more correct
'must: not be destroyed while X' in the
<<fundamentals-objectmodel-lifetime,Object Lifetime>> section. Disallow
destroying a pipeline layout while a command buffer using it is
recording (internal issue 241).
* Clarify that ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT is valid for
all images used as attachments in elink:VkImageUsageFlagBits and the
slink:VkImageLayout validity language (internal issue 320).
* Note that <<extended-functionality-layers,Layers>> may wrap object
handles, but that this is a generally discouraged. A link to additional
information in the documentation for layer authors is provided (issue
398)
* Replace the mustnot: and shouldnot: macros with equivalent must: not and
should: not to get rid of non-English words while still highlighting
normative language (internal issue 407).
* Disallow creating multisampled images with
ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT in the slink:VkImageLayout
validity language and the <<features-supported-sample-counts,Supported
Sample Counts>> section (internal issue 445).
* Fix typo so that flink:vkCmdDrawIndexedIndirect is defined in terms of
flink:vkCmdDrawIndexed rather than flink:vkCmdDrawIndirect (internal
issue 446).
* Reorganize the per-extension information sections to all be in the
<<extensions,Layers & Extensions>> appendix. Also fix a typo in
+VK_IMG_filter_cubic+ which incorrectly identified it as a +KHR+
extension (internal issue 461).
Other Issues:
* Use asciidoc markup instead of latexmath to simplify diagrams in the
<<features-formats-non-packed,byte mapping tables>> for color formats.
* Fix a markup problem with the wildcarded enumerant names in a NOTE in
the <<textures-texel-replacement,Texel Replacement>> section.
* Fix missing attributes in the XML interface for
elink:VkExternalMemoryHandleTypeFlagBitsNV and
elink:VkExternalMemoryFeatureFlagBitsNV (KhronosGroup/Vulkan-Hpp issue
#25)
* Cleanup reference page builds so only core pages are built for releases.
247 lines
10 KiB
Plaintext
247 lines
10 KiB
Plaintext
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[initialization]]
|
|
= Initialization
|
|
|
|
Before using Vulkan, an application must: initialize it by loading the
|
|
Vulkan commands, and creating a sname:VkInstance object.
|
|
|
|
[[initialization-functionpointers]]
|
|
== Command Function Pointers
|
|
|
|
// refBegin vkGetInstanceProcAddr Return a function pointer for a command
|
|
|
|
Vulkan commands are not necessarily exposed statically on a platform.
|
|
Function pointers for all Vulkan commands can: be obtained with the
|
|
command:
|
|
|
|
include::../api/protos/vkGetInstanceProcAddr.txt[]
|
|
|
|
* pname:instance is the instance that the function pointer will be
|
|
compatible with, or `NULL` for commands not dependent on any instance.
|
|
* pname:pName is the name of the command to obtain.
|
|
|
|
fname:vkGetInstanceProcAddr itself is obtained in a platform- and loader-
|
|
specific manner. Typically, the loader library will export this command as a
|
|
function symbol, so applications can: link against the loader library, or
|
|
load it dynamically and look up the symbol using platform-specific APIs.
|
|
Loaders are encouraged to export function symbols for all other core
|
|
Vulkan commands as well; if this is done, then applications that use only
|
|
the core Vulkan commands have no need to use fname:vkGetInstanceProcAddr.
|
|
|
|
The table below defines the various use cases for fname:vkGetInstanceProcAddr
|
|
and expected return value ("fp" is function pointer) for each case.
|
|
|
|
The returned function pointer is of type tlink:PFN_vkVoidFunction, and must
|
|
be cast to the type of the command being queried.
|
|
|
|
.vkGetInstanceProcAddr behavior
|
|
[width="80%",options="header",align="center"]
|
|
|=====
|
|
| pname:instance | pname:pName | return value
|
|
| * | NULL | undefined
|
|
| invalid instance | * | undefined
|
|
| NULL | flink:vkEnumerateInstanceExtensionProperties | fp
|
|
| NULL | flink:vkEnumerateInstanceLayerProperties | fp
|
|
| NULL | flink:vkCreateInstance | fp
|
|
| NULL | * (any pname:pName not covered above) | NULL
|
|
| instance | core Vulkan command | fp^1^
|
|
| instance | enabled instance extension commands for pname:instance | fp^1^
|
|
| instance | available device extension commands for pname:instance | fp^1,2^
|
|
| instance | * (any pname:pName not covered above) | NULL
|
|
|=====
|
|
|
|
1::
|
|
The returned function pointer must: only be called with a dispatchable object
|
|
(the first parameter) that is pname:instance or a child of pname:instance.
|
|
e.g. sname:VkInstance, sname:VkPhysicalDevice, sname:VkDevice, sname:VkQueue, or
|
|
sname:VkCommandBuffer.
|
|
|
|
2::
|
|
An ``available extension'' is an extension function supported by any of the
|
|
loader, driver or layer.
|
|
|
|
ifdef::editing-notes[]
|
|
[NOTE]
|
|
.editing-note
|
|
====
|
|
(Jon, Bug 14886 / Gitlab issue 4) The WSI group tentatively agreed that the
|
|
WSI extensions were special, and should: get static entry points in link
|
|
libraries and prototypes in +vulkan.h+, while future extensions would have
|
|
to be dynamically loaded. If this decision is upheld by the group as a
|
|
whole, it would probably be encoded in the previous paragraph, in the WSI
|
|
extensions branch of the Specification.
|
|
|
|
However, this decision has not been fully signed off on by the entire Vulkan
|
|
WG yet AFAIK. Note that implementations typically will not support many of the
|
|
WSI extensions, so ``static entry points'' do not relieve apps of the
|
|
neccessity of runtime enabling and testing of each extension before using
|
|
it.
|
|
====
|
|
endif::editing-notes[]
|
|
|
|
include::../validity/protos/vkGetInstanceProcAddr.txt[]
|
|
|
|
// refEnd vkGetInstanceProcAddr PFN_vkVoidFunction
|
|
|
|
// refBegin vkGetDeviceProcAddr Return a function pointer for a command
|
|
|
|
In order to support systems with multiple Vulkan implementations
|
|
comprising heterogeneous collections of hardware and software, the function
|
|
pointers returned by fname:vkGetInstanceProcAddr may: point to dispatch
|
|
code, which calls a different real implementation for different
|
|
sname:VkDevice objects (and objects created from them). The overhead of this
|
|
internal dispatch can: be avoided by obtaining device-specific function
|
|
pointers for any commands that use a device or device-child object as their
|
|
dispatchable object. Such function pointers can: be obtained with the
|
|
command:
|
|
|
|
include::../api/protos/vkGetDeviceProcAddr.txt[]
|
|
|
|
The table below defines the various use cases for fname:vkGetDeviceProcAddr
|
|
and expected return value for each case.
|
|
|
|
The returned function pointer is of type tlink:PFN_vkVoidFunction, and must
|
|
be cast to the type of the command being queried.
|
|
|
|
.vkGetDeviceProcAddr behavior
|
|
[width="80%",options="header",align="center"]
|
|
|=====
|
|
| pname:device | pname:pName | return value
|
|
| NULL | * | undefined
|
|
| invalid device | * | undefined
|
|
| device | NULL | undefined
|
|
| device | core Vulkan command^1^ | fp
|
|
| device | enabled extension commands^1^ | fp
|
|
| device | * (any pname:pName not covered above) | NULL
|
|
|=====
|
|
|
|
1::
|
|
The returned function pointer must: only be called with a dispatchable object
|
|
(the first parameter) that is pname:device or a child of pname:device.
|
|
e.g. sname:VkDevice, sname:VkQueue, or sname:VkCommandBuffer.
|
|
|
|
include::../validity/protos/vkGetDeviceProcAddr.txt[]
|
|
|
|
// refEnd vkGetDeviceProcAddr PFN_vkVoidFunction
|
|
|
|
// refBegin PFN_vkVoidFunction Dummy function pointer type returned by queries
|
|
|
|
The definition of tlink:PFN_vkVoidFunction is:
|
|
|
|
include::../api/funcpointers/PFN_vkVoidFunction.txt[]
|
|
|
|
// refEnd PFN_vkVoidFunction vkGetDeviceProcAddr vkGetInstanceProcAddr
|
|
|
|
|
|
[[initialization-instances]]
|
|
== Instances
|
|
|
|
// refBegin VkInstance - Opaque handle to a instance object
|
|
|
|
There is no global state in Vulkan and all per-application state is
|
|
stored in a sname:VkInstance object. Creating a sname:VkInstance object
|
|
initializes the Vulkan library and allows the application to pass
|
|
information about itself to the implementation.
|
|
|
|
Instances are represented by sname:VkInstance handles:
|
|
|
|
include::../api/handles/VkInstance.txt[]
|
|
|
|
// refEnd VkInstance
|
|
|
|
// refBegin vkCreateInstance Create a new Vulkan instance
|
|
|
|
To create an instance object, call:
|
|
|
|
include::../api/protos/vkCreateInstance.txt[]
|
|
|
|
* pname:pCreateInfo points to an instance of slink:VkInstanceCreateInfo
|
|
controlling creation of the instance.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pInstance points a sname:VkInstance handle in which the resulting
|
|
instance is returned.
|
|
|
|
fname:vkCreateInstance creates the instance, then enables and initializes
|
|
global layers and extensions requested by the application. If an extension
|
|
is provided by a layer, both the layer and extension must: be specified at
|
|
fname:vkCreateInstance time. If a specified layer cannot be found, no
|
|
sname:VkInstance will be created and the function will return
|
|
ename:VK_ERROR_LAYER_NOT_PRESENT. Likewise, if a specified extension cannot
|
|
be found the call will return ename:VK_ERROR_EXTENSION_NOT_PRESENT.
|
|
|
|
include::../validity/protos/vkCreateInstance.txt[]
|
|
|
|
// refBegin VkInstanceCreateInfo - Structure specifying parameters of a newly created instance
|
|
|
|
The sname:VkInstanceCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkInstanceCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use.
|
|
* pname:pApplicationInfo is `NULL` or a pointer to an instance of
|
|
sname:VkApplicationInfo. If not `NULL`, this information helps
|
|
implementations recognize behavior inherent to classes of applications.
|
|
slink:VkApplicationInfo is defined in detail below.
|
|
* pname:enabledLayerCount is the number of global layers to enable.
|
|
* pname:ppEnabledLayerNames is a pointer to an array of
|
|
pname:enabledLayerCount null-terminated UTF-8 strings containing the
|
|
names of layers to enable for the created instance. See the
|
|
<<extended-functionality-layers,Layers>> section for further details.
|
|
* pname:enabledExtensionCount is the number of global extensions to
|
|
enable.
|
|
* pname:ppEnabledExtensionNames is a pointer to an array of
|
|
pname:enabledExtensionCount null-terminated UTF-8 strings containing the
|
|
names of extensions to enable.
|
|
|
|
include::../validity/structs/VkInstanceCreateInfo.txt[]
|
|
|
|
The pname:pApplicationInfo member of slink:VkInstanceCreateInfo can: point
|
|
to an instance of sname:VkApplicationInfo.
|
|
|
|
// refBegin VkApplicationInfo - Structure specifying application info
|
|
|
|
The sname:VkApplicationInfo structure is defined as:
|
|
|
|
include::../api/structs/VkApplicationInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:pApplicationName is a pointer to a null-terminated UTF-8 string
|
|
containing the name of the application.
|
|
* pname:applicationVersion is an unsigned integer variable containing the
|
|
developer-supplied version number of the application.
|
|
* pname:pEngineName is a pointer to a null-terminated UTF-8 string
|
|
containing the name of the engine (if any) used to create the
|
|
application.
|
|
* pname:engineVersion is an unsigned integer variable containing the
|
|
developer-supplied version number of the engine used to create the
|
|
application.
|
|
* pname:apiVersion is the version of the Vulkan API against which the
|
|
application expects to run, encoded as described in the
|
|
<<fundamentals-versionnum,API Version Numbers and Semantics>> section.
|
|
If pname:apiVersion is 0 the implementation must: ignore it, otherwise
|
|
if the implementation does not support the requested pname:apiVersion it
|
|
must: return ename:VK_ERROR_INCOMPATIBLE_DRIVER. The patch version number
|
|
specified in pname:apiVersion is ignored when creating an instance
|
|
object. Only the major and minor versions of the instance must: match
|
|
those requested in pname:apiVersion.
|
|
|
|
include::../validity/structs/VkApplicationInfo.txt[]
|
|
|
|
// refBegin vkDestroyInstance Destroy an instance of Vulkan.
|
|
|
|
To destroy an instance, call:
|
|
|
|
include::../api/protos/vkDestroyInstance.txt[]
|
|
|
|
* pname:instance is the handle of the instance to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
include::../validity/protos/vkDestroyInstance.txt[]
|