protocols/vk-gen/appendices/VK_KHR_device_group.txt

// Copyright (c) 2016-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

include::meta/VK_KHR_device_group.txt[]

*Last Modified Date*::
    2017-10-06
*IP Status*::
    No known IP claims.
*Interactions and External Dependencies*::
  - Promoted to Vulkan 1.1 Core
*Contributors*::
  - Jeff Bolz, NVIDIA
  - Tobias Hector, Imagination Technologies

This extension provides functionality to use a logical device that consists
of multiple physical devices, as created with the
`<<VK_KHR_device_group_creation>>` extension.
A device group can allocate memory across the subdevices, bind memory from
one subdevice to a resource on another subdevice, record command buffers
where some work executes on an arbitrary subset of the subdevices, and
potentially present a swapchain image from one or more subdevices.

=== New Object Types

None.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_FLAGS_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_RENDER_PASS_BEGIN_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_COMMAND_BUFFER_BEGIN_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SUBMIT_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_BIND_SPARSE_INFO_KHR
ifdef::VK_KHR_swapchain[]
  ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
  ** ename:VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
endif::VK_KHR_swapchain[]
  ** ename:VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO_KHR
  * Extending elink:VkImageCreateFlagBits
  ** ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
  * Extending elink:VkPipelineCreateFlagBits
  ** ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHR
  ** ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHR
  * Extending elink:VkDependencyFlagBits
  ** ename:VK_DEPENDENCY_DEVICE_GROUP_BIT_KHR
ifdef::VK_KHR_swapchain[]
  * Extending elink:VkSwapchainCreateFlagBitsKHR
  ** ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
endif::VK_KHR_swapchain[]

=== New Enums

  * elink:VkPeerMemoryFeatureFlagBitsKHR
  * elink:VkMemoryAllocateFlagBitsKHR
ifdef::VK_KHR_swapchain[]
  * elink:VkDeviceGroupPresentModeFlagBitsKHR
endif::VK_KHR_swapchain[]

=== New Structures

  * slink:VkMemoryAllocateFlagsInfoKHR
  * slink:VkDeviceGroupRenderPassBeginInfoKHR
  * slink:VkDeviceGroupCommandBufferBeginInfoKHR
  * slink:VkDeviceGroupSubmitInfoKHR
  * slink:VkDeviceGroupBindSparseInfoKHR
  * slink:VkBindBufferMemoryDeviceGroupInfoKHR
  * slink:VkBindImageMemoryDeviceGroupInfoKHR
ifdef::VK_KHR_swapchain[]
  * slink:VkDeviceGroupPresentCapabilitiesKHR
  * slink:VkImageSwapchainCreateInfoKHR
  * slink:VkBindImageMemorySwapchainInfoKHR
  * slink:VkAcquireNextImageInfoKHR
  * slink:VkDeviceGroupPresentInfoKHR
  * slink:VkDeviceGroupSwapchainCreateInfoKHR
endif::VK_KHR_swapchain[]

=== New Functions

  * flink:vkGetDeviceGroupPeerMemoryFeaturesKHR
  * flink:vkCmdSetDeviceMaskKHR
  * flink:vkCmdDispatchBaseKHR
ifdef::VK_KHR_swapchain[]
  * flink:vkGetDeviceGroupPresentCapabilitiesKHR
  * flink:vkGetDeviceGroupSurfacePresentModesKHR
  * flink:vkGetPhysicalDevicePresentRectanglesKHR
  * flink:vkAcquireNextImage2KHR
endif::VK_KHR_swapchain[]

=== New Built-In Variables

  * <<interfaces-builtin-variables-deviceindex,code:DeviceIndex>>

=== New SPIR-V Capabilities

  * <<spirvenv-capabilities,code:DeviceGroup>>

=== Promotion to Vulkan 1.1

ifdef::VK_KHR_swapchain[]
The following enums, types and commands are included as interactions with
`<<VK_KHR_swapchain>>`:

  * ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
  * ename:VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
  * ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
  * ename:VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR
  * ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
  * ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
  * ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
  * elink:VkDeviceGroupPresentModeFlagBitsKHR
  * slink:VkDeviceGroupPresentCapabilitiesKHR
  * slink:VkImageSwapchainCreateInfoKHR
  * slink:VkBindImageMemorySwapchainInfoKHR
  * slink:VkAcquireNextImageInfoKHR
  * slink:VkDeviceGroupPresentInfoKHR
  * slink:VkDeviceGroupSwapchainCreateInfoKHR
  * flink:vkGetDeviceGroupPresentCapabilitiesKHR
  * flink:vkGetDeviceGroupSurfacePresentModesKHR
  * flink:vkGetPhysicalDevicePresentRectanglesKHR
  * flink:vkAcquireNextImage2KHR

If Vulkan 1.1 and VK_KHR_swapchain are supported, these are included by
VK_KHR_swapchain.
endif::VK_KHR_swapchain[]

The base functionality in this extension is included in core Vulkan 1.1,
with the KHR suffix omitted.
The original type, enum and command names are still available as aliases of
the core functionality.

=== Issues

None.

=== Examples

TODO

=== Version History

 * Revision 1, 2016-10-19 (Jeff Bolz)
   - Internal revisions
 * Revision 2, 2017-05-19 (Tobias Hector)
   - Removed extended memory bind functions to VK_KHR_bind_memory2, added
     dependency on that extension, and device-group-specific structs for
     those functions.
 * Revision 3, 2017-10-06 (Ian Elliott)
   - Corrected Vulkan 1.1 interactions with the WSI extensions.
     All Vulkan 1.1 WSI interactions are with the VK_KHR_swapchain
     extension.
 * Revision 4, 2017-10-10 (Jeff Bolz)
   - Rename "SFR" bits and structure members to use the phrase "split
     instance bind regions".