org.lwjgl.vulkan.KHRDeferredHostOperations Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of lwjgl-vulkan Show documentation
A new generation graphics and compute API that provides high-efficiency, cross-platform access to modern GPUs used in a wide variety of devices from PCs and consoles to mobile phones and embedded platforms.
There is a newer version: 3.3.4
Show newest version
/*
 * Copyright LWJGL. All rights reserved.
 * License terms: https://www.lwjgl.org/license
 * MACHINE GENERATED FILE, DO NOT EDIT
 */
package org.lwjgl.vulkan;

import javax.annotation.*;

import java.nio.*;

import org.lwjgl.system.*;

import static org.lwjgl.system.Checks.*;
import static org.lwjgl.system.JNI.*;
import static org.lwjgl.system.MemoryUtil.*;

/**
 * The {@link KHRDeferredHostOperations VK_KHR_deferred_host_operations} extension defines the infrastructure and usage patterns for deferrable commands, but does not specify any commands as deferrable. This is left to additional dependent extensions. Commands must not be deferred unless the deferral is specifically allowed by another extension which depends on {@link KHRDeferredHostOperations VK_KHR_deferred_host_operations}.
 * 
 * Code Examples
 * 
 * The following examples will illustrate the concept of deferrable operations using a hypothetical example. The command {@code vkDoSomethingExpensiveEXT} denotes a deferrable command. The structure stext:VkExpensiveOperationArgsEXT represents the arguments which it would normally accept.
 * 
 * The following example illustrates how a vulkan application might request deferral of an expensive operation:
 * 
 * 
 * // create a deferred operation
 * VkDeferredOperationKHR hOp;
 * VkResult result = vkCreateDeferredOperationKHR(device, pCallbacks, &hOp);
 * assert(result == VK_SUCCESS);
 * 
 * result = vkDoSomethingExpensive(device, hOp, ...);
 * assert( result == VK_OPERATION_DEFERRED_KHR );
 * 
 * // operation was deferred.  Execute it asynchronously
 * std::async::launch(
 *     [ hOp ] ( )
 *     {
 *         vkDeferredOperationJoinKHR(device, hOp);
 * 
 *         result = vkGetDeferredOperationResultKHR(device, hOp);
 * 
 *         // deferred operation is now complete.  'result' indicates success or failure
 * 
 *         vkDestroyDeferredOperationKHR(device, hOp, pCallbacks);
 *     }
 * );
 * 
 * The following example illustrates extracting concurrency from a single deferred operation:
 * 
 * 
 * // create a deferred operation
 * VkDeferredOperationKHR hOp;
 * VkResult result = vkCreateDeferredOperationKHR(device, pCallbacks, &hOp);
 * assert(result == VK_SUCCESS);
 * 
 * result = vkDoSomethingExpensive(device, hOp, ...);
 * assert( result == VK_OPERATION_DEFERRED_KHR );
 * 
 * // Query the maximum amount of concurrency and clamp to the desired maximum
 * uint32_t numLaunches = std::min(vkGetDeferredOperationMaxConcurrencyKHR(device, hOp), maxThreads);
 * 
 * std::vector<std::future<void> > joins;
 * 
 * for (uint32_t i = 0; i < numLaunches; i++) {
 *   joins.emplace_back(std::async::launch(
 *     [ hOp ] ( )
 *     {
 *         vkDeferredOperationJoinKHR(device, hOp);
 *                 // in a job system, a return of VK_THREAD_IDLE_KHR should queue another
 *                 // job, but it is not functionally required
 *     }
 *   );
 * }
 * 
 * for (auto &f : joins) {
 *   f.get();
 * }
 * 
 * result = vkGetDeferredOperationResultKHR(device, hOp);
 * 
 * // deferred operation is now complete.  'result' indicates success or failure
 * 
 * vkDestroyDeferredOperationKHR(device, hOp, pCallbacks);
 * 
 * The following example shows a subroutine which guarantees completion of a deferred operation, in the presence of multiple worker threads, and returns the result of the operation.
 * 
 * 
 * VkResult FinishDeferredOperation(VkDeferredOperationKHR hOp)
 * {
 *     // Attempt to join the operation until the implementation indicates that we should stop
 * 
 *     VkResult result = vkDeferredOperationJoinKHR(device, hOp);
 *     while( result == VK_THREAD_IDLE_KHR )
 *     {
 *         std::this_thread::yield();
 *         result = vkDeferredOperationJoinKHR(device, hOp);
 *     }
 * 
 *     switch( result )
 *     {
 *     case VK_SUCCESS:
 *         {
 *             // deferred operation has finished.  Query its result
 *             result = vkGetDeferredOperationResultKHR(device, hOp);
 *         }
 *         break;
 * 
 *     case VK_THREAD_DONE_KHR:
 *         {
 *             // deferred operation is being wrapped up by another thread
 *             //  wait for that thread to finish
 *             do
 *             {
 *                 std::this_thread::yield();
 *                 result = vkGetDeferredOperationResultKHR(device, hOp);
 *             } while( result == VK_NOT_READY );
 *         }
 *         break;
 * 
 *     default:
 *         assert(false); // other conditions are illegal.
 *         break;
 *     }
 * 
 *     return result;
 * }
 * 
 * VK_KHR_deferred_host_operations
 * 
 * 
 * Name String
 * {@code VK_KHR_deferred_host_operations}
 * Extension Type
 * Device extension
 * Registered Extension Number
 * 269
 * Revision
 * 4
 * Extension and Version Dependencies
 * 
 * Requires Vulkan 1.0
 * 
 * Contact
 * 
 * Josh Barczak jbarczak
 * 
 * 
 * 
 * Other Extension Metadata
 * 
 * 
 * Last Modified Date
 * 2020-11-12
 * IP Status
 * No known IP claims.
 * Contributors
 * 
 * Joshua Barczak, Intel
 * Jeff Bolz, NVIDIA
 * Daniel Koch, NVIDIA
 * Slawek Grajewski, Intel
 * Tobias Hector, AMD
 * Yuriy O’Donnell, Epic
 * Eric Werness, NVIDIA
 * Baldur Karlsson, Valve
 * Jesse Barker, Unity
 * Contributors to VK_KHR_acceleration_structure, VK_KHR_ray_tracing_pipeline
 * 
 * 
 */
