VkImageDrmFormatModifierExplicitCreateInfoEXT(3)

# VkImageDrmFormatModifierExplicitCreateInfoEXT(3) Manual Page

## Name

VkImageDrmFormatModifierExplicitCreateInfoEXT - Specify that an image be created with the provided DRM format modifier and explicit memory layout

## C Specification

If the `pNext` chain of VkImageCreateInfo contains VkImageDrmFormatModifierExplicitCreateInfoEXT, then the image will be created with the Linux DRM format modifier and memory layout defined by the structure.

The VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined as:

    typedef struct VkImageDrmFormatModifierExplicitCreateInfoEXT {
        VkStructureType               sType;
        const void*                   pNext;
        uint64_t                      drmFormatModifier;
        uint32_t                      drmFormatModifierPlaneCount;
        const VkSubresourceLayout*    pPlaneLayouts;
    } VkImageDrmFormatModifierExplicitCreateInfoEXT;

## Members

- `sType` is the type of this structure.

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

- `drmFormatModifier` is the Linux DRM format modifier with which the image will be created.

- `drmFormatModifierPlaneCount` is the number of memory planes in the image (as reported by VkDrmFormatModifierPropertiesEXT) as well as the length of the `pPlaneLayouts` array.

- `pPlaneLayouts` is a pointer to an array of VkSubresourceLayout structures describing the image’s memory planes.

## Description

The `i`th member of `pPlaneLayouts` describes the layout of the image’s `i`th memory plane (that is, `VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT`). In each element of `pPlaneLayouts`, the implementation must ignore `size`. The implementation calculates the size of each plane, which the application can query with vkGetImageSubresourceLayout.

When creating an image with VkImageDrmFormatModifierExplicitCreateInfoEXT, it is the application’s responsibility to satisfy all valid usage requirements. However, the implementation must validate that the provided `pPlaneLayouts`, when combined with the provided `drmFormatModifier` and other creation parameters in VkImageCreateInfo and its `pNext` chain, produce a valid image. (This validation is necessarily implementation-dependent and outside the scope of Vulkan, and therefore not described by valid usage requirements). If this validation fails, then vkCreateImage returns `VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT`.

Valid Usage

- `drmFormatModifier` must be compatible with the parameters in VkImageCreateInfo and its `pNext` chain, as determined by querying VkPhysicalDeviceImageFormatInfo2 extended with VkPhysicalDeviceImageDrmFormatModifierInfoEXT.

- `drmFormatModifierPlaneCount` must be equal to the VkDrmFormatModifierPropertiesEXT::`drmFormatModifierPlaneCount` associated with VkImageCreateInfo::`format` and `drmFormatModifier`, as found by querying VkDrmFormatModifierPropertiesListEXT.

- For each element of `pPlaneLayouts`, `size` must be 0

- For each element of `pPlaneLayouts`, `arrayPitch` must be 0 if VkImageCreateInfo::`arrayLayers` is 1.

- For each element of `pPlaneLayouts`, `depthPitch` must be 0 if VkImageCreateInfo::`extent`::`depth` is 1.

Valid Usage (Implicit)

- `sType` must be `VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT`

- If `drmFormatModifierPlaneCount` is not `0`, `pPlaneLayouts` must be a valid pointer to an array of `drmFormatModifierPlaneCount` `VkSubresourceLayout` structures

## See Also

VkStructureType, VkSubresourceLayout

## 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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.