Vulkan.Core10.Device

Documentation

createDevice :: forall a io. (Extendss DeviceCreateInfo a, PokeChain a, MonadIO io) => PhysicalDevice -> DeviceCreateInfo a -> ("allocator" ::: Maybe AllocationCallbacks) -> io Device

vkCreateDevice - Create a new device instance

Parameters

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

• pCreateInfo is a pointer to a DeviceCreateInfo 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 Device is returned.

Description

createDevice 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, createDevice must return ERROR_EXTENSION_NOT_PRESENT. If any requested feature is not supported, createDevice must return ERROR_FEATURE_NOT_PRESENT. Support for extensions can be checked before creating a device by querying enumerateDeviceExtensionProperties. Support for features can similarly be checked by querying getPhysicalDeviceFeatures.

After verifying and enabling the extensions the Device object is created and returned to the application. If a requested extension is only supported by a layer, both the layer and the extension need to be specified at createInstance time for the creation to succeed.

Multiple logical devices can be created from the same physical device. Logical device creation may fail due to lack of device-specific resources (in addition to the other errors). If that occurs, createDevice will return ERROR_TOO_MANY_OBJECTS.

Valid Usage

• All required extensions for each extension in the DeviceCreateInfo::ppEnabledExtensionNames list must also be present in that list

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• pCreateInfo must be a valid pointer to a valid DeviceCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pDevice must be a valid pointer to a Device handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_INITIALIZATION_FAILED
• ERROR_EXTENSION_NOT_PRESENT
• ERROR_FEATURE_NOT_PRESENT
• ERROR_TOO_MANY_OBJECTS
• ERROR_DEVICE_LOST

See Also

AllocationCallbacks, Device, DeviceCreateInfo, PhysicalDevice

withDevice :: forall a io r. (Extendss DeviceCreateInfo a, PokeChain a, MonadIO io) => PhysicalDevice -> DeviceCreateInfo a -> Maybe AllocationCallbacks -> (io Device -> (Device -> io ()) -> r) -> r

A convenience wrapper to make a compatible pair of calls to createDevice and destroyDevice

