"""
This module provides utilities for textures.

"""

import typing
import collections.abc
import typing_extensions
import numpy.typing as npt
import bpy.types
import gpu.types

def from_external_memory(
    handle: int,
    handle_type: str,
    format: typing.Literal[
        "RGBA8UI",
        "RGBA8I",
        "RGBA8",
        "RGBA32UI",
        "RGBA32I",
        "RGBA32F",
        "RGBA16UI",
        "RGBA16I",
        "RGBA16F",
        "RGBA16",
        "RG8UI",
        "RG8I",
        "RG8",
        "RG32UI",
        "RG32I",
        "RG32F",
        "RG16UI",
        "RG16I",
        "RG16F",
        "RG16",
        "R8UI",
        "R8I",
        "R8",
        "R32UI",
        "R32I",
        "R32F",
        "R16UI",
        "R16I",
        "R16F",
        "R16",
        "R11F_G11F_B10F",
        "DEPTH32F_STENCIL8",
        "DEPTH24_STENCIL8",
        "SRGB8_A8",
        "RGB16F",
        "SRGB8_A8_DXT1",
        "SRGB8_A8_DXT3",
        "SRGB8_A8_DXT5",
        "RGBA8_DXT1",
        "RGBA8_DXT3",
        "RGBA8_DXT5",
        "DEPTH_COMPONENT32F",
        "DEPTH_COMPONENT24",
        "DEPTH_COMPONENT16",
    ],
    width: int,
    height: int,
    stride: int,
) -> None | gpu.types.GPUTexture:
    """Create a `gpu.types.GPUTexture` from an externally-owned GPU memory handle.
    Zero-copy Vulkan external memory import. Requires the Vulkan backend and the matching
    device extension (VK_KHR_external_memory_fd on Linux,
    VK_KHR_external_memory_win32 on Windows).
    Returns None if the extension is unavailable or import fails.

        :param handle: DMA-BUF fd (Linux) or Win32 HANDLE (Windows) cast to int.
        :param handle_type: External memory handle type string.
    DMA_BUF    VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT (Linux).
    D3D11_KMT  VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT (Windows).
        :param format: Internal GPU texture format string.
        :param width: Texture width in pixels.
        :param height: Texture height in pixels.
        :param stride: Row stride in bytes.
        :return: The imported texture, or None on failure.
    """

def from_image(image: bpy.types.Image) -> gpu.types.GPUTexture:
    """Get GPUTexture corresponding to an Image data-block. The GPUTexture memory is shared with Blender.
    Note: Colors read from the texture will be in scene linear color space and have premultiplied or straight alpha matching the image alpha mode.

        :param image: The Image data-block.
        :return: The GPUTexture used by the image.
    """

def set_image_texture(
    image: bpy.types.Image, texture: None | gpu.types.GPUTexture
) -> None:
    """Override the GPU texture used by a `bpy.types.Image` datablock.
    Material Image Texture nodes will sample from texture instead of
    uploading pixel data from CPU memory.
    Pass None to clear the override and restore normal behaviour.

        :param image: The Image datablock to override.
        :param texture: Texture to use, or None to clear.
    """
