All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.lwjgl.vulkan.EXTImageDrmFormatModifier Maven / Gradle / Ivy

Go to download

A new generation graphics and compute API that provides high-efficiency, cross-platform access to modern GPUs used in a wide variety of devices from PCs and consoles to mobile phones and embedded platforms.

There is a newer version: 3.3.4
Show newest version
/*
 * Copyright LWJGL. All rights reserved.
 * License terms: https://www.lwjgl.org/license
 * MACHINE GENERATED FILE, DO NOT EDIT
 */
package org.lwjgl.vulkan;

import org.lwjgl.system.*;

import static org.lwjgl.system.Checks.*;
import static org.lwjgl.system.JNI.*;

/**
 * This extension provides the ability to use DRM format modifiers with images, enabling Vulkan to better integrate with the Linux ecosystem of graphics, video, and display APIs.
 * 
 * 
Its functionality closely overlaps with {@code EGL_EXT_image_dma_buf_import_modifiers}2 and {@code EGL_MESA_image_dma_buf_export}3. Unlike the EGL extensions, this extension does not require the use of a specific handle type (such as a dma_buf) for external memory and provides more explicit control of image creation.

 * 
 * 
Introduction to DRM Format Modifiers

 * 
 * 
A DRM format modifier is a 64-bit, vendor-prefixed, semi-opaque unsigned integer. Most modifiers represent a concrete, vendor-specific tiling format for images. Some exceptions are {@code DRM_FORMAT_MOD_LINEAR} (which is not vendor-specific); {@code DRM_FORMAT_MOD_NONE} (which is an alias of {@code DRM_FORMAT_MOD_LINEAR} due to historical accident); and {@code DRM_FORMAT_MOD_INVALID} (which does not represent a tiling format). The modifier’s vendor prefix consists of the 8 most significant bits. The canonical list of modifiers and vendor prefixes is found in {@code drm_fourcc.h} in the Linux kernel source. The other dominant source of modifiers are vendor kernel trees.

 * 
 * 
One goal of modifiers in the Linux ecosystem is to enumerate for each vendor a reasonably sized set of tiling formats that are appropriate for images shared across processes, APIs, and/or devices, where each participating component may possibly be from different vendors. A non-goal is to enumerate all tiling formats supported by all vendors. Some tiling formats used internally by vendors are inappropriate for sharing; no modifiers should be assigned to such tiling formats.

 * 
 * 
Modifier values typically do not describe memory layouts. More precisely, a modifier's lower 56 bits usually have no structure. Instead, modifiers name memory layouts; they name a small set of vendor-preferred layouts for image sharing. As a consequence, in each vendor namespace the modifier values are often sequentially allocated starting at 1.

 * 
 * 
Each modifier is usually supported by a single vendor and its name matches the pattern {@code {VENDOR}_FORMAT_MOD_*} or {@code DRM_FORMAT_MOD_{VENDOR}_*}. Examples are {@code I915_FORMAT_MOD_X_TILED} and {@code DRM_FORMAT_MOD_BROADCOM_VC4_T_TILED}. An exception is {@code DRM_FORMAT_MOD_LINEAR}, which is supported by most vendors.

 * 
 * 
Many APIs in Linux use modifiers to negotiate and specify the memory layout of shared images. For example, a Wayland compositor and Wayland client may, by relaying modifiers over the Wayland protocol {@code zwp_linux_dmabuf_v1}, negotiate a vendor-specific tiling format for a shared {@code wl_buffer}. The client may allocate the underlying memory for the {@code wl_buffer} with GBM, providing the chosen modifier to {@code gbm_bo_create_with_modifiers}. The client may then import the {@code wl_buffer} into Vulkan for producing image content, providing the resource’s dma_buf to {@link VkImportMemoryFdInfoKHR} and its modifier to {@link VkImageDrmFormatModifierExplicitCreateInfoEXT}. The compositor may then import the {@code wl_buffer} into OpenGL for sampling, providing the resource’s dma_buf and modifier to {@code eglCreateImage}. The compositor may also bypass OpenGL and submit the {@code wl_buffer} directly to the kernel’s display API, providing the dma_buf and modifier through {@code drm_mode_fb_cmd2}.

 * 
 * 
Format Translation

 * 
 * 
Modifier-capable APIs often pair modifiers with DRM formats, which are defined in {@code drm_fourcc.h}. However, {@code VK_EXT_image_drm_format_modifier} uses {@code VkFormat} instead of DRM formats. The application must convert between {@code VkFormat} and DRM format when it sends or receives a DRM format to or from an external API.

 * 
 * 
The mapping from {@code VkFormat} to DRM format is lossy. Therefore, when receiving a DRM format from an external API, often the application must use information from the external API to accurately map the DRM format to a {@code VkFormat}. For example, DRM formats do not distinguish between RGB and sRGB (as of 2018-03-28); external information is required to identify the image’s colorspace.

 * 
 * 
The mapping between {@code VkFormat} and DRM format is also incomplete. For some DRM formats there exist no corresponding Vulkan format, and for some Vulkan formats there exist no corresponding DRM format.

 * 
 * 
Usage Patterns

 * 
 * 
Three primary usage patterns are intended for this extension:

 * 
 * 
    
 * 
  • Negotiation. The application negotiates with modifier-aware, external components to determine sets of image creation parameters supported among all components.
 * In the Linux ecosystem, the negotiation usually assumes the image is a 2D, single-sampled, non-mipmapped, non-array image; this extension permits that assumption but does not require it. The result of the negotiation usually resembles a set of tuples such as (drmFormat, drmFormatModifier), where each participating component supports all tuples in the set.
 * 
 * 
    Many details of this negotiation—such as the protocol used during negotiation, the set of image creation parameters expressable in the protocol, and how the protocol chooses which process and which API will create the image—are outside the scope of this specification.
    
 * 
 * 
    In this extension, {@link VK11#vkGetPhysicalDeviceFormatProperties2 GetPhysicalDeviceFormatProperties2} with {@link VkDrmFormatModifierPropertiesListEXT} serves a primary role during the negotiation, and {@link VK11#vkGetPhysicalDeviceImageFormatProperties2 GetPhysicalDeviceImageFormatProperties2} with {@link VkPhysicalDeviceImageDrmFormatModifierInfoEXT} serves a secondary role.
    
 * 
    • 
 * 
  • Import. The application imports an image with a modifier.
 * In this pattern, the application receives from an external source the image’s memory and its creation parameters, which are often the result of the negotiation described above. Some image creation parameters are implicitly defined by the external source; for example, {@link VK10#VK_IMAGE_TYPE_2D IMAGE_TYPE_2D} is often assumed. Some image creation parameters are usually explicit, such as the image’s {@code format}, {@code drmFormatModifier}, and {@code extent}; and each plane’s {@code offset} and {@code rowPitch}.
 * 
 * 
    Before creating the image, the application first verifies that the physical device supports the received creation parameters by querying {@link VK11#vkGetPhysicalDeviceFormatProperties2 GetPhysicalDeviceFormatProperties2} with {@link VkDrmFormatModifierPropertiesListEXT} and {@link VK11#vkGetPhysicalDeviceImageFormatProperties2 GetPhysicalDeviceImageFormatProperties2} with {@link VkPhysicalDeviceImageDrmFormatModifierInfoEXT}. Then the application creates the image by chaining {@link VkImageDrmFormatModifierExplicitCreateInfoEXT} and {@link VkExternalMemoryImageCreateInfo} onto {@link VkImageCreateInfo}.
    
 * 
    • 
 * 
  • Export. The application creates an image and allocates its memory. Then the application exports to modifier-aware consumers the image’s memory handles; its creation parameters; its modifier; and the {@code offset}, {@code size}, and {@code rowPitch} of each memory plane.
 * In this pattern, the Vulkan device is the authority for the image; it is the allocator of the image’s memory and the decider of the image’s creation parameters. When choosing the image’s creation parameters, the application usually chooses a tuple (format, drmFormatModifier) from the result of the negotiation described above. The negotiation’s result often contains multiple tuples that share the same format but differ in their modifier. In this case, the application should defer the choice of the image’s modifier to the Vulkan implementation by providing all such modifiers to {@link VkImageDrmFormatModifierListCreateInfoEXT}{@code ::pDrmFormatModifiers}; and the implementation should choose from {@code pDrmFormatModifiers} the optimal modifier in consideration with the other image parameters.
 * 
 * 
    The application creates the image by chaining {@link VkImageDrmFormatModifierListCreateInfoEXT} and {@link VkExternalMemoryImageCreateInfo} onto {@link VkImageCreateInfo}. The protocol and APIs by which the application will share the image with external consumers will likely determine the value of {@link VkExternalMemoryImageCreateInfo}{@code ::handleTypes}. The implementation chooses for the image an optimal modifier from {@link VkImageDrmFormatModifierListCreateInfoEXT}{@code ::pDrmFormatModifiers}. The application then queries the implementation-chosen modifier with {@link #vkGetImageDrmFormatModifierPropertiesEXT GetImageDrmFormatModifierPropertiesEXT}, and queries the memory layout of each plane with {@link VK10#vkGetImageSubresourceLayout GetImageSubresourceLayout}.
    
 * 
 * 
    The application then allocates the image’s memory with {@link VkMemoryAllocateInfo}, adding chained extending structures for external memory; binds it to the image; and exports the memory, for example, with {@link KHRExternalMemoryFd#vkGetMemoryFdKHR GetMemoryFdKHR}.
    
 * 
 * 
    Finally, the application sends the image’s creation parameters, its modifier, its per-plane memory layout, and the exported memory handle to the external consumers. The details of how the application transmits this information to external consumers is outside the scope of this specification.
    
 * 
    • 
 * 

 * 
 * 
Prior Art

 * 
 * 
Extension {@code EGL_EXT_image_dma_buf_import}1 introduced the ability to create an {@code EGLImage} by importing for each plane a dma_buf, offset, and row pitch.

 * 
 * 
Later, extension {@code EGL_EXT_image_dma_buf_import_modifiers}2 introduced the ability to query which combination of formats and modifiers the implementation supports and to specify modifiers during creation of the {@code EGLImage}.

 * 
 * 
Extension {@code EGL_MESA_image_dma_buf_export}3 is the inverse of {@code EGL_EXT_image_dma_buf_import_modifiers}.

 * 
 * 
The Linux kernel modesetting API (KMS), when configuring the display’s framebuffer with {@code struct drm_mode_fb_cmd2}4, allows one to specify the frambuffer’s modifier as well as a per-plane memory handle, offset, and row pitch.

 * 
 * 
GBM, a graphics buffer manager for Linux, allows creation of a {@code gbm_bo} (that is, a graphics buffer object) by importing data similar to that in {@code EGL_EXT_image_dma_buf_import_modifiers}1; and symmetrically allows exporting the same data from the {@code gbm_bo}. See the references to modifier and plane in {@code gbm.h}5.

 * 
 * 
VK_EXT_image_drm_format_modifier

 * 
 * 

 * 
Name String

 * 
{@code VK_EXT_image_drm_format_modifier}

 * 
Extension Type

 * 
Device extension

 * 
Registered Extension Number

 * 
159

 * 
Revision

 * 
2

 * 
Extension and Version Dependencies

 * 
    
 * 
  • Requires Vulkan 1.0
    • 
 * 
  • Requires {@link KHRBindMemory2 VK_KHR_bind_memory2}
    • 
 * 
  • Requires {@link KHRGetPhysicalDeviceProperties2 VK_KHR_get_physical_device_properties2}
    • 
 * 
  • Requires {@link KHRImageFormatList VK_KHR_image_format_list}
    • 
 * 
  • Requires {@link KHRSamplerYcbcrConversion VK_KHR_sampler_ycbcr_conversion}
    • 
 * 

 * 
Contact

 * 

 * 

 * 
 * 
Other Extension Metadata

 * 
 * 

 * 
Last Modified Date

 * 
2021-09-30

 * 
IP Status

 * 
No known IP claims.

 * 
Contributors

 * 
    
 * 
  • Antoine Labour, Google
    • 
 * 
  • Bas Nieuwenhuizen, Google
    • 
 * 
  • Chad Versace, Google
    • 
 * 
  • James Jones, NVIDIA
    • 
 * 
  • Jason Ekstrand, Intel
    • 
 * 
  • Jőrg Wagner, ARM
    • 
 * 
  • Kristian Høgsberg Kristensen, Google
    • 
 * 
  • Ray Smith, ARM
    • 
 * 

 * 

 */
