122 lines
5.2 KiB
Plaintext
122 lines
5.2 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.
|
||
|
|
|
||
|
|
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 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[]
|