// Copyright (c) 2018-2020 Nintendo
//
// SPDX-License-Identifier: CC-BY-4.0

[[platformCreateSurface_vi,platformCreateSurface_vi]]
=== VI Platform

[open,refpage='vkCreateViSurfaceNN',desc='Create a slink:VkSurfaceKHR object for a VI layer',type='protos']
--
To create a sname:VkSurfaceKHR object for an code:nn::code:vi::code:Layer,
query the layer's native handle using
code:nn::code:vi::code:GetNativeWindow, and then call:

include::{generated}/api/protos/vkCreateViSurfaceNN.txt[]

  * pname:instance is the instance with which to associate the surface.
  * pname:pCreateInfo is a pointer to a sname:VkViSurfaceCreateInfoNN
    structure containing parameters affecting the creation of the surface
    object.
  * pname:pAllocator is the allocator used for host memory allocated for the
    surface object when there is no more specific allocator available (see
    <<memory-allocation,Memory Allocation>>).
  * pname:pSurface is a pointer to a slink:VkSurfaceKHR handle in which the
    created surface object is returned.

During the lifetime of a surface created using a particular
code:nn::code:vi::code:NativeWindowHandle, applications must: not attempt to
create another surface for the same code:nn::code:vi::code:Layer or attempt
to connect to the same code:nn::code:vi::code:Layer through other platform
mechanisms.

If the native window is created with a specified size, pname:currentExtent
will reflect that size.
In this case, applications should use the same size for the swapchain's
pname:imageExtent.
Otherwise, the pname:currentExtent will have the special value
[eq]#(0xFFFFFFFF, 0xFFFFFFFF)#, indicating that applications are expected to
choose an appropriate size for the swapchain's pname:imageExtent (e.g., by
matching the result of a call to
code:nn::code:vi::code:GetDisplayResolution).

include::{generated}/validity/protos/vkCreateViSurfaceNN.txt[]
--

[open,refpage='VkViSurfaceCreateInfoNN',desc='Structure specifying parameters of a newly created VI surface object',type='structs']
--
The sname:VkViSurfaceCreateInfoNN structure is defined as:

include::{generated}/api/structs/VkViSurfaceCreateInfoNN.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:window is the code:nn::code:vi::code:NativeWindowHandle for the
    code:nn::code:vi::code:Layer with which to associate the surface.

.Valid Usage
****
  * [[VUID-VkViSurfaceCreateInfoNN-window-01318]]
    pname:window must: be a valid code:nn::code:vi::code:NativeWindowHandle
****

include::{generated}/validity/structs/VkViSurfaceCreateInfoNN.txt[]
--

[open,refpage='VkViSurfaceCreateFlagsNN',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkViSurfaceCreateFlagsNN.txt[]

tname:VkViSurfaceCreateFlagsNN is a bitmask type for setting a mask, but is
currently reserved for future use.
--