Class VkSwapchainCreateInfoKHR

  • All Implemented Interfaces:
    java.lang.AutoCloseable, NativeResource, Pointer

    public class VkSwapchainCreateInfoKHR
    extends Struct
    implements NativeResource
    Structure specifying parameters of a newly created swapchain object.
    Valid Usage (Implicit)
    • Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkDeviceGroupSwapchainCreateInfoKHR, VkImageFormatListCreateInfoKHR, VkSurfaceFullScreenExclusiveInfoEXT, VkSurfaceFullScreenExclusiveWin32InfoEXT, VkSwapchainCounterCreateInfoEXT, or VkSwapchainDisplayNativeHdrCreateInfoAMD
    • Each sType member in the pNext chain must be unique
    • flags must be a valid combination of VkSwapchainCreateFlagBitsKHR values
    • surface must be a valid VkSurfaceKHR handle
    • imageFormat must be a valid VkFormat value
    • imageColorSpace must be a valid VkColorSpaceKHR value
    • imageUsage must be a valid combination of VkImageUsageFlagBits values
    • imageUsage must not be 0
    • imageSharingMode must be a valid VkSharingMode value
    • preTransform must be a valid VkSurfaceTransformFlagBitsKHR value
    • compositeAlpha must be a valid VkCompositeAlphaFlagBitsKHR value
    • presentMode must be a valid VkPresentModeKHR value
    • If oldSwapchain is not NULL_HANDLE, oldSwapchain must be a valid VkSwapchainKHR handle
    • If oldSwapchain is a valid handle, it must have been created, allocated, or retrieved from surface
    • Both of oldSwapchain, and surface that are valid handles must have been created, allocated, or retrieved from the same VkInstance
    See Also

    VkExtent2D, CreateSharedSwapchainsKHR, CreateSwapchainKHR

    Member documentation

    • sType – the type of this structure.
    • pNextNULL or a pointer to an extension-specific structure.
    • flags – a bitmask of VkSwapchainCreateFlagBitsKHR indicating parameters of the swapchain creation.
    • surface – the surface onto which the swapchain will present images. If the creation succeeds, the swapchain becomes associated with surface.
    • minImageCount – the minimum number of presentable images that the application needs. The implementation will either create the swapchain with at least that many images, or it will fail to create the swapchain.
    • imageFormat – a VkFormat value specifying the format the swapchain image(s) will be created with.
    • imageColorSpace – a VkColorSpaceKHR value specifying the way the swapchain interprets image data.
    • imageExtent – the size (in pixels) of the swapchain image(s). The behavior is platform-dependent if the image extent does not match the surface’s currentExtent as returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR.

      On some platforms, it is normal that maxImageExtent may become (0, 0), for example when the window is minimized. In such a case, it is not possible to create a swapchain due to the Valid Usage requirements.

    • imageArrayLayers – the number of views in a multiview/stereo surface. For non-stereoscopic-3D applications, this value is 1.
    • imageUsage – a bitmask of VkImageUsageFlagBits describing the intended usage of the (acquired) swapchain images.
    • imageSharingMode – the sharing mode used for the image(s) of the swapchain.
    • queueFamilyIndexCount – the number of queue families having access to the image(s) of the swapchain when imageSharingMode is SHARING_MODE_CONCURRENT.
    • pQueueFamilyIndices – an array of queue family indices having access to the images(s) of the swapchain when imageSharingMode is SHARING_MODE_CONCURRENT.
    • preTransform – a VkSurfaceTransformFlagBitsKHR value describing the transform, relative to the presentation engine’s natural orientation, applied to the image content prior to presentation. If it does not match the currentTransform value returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine will transform the image content as part of the presentation operation.
    • compositeAlpha – a VkCompositeAlphaFlagBitsKHR value indicating the alpha compositing mode to use when this surface is composited together with other surfaces on certain window systems.
    • presentMode – the presentation mode the swapchain will use. A swapchain’s present mode determines how incoming present requests will be processed and queued internally.
    • clipped – specifies whether the Vulkan implementation is allowed to discard rendering operations that affect regions of the surface that are not visible.
      • If set to TRUE, the presentable images associated with the swapchain may not own all of their pixels. Pixels in the presentable images that correspond to regions of the target surface obscured by another window on the desktop, or subject to some other clipping mechanism will have undefined content when read back. Pixel shaders may not execute for these pixels, and thus any side effects they would have had will not occur. TRUE value does not guarantee any clipping will occur, but allows more optimal presentation methods to be used on some platforms.
      • If set to FALSE, presentable images associated with the swapchain will own all of the pixels they contain.

        Applications should set this value to TRUE if they do not expect to read back the content of presentable images before presenting them or after reacquiring them, and if their pixel shaders do not have any side effects that require them to run for all pixels in the presentable image.

    • oldSwapchainNULL_HANDLE, or the existing non-retired swapchain currently associated with surface. Providing a valid oldSwapchain may aid in the resource reuse, and also allows the application to still present any images that are already acquired from it.

      Upon calling vkCreateSwapchainKHR with an oldSwapchain that is not NULL_HANDLE, oldSwapchain is retired -- even if creation of the new swapchain fails. The new swapchain is created in the non-retired state whether or not oldSwapchain is NULL_HANDLE.

      Upon calling vkCreateSwapchainKHR with an oldSwapchain that is not NULL_HANDLE, any images from oldSwapchain that are not acquired by the application may be freed by the implementation, which may occur even if creation of the new swapchain fails. The application can destroy oldSwapchain to free all memory associated with oldSwapchain.


      Multiple retired swapchains can be associated with the same VkSurfaceKHR through multiple uses of oldSwapchain that outnumber calls to DestroySwapchainKHR.

      After oldSwapchain is retired, the application can pass to QueuePresentKHR any images it had already acquired from oldSwapchain. E.g., an application may present an image from the old swapchain before an image from the new swapchain is ready to be presented. As usual, QueuePresentKHR may fail if oldSwapchain has entered a state that causes ERROR_OUT_OF_DATE_KHR to be returned.

      The application can continue to use a shared presentable image obtained from oldSwapchain until a presentable image is acquired from the new swapchain, as long as it has not entered a state that causes it to return ERROR_OUT_OF_DATE_KHR.


     struct VkSwapchainCreateInfoKHR {
         VkStructureType sType;
         void const * pNext;
         VkSwapchainCreateFlagsKHR flags;
         VkSurfaceKHR surface;
         uint32_t minImageCount;
         VkFormat imageFormat;
         VkColorSpaceKHR imageColorSpace;
         VkExtent2D imageExtent;
         uint32_t imageArrayLayers;
         VkImageUsageFlags imageUsage;
         VkSharingMode imageSharingMode;
         uint32_t queueFamilyIndexCount;
         uint32_t const * pQueueFamilyIndices;
         VkSurfaceTransformFlagBitsKHR preTransform;
         VkCompositeAlphaFlagBitsKHR compositeAlpha;
         VkPresentModeKHR presentMode;
         VkBool32 clipped;
         VkSwapchainKHR oldSwapchain;
    • Field Detail

      • SIZEOF

        The struct size in bytes.
      • ALIGNOF

        The struct alignment in bytes.

        The struct member offsets.
    • Constructor Detail

      • VkSwapchainCreateInfoKHR

        public VkSwapchainCreateInfoKHR​(java.nio.ByteBuffer container)
        Creates a VkSwapchainCreateInfoKHR instance at the current position of the specified ByteBuffer container. Changes to the buffer's content will be visible to the struct instance and vice versa.

        The created instance holds a strong reference to the container object.

    • Method Detail

      • sizeof

        public int sizeof()
        Description copied from class: Struct
        Returns sizeof(struct).
        Specified by:
        sizeof in class Struct
      • sType

        public int sType()
        Returns the value of the sType field.
      • pNext

        public long pNext()
        Returns the value of the pNext field.
      • flags

        public int flags()
        Returns the value of the flags field.
      • surface

        public long surface()
        Returns the value of the surface field.
      • minImageCount

        public int minImageCount()
        Returns the value of the minImageCount field.
      • imageFormat

        public int imageFormat()
        Returns the value of the imageFormat field.
      • imageColorSpace

        public int imageColorSpace()
        Returns the value of the imageColorSpace field.
      • imageArrayLayers

        public int imageArrayLayers()
        Returns the value of the imageArrayLayers field.
      • imageUsage

        public int imageUsage()
        Returns the value of the imageUsage field.
      • imageSharingMode

        public int imageSharingMode()
        Returns the value of the imageSharingMode field.
      • queueFamilyIndexCount

        public int queueFamilyIndexCount()
        Returns the value of the queueFamilyIndexCount field.
      • pQueueFamilyIndices

        public java.nio.IntBuffer pQueueFamilyIndices()
        Returns a IntBuffer view of the data pointed to by the pQueueFamilyIndices field.
      • preTransform

        public int preTransform()
        Returns the value of the preTransform field.
      • compositeAlpha

        public int compositeAlpha()
        Returns the value of the compositeAlpha field.
      • presentMode

        public int presentMode()
        Returns the value of the presentMode field.
      • clipped

        public boolean clipped()
        Returns the value of the clipped field.
      • oldSwapchain

        public long oldSwapchain()
        Returns the value of the oldSwapchain field.
      • minImageCount

        public VkSwapchainCreateInfoKHR minImageCount​(int value)
        Sets the specified value to the minImageCount field.
      • imageFormat

        public VkSwapchainCreateInfoKHR imageFormat​(int value)
        Sets the specified value to the imageFormat field.
      • imageColorSpace

        public VkSwapchainCreateInfoKHR imageColorSpace​(int value)
        Sets the specified value to the imageColorSpace field.
      • imageArrayLayers

        public VkSwapchainCreateInfoKHR imageArrayLayers​(int value)
        Sets the specified value to the imageArrayLayers field.
      • imageUsage

        public VkSwapchainCreateInfoKHR imageUsage​(int value)
        Sets the specified value to the imageUsage field.
      • imageSharingMode

        public VkSwapchainCreateInfoKHR imageSharingMode​(int value)
        Sets the specified value to the imageSharingMode field.
      • pQueueFamilyIndices

        public VkSwapchainCreateInfoKHR pQueueFamilyIndices​(@Nullable
                                                            java.nio.IntBuffer value)
        Sets the address of the specified IntBuffer to the pQueueFamilyIndices field.
      • preTransform

        public VkSwapchainCreateInfoKHR preTransform​(int value)
        Sets the specified value to the preTransform field.
      • compositeAlpha

        public VkSwapchainCreateInfoKHR compositeAlpha​(int value)
        Sets the specified value to the compositeAlpha field.
      • presentMode

        public VkSwapchainCreateInfoKHR presentMode​(int value)
        Sets the specified value to the presentMode field.
      • oldSwapchain

        public VkSwapchainCreateInfoKHR oldSwapchain​(long value)
        Sets the specified value to the oldSwapchain field.
      • set

        public VkSwapchainCreateInfoKHR set​(int sType,
                                            long pNext,
                                            int flags,
                                            long surface,
                                            int minImageCount,
                                            int imageFormat,
                                            int imageColorSpace,
                                            VkExtent2D imageExtent,
                                            int imageArrayLayers,
                                            int imageUsage,
                                            int imageSharingMode,
                                            java.nio.IntBuffer pQueueFamilyIndices,
                                            int preTransform,
                                            int compositeAlpha,
                                            int presentMode,
                                            boolean clipped,
                                            long oldSwapchain)
        Initializes this struct with the specified values.
      • malloc

        public static VkSwapchainCreateInfoKHR malloc()
        Returns a new VkSwapchainCreateInfoKHR instance allocated with memAlloc. The instance must be explicitly freed.
      • calloc

        public static VkSwapchainCreateInfoKHR calloc()
        Returns a new VkSwapchainCreateInfoKHR instance allocated with memCalloc. The instance must be explicitly freed.
      • create

        public static VkSwapchainCreateInfoKHR create​(long address)
        Returns a new VkSwapchainCreateInfoKHR instance for the specified memory address.
      • callocStack

        public static VkSwapchainCreateInfoKHR callocStack()
        Returns a new VkSwapchainCreateInfoKHR instance allocated on the thread-local MemoryStack and initializes all its bits to zero.
      • mallocStack

        public static VkSwapchainCreateInfoKHR mallocStack​(MemoryStack stack)
        Returns a new VkSwapchainCreateInfoKHR instance allocated on the specified MemoryStack.
        stack - the stack from which to allocate
      • callocStack

        public static VkSwapchainCreateInfoKHR callocStack​(MemoryStack stack)
        Returns a new VkSwapchainCreateInfoKHR instance allocated on the specified MemoryStack and initializes all its bits to zero.
        stack - the stack from which to allocate
      • nsType

        public static int nsType​(long struct)
        Unsafe version of sType().
      • npNext

        public static long npNext​(long struct)
        Unsafe version of pNext().
      • nflags

        public static int nflags​(long struct)
        Unsafe version of flags().
      • nsurface

        public static long nsurface​(long struct)
        Unsafe version of surface().
      • nminImageCount

        public static int nminImageCount​(long struct)
        Unsafe version of minImageCount().
      • nimageFormat

        public static int nimageFormat​(long struct)
        Unsafe version of imageFormat().
      • nimageColorSpace

        public static int nimageColorSpace​(long struct)
        Unsafe version of imageColorSpace().
      • nimageArrayLayers

        public static int nimageArrayLayers​(long struct)
        Unsafe version of imageArrayLayers().
      • nimageUsage

        public static int nimageUsage​(long struct)
        Unsafe version of imageUsage().
      • nimageSharingMode

        public static int nimageSharingMode​(long struct)
        Unsafe version of imageSharingMode().
      • nqueueFamilyIndexCount

        public static int nqueueFamilyIndexCount​(long struct)
        Unsafe version of queueFamilyIndexCount().
      • npQueueFamilyIndices

        public static java.nio.IntBuffer npQueueFamilyIndices​(long struct)
        Unsafe version of pQueueFamilyIndices.
      • npreTransform

        public static int npreTransform​(long struct)
        Unsafe version of preTransform().
      • ncompositeAlpha

        public static int ncompositeAlpha​(long struct)
        Unsafe version of compositeAlpha().
      • npresentMode

        public static int npresentMode​(long struct)
        Unsafe version of presentMode().
      • nclipped

        public static int nclipped​(long struct)
        Unsafe version of clipped().
      • noldSwapchain

        public static long noldSwapchain​(long struct)
        Unsafe version of oldSwapchain().
      • nsType

        public static void nsType​(long struct,
                                  int value)
        Unsafe version of sType.
      • npNext

        public static void npNext​(long struct,
                                  long value)
        Unsafe version of pNext.
      • nflags

        public static void nflags​(long struct,
                                  int value)
        Unsafe version of flags.
      • nsurface

        public static void nsurface​(long struct,
                                    long value)
        Unsafe version of surface.
      • nminImageCount

        public static void nminImageCount​(long struct,
                                          int value)
        Unsafe version of minImageCount.
      • nimageFormat

        public static void nimageFormat​(long struct,
                                        int value)
        Unsafe version of imageFormat.
      • nimageColorSpace

        public static void nimageColorSpace​(long struct,
                                            int value)
        Unsafe version of imageColorSpace.
      • nimageExtent

        public static void nimageExtent​(long struct,
                                        VkExtent2D value)
        Unsafe version of imageExtent.
      • nimageArrayLayers

        public static void nimageArrayLayers​(long struct,
                                             int value)
        Unsafe version of imageArrayLayers.
      • nimageUsage

        public static void nimageUsage​(long struct,
                                       int value)
        Unsafe version of imageUsage.
      • nimageSharingMode

        public static void nimageSharingMode​(long struct,
                                             int value)
        Unsafe version of imageSharingMode.
      • nqueueFamilyIndexCount

        public static void nqueueFamilyIndexCount​(long struct,
                                                  int value)
        Sets the specified value to the queueFamilyIndexCount field of the specified struct.
      • npQueueFamilyIndices

        public static void npQueueFamilyIndices​(long struct,
                                                java.nio.IntBuffer value)
        Unsafe version of pQueueFamilyIndices.
      • npreTransform

        public static void npreTransform​(long struct,
                                         int value)
        Unsafe version of preTransform.
      • ncompositeAlpha

        public static void ncompositeAlpha​(long struct,
                                           int value)
        Unsafe version of compositeAlpha.
      • npresentMode

        public static void npresentMode​(long struct,
                                        int value)
        Unsafe version of presentMode.
      • nclipped

        public static void nclipped​(long struct,
                                    int value)
        Unsafe version of clipped.
      • noldSwapchain

        public static void noldSwapchain​(long struct,
                                         long value)
        Unsafe version of oldSwapchain.
      • validate

        public static void validate​(long struct)
        Validates pointer members that should not be NULL.
        struct - the struct to validate
      • validate

        public static void validate​(long array,
                                    int count)
        Calls validate(long) for each struct contained in the specified struct array.
        array - the struct array to validate
        count - the number of structs in array