public class EXTImageDrmFormatModifier {

    /** The extension specification version. */
    public static final int VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSION = 2;

    /** The extension name. */
    public static final String VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_EXTENSION_NAME = "VK_EXT_image_drm_format_modifier";

    /** Extends {@code VkResult}. */
    public static final int VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT = -1000158000;

    /**
     * Extends {@code VkStructureType}.
     * 
     * 
Enum values:

     * 
     * 
    
     * 
  • {@link #VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT}
    • 
     * 
  • {@link #VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT}
    • 
     * 
  • {@link #VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT}
    • 
     * 
  • {@link #VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT}
    • 
     * 
  • {@link #VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT}
    • 
     * 

     */
    public static final int
        VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT            = 1000158000,
        VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT = 1000158002,
        VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT     = 1000158003,
        VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT = 1000158004,
        VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT           = 1000158005;

    /** Extends {@code VkImageTiling}. */
    public static final int VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT = 1000158000;

    /**
     * Extends {@code VkImageAspectFlagBits}.
     * 
     * 
Enum values:

     * 
     * 
    
     * 
  • {@link #VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT}
    • 
     * 
  • {@link #VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT}
    • 
     * 
  • {@link #VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT}
    • 
     * 
  • {@link #VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT}
    • 
     * 

     */
    public static final int
        VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT = 0x80,
        VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT = 0x100,
        VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT = 0x200,
        VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT = 0x400;