public class KHRDeferredHostOperations {

    /** The extension specification version. */
    public static final int VK_KHR_DEFERRED_HOST_OPERATIONS_SPEC_VERSION = 4;

    /** The extension name. */
    public static final String VK_KHR_DEFERRED_HOST_OPERATIONS_EXTENSION_NAME = "VK_KHR_deferred_host_operations";

    /** Extends {@code VkObjectType}. */
    public static final int VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR = 1000268000;

    /**
     * Extends {@code VkResult}.
     * 
     * Enum values:
     * 
     * 
     * {@link #VK_THREAD_IDLE_KHR THREAD_IDLE_KHR}
     * {@link #VK_THREAD_DONE_KHR THREAD_DONE_KHR}
     * {@link #VK_OPERATION_DEFERRED_KHR OPERATION_DEFERRED_KHR}
     * {@link #VK_OPERATION_NOT_DEFERRED_KHR OPERATION_NOT_DEFERRED_KHR}
     * 
     */
    public static final int
        VK_THREAD_IDLE_KHR            = 1000268000,
        VK_THREAD_DONE_KHR            = 1000268001,
        VK_OPERATION_DEFERRED_KHR     = 1000268002,
        VK_OPERATION_NOT_DEFERRED_KHR = 1000268003;

    protected KHRDeferredHostOperations() {
        throw new UnsupportedOperationException();
    }

    // --- [ vkCreateDeferredOperationKHR ] ---

    /** Unsafe version of: {@link #vkCreateDeferredOperationKHR CreateDeferredOperationKHR} */
    public static int nvkCreateDeferredOperationKHR(VkDevice device, long pAllocator, long pDeferredOperation) {
        long __functionAddress = device.getCapabilities().vkCreateDeferredOperationKHR;
        if (CHECKS) {
            check(__functionAddress);
            if (pAllocator != NULL) { VkAllocationCallbacks.validate(pAllocator); }
        }
        return callPPPI(device.address(), pAllocator, pDeferredOperation, __functionAddress);
    }

