1// Copyright (c) 2018-2020 Nintendo
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[platformCreateSurface_vi]]
6=== VI Platform
7
8[open,refpage='vkCreateViSurfaceNN',desc='Create a slink:VkSurfaceKHR object for a VI layer',type='protos']
9--
10:refpage: vkCreateViSurfaceNN
11
12To create a sname:VkSurfaceKHR object for an code:nn::code:vi::code:Layer,
13query the layer's native handle using
14code:nn::code:vi::code:GetNativeWindow, and then call:
15
16include::{generated}/api/protos/vkCreateViSurfaceNN.adoc[]
17
18  * pname:instance is the instance with which to associate the surface.
19  * pname:pCreateInfo is a pointer to a sname:VkViSurfaceCreateInfoNN
20    structure containing parameters affecting the creation of the surface
21    object.
22  * pname:pAllocator is the allocator used for host memory allocated for the
23    surface object when there is no more specific allocator available (see
24    <<memory-allocation,Memory Allocation>>).
25  * pname:pSurface is a pointer to a slink:VkSurfaceKHR handle in which the
26    created surface object is returned.
27
28During the lifetime of a surface created using a particular
29code:nn::code:vi::code:NativeWindowHandle, applications must: not attempt to
30create another surface for the same code:nn::code:vi::code:Layer or attempt
31to connect to the same code:nn::code:vi::code:Layer through other platform
32mechanisms.
33
34If the native window is created with a specified size, pname:currentExtent
35will reflect that size.
36In this case, applications should use the same size for the swapchain's
37pname:imageExtent.
38Otherwise, the pname:currentExtent will have the special value
39[eq]#(0xFFFFFFFF, 0xFFFFFFFF)#, indicating that applications are expected to
40choose an appropriate size for the swapchain's pname:imageExtent (e.g., by
41matching the result of a call to
42code:nn::code:vi::code:GetDisplayResolution).
43
44include::{generated}/validity/protos/vkCreateViSurfaceNN.adoc[]
45--
46
47[open,refpage='VkViSurfaceCreateInfoNN',desc='Structure specifying parameters of a newly created VI surface object',type='structs']
48--
49The sname:VkViSurfaceCreateInfoNN structure is defined as:
50
51include::{generated}/api/structs/VkViSurfaceCreateInfoNN.adoc[]
52
53  * pname:sType is a elink:VkStructureType value identifying this structure.
54  * pname:pNext is `NULL` or a pointer to a structure extending this
55    structure.
56  * pname:flags is reserved for future use.
57  * pname:window is the code:nn::code:vi::code:NativeWindowHandle for the
58    code:nn::code:vi::code:Layer with which to associate the surface.
59
60.Valid Usage
61****
62  * [[VUID-VkViSurfaceCreateInfoNN-window-01318]]
63    pname:window must: be a valid code:nn::code:vi::code:NativeWindowHandle
64****
65
66include::{generated}/validity/structs/VkViSurfaceCreateInfoNN.adoc[]
67--
68
69[open,refpage='VkViSurfaceCreateFlagsNN',desc='Reserved for future use',type='flags']
70--
71include::{generated}/api/flags/VkViSurfaceCreateFlagsNN.adoc[]
72
73tname:VkViSurfaceCreateFlagsNN is a bitmask type for setting a mask, but is
74currently reserved for future use.
75--
76