C Specification

A logical device is created as a connection to a physical device. To create a logical device, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateDevice(
    VkPhysicalDevice                            physicalDevice,
    const VkDeviceCreateInfo*                   pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkDevice*                                   pDevice);

Parameters

  • physicalDevice must be one of the device handles returned from a call to vkEnumeratePhysicalDevices (see Physical Device Enumeration).

  • pCreateInfo is a pointer to a VkDeviceCreateInfo structure containing information about how to create the device.

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

  • pDevice is a pointer to a handle in which the created VkDevice is returned.

Description

vkCreateDevice verifies that extensions and features requested in the ppEnabledExtensionNames and pEnabledFeatures members of pCreateInfo, respectively, are supported by the implementation. If any requested extension is not supported, vkCreateDevice must return VK_ERROR_EXTENSION_NOT_PRESENT. If any requested feature is not supported, vkCreateDevice must return VK_ERROR_FEATURE_NOT_PRESENT. Support for extensions can be checked before creating a device by querying vkEnumerateDeviceExtensionProperties. Support for features can similarly be checked by querying vkGetPhysicalDeviceFeatures.

vkCreateDevice also verifies that mandatory structures and features for Vulkan SC are present and enabled:

If any of these conditions are not met, vkCreateDevice must return VK_ERROR_INITIALIZATION_FAILED.

After verifying and enabling the extensions the VkDevice object is created and returned to the application.

An implementation may allow multiple logical devices to be created from the same physical device. Logical device creation may fail due to lack of device-specific resources, including too many other logical devices, in addition to other errors. If that occurs, vkCreateDevice will return VK_ERROR_TOO_MANY_OBJECTS.

If the pipeline cache data pointed to by the pInitialData member of any element of VkDeviceObjectReservationCreateInfo::pPipelineCacheCreateInfos is not compatible with the device, then vkCreateDevice will return VK_ERROR_INVALID_PIPELINE_CACHE_DATA.

To provide application parameters at device creation time, an application can link one or more VkApplicationParametersEXT structures to the pNext chain of the VkDeviceCreateInfo structure.

If the VkApplicationParametersEXT::vendorID and VkApplicationParametersEXT::deviceID values do not match the VkPhysicalDeviceProperties::vendorID and VkPhysicalDeviceProperties::deviceID of physicalDevice, vkCreateDevice must return VK_ERROR_INITIALIZATION_FAILED.

If VkApplicationParametersEXT::key is not a valid implementation-defined application parameter key for the device being created, or if value is not a valid value for the specified key, vkCreateDevice will fail and return VK_ERROR_INITIALIZATION_FAILED.

For any implementation-defined application parameter key that exists but is not set by the application, the implementation-specific default value is used.

Valid Usage

  • VUID-vkCreateDevice-ppEnabledExtensionNames-01387
    All required device extensions for each extension in the VkDeviceCreateInfo::ppEnabledExtensionNames list must also be present in that list

  • VUID-vkCreateDevice-key-05092
    The key value of each VkApplicationParametersEXT structure in the VkDeviceCreateInfo::pNext chain must be unique

  • VUID-vkCreateDevice-deviceMemoryRequestCount-05095
    The sum of deviceMemoryRequestCount over all VkDeviceObjectReservationCreateInfo structures included in the VkDeviceCreateInfo::pNext chain must be less than or equal to VkPhysicalDeviceLimits::maxMemoryAllocationCount

  • VUID-vkCreateDevice-samplerRequestCount-05096
    The sum of samplerRequestCount over all VkDeviceObjectReservationCreateInfo structures included in the VkDeviceCreateInfo::pNext chain must be less than or equal to VkPhysicalDeviceLimits::maxSamplerAllocationCount

Valid Usage (Implicit)

  • VUID-vkCreateDevice-physicalDevice-parameter
    physicalDevice must be a valid VkPhysicalDevice handle

  • VUID-vkCreateDevice-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkDeviceCreateInfo structure

  • VUID-vkCreateDevice-pAllocator-null
    pAllocator must be NULL

  • VUID-vkCreateDevice-pDevice-parameter
    pDevice must be a valid pointer to a VkDevice handle

Return Codes
On success, this command returns

  • VK_SUCCESS

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_EXTENSION_NOT_PRESENT

  • VK_ERROR_FEATURE_NOT_PRESENT

  • VK_ERROR_TOO_MANY_OBJECTS

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_INVALID_PIPELINE_CACHE_DATA

See Also

VK_VERSION_1_0, VkAllocationCallbacks, VkDevice, VkDeviceCreateInfo, VkPhysicalDevice

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0