To ensure that destroyDevice is always called: pass bracket (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass (,) as the first argument.

destroyDevice :: forall io. MonadIO io => Device -> ("allocator" ::: Maybe AllocationCallbacks) -> io ()

vkDestroyDevice - Destroy a logical device

Parameters

• device is the logical device to destroy.

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

Description

To ensure that no work is active on the device, deviceWaitIdle can be used to gate the destruction of the device. Prior to destroying a device, an application is responsible for destroying/freeing any Vulkan objects that were created using that device as the first parameter of the corresponding vkCreate* or vkAllocate* command.

Note

The lifetime of each of these objects is bound by the lifetime of the Device object. Therefore, to avoid resource leaks, it is critical that an application explicitly free all of these resources prior to calling destroyDevice.

Valid Usage

• All child objects created on device must have been destroyed prior to destroying device

• If AllocationCallbacks were provided when device was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when device was created, pAllocator must be NULL

Valid Usage (Implicit)

• If device is not NULL, device must be a valid Device handle

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

Host Synchronization

• Host access to device must be externally synchronized

• Host access to all Queue objects received from device must be externally synchronized

See Also

AllocationCallbacks, Device

data DeviceQueueCreateInfo (es :: [Type])

VkDeviceQueueCreateInfo - Structure specifying parameters of a newly created device queue

Valid Usage

• queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by getPhysicalDeviceQueueFamilyProperties

• queueCount must be less than or equal to the queueCount member of the QueueFamilyProperties structure, as returned by getPhysicalDeviceQueueFamilyProperties in the pQueueFamilyProperties[queueFamilyIndex]
• Each element of pQueuePriorities must be between 0.0 and 1.0 inclusive
• If the protected memory feature is not enabled, the DEVICE_QUEUE_CREATE_PROTECTED_BIT bit of flags must not be set

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO

• pNext must be NULL or a pointer to a valid instance of DeviceQueueGlobalPriorityCreateInfoEXT
• The sType value of each struct in the pNext chain must be unique
• flags must be a valid combination of DeviceQueueCreateFlagBits values
• pQueuePriorities must be a valid pointer to an array of queueCount float values
• queueCount must be greater than 0

See Also

DeviceCreateInfo, DeviceQueueCreateFlags, StructureType

Constructors

DeviceQueueCreateInfo

Fields

• next :: Chain es

  pNext is NULL or a pointer to an extension-specific structure.

• flags :: DeviceQueueCreateFlags

  flags is a bitmask indicating behavior of the queue.

• queueFamilyIndex :: Word32

  queueFamilyIndex is an unsigned integer indicating the index of the queue family to create on this device. This index corresponds to the index of an element of the pQueueFamilyProperties array that was returned by getPhysicalDeviceQueueFamilyProperties.

• queuePriorities :: Vector Float

  pQueuePriorities is a pointer to an array of queueCount normalized floating point values, specifying priorities of work that will be submitted to each created queue. See Queue Priority for more information.

Instances

Extensible DeviceQueueCreateInfo

Defined in Vulkan.Core10.Device

Methods

extensibleType :: StructureType

getNext :: forall (es :: [Type]). DeviceQueueCreateInfo es -> Chain es

setNext :: forall (ds :: [Type]) (es :: [Type]). DeviceQueueCreateInfo ds -> Chain es -> DeviceQueueCreateInfo es

extends :: forall e b proxy. Typeable e => proxy e -> (Extends DeviceQueueCreateInfo e => b) -> Maybe b

Show (Chain es) => Show (DeviceQueueCreateInfo es)

Defined in Vulkan.Core10.Device

Methods

showsPrec :: Int -> DeviceQueueCreateInfo es -> ShowS

show :: DeviceQueueCreateInfo es -> String

showList :: [DeviceQueueCreateInfo es] -> ShowS

(Extendss DeviceQueueCreateInfo es, PeekChain es) => FromCStruct (DeviceQueueCreateInfo es)

Defined in Vulkan.Core10.Device

Methods

peekCStruct :: Ptr (DeviceQueueCreateInfo es) -> IO (DeviceQueueCreateInfo es)

(Extendss DeviceQueueCreateInfo es, PokeChain es) => ToCStruct (DeviceQueueCreateInfo es)

Defined in Vulkan.Core10.Device

Methods

withCStruct :: DeviceQueueCreateInfo es -> (Ptr (DeviceQueueCreateInfo es) -> IO b) -> IO b

pokeCStruct :: Ptr (DeviceQueueCreateInfo es) -> DeviceQueueCreateInfo es -> IO b -> IO b

withZeroCStruct :: (Ptr (DeviceQueueCreateInfo es) -> IO b) -> IO b

pokeZeroCStruct :: Ptr (DeviceQueueCreateInfo es) -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

es ~ ('[] :: [Type]) => Zero (DeviceQueueCreateInfo es)

Defined in Vulkan.Core10.Device

Methods

zero :: DeviceQueueCreateInfo es

data DeviceCreateInfo (es :: [Type])

VkDeviceCreateInfo - Structure specifying parameters of a newly created device

Valid Usage

• The queueFamilyIndex member of each element of pQueueCreateInfos must be unique within pQueueCreateInfos, except that two members can share the same queueFamilyIndex if one is a protected-capable queue and one is not a protected-capable queue

• If the pNext chain includes a PhysicalDeviceFeatures2 structure, then pEnabledFeatures must be NULL
• ppEnabledExtensionNames must not contain VK_AMD_negative_viewport_height
• ppEnabledExtensionNames must not contain both VK_KHR_buffer_device_address and VK_EXT_buffer_device_address
• If the pNext chain includes a PhysicalDeviceVulkan11Features structure, then it must not include a PhysicalDevice16BitStorageFeatures, PhysicalDeviceMultiviewFeatures, PhysicalDeviceVariablePointersFeatures, PhysicalDeviceProtectedMemoryFeatures, PhysicalDeviceSamplerYcbcrConversionFeatures, or PhysicalDeviceShaderDrawParametersFeatures structure
• If the pNext chain includes a PhysicalDeviceVulkan12Features structure, then it must not include a PhysicalDevice8BitStorageFeatures, PhysicalDeviceShaderAtomicInt64Features, PhysicalDeviceShaderFloat16Int8Features, PhysicalDeviceDescriptorIndexingFeatures, PhysicalDeviceScalarBlockLayoutFeatures, PhysicalDeviceImagelessFramebufferFeatures, PhysicalDeviceUniformBufferStandardLayoutFeatures, PhysicalDeviceShaderSubgroupExtendedTypesFeatures, PhysicalDeviceSeparateDepthStencilLayoutsFeatures, PhysicalDeviceHostQueryResetFeatures, PhysicalDeviceTimelineSemaphoreFeatures, PhysicalDeviceBufferDeviceAddressFeatures, or PhysicalDeviceVulkanMemoryModelFeatures structure
• If ppEnabledExtensions contains "VK_KHR_draw_indirect_count" and the pNext chain includes a PhysicalDeviceVulkan12Features structure, then PhysicalDeviceVulkan12Features::drawIndirectCount must be TRUE
• If ppEnabledExtensions contains "VK_KHR_sampler_mirror_clamp_to_edge" and the pNext chain includes a PhysicalDeviceVulkan12Features structure, then PhysicalDeviceVulkan12Features::samplerMirrorClampToEdge must be TRUE
• If ppEnabledExtensions contains "VK_EXT_descriptor_indexing" and the pNext chain includes a PhysicalDeviceVulkan12Features structure, then PhysicalDeviceVulkan12Features::descriptorIndexing must be TRUE
• If ppEnabledExtensions contains "VK_EXT_sampler_filter_minmax" and the pNext chain includes a PhysicalDeviceVulkan12Features structure, then PhysicalDeviceVulkan12Features::samplerFilterMinmax must be TRUE
• If ppEnabledExtensions contains "VK_EXT_shader_viewport_index_layer" and the pNext chain includes a PhysicalDeviceVulkan12Features structure, then PhysicalDeviceVulkan12Features::shaderOutputViewportIndex and PhysicalDeviceVulkan12Features::shaderOutputLayer must both be TRUE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_DEVICE_CREATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of DeviceDiagnosticsConfigCreateInfoNV, DeviceGroupDeviceCreateInfo, DeviceMemoryOverallocationCreateInfoAMD, PhysicalDevice16BitStorageFeatures, PhysicalDevice8BitStorageFeatures, PhysicalDeviceASTCDecodeFeaturesEXT, PhysicalDeviceBlendOperationAdvancedFeaturesEXT, PhysicalDeviceBufferDeviceAddressFeatures, PhysicalDeviceBufferDeviceAddressFeaturesEXT, PhysicalDeviceCoherentMemoryFeaturesAMD, PhysicalDeviceComputeShaderDerivativesFeaturesNV, PhysicalDeviceConditionalRenderingFeaturesEXT, PhysicalDeviceCooperativeMatrixFeaturesNV, PhysicalDeviceCornerSampledImageFeaturesNV, PhysicalDeviceCoverageReductionModeFeaturesNV, PhysicalDeviceCustomBorderColorFeaturesEXT, PhysicalDeviceDedicatedAllocationImageAliasingFeaturesNV, PhysicalDeviceDepthClipEnableFeaturesEXT, PhysicalDeviceDescriptorIndexingFeatures, PhysicalDeviceDeviceGeneratedCommandsFeaturesNV, PhysicalDeviceDiagnosticsConfigFeaturesNV, PhysicalDeviceExclusiveScissorFeaturesNV, PhysicalDeviceFeatures2, PhysicalDeviceFragmentDensityMapFeaturesEXT, PhysicalDeviceFragmentShaderBarycentricFeaturesNV, PhysicalDeviceFragmentShaderInterlockFeaturesEXT, PhysicalDeviceHostQueryResetFeatures, PhysicalDeviceImagelessFramebufferFeatures, PhysicalDeviceIndexTypeUint8FeaturesEXT, PhysicalDeviceInlineUniformBlockFeaturesEXT, PhysicalDeviceLineRasterizationFeaturesEXT, PhysicalDeviceMemoryPriorityFeaturesEXT, PhysicalDeviceMeshShaderFeaturesNV, PhysicalDeviceMultiviewFeatures, PhysicalDevicePerformanceQueryFeaturesKHR, PhysicalDevicePipelineCreationCacheControlFeaturesEXT, PhysicalDevicePipelineExecutablePropertiesFeaturesKHR, PhysicalDeviceProtectedMemoryFeatures, PhysicalDeviceRayTracingFeaturesKHR, PhysicalDeviceRepresentativeFragmentTestFeaturesNV, PhysicalDeviceRobustness2FeaturesEXT, PhysicalDeviceSamplerYcbcrConversionFeatures, PhysicalDeviceScalarBlockLayoutFeatures, PhysicalDeviceSeparateDepthStencilLayoutsFeatures, PhysicalDeviceShaderAtomicInt64Features, PhysicalDeviceShaderClockFeaturesKHR, PhysicalDeviceShaderDemoteToHelperInvocationFeaturesEXT, PhysicalDeviceShaderDrawParametersFeatures, PhysicalDeviceShaderFloat16Int8Features, PhysicalDeviceShaderImageFootprintFeaturesNV, PhysicalDeviceShaderIntegerFunctions2FeaturesINTEL, PhysicalDeviceShaderSMBuiltinsFeaturesNV, PhysicalDeviceShaderSubgroupExtendedTypesFeatures, PhysicalDeviceShadingRateImageFeaturesNV, PhysicalDeviceSubgroupSizeControlFeaturesEXT, PhysicalDeviceTexelBufferAlignmentFeaturesEXT, PhysicalDeviceTextureCompressionASTCHDRFeaturesEXT, PhysicalDeviceTimelineSemaphoreFeatures, PhysicalDeviceTransformFeedbackFeaturesEXT, PhysicalDeviceUniformBufferStandardLayoutFeatures, PhysicalDeviceVariablePointersFeatures, PhysicalDeviceVertexAttributeDivisorFeaturesEXT, PhysicalDeviceVulkan11Features, PhysicalDeviceVulkan12Features, PhysicalDeviceVulkanMemoryModelFeatures, or PhysicalDeviceYcbcrImageArraysFeaturesEXT
• The sType value of each struct in the pNext chain must be unique
• flags must be 0
• pQueueCreateInfos must be a valid pointer to an array of queueCreateInfoCount valid DeviceQueueCreateInfo structures
• If enabledLayerCount is not 0, ppEnabledLayerNames must be a valid pointer to an array of enabledLayerCount null-terminated UTF-8 strings
• If enabledExtensionCount is not 0, ppEnabledExtensionNames must be a valid pointer to an array of enabledExtensionCount null-terminated UTF-8 strings
• If pEnabledFeatures is not NULL, pEnabledFeatures must be a valid pointer to a valid PhysicalDeviceFeatures structure
• queueCreateInfoCount must be greater than 0

See Also

DeviceCreateFlags, DeviceQueueCreateInfo, PhysicalDeviceFeatures, StructureType, createDevice

Constructors

DeviceCreateInfo

Fields

• next :: Chain es

  pNext is NULL or a pointer to an extension-specific structure.

• flags :: DeviceCreateFlags

  flags is reserved for future use.

• queueCreateInfos :: Vector (SomeStruct DeviceQueueCreateInfo)

  pQueueCreateInfos is a pointer to an array of DeviceQueueCreateInfo structures describing the queues that are requested to be created along with the logical device. Refer to the Queue Creation section below for further details.

• enabledLayerNames :: Vector ByteString

  ppEnabledLayerNames is deprecated and ignored. See https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#extendingvulkan-layers-devicelayerdeprecation.

• enabledExtensionNames :: Vector ByteString

  ppEnabledExtensionNames is a pointer to an array of enabledExtensionCount null-terminated UTF-8 strings containing the names of extensions to enable for the created device. See the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#extendingvulkan-extensions section for further details.

• enabledFeatures :: Maybe PhysicalDeviceFeatures

  pEnabledFeatures is NULL or a pointer to a PhysicalDeviceFeatures structure containing boolean indicators of all the features to be enabled. Refer to the Features section for further details.

Instances

Extensible DeviceCreateInfo

Defined in Vulkan.Core10.Device

Methods

extensibleType :: StructureType

getNext :: forall (es :: [Type]). DeviceCreateInfo es -> Chain es

setNext :: forall (ds :: [Type]) (es :: [Type]). DeviceCreateInfo ds -> Chain es -> DeviceCreateInfo es

extends :: forall e b proxy. Typeable e => proxy e -> (Extends DeviceCreateInfo e => b) -> Maybe b

Show (Chain es) => Show (DeviceCreateInfo es)

Defined in Vulkan.Core10.Device

Methods

showsPrec :: Int -> DeviceCreateInfo es -> ShowS

show :: DeviceCreateInfo es -> String

showList :: [DeviceCreateInfo es] -> ShowS

(Extendss DeviceCreateInfo es, PeekChain es) => FromCStruct (DeviceCreateInfo es)

Defined in Vulkan.Core10.Device

Methods

peekCStruct :: Ptr (DeviceCreateInfo es) -> IO (DeviceCreateInfo es)

(Extendss DeviceCreateInfo es, PokeChain es) => ToCStruct (DeviceCreateInfo es)

Defined in Vulkan.Core10.Device

Methods

withCStruct :: DeviceCreateInfo es -> (Ptr (DeviceCreateInfo es) -> IO b) -> IO b

pokeCStruct :: Ptr (DeviceCreateInfo es) -> DeviceCreateInfo es -> IO b -> IO b

withZeroCStruct :: (Ptr (DeviceCreateInfo es) -> IO b) -> IO b

pokeZeroCStruct :: Ptr (DeviceCreateInfo es) -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

es ~ ('[] :: [Type]) => Zero (DeviceCreateInfo es)

Defined in Vulkan.Core10.Device

Methods

zero :: DeviceCreateInfo es