vkCreateMicromapEXT(3)

# vkCreateMicromapEXT(3) Manual Page

## Name

vkCreateMicromapEXT - Create a new micromap object

Loading… please wait.

## C Specification

To create a micromap, call:

    // Provided by VK_EXT_opacity_micromap
    VkResult vkCreateMicromapEXT(
        VkDevice                                    device,
        const VkMicromapCreateInfoEXT*              pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkMicromapEXT*                              pMicromap);

## Parameters

- `device` is the logical device that creates the acceleration structure object.

- `pCreateInfo` is a pointer to a VkMicromapCreateInfoEXT structure containing parameters affecting creation of the micromap.

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

- `pMicromap` is a pointer to a `VkMicromapEXT` handle in which the resulting micromap object is returned.

## Description

Similar to other objects in Vulkan, the micromap creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into a micromap is determined by the parameters of VkMicromapCreateInfoEXT.

The micromap data is stored in the object referred to by `VkMicromapCreateInfoEXT`::`buffer`. Once memory has been bound to that buffer, it must be populated by micromap build or micromap copy commands such as vkCmdBuildMicromapsEXT, vkBuildMicromapsEXT, vkCmdCopyMicromapEXT, and vkCopyMicromapEXT.

| Note The expected usage for a trace capture/replay tool is that it will serialize and later deserialize the micromap data using micromap copy commands. During capture the tool will use vkCopyMicromapToMemoryEXT or vkCmdCopyMicromapToMemoryEXT with a `mode` of `VK_COPY_MICROMAP_MODE_SERIALIZE_EXT`, and vkCopyMemoryToMicromapEXT or vkCmdCopyMemoryToMicromapEXT with a `mode` of `VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT` during replay.

The input buffers passed to micromap build commands will be referenced by the implementation for the duration of the command. Micromaps must be fully self-contained. The application can reuse or free any memory which was used by the command as an input or as scratch without affecting the results of a subsequent acceleration structure build using the micromap or traversal of that acceleration structure.

Valid Usage

- VUID-vkCreateMicromapEXT-micromap-07430
  The `micromap` feature must be enabled

- VUID-vkCreateMicromapEXT-deviceAddress-07431
  If VkMicromapCreateInfoEXT::`deviceAddress` is not zero, the `micromapCaptureReplay` feature must be enabled

- VUID-vkCreateMicromapEXT-device-07432
  If `device` was created with multiple physical devices, then the `bufferDeviceAddressMultiDevice` feature must be enabled

Valid Usage (Implicit)

- VUID-vkCreateMicromapEXT-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkCreateMicromapEXT-pCreateInfo-parameter
  `pCreateInfo` must be a valid pointer to a valid VkMicromapCreateInfoEXT structure

- VUID-vkCreateMicromapEXT-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkCreateMicromapEXT-pMicromap-parameter
  `pMicromap` must be a valid pointer to a VkMicromapEXT handle

Return Codes

On success, this command returns

  - `VK_SUCCESS`

On failure, this command returns

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR`

## See Also

VK_EXT_opacity_micromap, VkAllocationCallbacks, VkDevice, VkMicromapCreateInfoEXT, VkMicromapEXT

## 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