// Copyright (c) 2016-2019 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_creation.txt[]

*Last Modified Date*::
    2016-10-19
*IP Status*::
    No known IP claims.
*Interactions and External Dependencies*::
  - Promoted to Vulkan 1.1 Core
*Contributors*::
  - Jeff Bolz, NVIDIA

This extension provides instance-level commands to enumerate groups of
physical devices, and to create a logical device from a subset of one of
those groups.
Such a logical device can then be used with new features in the
`<<VK_KHR_device_group>>` extension.

=== New Object Types

None.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR
  ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR
  * Extending elink:VkMemoryHeapFlagBits
  ** ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHR


=== New Enums

None.

=== New Structures

  * slink:VkPhysicalDeviceGroupPropertiesKHR
  * slink:VkDeviceGroupDeviceCreateInfoKHR

=== New Functions

  * flink:vkEnumeratePhysicalDeviceGroupsKHR

=== Promotion to Vulkan 1.1

All 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

[source,c++]
----------------------------------------

    VkDeviceCreateInfo devCreateInfo = { VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO };
    // (not shown) fill out devCreateInfo as usual.
    uint32_t deviceGroupCount = 0;
    VkPhysicalDeviceGroupPropertiesKHR *props = NULL;

    // Query the number of device groups
    vkEnumeratePhysicalDeviceGroupsKHR(g_vkInstance, &deviceGroupCount, NULL);

    // Allocate and initialize structures to query the device groups
    props = (VkPhysicalDeviceGroupPropertiesKHR *)malloc(deviceGroupCount*sizeof(VkPhysicalDeviceGroupPropertiesKHR));
    for (i = 0; i < deviceGroupCount; ++i) {
        props[i].sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_GROUP_PROPERTIES_KHR;
        props[i].pNext = NULL;
    }
    vkEnumeratePhysicalDeviceGroupsKHR(g_vkInstance, &deviceGroupCount, props);

    // If the first device group has more than one physical device. create
    // a logical device using all of the physical devices.
    VkDeviceGroupDeviceCreateInfoKHR deviceGroupInfo = { VK_STRUCTURE_TYPE_DEVICE_GROUP_DEVICE_CREATE_INFO_KHR };
    if (props[0].physicalDeviceCount > 1) {
        deviceGroupInfo.physicalDeviceCount = props[0].physicalDeviceCount;
        deviceGroupInfo.pPhysicalDevices = props[0].physicalDevices;
        devCreateInfo.pNext = &deviceGroupInfo;
    }

    vkCreateDevice(props[0].physicalDevices[0], &devCreateInfo, NULL, &g_vkDevice);
    free(props);

----------------------------------------

=== Version History

 * Revision 1, 2016-10-19 (Jeff Bolz)
   - Internal revisions