Package org.lwjgl.vulkan

Class KHRMaintenance1


  • public class KHRMaintenance1
extends java.lang.Object
    VK_KHR_maintenance1 adds a collection of minor features that were intentionally left out or overlooked from the original Vulkan 1.0 release.

    The new features are as follows:

    • Allow 2D and 2D array image views to be created from 3D images, which can then be used as color framebuffer attachments. This allows applications to render to slices of a 3D image.
    • Support CmdCopyImage between 2D array layers and 3D slices. This extension allows copying from layers of a 2D array image to slices of a 3D image and vice versa.
    • Allow negative height to be specified in the slink::VkViewport::height field to perform y-inversion of the clip-space to framebuffer-space transform. This allows apps to avoid having to use gl_Position.y = -gl_Position.y in shaders also targeting other APIs.
    • Allow implementations to express support for doing just transfers and clears of image formats that they otherwise support no other format features for. This is done by adding new format feature flags FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR and FORMAT_FEATURE_TRANSFER_DST_BIT_KHR.
    • Support CmdFillBuffer on transfer-only queues. Previously CmdFillBuffer was defined to only work on command buffers allocated from command pools which support graphics or compute queues. It is now allowed on queues that just support transfer operations.
    • Fix the inconsistency of how error conditions are returned between the CreateGraphicsPipelines and CreateComputePipelines functions and the AllocateDescriptorSets and AllocateCommandBuffers functions.
    • Add new ERROR_OUT_OF_POOL_MEMORY_KHR error so implementations can give a more precise reason for AllocateDescriptorSets failures.
    • Add a new command TrimCommandPoolKHR which gives the implementation an opportunity to release any unused command pool memory back to the system.
    Name String
    VK_KHR_maintenance1
    Extension Type
    Device extension
    Registered Extension Number
    70
    Status
    Draft
    Last Modified Date
    2016-10-26
    Revision
    1
    Dependencies
    • This extension is written against version 1.0 of the Vulkan API.
    Contributors
    • Dan Ginsburg, Valve
    • Daniel Koch, NVIDIA
    • Daniel Rakos, AMD
    • Jan-Harald Fredriksen, ARM
    • Jason Ekstrand, Intel
    • Jeff Bolz, NVIDIA
    • Jesse Hall, Google
    • John Kessenich, Google
    • Michael Worcester, Imagination Technologies
    • Neil Henning, Codeplay Software Ltd.
    • Piers Daniell, NVIDIA
    • Slawomir Grajewski, Intel
    • Tobias Hector, Imagination Technologies
    • Tom Olson, ARM
    Contacts
    • Piers Daniell (pdaniell 'at' nvidia.com)

    • Method Detail

      • vkTrimCommandPoolKHR

        public static void vkTrimCommandPoolKHR(VkDevice device,
                                        long commandPool,
                                        int flags)
        Trim a command pool.
        C Specification

        To trim a command pool, call:

         void vkTrimCommandPoolKHR(
     VkDevice                                    device,
     VkCommandPool                               commandPool,
     VkCommandPoolTrimFlagsKHR                   flags);
        Description

        Trimming a command pool recycles unused memory from the command pool back to the system. Command buffers allocated from the pool are not affected by the command.

        Note

        This command provides applications with some control over the internal memory allocations used by command pools.

        Unused memory normally arises from command buffers that have been recorded and later reset, such that they are no longer using the memory. On reset, a command buffer can return memory to its command pool, but the only way to release memory from a command pool to the system requires calling ResetCommandPool, which cannot be executed while any command buffers from that pool are still in use. Subsequent recording operations into command buffers will re-use this memory but since total memory requirements fluctuate over time, unused memory can accumulate.

        In this situation, trimming a command pool may be useful to return unused memory back to the system, returning the total outstanding memory allocated by the pool back to a more "average" value.

        Implementations utilize many internal allocation strategies that make it impossible to guarantee that all unused memory is released back to the system. For instance, an implementation of a command pool may involve allocating memory in bulk from the system and sub-allocating from that memory. In such an implementation any live command buffer that holds a reference to a bulk allocation would prevent that allocation from being freed, even if only a small proportion of the bulk allocation is in use.

        In most cases trimming will result in a reduction in allocated but unused memory, but it does not guarantee the "ideal" behaviour.

        Trimming may be an expensive operation, and should not be called frequently. Trimming should be treated as a way to relieve memory pressure after application-known points when there exists enough unused memory that the cost of trimming is "worth" it.

        Valid Usage (Implicit)
        • device must be a valid VkDevice handle
        • commandPool must be a valid VkCommandPool handle
        • flags must be 0
        • commandPool must have been created, allocated, or retrieved from device
        Host Synchronization
        • Host access to commandPool must be externally synchronized
        Parameters:
        device - the logical device that owns the command pool.
        commandPool - the command pool to trim.
        flags - reserved for future use.