246 lines
10 KiB
Plaintext
246 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 a child of pname:instance.
|
|
e.g. sname:VkInstance, sname:VkPhysicalDevice, sname:VkDevice, sname:VkQueue, or
|
|
sname:VkCommandBuffer.
|
|
|
|
2::
|
|
available extension is an extension function supported by any of the loader, ICD 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 device extension commands for pname:device | fp
|
|
| device | * (any pname:pName not covered above) | NULL
|
|
|=====
|
|
|
|
1::
|
|
pname:pName is the name of any Vulkan command whose first parameter
|
|
is sname:VkDevice or any of its dispatchable children (e.g. sname:VkQueue,
|
|
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[]
|