## D.5. VK_KHR_display_swapchain

Name String
  VK_KHR_display_swapchain
Extension Type
  Device extension
Registered Extension Number
  4
Status
  Draft.
Last Modified Date
  11/10/2015
Revision
  9
IP Status
  No known IP claims.
Dependencies
  - This extension is written against revision 1.0 of the Vulkan API.
  - This extension requires VK_KHR_swapchain and VK_KHR_display
Contributors
  - James Jones, NVIDIA
  - Jeff Vigil, Qualcomm
  - Jesse Hall, Google
Contacts
  - James Jones (jajones at nvidia.com)

This extension provides an API to create a swapchain directly on a device’s display without any underlying window system.

### D.5.1. New Object Types

None

### D.5.2. New Enum Constants

- Extending `VkStructureType`:

  - `VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR`

- Extending `VkResult`:

  - `VK_ERROR_INCOMPATIBLE_DISPLAY_KHR`

### D.5.3. New Enums

None

### D.5.4. New Structures

- `VkDisplayPresentInfoKHR`

### D.5.5. New Functions

- `vkCreateSharedSwapchainsKHR`

### D.5.6. Issues

1) Should swapchains sharing images each hold a reference to the images, or should it be up to the application to destroy the swapchains and images in an order that avoids the need for reference counting?

    PROPOSED RESOLUTION: Take a reference.  The lifetime of presentable
    images is already complex enough.

2) Should the srcRect/dstRect parameters be specified as part of the present command, or at swapchain creation time?

    PROPOSED RESOLUTION: As part of the presentation command.  This allows
    moving and scaling the image on the screen without the need to
    respecify the mode or create a new swapchain presentable images.

3) Should srcRect/dstRect be specified as rects, or separate offset/extent values?

    PROPOSED RESOLUTION: As rects.  Specifying them separately might make
    it easier for hardware to expose support for one but not the other, but
    in such cases applications must just take care to obey the reported
    capabilities and not use non-zero offsets or extents that require
    scaling, as appropriate.

4) How can applications create multiple swapchains that use the same images?

    RESOLUTION: By calling vkCreateSharedSwapchainsKHR().

    An earlier resolution used vkCreateSwapchainKHR(), chaining multiple
    VkSwapchainCreateInfoKHR structures through pNext.  In order to allow each
    swapchain to also allow other extension structs, a level of indirection
    was used: VkSwapchainCreateInfoKHR::pNext pointed to a different structure,
    which had both an sType/pNext for additional extensions, and also had a
    pointer to the next VkSwapchainCreateInfoKHR structure.  The number of
    swapchains to be created could only be found by walking this linked list
    of alternating structures, and the pSwapchains out parameter was
    reinterpreted to be an array of VkSwapchainKHR handles.

    Another option considered was a method to specify a "shared"
    swapchain when creating a new swapchain, such that groups of swapchains
    using the same images could be built up one at a time.  This was deemed
    unusable because drivers need to know all of the displays an image
    will be used on when determining which internal formats and layouts to
    use for that image.

### D.5.7. Examples

Example 1

Create a swapchain on a display mode and plane

        // See VK_KHR_display for an example of how to pick a display,
        // display mode, plane, and how to create a VkSurfaceKHR for
        // that plane.
        extern VkPhysicalDevice physDevice;
        extern VkDisplayModePropertiesKHR myModeProps;
        extern VkSurfaceKHR mySurface;
        extern VkDevice device;

        uint32_t queueCount, i;
        uint32_t presentQueueFamilyIndex = UINT32_MAX;
        VkBool32 supportsPresent;

        // Find a queue family that supports presenting to this surface
        uint32_t familyCount;
        vkGetPhysicalDeviceQueueFamilyProperties(physDevice, &familyCount, NULL);

        for (i = 0; i < familyCount; ++i)
        {
            vkGetPhysicalDeviceSurfaceSupportKHR(physDevice, i, mySurface, &supportsPresent);

            if (supportsPresent) {
                // Found a queue family that supports present.  See
                // VK_KHR_surface for an example of how to find a queue that
                // supports both presentation and graphics
                presentQueueFamilyIndex = i;
                break;
            }
        }

        // Figure out which formats and present modes this surface supports.
        uint32_t formatCount;
        vkGetPhysicalDeviceSurfaceFormatsKHR(physDevice, mySurface, &formatCount, NULL);

        VkSurfaceFormatKHR* formats = (VkSurfaceFormatKHR*)malloc(sizeof(VkSurfaceFormatKHR) * formatCount);
        vkGetPhysicalDeviceSurfaceFormatsKHR(physDevice, mySurface, &formatCount, formats);

        const VkSwapchainCreateInfoKHR createInfo =
        {
            VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR,    // sType
            NULL,                                           // pNext
            0,                                              // flags
            mySurface,                                      // surface
            3,                                              // minImageCount
            formats[0].format,                              // imageFormat
            formats[0].colorSpace,                          // imageColorSpace
            myModeProps.parameters.visibleRegion,           // imageExtent
            1,                                              // imageArrayLayers
            VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,            // imageUsage
            VK_SHARING_MODE_EXCLUSIVE,                      // imageSharingMode
            0,                                              // queueFamilyIndexCount
            NULL,                                           // pQueueFamilyIndices
            VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR,          // preTransform
            VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR,              // compositeAlpha
            VK_PRESENT_MODE_FIFO_KHR,                       // presentMode
            VK_TRUE,                                        // clipped
            VK_NULL_HANDLE                                  // oldSwapchain
        };

        VkSwapchainKHR swapchain;
        // This is equivalent to vkCreateSwapchainKHR.
        vkCreateSharedSwapchainsKHR(device, 1, &createInfo, NULL, &swapchain);

### D.5.8. Version History

- Revision 1, 2015-07-29 (James Jones)

  - Initial draft

- Revision 2, 2015-08-21 (Ian Elliott)

  - Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.
  - Switched from "revision" to "version", including use of the VK_MAKE_VERSION macro in the header file.

- Revision 3, 2015-09-01 (James Jones)

  - Restore single-field revision number.

- Revision 4, 2015-09-08 (James Jones)

  - Allow creating multiple swap chains that share the same images using a single call to vkCreateSwapChainKHR().

- Revision 5, 2015-09-10 (Alon Or-bach)

  - Removed underscores from SWAP_CHAIN in two enums.

- Revision 6, 2015-10-02 (James Jones)

  - Added support for smart panels/buffered displays.

- Revision 7, 2015-10-26 (Ian Elliott)

  - Renamed from VK_EXT_KHR_display_swapchain to VK_KHR_display_swapchain.

- Revision 8, 2015-11-03 (Daniel Rakos)

  - Updated sample code based on the changes to VK_KHR_swapchain.

- Revision 9, 2015-11-10 (Jesse Hall)

  - Replaced VkDisplaySwapchainCreateInfoKHR with vkCreateSharedSwapchainsKHR, changing resolution of issue #4.