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

from __future__ import annotations

from dataclasses import dataclass


@dataclass
class MipmappedArrayOptions:
    """Options for :meth:`cuda.core.Device.create_mipmapped_array`.

    Attributes
    ----------
    shape : tuple of int
        ``(width,)``, ``(width, height)``, or ``(width, height, depth)`` in
        elements, for the base (level 0) mip.
    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.
    num_levels : int
        Number of mip levels to allocate; must be >= 1. The driver caps this at
        the log2 of the largest dimension; passing a larger value yields a
        driver error.
    is_surface_load_store : bool
        If True, allocate with ``CUDA_ARRAY3D_SURFACE_LDST`` so individual
        levels (obtained via :meth:`MipmappedArray.get_level`) can be bound as
        a :class:`~cuda.core.texture.SurfaceObject` for kernel-side writes.
        Default False.

    .. versionadded:: 1.1.0
    """
    shape: tuple[int, ...]
    format: object
    num_channels: int
    num_levels: int
    is_surface_load_store: bool = False

    def __post_init__(self):
        ...

class MipmappedArray:
    """A mipmapped CUDA array for texture/surface access across levels.

    Wraps ``CUmipmappedArray``. Each mip level is a distinct, hardware-laid-out
    allocation accessible only via a :class:`TextureObject` (or by retrieving
    the level's :class:`OpaqueArray` and binding it as a :class:`SurfaceObject`).
    Destroying the :class:`MipmappedArray` destroys all level arrays
    implicitly, so the :class:`OpaqueArray` instances returned by :meth:`get_level`
    are non-owning and hold a strong reference back to their parent.

    Construct via :meth:`cuda.core.Device.create_mipmapped_array`.

    .. versionadded:: 1.1.0
    """

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

        Destruction (``cuMipmappedArrayDestroy``) happens via the handle's
        deleter when the last reference is dropped. A level :class:`OpaqueArray`
        from :meth:`get_level` holds its own reference to this mipmap's storage,
        so it stays valid until both it and this object are released. Idempotent.
        """

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

    def get_level(self, level):
        """Return a non-owning :class:`OpaqueArray` view of the given mip level.

        Parameters
        ----------
        level : int
            Mip level index in ``[0, num_levels)``.

        Returns
        -------
        OpaqueArray
            A non-owning :class:`OpaqueArray` wrapping the level's ``CUarray``.
            The :class:`MipmappedArray` is kept alive for the lifetime of the
            returned :class:`OpaqueArray`; the underlying storage is released only
            when this :class:`MipmappedArray` is destroyed.
        """

    @property
    def handle(self):
        """The underlying ``CUmipmappedArray`` as an integer."""

    @property
    def shape(self):
        """Base-level (level 0) allocation shape, in elements."""

    @property
    def format(self):
        """The element :class:`~cuda.core.typing.ArrayFormatType`."""

    @property
    def num_channels(self):
        """Channels per element (1, 2, or 4)."""

    @property
    def num_levels(self):
        """Number of mip levels."""

    @property
    def is_surface_load_store(self):
        """True if this mipmap (and each of its levels) was created with
        ``CUDA_ARRAY3D_SURFACE_LDST`` and can back a :class:`SurfaceObject`."""

    @property
    def device(self):
        """The :class:`Device` this mipmap was allocated on."""

    def __enter__(self):
        ...

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

    def __repr__(self):
        ...

def _create_mipmapped_array(options):
    """Allocate a new :class:`MipmappedArray` on the current device.

    Backs :meth:`cuda.core.Device.create_mipmapped_array`. ``options`` is a
    :class:`MipmappedArrayOptions` (or a mapping accepted by it); its fields are
    validated at construction.
    """