1// Copyright 2014-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[platformCreateSurface_android]] 6=== Android Platform 7 8[open,refpage='vkCreateAndroidSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for an Android native window',type='protos'] 9-- 10To create a sname:VkSurfaceKHR object for an Android native window, call: 11 12include::{generated}/api/protos/vkCreateAndroidSurfaceKHR.adoc[] 13 14 * pname:instance is the instance to associate the surface with. 15 * pname:pCreateInfo is a pointer to a sname:VkAndroidSurfaceCreateInfoKHR 16 structure containing parameters affecting the creation of the surface 17 object. 18 * pname:pAllocator is the allocator used for host memory allocated for the 19 surface object when there is no more specific allocator available (see 20 <<memory-allocation,Memory Allocation>>). 21 * pname:pSurface is a pointer to a slink:VkSurfaceKHR handle in which the 22 created surface object is returned. 23 24During the lifetime of a surface created using a particular 25basetype:ANativeWindow handle any attempts to create another surface for the 26same basetype:ANativeWindow and any attempts to connect to the same 27basetype:ANativeWindow through other platform mechanisms will fail. 28 29[NOTE] 30.Note 31==== 32In particular, only one sname:VkSurfaceKHR can: exist at a time for a given 33window. 34Similarly, a native window cannot: be used by both a sname:VkSurfaceKHR and 35code:EGLSurface simultaneously. 36==== 37 38If successful, fname:vkCreateAndroidSurfaceKHR increments the 39basetype:ANativeWindow's reference count, and fname:vkDestroySurfaceKHR will 40decrement it. 41 42On Android, when a swapchain's pname:imageExtent does not match the 43surface's pname:currentExtent, the presentable images will be scaled to the 44surface's dimensions during presentation. 45pname:minImageExtent is [eq]#(1,1)#, and pname:maxImageExtent is the maximum 46image size supported by the consumer. 47For the system compositor, pname:currentExtent is the window size (i.e. the 48consumer's preferred size). 49 50include::{generated}/validity/protos/vkCreateAndroidSurfaceKHR.adoc[] 51-- 52 53[open,refpage='VkAndroidSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Android surface object',type='structs'] 54-- 55The sname:VkAndroidSurfaceCreateInfoKHR structure is defined as: 56 57include::{generated}/api/structs/VkAndroidSurfaceCreateInfoKHR.adoc[] 58 59 * pname:sType is the type of this structure. 60 * pname:pNext is `NULL` or a pointer to a structure extending this 61 structure. 62 * pname:flags is reserved for future use. 63 * pname:window is a pointer to the basetype:ANativeWindow to associate the 64 surface with. 65 66.Valid Usage 67**** 68 * [[VUID-VkAndroidSurfaceCreateInfoKHR-window-01248]] 69 pname:window must: point to a valid Android basetype:ANativeWindow 70**** 71 72include::{generated}/validity/structs/VkAndroidSurfaceCreateInfoKHR.adoc[] 73-- 74 75[open,refpage='ANativeWindow',desc='Android native window type',type='basetypes'] 76-- 77To remove an unnecessary compile-time dependency, an incomplete type 78definition of basetype:ANativeWindow is provided in the Vulkan headers: 79 80include::{generated}/api/basetypes/ANativeWindow.adoc[] 81 82The actual basetype:ANativeWindow type is defined in Android NDK headers. 83-- 84 85[open,refpage='VkAndroidSurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags'] 86-- 87include::{generated}/api/flags/VkAndroidSurfaceCreateFlagsKHR.adoc[] 88 89tname:VkAndroidSurfaceCreateFlagsKHR is a bitmask type for setting a mask, 90but is currently reserved for future use. 91-- 92