// Copyright 2019-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[open,refpage='VkSwapchainPresentScalingCreateInfoEXT',desc='Scaling behavior when presenting to the surface',type='structs']
--
When an application presents a swapchain image with dimensions different
than those of the target surface, different behavior is possible on
different platforms per their respective specifications:

  * Presentation fails and ename:VK_ERROR_OUT_OF_DATE_KHR is returned
  * Scaling is done and ename:VK_SUCCESS or ename:VK_SUBOPTIMAL_KHR is
    returned
  * Unspecified scaling using an arbitrary combination of stretching,
    centering and/or clipping.

Applications can: define specific behavior when creating a swapchain by
including the sname:VkSwapchainPresentScalingCreateInfoEXT structure in the
pname:pNext chain of the slink:VkSwapchainCreateInfoKHR structure.

The sname:VkSwapchainPresentScalingCreateInfoEXT structure is defined as:

include::{generated}/api/structs/VkSwapchainPresentScalingCreateInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:scalingBehavior is `0` or the scaling method to use when the
    dimensions of the surface and swapchain images differ.
  * pname:presentGravityX is `0` or the x-axis direction in which swapchain
    image pixels gravitate relative to the surface when
    pname:scalingBehavior does not result in a one-to-one pixel mapping
    between the scaled swapchain image and the surface.
  * pname:presentGravityY is `0` or the y-axis direction in which swapchain
    image pixels gravitate relative to the surface when
    pname:scalingBehavior does not result in a one-to-one pixel mapping
    between the scaled swapchain image and the surface.

If pname:scalingBehavior is `0`, the result of presenting a swapchain image
with dimensions that do not match the surface dimensions is implementation
and platform-dependent.
If pname:presentGravityX or pname:presentGravityY are `0`, the presentation
gravity must: match that defined by the native platform surface on platforms
which define surface gravity.

.Valid Usage
****
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07765]]
    If pname:presentGravityX is `0`, pname:presentGravityY must: be `0`
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07766]]
    If pname:presentGravityX is not `0`, pname:presentGravityY must: not be
    `0`
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-07767]]
    pname:scalingBehavior must: not have more than one bit set
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07768]]
    pname:presentGravityX must: not have more than one bit set
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07769]]
    pname:presentGravityY must: not have more than one bit set
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-07770]]
    pname:scalingBehavior must: be a valid scaling method for the surface as
    returned in
    slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentScaling,
    given slink:VkSwapchainCreateInfoKHR::pname:presentMode in
    slink:VkSurfacePresentModeEXT
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-07771]]
    If the swapchain is created with
    slink:VkSwapchainPresentModesCreateInfoEXT, pname:scalingBehavior must:
    be a valid scaling method for the surface as returned in
    slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentScaling,
    given each present mode in
    slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in
    slink:VkSurfacePresentModeEXT
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07772]]
    pname:presentGravityX must: be a valid x-axis present gravity for the
    surface as returned in
    slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityX,
    given slink:VkSwapchainCreateInfoKHR::pname:presentMode in
    slink:VkSurfacePresentModeEXT
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-07773]]
    If the swapchain is created with
    slink:VkSwapchainPresentModesCreateInfoEXT, pname:presentGravityX must:
    be a valid x-axis present gravity for the surface as returned in
    slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityX,
    given each present mode in
    slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in
    slink:VkSurfacePresentModeEXT
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07774]]
    pname:presentGravityY must: be a valid y-axis present gravity for the
    surface as returned in
    slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityY,
    given slink:VkSwapchainCreateInfoKHR::pname:presentMode in
    slink:VkSurfacePresentModeEXT
  * [[VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-07775]]
    If the swapchain is created with
    slink:VkSwapchainPresentModesCreateInfoEXT, pname:presentGravityY must:
    be a valid y-axis present gravity for the surface as returned in
    slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityY,
    given each present mode in
    slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in
    slink:VkSurfacePresentModeEXT
****

include::{generated}/validity/structs/VkSwapchainPresentScalingCreateInfoEXT.adoc[]
--