VkMicromapCreateInfoEXT(3)

# VkMicromapCreateInfoEXT(3) Manual Page

## Name

VkMicromapCreateInfoEXT - Structure specifying the parameters of a newly created micromap object

Loading… please wait.

## C Specification

The `VkMicromapCreateInfoEXT` structure is defined as:

    // Provided by VK_EXT_opacity_micromap
    typedef struct VkMicromapCreateInfoEXT {
        VkStructureType             sType;
        const void*                 pNext;
        VkMicromapCreateFlagsEXT    createFlags;
        VkBuffer                    buffer;
        VkDeviceSize                offset;
        VkDeviceSize                size;
        VkMicromapTypeEXT           type;
        VkDeviceAddress             deviceAddress;
    } VkMicromapCreateInfoEXT;

## Members

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

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

- `createFlags` is a bitmask of VkMicromapCreateFlagBitsEXT specifying additional creation parameters of the micromap.

- `buffer` is the buffer on which the micromap will be stored.

- `offset` is an offset in bytes from the base address of the buffer at which the micromap will be stored, and must be a multiple of `256`.

- `size` is the size required for the micromap.

- `type` is a VkMicromapTypeEXT value specifying the type of micromap that will be created.

- `deviceAddress` is the device address requested for the micromap if the `micromapCaptureReplay` feature is being used.

## Description

If `deviceAddress` is zero, no specific address is requested.

If `deviceAddress` is not zero, `deviceAddress` must be an address retrieved from an identically created micromap on the same implementation. The micromap must also be placed on an identically created `buffer` and at the same `offset`.

Applications should avoid creating micromaps with application-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR` errors.

| Note The expected usage for this is that a trace capture/replay tool will add the `VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT` flag to all buffers that use `VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT`, and will add `VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT` to all buffers used as storage for a micromap where `deviceAddress` is not zero. This also means that the tool will need to add `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT` to memory allocations to allow the flag to be set where the application may not have otherwise required it. During capture the tool will save the queried opaque device addresses in the trace. During replay, the buffers will be created specifying the original address so any address values stored in the trace data will remain valid. Implementations are expected to separate such buffers in the GPU address space so normal allocations will avoid using these addresses. Apps/tools should avoid mixing app-provided and implementation-provided addresses for buffers created with `VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT`, to avoid address space allocation conflicts.

If the micromap will be the target of a build operation, the required size for a micromap can be queried with vkGetMicromapBuildSizesEXT.

Valid Usage

- VUID-VkMicromapCreateInfoEXT-deviceAddress-07433
  If `deviceAddress` is not zero, `createFlags` must include `VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT`

- VUID-VkMicromapCreateInfoEXT-createFlags-07434
  If `createFlags` includes `VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT`, VkPhysicalDeviceOpacityMicromapFeaturesEXT::`micromapCaptureReplay` must be `VK_TRUE`

- VUID-VkMicromapCreateInfoEXT-buffer-07435
  `buffer` must have been created with a `usage` value containing `VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT`

- VUID-VkMicromapCreateInfoEXT-buffer-07436
  `buffer` must not have been created with `VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT`

- VUID-VkMicromapCreateInfoEXT-offset-07437
  The sum of `offset` and `size` must be less than the size of `buffer`

- VUID-VkMicromapCreateInfoEXT-offset-07438
  `offset` must be a multiple of `256` bytes

Valid Usage (Implicit)

- VUID-VkMicromapCreateInfoEXT-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_MICROMAP_CREATE_INFO_EXT`

- VUID-VkMicromapCreateInfoEXT-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkMicromapCreateInfoEXT-createFlags-parameter
  `createFlags` must be a valid combination of VkMicromapCreateFlagBitsEXT values

- VUID-VkMicromapCreateInfoEXT-buffer-parameter
  `buffer` must be a valid VkBuffer handle

- VUID-VkMicromapCreateInfoEXT-type-parameter
  `type` must be a valid VkMicromapTypeEXT value

## See Also

VK_EXT_opacity_micromap, VkBuffer, VkDeviceAddress, VkDeviceSize, VkMicromapCreateFlagsEXT, VkMicromapTypeEXT, VkStructureType, vkCreateMicromapEXT

## 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0