HORIZON HASKELLDocslts/ghc-10.0.xfc4e5982026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 10.0.0.20260917 · lts/ghc-10.0.x · fc4e598 · 2026-10-11

Modulevulkan-3.27GHC2021

Vulkan.Extensions.VK_NV_compute_occupancy_priority

Name

VK_NV_compute_occupancy_priority - device extension

VK_NV_compute_occupancy_priority

Name String

VK_NV_compute_occupancy_priority

Extension Type

Device extension

Registered Extension Number

646

Revision

1

Ratification Status

Not ratified

Extension and Version Dependencies

VK_KHR_get_physical_device_properties2

or

Vulkan Version 1.1

Contact
Extension Proposal

VK_NV_compute_occupancy_priority

Other Extension Metadata

Last Modified Date

2025-12-01

Contributors

  • Chris Lentini, NVIDIA

  • Eric Werness, NVIDIA

  • Lionel Duc, NVIDIA

  • Peter Deayton, NVIDIA

Description

This extension provides applications with control over how their compute workloads utilize GPU compute resources, specifically allowing prioritization relative to other simultaneously executing workloads. Applications can specify the priority with which compute workloads should occupy GPU compute resources, allowing for a fine-grained distinction between workloads that may want to execute at a background priority over a long period of time versus workloads with harder latency requirements.

The extension introduces a new command cmdSetComputeOccupancyPriorityNV that allows applications to set the occupancy priority for subsequent compute dispatches. The occupancy priority affects how compute workloads utilize GPU compute resources relative to other simultaneously executing workloads.

The occupancy priority is stateful on a command buffer. All commands listed in the Dispatching Commands chapter issued subsequent to a cmdSetComputeOccupancyPriorityNV call will be executed with the specified priority parameters until another cmdSetComputeOccupancyPriorityNV call is made.

For convenience, three named occupancy priority values are defined:

  • VK_COMPUTE_OCCUPANCY_PRIORITY_LOW_NV - a constant value that can be used for ComputeOccupancyPriorityParametersNV::occupancyPriority to specify a low priority level.

  • VK_COMPUTE_OCCUPANCY_PRIORITY_NORMAL_NV - a constant value that can be used for ComputeOccupancyPriorityParametersNV::occupancyPriority to specify a normal priority level. This represents the default priority level.

  • VK_COMPUTE_OCCUPANCY_PRIORITY_HIGH_NV - a constant value that can be used for ComputeOccupancyPriorityParametersNV::occupancyPriority to specify a high priority level.

All command buffers (primary and secondary) start with a priority level equal to the VK_COMPUTE_OCCUPANCY_PRIORITY_NORMAL_NV value. The priority state is not inherited by secondary command buffers - each command buffer maintains its own independent priority state.

New Commands

New Structures

New Enum Constants

The extension only allows specification of occupancy priority for compute workloads, however, the priorities will also impact the prioritization of compute workloads relative to simultaneously executing graphics workloads. In such a scenario, the graphics workload may be thought of as executing at VK_COMPUTE_OCCUPANCY_PRIORITY_NORMAL_NV priority, and so a simultaneously executing compute workload with VK_COMPUTE_OCCUPANCY_PRIORITY_HIGH_NV occupancy priority will preferentially utilize available compute resources.

Workloads specified with a higher priority may begin execution after workloads specified with a lower priority, at which point they may find GPU compute resources already occupied. So, while they will from that point forward preferentially occupy available compute resources, they may not ramp up to full occupancy until the already present lower priority work has reached a point where it can relinquish compute resources.

Issues

None.

Version History

  • Revision 1, 2025-08-06 (Chris Lentini)

    • Initial revision

See Also

No cross-references are available

Document Notes

For more information, see the Vulkan Specification.

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

  • 4 types
  • 1 value
  • Packagevulkan-3.27
  • Exports10
  • LanguageGHC2021
  • LicenceBSD-3-Clause
  • SourceVK_NV_compute_occupancy_priority.hs
valuecmdSetComputeOccupancyPriorityNV
  1. :: MonadIO io
  2. => CommandBuffer

    commandBuffer is the command buffer into which the command will be recorded.

  3. -> ComputeOccupancyPriorityParametersNV

    pParameters is a pointer to a ComputeOccupancyPriorityParametersNV structure specifying the occupancy priority parameters.

  4. -> io ()
#

vkCmdSetComputeOccupancyPriorityNV - Set the compute occupancy priority for subsequent compute dispatches

Description

The occupancy priority affects how compute workloads utilize GPU compute resources relative to other simultaneously executing workloads. The priority is stateful on a command buffer. All compute dispatch commands issued subsequent to a cmdSetComputeOccupancyPriorityNV call will be executed with the specified priority parameters until another cmdSetComputeOccupancyPriorityNV call is made.

All command buffers (primary and secondary) start with a priority level equal to the COMPUTE_OCCUPANCY_PRIORITY_NORMAL_NV value. The priority state is not inherited by secondary command buffers - each command buffer maintains its own independent priority state.

Valid Usage (Implicit)

Host Synchronization

  • Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary Secondary

Both

Outside

VK_QUEUE_COMPUTE_BIT

State

Conditional Rendering

vkCmdSetComputeOccupancyPriorityNV is not affected by conditional rendering

See Also

VK_NV_compute_occupancy_priority, CommandBuffer, ComputeOccupancyPriorityParametersNV

datadata ComputeOccupancyPriorityParametersNV
#

VkComputeOccupancyPriorityParametersNV - Structure specifying compute occupancy priority parameters

Valid Usage (Implicit)

See Also

VK_NV_compute_occupancy_priority, StructureType, cmdSetComputeOccupancyPriorityNV

Constructors

  • ComputeOccupancyPriorityParametersNV
    • occupancyPriority :: Float

      occupancyPriority is a value specifying the occupancy priority for subsequent compute workloads, with a valid range of [0.0, 1.0]. A value of 0.0 represents the lowest priority, while a value of 1.0 is the maximum priority. Default priority is specified by a value of 0.5.

      occupancyPriority must be between 0 and 1, inclusive

    • occupancyThrottling :: Float

      occupancyThrottling is a value specifying the level of occupancy throttling applied to subsequent workloads, with a valid range of [0.0, 1.0]. A value of 0.0 (the default) means no throttling is applied, allowing workloads to use the full available compute capacity. Non-zero values represent increasing levels of throttling, with higher values resulting in more restrictive occupancy limits. A value of 1.0 represents the maximum level of throttling supported by the implementation.

      occupancyThrottling must be between 0 and 1, inclusive

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata PhysicalDeviceComputeOccupancyPriorityFeaturesNV
#

VkPhysicalDeviceComputeOccupancyPriorityFeaturesNV - Structure describing whether compute occupancy priority is supported by the implementation

Members

This structure describes the following features:

Description

If the PhysicalDeviceComputeOccupancyPriorityFeaturesNV structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDeviceComputeOccupancyPriorityFeaturesNV, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

See Also

VK_NV_compute_occupancy_priority, Bool32, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero