mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-27 22:56:18 +00:00
95dd2f34c5
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
239 lines
9.8 KiB
Plaintext
239 lines
9.8 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.
|
|
|
|
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[]
|