# Vulkan® 1.4.321 - A Specification (with all registered extensions)

The Khronos® Vulkan Working Group
version 1.4.321, 2025-07-17 19:31:47Z
from git branch: makepkg commit: dad857284bf63d027ac9d6a97e9a1689831bab0d

Loading… please wait.

Search:

## 46. External Compute Queues

External compute queues are used to join compatible external APIs to a `VkDevice`, allowing workloads submitted through these external APIs to be executed simultaneously to workloads submitted through Vulkan.

External compute queues are represented by `VkExternalComputeQueueNV` handles:

    // Provided by VK_NV_external_compute_queue
    VK_DEFINE_HANDLE(VkExternalComputeQueueNV)

To create an external compute queue for use by compatible external APIs call:

    // Provided by VK_NV_external_compute_queue
    VkResult vkCreateExternalComputeQueueNV(
        VkDevice                                    device,
        const VkExternalComputeQueueCreateInfoNV*   pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkExternalComputeQueueNV*                   pExternalQueue);

- `device` is the VkDevice that the external queue will be a part of.

- `pCreateInfo` is a pointer to a VkExternalComputeQueueCreateInfoNV structure specifying configuration info for creating the external queue.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

- `pExternalQueue` is a pointer to a VkExternalComputeQueueNV object that will be filled with the handle for the created external queue.

Valid Usage (Implicit)

- VUID-vkCreateExternalComputeQueueNV-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkCreateExternalComputeQueueNV-pCreateInfo-parameter
  `pCreateInfo` must be a valid pointer to a valid VkExternalComputeQueueCreateInfoNV structure

- VUID-vkCreateExternalComputeQueueNV-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkCreateExternalComputeQueueNV-pExternalQueue-parameter
  `pExternalQueue` must be a valid pointer to a VkExternalComputeQueueNV handle

- VUID-vkCreateExternalComputeQueueNV-device-queuecount
  The device must have been created with at least `1` queue

Return Codes

Success

  - `VK_SUCCESS`

Failure

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_TOO_MANY_OBJECTS`

To destroy a previously created external compute queue call:

    // Provided by VK_NV_external_compute_queue
    void vkDestroyExternalComputeQueueNV(
        VkDevice                                    device,
        VkExternalComputeQueueNV                    externalQueue,
        const VkAllocationCallbacks*                pAllocator);

- `device` is the logical device that destroys the external queue.

- `externalQueue` is the VkExternalComputeQueueNV to destroy.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage (Implicit)

- VUID-vkDestroyExternalComputeQueueNV-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkDestroyExternalComputeQueueNV-externalQueue-parameter
  `externalQueue` must be a valid VkExternalComputeQueueNV handle

- VUID-vkDestroyExternalComputeQueueNV-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkDestroyExternalComputeQueueNV-externalQueue-parent
  `externalQueue` must have been created, allocated, or retrieved from `device`

To query the implementation-specific data that must be passed to compatible external APIs during their initialization process call:

    // Provided by VK_NV_external_compute_queue
    void vkGetExternalComputeQueueDataNV(
        VkExternalComputeQueueNV                    externalQueue,
        VkExternalComputeQueueDataParamsNV*         params,
        void*                                       pData);

- `externalQueue` is the VkExternalComputeQueueNV to query the data for.

- `params` is a pointer to a VkExternalComputeQueueDataParamsNV structure specifying parameters required for retrieval of the implementation-specific data.

- `pData` is a pointer to application-allocated memory in which the requested data will be returned.

Valid Usage

- VUID-vkGetExternalComputeQueueDataNV-pData-08134
  `pData` must be at least the size specified by the externalDataSize field in the VkPhysicalDeviceExternalComputeQueuePropertiesNV structure

Valid Usage (Implicit)

- VUID-vkGetExternalComputeQueueDataNV-externalQueue-parameter
  `externalQueue` must be a valid VkExternalComputeQueueNV handle

- VUID-vkGetExternalComputeQueueDataNV-params-parameter
  `params` must be a valid pointer to a VkExternalComputeQueueDataParamsNV structure

- VUID-vkGetExternalComputeQueueDataNV-pData-parameter
  `pData` must be a pointer value

The `VkExternalComputeQueueDeviceCreateInfoNV` structure is defined as:

    // Provided by VK_NV_external_compute_queue
    typedef struct VkExternalComputeQueueDeviceCreateInfoNV {
        VkStructureType    sType;
        const void*        pNext;
        uint32_t           reservedExternalQueues;
    } VkExternalComputeQueueDeviceCreateInfoNV;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `reservedExternalQueues` is the maximum number of external queues an application can create at once. This must be less than or equal to the `maxExternalQueues` value reported by VkPhysicalDeviceExternalComputeQueuePropertiesNV

Valid Usage (Implicit)

- VUID-VkExternalComputeQueueDeviceCreateInfoNV-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_DEVICE_CREATE_INFO_NV`

The `VkExternalComputeQueueCreateInfoNV` structure is defined as:

    // Provided by VK_NV_external_compute_queue
    typedef struct VkExternalComputeQueueCreateInfoNV {
        VkStructureType    sType;
        const void*        pNext;
        VkQueue            preferredQueue;
    } VkExternalComputeQueueCreateInfoNV;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `preferredQueue` is a `VkQueue` supporting graphics commands.

When creating a `VkExternalComputeQueueNV`, the `preferredQueue` field is a strong scheduling hint as to which `VkQueue` Vulkan graphics workloads will be submitted to with the expectation that execution will overlap with execution of work submitted by the external API.

Valid Usage (Implicit)

- VUID-VkExternalComputeQueueCreateInfoNV-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_CREATE_INFO_NV`

- VUID-VkExternalComputeQueueCreateInfoNV-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkExternalComputeQueueCreateInfoNV-preferredQueue-parameter
  `preferredQueue` must be a valid VkQueue handle

The `VkExternalComputeQueueDataParamsNV` structure is defined as:

    // Provided by VK_NV_external_compute_queue
    typedef struct VkExternalComputeQueueDataParamsNV {
        VkStructureType    sType;
        const void*        pNext;
        uint32_t           deviceIndex;
    } VkExternalComputeQueueDataParamsNV;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `deviceIndex` is the index of the device within a device group that the data is being queried for. This is ignored if device groups are not utilized.

Valid Usage (Implicit)

- VUID-VkExternalComputeQueueDataParamsNV-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_EXTERNAL_COMPUTE_QUEUE_DATA_PARAMS_NV`

- VUID-VkExternalComputeQueueDataParamsNV-pNext-pNext
  `pNext` must be `NULL`

The `VkPhysicalDeviceExternalComputeQueuePropertiesNV` structure is defined as:

    // Provided by VK_NV_external_compute_queue
    typedef struct VkPhysicalDeviceExternalComputeQueuePropertiesNV {
        VkStructureType    sType;
        void*              pNext;
        uint32_t           externalDataSize;
        uint32_t           maxExternalQueues;
    } VkPhysicalDeviceExternalComputeQueuePropertiesNV;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `externalDataSize` is the minimum size of the memory allocation that applications can pass to vkGetExternalComputeQueueDataNV.

- `maxExternalQueues` is the maximum number of external queues that an application can create.

Valid Usage (Implicit)

- VUID-VkPhysicalDeviceExternalComputeQueuePropertiesNV-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_COMPUTE_QUEUE_PROPERTIES_NV`