-
Notifications
You must be signed in to change notification settings - Fork 453
/
vkCreateInstance.txt
124 lines (92 loc) · 5.44 KB
/
vkCreateInstance.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
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[]