# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/texture/_texture.pyx

from __future__ import annotations

from dataclasses import dataclass

from cuda.bindings import cydriver
from cuda.core.typing import AddressModeType, FilterModeType, ReadModeType


class ResourceDescriptor:
    """Describes the memory backing a :class:`TextureObject`.

    Construct via the ``from_*`` classmethods:

    - :meth:`from_opaque_array` wraps a :class:`OpaqueArray` (works for both
      :class:`TextureObject` and :class:`SurfaceObject`).
    - :meth:`from_mipmapped_array` wraps a :class:`MipmappedArray` for mipmapped
      sampling (texture only, not surface).
    - :meth:`from_linear` wraps a :class:`Buffer` as a typed 1D fetch. Texture
      objects built from a linear resource do not support filtering,
      normalized coordinates, or addressing modes.
    - :meth:`from_pitch2d` wraps a :class:`Buffer` as a row-pitched 2D image.
      Supports filtering and 2D addressing, but only 2D access.

    Linear and pitch2D resources cannot back a :class:`SurfaceObject` — those
    require an :class:`OpaqueArray` allocated with ``is_surface_load_store=True``.

    .. versionadded:: 1.1.0
    """
    __slots__ = ('_kind', '_source', '_format', '_num_channels', '_size_bytes', '_width', '_height', '_pitch_bytes')

    def __init__(self):
        ...

    @classmethod
    def from_opaque_array(cls, array):
        """Build a resource descriptor backed by a :class:`OpaqueArray`."""

    @classmethod
    def from_mipmapped_array(cls, mipmapped_array):
        """Build a resource descriptor backed by a :class:`MipmappedArray`.

        Suitable for binding to a :class:`TextureObject` for mipmapped
        sampling. Not valid as a :class:`SurfaceObject` backing: surfaces
        require a single :class:`OpaqueArray` level (obtain via
        :meth:`MipmappedArray.get_level`).
        """

    @classmethod
    def from_linear(cls, buffer, *, format, num_channels, size_bytes=None):
        """Build a resource descriptor for a linear (typed 1D) texture fetch.

        Parameters
        ----------
        buffer : Buffer
            Device-memory backing. Must remain alive for the lifetime of any
            :class:`TextureObject` built from this descriptor.
        format : ArrayFormatType, str, or numpy.dtype
            Element format. Accepts an :class:`~cuda.core.typing.ArrayFormatType`,
            a plain string (e.g. ``"float32"``), or a NumPy dtype object.
        num_channels : int
            Channels per element. Must be 1, 2, or 4.
        size_bytes : int, optional
            Bytes of ``buffer`` to bind. Defaults to ``buffer.size``. Must not
            exceed it.

        Notes
        -----
        Texture objects built from a linear resource ignore the
        :class:`TextureObjectOptions` addressing/filtering fields — kernels read
        through a typed 1D fetch with bounds checking only.
        """

    @classmethod
    def from_pitch2d(cls, buffer, *, format, num_channels, width, height, pitch_bytes):
        """Build a resource descriptor for a row-pitched 2D image.

        Parameters
        ----------
        buffer : Buffer
            Device-memory backing. Must remain alive for the lifetime of any
            :class:`TextureObject` built from this descriptor.
        format : ArrayFormatType, str, or numpy.dtype
            Element format. Accepts an :class:`~cuda.core.typing.ArrayFormatType`,
            a plain string (e.g. ``"float32"``), or a NumPy dtype object.
        num_channels : int
            Channels per element. Must be 1, 2, or 4.
        width : int
            Image width, in elements.
        height : int
            Image height, in rows.
        pitch_bytes : int
            Distance between consecutive rows, in bytes. Must be at least
            ``width * format_size * num_channels`` and meet the driver's
            ``CU_DEVICE_ATTRIBUTE_TEXTURE_PITCH_ALIGNMENT``.
        """

    @property
    def kind(self):
        ...

    @property
    def source(self):
        ...

    @property
    def format(self):
        """The element :class:`~cuda.core.typing.ArrayFormatType` (``None`` for array-backed)."""

    @property
    def num_channels(self):
        """Channels per element (``None`` for array-backed)."""

    @property
    def size_bytes(self):
        """Bytes bound for a linear resource (``None`` for other kinds)."""

    @property
    def width(self):
        """Pitch2D image width, in elements (``None`` for other kinds)."""

    @property
    def height(self):
        """Pitch2D image height, in rows (``None`` for other kinds)."""

    @property
    def pitch_bytes(self):
        """Pitch2D row pitch, in bytes (``None`` for other kinds)."""

    def __repr__(self):
        ...

