mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-14 15:26:41 +00:00
348990517c
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
253 lines
10 KiB
Plaintext
253 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^2^ commands for pname:instance | fp^1^
|
|
| 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.
|
|
|
|
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 | fp^1^
|
|
| device | enabled extension commands | fp^1^
|
|
| 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[]
|
|
|
|
ifdef::VK_EXT_validation_flags[]
|
|
include::VK_EXT_validation_flags.txt[]
|
|
endif::VK_EXT_validation_flags[]
|
|
|
|
|
|
// 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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:apiVersion must: be zero, or otherwise it must: be a version that
|
|
the implementation supports, or supports an effective substitute for
|
|
****
|
|
|
|
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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* All child objects created using pname:instance must: have been destroyed
|
|
prior to destroying pname:instance
|
|
* If sname:VkAllocationCallbacks were provided when pname:instance was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* If no sname:VkAllocationCallbacks were provided when pname:instance was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyInstance.txt[]
|