1// Copyright 2019-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[open,refpage='VkSwapchainPresentScalingCreateInfoEXT',desc='Scaling behavior when presenting to the surface',type='structs'] 6-- 7When an application presents a swapchain image with dimensions different 8than those of the target surface, different behavior is possible on 9different platforms per their respective specifications: 10 11 * Presentation fails and ename:VK_ERROR_OUT_OF_DATE_KHR is returned 12 * Scaling is done and ename:VK_SUCCESS or ename:VK_SUBOPTIMAL_KHR is 13 returned 14 * Unspecified scaling using an arbitrary combination of stretching, 15 centering and/or clipping. 16 17Applications can: define specific behavior when creating a swapchain by 18including the sname:VkSwapchainPresentScalingCreateInfoEXT structure in the 19pname:pNext chain of the slink:VkSwapchainCreateInfoKHR structure. 20 21The sname:VkSwapchainPresentScalingCreateInfoEXT structure is defined as: 22 23include::{generated}/api/structs/VkSwapchainPresentScalingCreateInfoEXT.adoc[] 24 25 * pname:sType is a elink:VkStructureType value identifying this structure. 26 * pname:pNext is `NULL` or a pointer to a structure extending this 27 structure. 28 * pname:scalingBehavior is `0` or the scaling method to use when the 29 dimensions of the surface and swapchain images differ. 30 * pname:presentGravityX is `0` or the x-axis direction in which swapchain 31 image pixels gravitate relative to the surface when 32 pname:scalingBehavior does not result in a one-to-one pixel mapping 33 between the scaled swapchain image and the surface. 34 * pname:presentGravityY is `0` or the y-axis direction in which swapchain 35 image pixels gravitate relative to the surface when 36 pname:scalingBehavior does not result in a one-to-one pixel mapping 37 between the scaled swapchain image and the surface. 38 39If pname:scalingBehavior is `0`, the result of presenting a swapchain image 40with dimensions that do not match the surface dimensions is implementation 41and platform-dependent. 42If pname:presentGravityX or pname:presentGravityY are `0`, the presentation 43gravity must: match that defined by the native platform surface on platforms 44which define surface gravity. 45 46.Valid Usage 47**** 48 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07765]] 49 If pname:presentGravityX is `0`, pname:presentGravityY must: be `0` 50 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07766]] 51 If pname:presentGravityX is not `0`, pname:presentGravityY must: not be 52 `0` 53 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-07767]] 54 pname:scalingBehavior must: not have more than one bit set 55 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07768]] 56 pname:presentGravityX must: not have more than one bit set 57 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07769]] 58 pname:presentGravityY must: not have more than one bit set 59 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-07770]] 60 pname:scalingBehavior must: be a valid scaling method for the surface as 61 returned in 62 slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentScaling, 63 given slink:VkSwapchainCreateInfoKHR::pname:presentMode in 64 slink:VkSurfacePresentModeEXT 65 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-07771]] 66 If the swapchain is created with 67 slink:VkSwapchainPresentModesCreateInfoEXT, pname:scalingBehavior must: 68 be a valid scaling method for the surface as returned in 69 slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentScaling, 70 given each present mode in 71 slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in 72 slink:VkSurfacePresentModeEXT 73 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07772]] 74 pname:presentGravityX must: be a valid x-axis present gravity for the 75 surface as returned in 76 slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityX, 77 given slink:VkSwapchainCreateInfoKHR::pname:presentMode in 78 slink:VkSurfacePresentModeEXT 79 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07773]] 80 If the swapchain is created with 81 slink:VkSwapchainPresentModesCreateInfoEXT, pname:presentGravityX must: 82 be a valid x-axis present gravity for the surface as returned in 83 slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityX, 84 given each present mode in 85 slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in 86 slink:VkSurfacePresentModeEXT 87 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07774]] 88 pname:presentGravityY must: be a valid y-axis present gravity for the 89 surface as returned in 90 slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityY, 91 given slink:VkSwapchainCreateInfoKHR::pname:presentMode in 92 slink:VkSurfacePresentModeEXT 93 * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07775]] 94 If the swapchain is created with 95 slink:VkSwapchainPresentModesCreateInfoEXT, pname:presentGravityY must: 96 be a valid y-axis present gravity for the surface as returned in 97 slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityY, 98 given each present mode in 99 slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in 100 slink:VkSurfacePresentModeEXT 101**** 102 103include::{generated}/validity/structs/VkSwapchainPresentScalingCreateInfoEXT.adoc[] 104-- 105 106