org.lwjgl.vulkan.KHRSwapchain Maven / Gradle / Ivy
Show all versions of lwjgl-vulkan Show documentation
/*
* Copyright LWJGL. All rights reserved.
* License terms: https://www.lwjgl.org/license
* MACHINE GENERATED FILE, DO NOT EDIT
*/
package org.lwjgl.vulkan;
import java.nio.*;
import static org.lwjgl.system.Checks.*;
import static org.lwjgl.system.JNI.*;
import static org.lwjgl.system.MemoryUtil.*;
/** The {@code VK_KHR_swapchain} extension is the device-level companion to the {@code VK_KHR_surface} extension. It introduces {@code VkSwapchainKHR} objects, which provide the ability to present rendering results to a surface. */
public class KHRSwapchain {
/** The extension specification version. */
public static final int VK_KHR_SWAPCHAIN_SPEC_VERSION = 68;
/** The extension name. */
public static final String VK_KHR_SWAPCHAIN_EXTENSION_NAME = "VK_KHR_swapchain";
/**
* Extends {@code VkStructureType}.
*
* Enum values:
*
*
* - {@link #VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR}
* - {@link #VK_STRUCTURE_TYPE_PRESENT_INFO_KHR STRUCTURE_TYPE_PRESENT_INFO_KHR}
*
*/
public static final int
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR = 1000001000,
VK_STRUCTURE_TYPE_PRESENT_INFO_KHR = 1000001001;
/** Extends {@code VkImageLayout}. */
public static final int VK_IMAGE_LAYOUT_PRESENT_SRC_KHR = 1000001002;
/**
* Extends {@code VkResult}.
*
* Enum values:
*
*
* - {@link #VK_SUBOPTIMAL_KHR SUBOPTIMAL_KHR}
* - {@link #VK_ERROR_OUT_OF_DATE_KHR ERROR_OUT_OF_DATE_KHR}
*
*/
public static final int
VK_SUBOPTIMAL_KHR = 1000001003,
VK_ERROR_OUT_OF_DATE_KHR = -1000001004;
protected KHRSwapchain() {
throw new UnsupportedOperationException();
}
static boolean isAvailable(VKCapabilities caps) {
return checkFunctions(
caps.vkCreateSwapchainKHR, caps.vkDestroySwapchainKHR, caps.vkGetSwapchainImagesKHR, caps.vkAcquireNextImageKHR, caps.vkQueuePresentKHR
);
}
// --- [ vkCreateSwapchainKHR ] ---
/** Unsafe version of: {@link #vkCreateSwapchainKHR CreateSwapchainKHR} */
public static int nvkCreateSwapchainKHR(VkDevice device, long pCreateInfo, long pAllocator, long pSwapchain) {
long __functionAddress = device.getCapabilities().vkCreateSwapchainKHR;
if ( CHECKS ) {
check(__functionAddress);
VkSwapchainCreateInfoKHR.validate(pCreateInfo);
if ( pAllocator != NULL ) VkAllocationCallbacks.validate(pAllocator);
}
return callPPPPI(__functionAddress, device.address(), pCreateInfo, pAllocator, pSwapchain);
}
/**
* Create a swapchain.
*
* C Specification
*
* To create a swapchain, call:
*
* VkResult vkCreateSwapchainKHR(
VkDevice device,
const VkSwapchainCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSwapchainKHR* pSwapchain);
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - {@code pCreateInfo} must be a pointer to a valid {@link VkSwapchainCreateInfoKHR} structure
* - If {@code pAllocator} is not {@code NULL}, {@code pAllocator} must be a pointer to a valid {@link VkAllocationCallbacks} structure
* - {@code pSwapchain} must be a pointer to a {@code VkSwapchainKHR} handle
*
*
* Host Synchronization
*
*
* - Host access to {@code pCreateInfo.surface} must be externally synchronized
* - Host access to {@code pCreateInfo.oldSwapchain} must be externally synchronized
*
*
* Return Codes
*
*
* - On success, this command returns
*
* - {@link VK10#VK_SUCCESS SUCCESS}
*
* - On failure, this command returns
*
* - {@link VK10#VK_ERROR_OUT_OF_HOST_MEMORY ERROR_OUT_OF_HOST_MEMORY}
* - {@link VK10#VK_ERROR_OUT_OF_DEVICE_MEMORY ERROR_OUT_OF_DEVICE_MEMORY}
* - {@link VK10#VK_ERROR_DEVICE_LOST ERROR_DEVICE_LOST}
* - {@link KHRSurface#VK_ERROR_SURFACE_LOST_KHR ERROR_SURFACE_LOST_KHR}
* - {@link KHRSurface#VK_ERROR_NATIVE_WINDOW_IN_USE_KHR ERROR_NATIVE_WINDOW_IN_USE_KHR}
*
*
*
* See Also
*
* {@link VkAllocationCallbacks}, {@link VkSwapchainCreateInfoKHR}
*
* @param device the device to create the swapchain for.
* @param pCreateInfo a pointer to an instance of the {@link VkSwapchainCreateInfoKHR} structure specifying the parameters of the created swapchain.
* @param pAllocator the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).
* @param pSwapchain a pointer to a {@code VkSwapchainKHR} handle in which the created swapchain object will be returned.
*/
public static int vkCreateSwapchainKHR(VkDevice device, VkSwapchainCreateInfoKHR pCreateInfo, VkAllocationCallbacks pAllocator, LongBuffer pSwapchain) {
if ( CHECKS )
check(pSwapchain, 1);
return nvkCreateSwapchainKHR(device, pCreateInfo.address(), memAddressSafe(pAllocator), memAddress(pSwapchain));
}
// --- [ vkDestroySwapchainKHR ] ---
/** Unsafe version of: {@link #vkDestroySwapchainKHR DestroySwapchainKHR} */
public static void nvkDestroySwapchainKHR(VkDevice device, long swapchain, long pAllocator) {
long __functionAddress = device.getCapabilities().vkDestroySwapchainKHR;
if ( CHECKS ) {
check(__functionAddress);
if ( pAllocator != NULL ) VkAllocationCallbacks.validate(pAllocator);
}
callPJPV(__functionAddress, device.address(), swapchain, pAllocator);
}
/**
* Destroy a swapchain object.
*
* C Specification
*
* To destroy a swapchain object call:
*
* void vkDestroySwapchainKHR(
VkDevice device,
VkSwapchainKHR swapchain,
const VkAllocationCallbacks* pAllocator);
*
* Description
*
* {@code swapchain} and all associated {@code VkImage} handles are destroyed, and must not be acquired or used any more by the application. The memory of each {@code VkImage} will only be freed after that image is no longer used by the platform. For example, if one image of the swapchain is being displayed in a window, the memory for that image may not be freed until the window is destroyed, or another swapchain is created for the window. Destroying the swapchain does not invalidate the parent {@code VkSurfaceKHR}, and a new swapchain can be created with it.
*
* If a swapchain associated with a display surface is destroyed and there are no valid descendants of that swapchain, the implementation must either revert any display resources modified by presenting images with the swapchain to their state prior to the first present performed with the swapchain and its ancestors, or leave such resources in their current state.
*
* Valid Usage
*
*
* - All uses of presentable images acquired from {@code swapchain} must have completed execution
* - If {@link VkAllocationCallbacks} were provided when {@code swapchain} was created, a compatible set of callbacks must be provided here
* - If no {@link VkAllocationCallbacks} were provided when {@code swapchain} was created, {@code pAllocator} must be {@code NULL}
*
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - If {@code swapchain} is not {@link VK10#VK_NULL_HANDLE NULL_HANDLE}, {@code swapchain} must be a valid {@code VkSwapchainKHR} handle
* - If {@code pAllocator} is not {@code NULL}, {@code pAllocator} must be a pointer to a valid {@link VkAllocationCallbacks} structure
*
*
* Host Synchronization
*
*
* - Host access to {@code swapchain} must be externally synchronized
*
*
* See Also
*
* {@link VkAllocationCallbacks}
*
* @param device the {@code VkDevice} associated with {@code swapchain}.
* @param swapchain the swapchain to destroy.
* @param pAllocator the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).
*/
public static void vkDestroySwapchainKHR(VkDevice device, long swapchain, VkAllocationCallbacks pAllocator) {
nvkDestroySwapchainKHR(device, swapchain, memAddressSafe(pAllocator));
}
// --- [ vkGetSwapchainImagesKHR ] ---
/**
* Unsafe version of: {@link #vkGetSwapchainImagesKHR GetSwapchainImagesKHR}
*
* @param pSwapchainImageCount a pointer to an integer related to the number of swapchain images available or queried, as described below.
*/
public static int nvkGetSwapchainImagesKHR(VkDevice device, long swapchain, long pSwapchainImageCount, long pSwapchainImages) {
long __functionAddress = device.getCapabilities().vkGetSwapchainImagesKHR;
if ( CHECKS )
check(__functionAddress);
return callPJPPI(__functionAddress, device.address(), swapchain, pSwapchainImageCount, pSwapchainImages);
}
/**
* Obtain the array of presentable images associated with a swapchain.
*
* C Specification
*
* To obtain the array of presentable images associated with a swapchain, call:
*
* VkResult vkGetSwapchainImagesKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint32_t* pSwapchainImageCount,
VkImage* pSwapchainImages);
*
* Description
*
* If {@code pSwapchainImages} is {@code NULL}, then the number of presentable images for {@code swapchain} is returned in {@code pSwapchainImageCount}. Otherwise, {@code pSwapchainImageCount} must point to a variable set by the user to the number of elements in the {@code pSwapchainImages} array, and on return the variable is overwritten with the number of structures actually written to {@code pSwapchainImages}. If the value of {@code pSwapchainImageCount} is less than the number of presentable images for {@code swapchain}, at most {@code pSwapchainImageCount} structures will be written. If {@code pSwapchainImageCount} is smaller than the number of presentable images for {@code swapchain}, {@link VK10#VK_INCOMPLETE INCOMPLETE} will be returned instead of {@link VK10#VK_SUCCESS SUCCESS} to indicate that not all the available values were returned.
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - {@code swapchain} must be a valid {@code VkSwapchainKHR} handle
* - {@code pSwapchainImageCount} must be a pointer to a {@code uint32_t} value
* - If the value referenced by {@code pSwapchainImageCount} is not 0, and {@code pSwapchainImages} is not {@code NULL}, {@code pSwapchainImages} must be a pointer to an array of {@code pSwapchainImageCount} {@code VkImage} handles
*
*
* Return Codes
*
*
* - On success, this command returns
*
* - {@link VK10#VK_SUCCESS SUCCESS}
* - {@link VK10#VK_INCOMPLETE INCOMPLETE}
*
* - On failure, this command returns
*
* - {@link VK10#VK_ERROR_OUT_OF_HOST_MEMORY ERROR_OUT_OF_HOST_MEMORY}
* - {@link VK10#VK_ERROR_OUT_OF_DEVICE_MEMORY ERROR_OUT_OF_DEVICE_MEMORY}
*
*
*
* @param device the device associated with {@code swapchain}.
* @param swapchain the swapchain to query.
* @param pSwapchainImageCount a pointer to an integer related to the number of swapchain images available or queried, as described below.
* @param pSwapchainImages either {@code NULL} or a pointer to an array of {@code VkImage} handles.
*/
public static int vkGetSwapchainImagesKHR(VkDevice device, long swapchain, IntBuffer pSwapchainImageCount, LongBuffer pSwapchainImages) {
if ( CHECKS ) {
check(pSwapchainImageCount, 1);
checkSafe(pSwapchainImages, pSwapchainImageCount.get(pSwapchainImageCount.position()));
}
return nvkGetSwapchainImagesKHR(device, swapchain, memAddress(pSwapchainImageCount), memAddressSafe(pSwapchainImages));
}
// --- [ vkAcquireNextImageKHR ] ---
/** Unsafe version of: {@link #vkAcquireNextImageKHR AcquireNextImageKHR} */
public static int nvkAcquireNextImageKHR(VkDevice device, long swapchain, long timeout, long semaphore, long fence, long pImageIndex) {
long __functionAddress = device.getCapabilities().vkAcquireNextImageKHR;
if ( CHECKS )
check(__functionAddress);
return callPJJJJPI(__functionAddress, device.address(), swapchain, timeout, semaphore, fence, pImageIndex);
}
/**
* Retrieve the index of the next available presentable image.
*
* C Specification
*
* To acquire an available presentable image to use, and retrieve the index of that image, call:
*
* VkResult vkAcquireNextImageKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint64_t timeout,
VkSemaphore semaphore,
VkFence fence,
uint32_t* pImageIndex);
*
* Valid Usage
*
*
* - If {@code semaphore} is not {@link VK10#VK_NULL_HANDLE NULL_HANDLE} it must be unsignaled
* - If {@code fence} is not {@link VK10#VK_NULL_HANDLE NULL_HANDLE} it must be unsignaled and must not be associated with any other queue command that has not yet completed execution on that queue
*
*
* Valid Usage (Implicit)
*
*
* - {@code device} must be a valid {@code VkDevice} handle
* - {@code swapchain} must be a valid {@code VkSwapchainKHR} handle
* - If {@code semaphore} is not {@link VK10#VK_NULL_HANDLE NULL_HANDLE}, {@code semaphore} must be a valid {@code VkSemaphore} handle
* - If {@code fence} is not {@link VK10#VK_NULL_HANDLE NULL_HANDLE}, {@code fence} must be a valid {@code VkFence} handle
* - {@code pImageIndex} must be a pointer to a {@code uint32_t} value
* - If {@code semaphore} is a valid handle, it must have been created, allocated, or retrieved from {@code device}
* - If {@code fence} is a valid handle, it must have been created, allocated, or retrieved from {@code device}
*
*
* Host Synchronization
*
*
* - Host access to {@code swapchain} must be externally synchronized
* - Host access to {@code semaphore} must be externally synchronized
* - Host access to {@code fence} must be externally synchronized
*
*
* Return Codes
*
*
* - On success, this command returns
*
* - {@link VK10#VK_SUCCESS SUCCESS}
* - {@link VK10#VK_TIMEOUT TIMEOUT}
* - {@link VK10#VK_NOT_READY NOT_READY}
* - {@link #VK_SUBOPTIMAL_KHR SUBOPTIMAL_KHR}
*
* - On failure, this command returns
*
* - {@link VK10#VK_ERROR_OUT_OF_HOST_MEMORY ERROR_OUT_OF_HOST_MEMORY}
* - {@link VK10#VK_ERROR_OUT_OF_DEVICE_MEMORY ERROR_OUT_OF_DEVICE_MEMORY}
* - {@link VK10#VK_ERROR_DEVICE_LOST ERROR_DEVICE_LOST}
* - {@link #VK_ERROR_OUT_OF_DATE_KHR ERROR_OUT_OF_DATE_KHR}
* - {@link KHRSurface#VK_ERROR_SURFACE_LOST_KHR ERROR_SURFACE_LOST_KHR}
*
*
*
* @param device the device associated with {@code swapchain}.
* @param swapchain the swapchain from which an image is being acquired.
* @param timeout indicates how long the function waits, in nanoseconds, if no image is available.
* @param semaphore {@link VK10#VK_NULL_HANDLE NULL_HANDLE} or a semaphore to signal.
* @param fence {@link VK10#VK_NULL_HANDLE NULL_HANDLE} or a fence to signal.
* @param pImageIndex a pointer to a {@code uint32_t} that is set to the index of the next image to use (i.e. an index into the array of images returned by {@link #vkGetSwapchainImagesKHR GetSwapchainImagesKHR}).
*/
public static int vkAcquireNextImageKHR(VkDevice device, long swapchain, long timeout, long semaphore, long fence, IntBuffer pImageIndex) {
if ( CHECKS )
check(pImageIndex, 1);
return nvkAcquireNextImageKHR(device, swapchain, timeout, semaphore, fence, memAddress(pImageIndex));
}
// --- [ vkQueuePresentKHR ] ---
/** Unsafe version of: {@link #vkQueuePresentKHR QueuePresentKHR} */
public static int nvkQueuePresentKHR(VkQueue queue, long pPresentInfo) {
long __functionAddress = queue.getCapabilities().vkQueuePresentKHR;
if ( CHECKS ) {
check(__functionAddress);
VkPresentInfoKHR.validate(pPresentInfo);
}
return callPPI(__functionAddress, queue.address(), pPresentInfo);
}
/**
* Queue an image for presentation.
*
* C Specification
*
* After queueing all rendering commands and transitioning the image to the correct layout, to queue an image for presentation, call:
*
* VkResult vkQueuePresentKHR(
VkQueue queue,
const VkPresentInfoKHR* pPresentInfo);
*
* Valid Usage
*
*
* - Any given element of {@code pSwapchains} member of {@code pPresentInfo} must be a swapchain that is created for a surface for which presentation is supported from {@code queue} as determined using a call to {@link KHRSurface#vkGetPhysicalDeviceSurfaceSupportKHR GetPhysicalDeviceSurfaceSupportKHR}
* - If more than one member of {@code pSwapchains} was created from a display surface, all display surfaces referenced that refer to the same display must use the same display mode
* - When a semaphore unsignal operation defined by the elements of the {@code pWaitSemaphores} member of {@code pPresentInfo} executes on {@code queue}, no other queue must be waiting on the same semaphore.
* - All elements of elements of the {@code pWaitSemaphores} member of {@code pPresentInfo} must be semaphores that are signaled, or have semaphore signal operations previously submitted for execution.
*
*
* Any writes to memory backing the images referenced by the {@code pImageIndices} and {@code pSwapchains} members of {@code pPresentInfo}, that are available before {@link #vkQueuePresentKHR QueuePresentKHR} is executed, are automatically made visible to the read access performed by the presentation engine. This automatic visibility operation for an image happens-after the semaphore signal operation, and happens-before the presentation engine accesses the image.
*
* Valid Usage (Implicit)
*
*
* - {@code queue} must be a valid {@code VkQueue} handle
* - {@code pPresentInfo} must be a pointer to a valid {@link VkPresentInfoKHR} structure
*
*
* Host Synchronization
*
*
* - Host access to {@code queue} must be externally synchronized
* - Host access to {@code pPresentInfo.pWaitSemaphores}[] must be externally synchronized
* - Host access to {@code pPresentInfo.pSwapchains}[] must be externally synchronized
*
*
* Command Properties
*
*
* Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type
* - - Any -
*
*
* Return Codes
*
*
* - On success, this command returns
*
* - {@link VK10#VK_SUCCESS SUCCESS}
* - {@link #VK_SUBOPTIMAL_KHR SUBOPTIMAL_KHR}
*
* - On failure, this command returns
*
* - {@link VK10#VK_ERROR_OUT_OF_HOST_MEMORY ERROR_OUT_OF_HOST_MEMORY}
* - {@link VK10#VK_ERROR_OUT_OF_DEVICE_MEMORY ERROR_OUT_OF_DEVICE_MEMORY}
* - {@link VK10#VK_ERROR_DEVICE_LOST ERROR_DEVICE_LOST}
* - {@link #VK_ERROR_OUT_OF_DATE_KHR ERROR_OUT_OF_DATE_KHR}
* - {@link KHRSurface#VK_ERROR_SURFACE_LOST_KHR ERROR_SURFACE_LOST_KHR}
*
*
*
* See Also
*
* {@link VkPresentInfoKHR}
*
* @param queue a queue that is capable of presentation to the target surface’s platform on the same device as the image’s swapchain.
* @param pPresentInfo a pointer to an instance of the {@link VkPresentInfoKHR} structure specifying the parameters of the presentation.
*/
public static int vkQueuePresentKHR(VkQueue queue, VkPresentInfoKHR pPresentInfo) {
return nvkQueuePresentKHR(queue, pPresentInfo.address());
}
/** Array version of: {@link #vkCreateSwapchainKHR CreateSwapchainKHR} */
public static int vkCreateSwapchainKHR(VkDevice device, VkSwapchainCreateInfoKHR pCreateInfo, VkAllocationCallbacks pAllocator, long[] pSwapchain) {
long __functionAddress = device.getCapabilities().vkCreateSwapchainKHR;
if ( CHECKS ) {
check(__functionAddress);
check(pSwapchain, 1);
VkSwapchainCreateInfoKHR.validate(pCreateInfo.address());
if ( pAllocator != null ) VkAllocationCallbacks.validate(pAllocator.address());
}
return callPPPPI(__functionAddress, device.address(), pCreateInfo.address(), memAddressSafe(pAllocator), pSwapchain);
}
/** Array version of: {@link #vkGetSwapchainImagesKHR GetSwapchainImagesKHR} */
public static int vkGetSwapchainImagesKHR(VkDevice device, long swapchain, int[] pSwapchainImageCount, long[] pSwapchainImages) {
long __functionAddress = device.getCapabilities().vkGetSwapchainImagesKHR;
if ( CHECKS ) {
check(__functionAddress);
check(pSwapchainImageCount, 1);
checkSafe(pSwapchainImages, pSwapchainImageCount[0]);
}
return callPJPPI(__functionAddress, device.address(), swapchain, pSwapchainImageCount, pSwapchainImages);
}
/** Array version of: {@link #vkAcquireNextImageKHR AcquireNextImageKHR} */
public static int vkAcquireNextImageKHR(VkDevice device, long swapchain, long timeout, long semaphore, long fence, int[] pImageIndex) {
long __functionAddress = device.getCapabilities().vkAcquireNextImageKHR;
if ( CHECKS ) {
check(__functionAddress);
check(pImageIndex, 1);
}
return callPJJJJPI(__functionAddress, device.address(), swapchain, timeout, semaphore, fence, pImageIndex);
}
}