C Specification

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 VK_ERROR_OUT_OF_DATE_KHR is returned

  • Scaling is done and VK_SUCCESS or 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 VkSwapchainPresentScalingCreateInfoEXT structure in the pNext chain of the VkSwapchainCreateInfoKHR structure.

The VkSwapchainPresentScalingCreateInfoEXT structure is defined as:

// Provided by VK_EXT_swapchain_maintenance1
typedef struct VkSwapchainPresentScalingCreateInfoEXT {
    VkStructureType             sType;
    const void*                 pNext;
    VkPresentScalingFlagsEXT    scalingBehavior;
    VkPresentGravityFlagsEXT    presentGravityX;
    VkPresentGravityFlagsEXT    presentGravityY;
} VkSwapchainPresentScalingCreateInfoEXT;

Members

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • scalingBehavior is 0 or the scaling method to use when the dimensions of the surface and swapchain images differ.

  • presentGravityX is 0 or the x-axis direction in which swapchain image pixels gravitate relative to the surface when scalingBehavior does not result in a one-to-one pixel mapping between the scaled swapchain image and the surface.

  • presentGravityY is 0 or the y-axis direction in which swapchain image pixels gravitate relative to the surface when scalingBehavior does not result in a one-to-one pixel mapping between the scaled swapchain image and the surface.

Description

If 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 presentGravityX or presentGravityY are 0, the presentation gravity must match that defined by the native platform surface on platforms which define surface gravity.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkSwapchainPresentScalingCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_SWAPCHAIN_PRESENT_SCALING_CREATE_INFO_EXT

  • VUID-VkSwapchainPresentScalingCreateInfoEXT-scalingBehavior-parameter
    scalingBehavior must be a valid combination of VkPresentScalingFlagBitsEXT values

  • VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityX-parameter
    presentGravityX must be a valid combination of VkPresentGravityFlagBitsEXT values

  • VUID-VkSwapchainPresentScalingCreateInfoEXT-presentGravityY-parameter
    presentGravityY must be a valid combination of VkPresentGravityFlagBitsEXT values

See Also

VK_EXT_swapchain_maintenance1, VkPresentGravityFlagsEXT, VkPresentScalingFlagsEXT, VkStructureType

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0