mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-04 18:43:56 +00:00
e29a51b231
* Bump API patch number and header version number to 41 for this update.
Github Issues:
* Made all uses of `NULL` vs. code:VK_NULL_HANDLE consistent (public issue
276).
* Clarify render pass compatibility in different usage scenarios (public
issues 303 and 304).
* Add valid usage statements to slink:VkFramebufferCreateInfo requiring
that the width, height, and number of layers of the framebuffer all be
nonzero (public issue 432).
* Allow `offset` and `align` in any GLSL version for the
`GL_KHR_vulkan_glsl` extension (public issue 435).
* Specify lifetime of string objects passed to the
tlink:PFN_vkDebugReportCallbackEXT user callback in the
+VK_EXT_debug_report+ extension (public issue 446).
* Fix inter-page links in multi-file reference pages (public issue 454).
Internal Issues:
* Update valid usage language for slink:VkImageCreateInfo to disallow
creating images that have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
set without other attachment usage bits
(ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT,
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, or
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT) (internal issue 540).
* Disable `VK_EXT_swapchain_colorspace` extension until internal issues
640 and 661 are mutually resolved.
* Allow alternative mipmap level selection when [eq]#lambda == 0.5# during
texture <<textures-image-level-selection,Image Level(s) Selection>>
(internal issue 680).
Other Issues:
* Add a clarification to the style guide that the extension revision
number is treated as a patch number, so that changes to published
extensions should only include bug fixes and spec clarifications.
277 lines
11 KiB
Plaintext
277 lines
11 KiB
Plaintext
// Copyright (c) 2015-2017 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"]
|
|
|====
|
|
| 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"]
|
|
|====
|
|
| 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
|
|
|
|
ifdef::VK_KHR_get_physical_device_properties2[]
|
|
|
|
=== Extending Physical Device From Device Extensions
|
|
|
|
When the +VK_KHR_get_physical_device_properties2+ extension is enabled,
|
|
physical device extension commands and structures can: be used with a
|
|
physical device if the corresponding extension is enumerated by
|
|
flink:vkEnumerateDeviceExtensionProperties for that physical device, even
|
|
before a logical device has been created.
|
|
|
|
To obtain a function pointer for a physical-device command from a device
|
|
extension, an application can: use fname:vkGetInstanceProcAddr.
|
|
This function pointer may: point to dispatch code, which calls a different
|
|
real implementation for different sname:VkPhysicalDevice objects.
|
|
Behavior is undefined if an extension physical-device command is called on a
|
|
physical device that does not support the extension.
|
|
|
|
Device extensions may: define structures that can: be added to the
|
|
pNext-chain of physical-device commands.
|
|
Behavior is undefined if such an extension structure is passed to a physical
|
|
device command for a physical device that does not support the extension.
|
|
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
|
|
|
|
[[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[]
|