mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-21 10:38:09 +00:00
31018cf088
* Bump API patch number and header version number to 17 for this
update.
Github Issues:
* Update description of vertex shader reuse in
<<shaders-vertex-execution>> (public issue 106).
* Simplify validity language around pname:ppEnabledExtensionNames and
pname:ppEnabledLayerNames (in the <<initialization-instances>> and
<<devsandqueues-device-creation>> sections) (public issue 214).
* Add missing validity rule to flink:vkCmdBeginRenderPass requiring
compatibility between slink:VkAttachmentDescription pname:initalLayout
members and the corresponding attached framebuffer images (public issue
233).
* Fix Unicode arrows appearing in output instead of relational operators
(public issue 239).
* Correctly describe the required number of elements for
code:TessLevelInner and code:TessLevelOuter arrays in the
<<interfaces-builtin-variables,Built-In Variables>> section as two and
four, respectively, instead of the other way around, and refer to this
section from the <<tessellation,Tessellation>> chapter (public issue
246).
Internal Issues:
* Document deprecation of ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR in the
VK_KHR_surface extension branch, and of
ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT in the
VK_EXT_debug_report branch (internal issue 328).
* Added language to define what a valid usage statement is and should be,
with a note about some apparent weirdnesses this might entail (internal
issue 357).
Other Commits:
* Added missing ename:VK_ERROR_DEVICE_LOST error to
flink:vkQueueBindSparse.
125 lines
5.4 KiB
Plaintext
125 lines
5.4 KiB
Plaintext
vkCreateInstance(3)
|
|
====================
|
|
|
|
Name
|
|
----
|
|
vkCreateInstance - Create a new Vulkan instance
|
|
|
|
C Specification
|
|
---------------
|
|
|
|
include::../protos/vkCreateInstance.txt[]
|
|
|
|
Parameters
|
|
----------
|
|
|
|
pname:pCreateInfo::
|
|
Pointer to instance creation structure.
|
|
|
|
pname:pInstance::
|
|
Pointer to variable which will receive the new instance handle.
|
|
|
|
Description
|
|
-----------
|
|
|
|
fname:vkCreateInstance creates a new Vulkan instance and places a handle to it in
|
|
the variable pointed to by pname:pInstance. pname:pCreateInfo is a pointer to an
|
|
instance of the slink:VkInstanceCreateInfo structure containing information about
|
|
how the instance should be created. The definition of slink:VkInstanceCreateInfo
|
|
is:
|
|
|
|
include::../structs/VkInstanceCreateInfo.txt[]
|
|
|
|
The pname:sType member of sname:VkInstanceCreateInfo should be set to ename:VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO.
|
|
The pname:pNext member of sname:VkInstanceCreateInfo is reserved for use by extensions
|
|
and should be set to code:NULL.
|
|
|
|
The pname:pApplicationInfo member, if non-code:NULL, points to an instance of the slink:VkApplicationInfo
|
|
structure containing information about the application. The expected contents of the pname:pApplicationInfo
|
|
member are documented below.
|
|
|
|
The pname:enabledLayerNameCount member of sname:VkInstanceCreateInfo specifies the number of global layers
|
|
to enable, and pname:ppEnabledLayerNames is a pointer to an array of pname:enabledLayerNameCount
|
|
code:NULL-terminated UTF-8 strings containing the names of layers
|
|
that should be enabled globally. If pname:enabledLayerNameCount is zero, then pname:ppEnabledLayerNames
|
|
is ignored and no global layers are enabled. If a layer cannot be found, the
|
|
call will not create a sname:VkInstance and will return ename:VK_ERROR_LAYER_NOT_PRESENT.
|
|
|
|
Similary, information about global extensions is specified in the pname:enabledExtensionNameCount and
|
|
pname:ppEnabledExtensionNames members. pname:enabledExtensionNameCount specifies the number of global
|
|
extensions to enable and pname:ppEnabledExtensionNames is a pointer to an array of pointers
|
|
to code:NULL-terminated UTF-8 strings containing the extension names. If an extension is provided
|
|
by a layer, both the layer and extension must be specified at
|
|
fname:vkCreateInstance time. If a extension cannot be found, the call will not
|
|
create a sname:VkInstance and will return ename:VK_ERROR_LAYER_NOT_PRESENT.
|
|
|
|
If pname:enabledExtensionNameCount is zero then no extensions are enabled and pname:ppEnabledExtensionNames
|
|
is ignored.
|
|
|
|
The definition of the slink:VkApplicationInfo structure is as follows:
|
|
|
|
include::../structs/VkApplicationInfo.txt[]
|
|
|
|
The pname:sType member of slink:VkApplicationInfo should be set to ename:VK_STRUCTURE_TYPE_APPLICATION_INFO.
|
|
The pname:pNext member of slink:VkApplicationInfo is reserved for use by extensions and should
|
|
be set to code:NULL.
|
|
|
|
pname:pApplicationName is a pointer to a code:NULL-terminated UTF-8 string containing the name of
|
|
the application. pname:applicationVersion contains an application-specific version number. It is
|
|
recommended that new versions of an existing application specify monotonically increasing
|
|
values for pname:applicationVersion.
|
|
|
|
If the application is built on a reusable engine, the name of the engine may be specified
|
|
in the NULL-terminated UTF-8 string pointed to by pname:pEngineName. pname:engineVersion
|
|
is the version of the engine used to create the application.
|
|
|
|
Finally, pname:apiVersion is the version of the Vulkan API that the application expects to
|
|
use.
|
|
|
|
Any application memory required by the instance will be allocated by calling functions
|
|
specified in the structure pointed to by ptext:pAllocCb. The definition of slink:VkAllocationCallbacks is:
|
|
|
|
include::../structs/VkAllocationCallbacks.txt[]
|
|
|
|
The slink:VkAllocationCallbacks structure contains two function pointers. pname:pfnAllocation
|
|
points to an allocation function whose protoype should be of the following
|
|
form:
|
|
|
|
[source,{basebackend@docbook:c++:cpp}]
|
|
------------------------------------------------------------------------------
|
|
typedef void* (*PFN_vkAllocationFunction)(
|
|
void* pUserData,
|
|
size_t size,
|
|
size_t alignment,
|
|
VkSystemAllocationScope allocationScope);
|
|
------------------------------------------------------------------------------
|
|
|
|
pname:pUserData is set to the value of pname:pUserData in the allocation info structure
|
|
passed to fname:vkCreateInstance. ptext:size is the size of the desired allocation,
|
|
ptext:alignment is the desired allocation, in bytes, and ptext:allocationScope represents
|
|
the intended usage of the allocation. The return value of function is a pointer
|
|
to the newly allocated memory.
|
|
|
|
The pname:pfnFree member of slink:VkAllocationCallbacks points to an instance of the
|
|
following function:
|
|
|
|
[source,{basebackend@docbook:c++:cpp}]
|
|
------------------------------------------------------------------------------
|
|
typedef void (*PFN_vkFreeFunction)(
|
|
void* pUserData,
|
|
void* pMemory);
|
|
------------------------------------------------------------------------------
|
|
|
|
Again, the pname:pUserData parameter is initialized to the value passed in the
|
|
slink:VkAllocationCallbacks structure passed to fname:vkCreateInstance. ptext:pMemory is a
|
|
pointer to the memory to be freed.
|
|
|
|
include::../validity/protos/vkCreateInstance.txt[]
|
|
|
|
See Also
|
|
--------
|
|
|
|
flink:vkDestroyInstance
|
|
|
|
include::footer.txt[]
|