@dataclass
class TextureObjectOptions:
    """Sampling state for a :class:`TextureObject` (mirrors ``CUDA_TEXTURE_DESC``).

    Attributes
    ----------
    address_mode : AddressModeType or tuple of AddressModeType
        Boundary behavior per axis. May be a single
        :class:`~cuda.core.typing.AddressModeType` (applied to all axes) or a
        tuple of 1-3 entries (one per dimension). Plain strings are accepted.
    filter_mode : FilterModeType
        Texel sampling mode. Default ``POINT``. Plain strings are accepted.
    read_mode : ReadModeType
        How sampled integer values are returned. Default ``ELEMENT_TYPE``.
        Plain strings are accepted.
    normalized_coords : bool
        If True, coordinates are in ``[0, 1]`` instead of pixel indices.
    srgb : bool
        If True, perform sRGB → linear conversion on read (8-bit formats only).
    disable_trilinear_optimization : bool
        If True, request exact trilinear filtering.
    seamless_cubemap : bool
        If True, enable seamless cubemap edge filtering.
    max_anisotropy : int
        Maximum anisotropy; 0 disables anisotropic filtering.
    mipmap_filter_mode : FilterModeType
        Filtering between mipmap levels. Default ``POINT``. Plain strings are
        accepted.
    mipmap_level_bias : float
    min_mipmap_level_clamp : float
    max_mipmap_level_clamp : float
    border_color : tuple of float or None
        4-tuple used when ``address_mode`` includes ``BORDER``; ``None`` means
        zero.

    .. versionadded:: 1.1.0
    """
    address_mode: AddressModeType | str | tuple[AddressModeType | str, ...] = AddressModeType.CLAMP
    filter_mode: FilterModeType | str = FilterModeType.POINT
    read_mode: ReadModeType | str = ReadModeType.ELEMENT_TYPE
    normalized_coords: bool = False
    srgb: bool = False
    disable_trilinear_optimization: bool = False
    seamless_cubemap: bool = False
    max_anisotropy: int = 0
    mipmap_filter_mode: FilterModeType | str = FilterModeType.POINT
    mipmap_level_bias: float = 0.0
    min_mipmap_level_clamp: float = 0.0
    max_mipmap_level_clamp: float = 0.0
    border_color: tuple[float, ...] | None = None

    def __post_init__(self):
        ...

class TextureObject:
    """A bindless texture handle for kernel-side sampled reads.

    Wraps ``cuTexObjectCreate``. The underlying memory resource (e.g. the
    :class:`OpaqueArray` referenced by the descriptor) is kept alive for the
    lifetime of this object to prevent dangling handles.

    Construct via :meth:`cuda.core.Device.create_texture_object`. Passes to
    kernels as a 64-bit handle (via the ``handle`` property).

    .. versionadded:: 1.1.0
    """

    def close(self):
        """Release this object's reference to the underlying ``CUtexObject``.

        Destruction (``cuTexObjectDestroy``) and release of the backing resource
        happen via the handle's deleter when the last reference is dropped.
        Idempotent.
        """

    def __init__(self, *args, **kwargs):
        ...

    @property
    def handle(self):
        """The underlying ``CUtexObject`` as an integer (64-bit kernel arg)."""

    @property
    def resource(self):
        """The :class:`ResourceDescriptor` this texture was built from."""

    @property
    def options(self):
        """The :class:`TextureObjectOptions` this texture was built from."""

    @property
    def device(self):
        ...

    def __enter__(self):
        ...

    def __exit__(self, exc_type, exc, tb):
        ...

    def __repr__(self):
        ...
_TRSF_READ_AS_INTEGER = 1
_TRSF_NORMALIZED_COORDINATES = 2
_TRSF_SRGB = 16
_TRSF_DISABLE_TRILINEAR_OPTIMIZATION = 32
_TRSF_SEAMLESS_CUBEMAP = 64
_ADDRESSMODE_TO_CU = {AddressModeType.WRAP: int(cydriver.CU_TR_ADDRESS_MODE_WRAP), AddressModeType.CLAMP: int(cydriver.CU_TR_ADDRESS_MODE_CLAMP), AddressModeType.MIRROR: int(cydriver.CU_TR_ADDRESS_MODE_MIRROR), AddressModeType.BORDER: int(cydriver.CU_TR_ADDRESS_MODE_BORDER)}
_FILTERMODE_TO_CU = {FilterModeType.POINT: int(cydriver.CU_TR_FILTER_MODE_POINT), FilterModeType.LINEAR: int(cydriver.CU_TR_FILTER_MODE_LINEAR)}

def _normalize_enum(name, value, enum_type):
    """Coerce ``value`` to ``enum_type`` (a StrEnum), accepting a plain str."""

def _normalize_address_modes(address_mode):
    """Return a 3-tuple of :class:`AddressModeType` values from a scalar or
    1-3 tuple. Individual entries may be plain strings."""

def _create_texture_object(resource, options):
    """Create a :class:`TextureObject` on the current device.

    Backs :meth:`cuda.core.Device.create_texture_object`. ``resource`` is a
    :class:`ResourceDescriptor`; ``options`` is a :class:`TextureObjectOptions`
    (or a mapping accepted by it).
    """