    /**
     * Create a deferred operation handle.
     * 
     * C Specification
     * 
     * To construct the tracking object for a deferred command, call:
     * 
     * 
     * VkResult vkCreateDeferredOperationKHR(
     *     VkDevice                                    device,
     *     const VkAllocationCallbacks*                pAllocator,
     *     VkDeferredOperationKHR*                     pDeferredOperation);
     * 
     * Valid Usage (Implicit)
     * 
     * 
     * {@code device} must be a valid {@code VkDevice} handle
     * If {@code pAllocator} is not {@code NULL}, {@code pAllocator} must be a valid pointer to a valid {@link VkAllocationCallbacks} structure
     * {@code pDeferredOperation} must be a valid pointer to a {@code VkDeferredOperationKHR} handle
     * 
     * 
     * 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}
     * 
     * 
     * 
     * See Also
     * 
     * {@link VkAllocationCallbacks}
     *
     * @param device             the device which owns {@code operation}.
     * @param pAllocator         controls host memory allocation as described in the Memory Allocation chapter.
     * @param pDeferredOperation a pointer to a handle in which the created {@code VkDeferredOperationKHR} is returned.
     */
    @NativeType("VkResult")
    public static int vkCreateDeferredOperationKHR(VkDevice device, @Nullable @NativeType("VkAllocationCallbacks const *") VkAllocationCallbacks pAllocator, @NativeType("VkDeferredOperationKHR *") LongBuffer pDeferredOperation) {
        if (CHECKS) {
            check(pDeferredOperation, 1);
        }
        return nvkCreateDeferredOperationKHR(device, memAddressSafe(pAllocator), memAddress(pDeferredOperation));
    }

    // --- [ vkDestroyDeferredOperationKHR ] ---

    /** Unsafe version of: {@link #vkDestroyDeferredOperationKHR DestroyDeferredOperationKHR} */
    public static void nvkDestroyDeferredOperationKHR(VkDevice device, long operation, long pAllocator) {
        long __functionAddress = device.getCapabilities().vkDestroyDeferredOperationKHR;
        if (CHECKS) {
            check(__functionAddress);
            if (pAllocator != NULL) { VkAllocationCallbacks.validate(pAllocator); }
        }
        callPJPV(device.address(), operation, pAllocator, __functionAddress);
    }

    /**
     * Destroy a deferred operation handle.
     * 
     * C Specification
     * 
     * When a deferred operation is completed, the application can destroy the tracking object by calling:
     * 
     * 
     * void vkDestroyDeferredOperationKHR(
     *     VkDevice                                    device,
     *     VkDeferredOperationKHR                      operation,
     *     const VkAllocationCallbacks*                pAllocator);
     * 
     * Valid Usage
     * 
     * 
     * If {@link VkAllocationCallbacks} were provided when {@code operation} was created, a compatible set of callbacks must be provided here
     * If no {@link VkAllocationCallbacks} were provided when {@code operation} was created, {@code pAllocator} must be {@code NULL}
     * {@code operation} must be completed
     * 
     * 
     * Valid Usage (Implicit)
     * 
     * 
     * {@code device} must be a valid {@code VkDevice} handle
     * If {@code operation} is not {@link VK10#VK_NULL_HANDLE NULL_HANDLE}, {@code operation} must be a valid {@code VkDeferredOperationKHR} handle
     * If {@code pAllocator} is not {@code NULL}, {@code pAllocator} must be a valid pointer to a valid {@link VkAllocationCallbacks} structure
     * If {@code operation} is a valid handle, it must have been created, allocated, or retrieved from {@code device}
     * 
     * 
     * Host Synchronization
     * 
     * 
     * Host access to {@code operation} must be externally synchronized
     * 
     * 
     * See Also
     * 
     * {@link VkAllocationCallbacks}
     *
     * @param device     the device which owns {@code operation}.
     * @param operation  the completed operation to be destroyed.
     * @param pAllocator controls host memory allocation as described in the Memory Allocation chapter.
     */
    public static void vkDestroyDeferredOperationKHR(VkDevice device, @NativeType("VkDeferredOperationKHR") long operation, @Nullable @NativeType("VkAllocationCallbacks const *") VkAllocationCallbacks pAllocator) {
        nvkDestroyDeferredOperationKHR(device, operation, memAddressSafe(pAllocator));
    }

    // --- [ vkGetDeferredOperationMaxConcurrencyKHR ] ---

