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.

Populating the data in the object after allocating and binding memory is done with commands such as vkCmdBuildMicromapsEXT, vkBuildMicromapsEXT, vkCmdCopyMicromapEXT, and vkCopyMicromapEXT.

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 may re-use 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-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0