    /** Extends {@code VkStructureType}. */
    public static final int VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_2_EXT = 1000158006;

    protected EXTImageDrmFormatModifier() {
        throw new UnsupportedOperationException();
    }

    // --- [ vkGetImageDrmFormatModifierPropertiesEXT ] ---

    /** Unsafe version of: {@link #vkGetImageDrmFormatModifierPropertiesEXT GetImageDrmFormatModifierPropertiesEXT} */
    public static int nvkGetImageDrmFormatModifierPropertiesEXT(VkDevice device, long image, long pProperties) {
        long __functionAddress = device.getCapabilities().vkGetImageDrmFormatModifierPropertiesEXT;
        if (CHECKS) {
            check(__functionAddress);
        }
        return callPJPI(device.address(), image, pProperties, __functionAddress);
    }

    /**
     * Returns an image’s DRM format modifier.
     * 
     * 
C Specification

     * 
     * 
If an image was created with {@link #VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT}, then the image has a Linux DRM format modifier. To query the modifier, call:

     * 
     * 

     * VkResult vkGetImageDrmFormatModifierPropertiesEXT(
     *     VkDevice                                    device,
     *     VkImage                                     image,
     *     VkImageDrmFormatModifierPropertiesEXT*      pProperties);

     * 
     * 
Valid Usage

     * 
     * 
    
     * 
  • {@code image} must have been created with {@link VkImageCreateInfo tiling} equal to {@link #VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT}
    • 
     * 

     * 
     * 
Valid Usage (Implicit)

     * 
     * 
    
     * 
  • {@code device} must be a valid {@code VkDevice} handle
    • 
     * 
  • {@code image} must be a valid {@code VkImage} handle
    • 
     * 
  • {@code pProperties} must be a valid pointer to a {@link VkImageDrmFormatModifierPropertiesEXT} structure
    • 
     * 
  • {@code image} must have been created, allocated, or retrieved from {@code device}
    • 
     * 

     * 
     * 
Return Codes

     * 
     * 

     * 
On success, this command returns

     * 
    
     * 
  • {@link VK10#VK_SUCCESS SUCCESS}
    • 
     * 

     * 
On failure, this command returns

     * 
    
     * 
  • {@link VK10#VK_ERROR_OUT_OF_HOST_MEMORY ERROR_OUT_OF_HOST_MEMORY}
    • 
     * 

     * 

     * 
     * 
See Also

     * 
     * 
{@link VkImageDrmFormatModifierPropertiesEXT}

     *
     * @param device      the logical device that owns the image.
     * @param image       the queried image.
     * @param pProperties a pointer to a {@link VkImageDrmFormatModifierPropertiesEXT} structure in which properties of the image’s DRM format modifier are returned.
     */
    @NativeType("VkResult")
    public static int vkGetImageDrmFormatModifierPropertiesEXT(VkDevice device, @NativeType("VkImage") long image, @NativeType("VkImageDrmFormatModifierPropertiesEXT *") VkImageDrmFormatModifierPropertiesEXT pProperties) {
        return nvkGetImageDrmFormatModifierPropertiesEXT(device, image, pProperties.address());
    }

}




© 2015 - 2024 Weber Informatics LLC | Privacy Policy