    /**
     * Query the maximum concurrency on a deferred operation.
     * 
     * C Specification
     * 
     * To query the number of additional threads that can usefully be joined to a deferred operation, call:
     * 
     * 
     * uint32_t vkGetDeferredOperationMaxConcurrencyKHR(
     *     VkDevice                                    device,
     *     VkDeferredOperationKHR                      operation);
     * 
     * Description
     * 
     * The returned value is the maximum number of threads that can usefully execute a deferred operation concurrently, reported for the state of the deferred operation at the point this command is called. This value is intended to be used to better schedule work onto available threads. Applications can join any number of threads to the deferred operation and expect it to eventually complete, though excessive joins may return {@link #VK_THREAD_DONE_KHR THREAD_DONE_KHR} immediately, performing no useful work.
     * 
     * If {@code operation} is complete, {@code vkGetDeferredOperationMaxConcurrencyKHR} returns zero.
     * 
     * If {@code operation} is currently joined to any threads, the value returned by this command may immediately be out of date.
     * 
     * If {@code operation} is pending, implementations must not return zero unless at least one thread is currently executing {@link #vkDeferredOperationJoinKHR DeferredOperationJoinKHR} on {@code operation}. If there are such threads, the implementation should return an estimate of the number of additional threads which it could profitably use.
     * 
     * Implementations may return 2³²-1 to indicate that the maximum concurrency is unknown and cannot be easily derived. Implementations may return values larger than the maximum concurrency available on the host CPU. In these situations, an application should clamp the return value rather than oversubscribing the machine.
     * 
     * Note
     * 
     * The recommended usage pattern for applications is to query this value once, after deferral, and schedule no more than the specified number of threads to join the operation. Each time a joined thread receives {@link #VK_THREAD_IDLE_KHR THREAD_IDLE_KHR}, the application should schedule an additional join at some point in the future, but is not required to do so.
     * 
     * 
     * Valid Usage (Implicit)
     * 
     * 
     * {@code device} must be a valid {@code VkDevice} handle
     * {@code operation} must be a valid {@code VkDeferredOperationKHR} handle
     * {@code operation} must have been created, allocated, or retrieved from {@code device}
     * 
     *
     * @param device    the device which owns {@code operation}.
     * @param operation the deferred operation to be queried.
     */
    @NativeType("uint32_t")
    public static int vkGetDeferredOperationMaxConcurrencyKHR(VkDevice device, @NativeType("VkDeferredOperationKHR") long operation) {
        long __functionAddress = device.getCapabilities().vkGetDeferredOperationMaxConcurrencyKHR;
        if (CHECKS) {
            check(__functionAddress);
        }
        return callPJI(device.address(), operation, __functionAddress);
    }

    // --- [ vkGetDeferredOperationResultKHR ] ---

    /**
     * Query the result of a deferred operation.
     * 
     * C Specification
     * 
     * The {@code vkGetDeferredOperationResultKHR} function is defined as:
     * 
     * 
     * VkResult vkGetDeferredOperationResultKHR(
     *     VkDevice                                    device,
     *     VkDeferredOperationKHR                      operation);
     * 
     * Description
     * 
     * If no command has been deferred on {@code operation}, {@code vkGetDeferredOperationResultKHR} returns {@link VK10#VK_SUCCESS SUCCESS}.
     * 
     * If the deferred operation is pending, {@code vkGetDeferredOperationResultKHR} returns {@link VK10#VK_NOT_READY NOT_READY}.
     * 
     * If the deferred operation is complete, it returns the appropriate return value from the original command. This value must be one of the {@code VkResult} values which could have been returned by the original command if the operation had not been deferred.
     * 
     * Valid Usage (Implicit)
     * 
     * 
     * {@code device} must be a valid {@code VkDevice} handle
     * {@code operation} must be a valid {@code VkDeferredOperationKHR} handle
     * {@code operation} must have been created, allocated, or retrieved from {@code device}
     * 
     * 
     * Return Codes
     * 
     * 
     * On success, this command returns
     * 
     * {@link VK10#VK_SUCCESS SUCCESS}
     * {@link VK10#VK_NOT_READY NOT_READY}
     * 
     * 
     *
     * @param device    the device which owns {@code operation}.
     * @param operation the operation whose deferred result is being queried.
     */
    @NativeType("VkResult")
    public static int vkGetDeferredOperationResultKHR(VkDevice device, @NativeType("VkDeferredOperationKHR") long operation) {
        long __functionAddress = device.getCapabilities().vkGetDeferredOperationResultKHR;
        if (CHECKS) {
            check(__functionAddress);
        }
        return callPJI(device.address(), operation, __functionAddress);
    }

    // --- [ vkDeferredOperationJoinKHR ] ---

    /**
     * Assign a thread to a deferred operation.
     * 
     * C Specification
     * 
     * To assign a thread to a deferred operation, call:
     * 
     * 
     * VkResult vkDeferredOperationJoinKHR(
     *     VkDevice                                    device,
     *     VkDeferredOperationKHR                      operation);
     * 
     * Description
     * 
     * The {@code vkDeferredOperationJoinKHR} command will execute a portion of the deferred operation on the calling thread.
     * 
     * The return value will be one of the following:
     * 
     * 
     * A return value of {@link VK10#VK_SUCCESS SUCCESS} indicates that {@code operation} is complete. The application should use {@link #vkGetDeferredOperationResultKHR GetDeferredOperationResultKHR} to retrieve the result of {@code operation}.
     * A return value of {@link #VK_THREAD_DONE_KHR THREAD_DONE_KHR} indicates that the deferred operation is not complete, but there is no work remaining to assign to threads. Future calls to {@link #vkDeferredOperationJoinKHR DeferredOperationJoinKHR} are not necessary and will simply harm performance. This situation may occur when other threads executing {@link #vkDeferredOperationJoinKHR DeferredOperationJoinKHR} are about to complete {@code operation}, and the implementation is unable to partition the workload any further.
     * A return value of {@link #VK_THREAD_IDLE_KHR THREAD_IDLE_KHR} indicates that the deferred operation is not complete, and there is no work for the thread to do at the time of the call. This situation may occur if the operation encounters a temporary reduction in parallelism. By returning {@link #VK_THREAD_IDLE_KHR THREAD_IDLE_KHR}, the implementation is signaling that it expects that more opportunities for parallelism will emerge as execution progresses, and that future calls to {@link #vkDeferredOperationJoinKHR DeferredOperationJoinKHR} can be beneficial. In the meantime, the application can perform other work on the calling thread.
     * 
     * 
     * Implementations must guarantee forward progress by enforcing the following invariants:
     * 
     * 
     * If only one thread has invoked {@link #vkDeferredOperationJoinKHR DeferredOperationJoinKHR} on a given operation, that thread must execute the operation to completion and return {@link VK10#VK_SUCCESS SUCCESS}.
     * If multiple threads have concurrently invoked {@link #vkDeferredOperationJoinKHR DeferredOperationJoinKHR} on the same operation, then at least one of them must complete the operation and return {@link VK10#VK_SUCCESS SUCCESS}.
     * 
     * 
     * Valid Usage (Implicit)
     * 
     * 
     * {@code device} must be a valid {@code VkDevice} handle
     * {@code operation} must be a valid {@code VkDeferredOperationKHR} handle
     * {@code operation} must have been created, allocated, or retrieved from {@code device}
     * 
     * 
     * Return Codes
     * 
     * 
     * On success, this command returns
     * 
     * {@link VK10#VK_SUCCESS SUCCESS}
     * {@link #VK_THREAD_DONE_KHR THREAD_DONE_KHR}
     * {@link #VK_THREAD_IDLE_KHR THREAD_IDLE_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}
     * 
     * 
     *
     * @param device    the device which owns {@code operation}.
     * @param operation the deferred operation that the calling thread should work on.
     */
    @NativeType("VkResult")
    public static int vkDeferredOperationJoinKHR(VkDevice device, @NativeType("VkDeferredOperationKHR") long operation) {
        long __functionAddress = device.getCapabilities().vkDeferredOperationJoinKHR;
        if (CHECKS) {
            check(__functionAddress);
        }
        return callPJI(device.address(), operation, __functionAddress);
    }

    /** Array version of: {@link #vkCreateDeferredOperationKHR CreateDeferredOperationKHR} */
    @NativeType("VkResult")
    public static int vkCreateDeferredOperationKHR(VkDevice device, @Nullable @NativeType("VkAllocationCallbacks const *") VkAllocationCallbacks pAllocator, @NativeType("VkDeferredOperationKHR *") long[] pDeferredOperation) {
        long __functionAddress = device.getCapabilities().vkCreateDeferredOperationKHR;
        if (CHECKS) {
            check(__functionAddress);
            check(pDeferredOperation, 1);
            if (pAllocator != null) { VkAllocationCallbacks.validate(pAllocator.address()); }
        }
        return callPPPI(device.address(), memAddressSafe(pAllocator), pDeferredOperation, __functionAddress);
    }

}