cuda.core.texture: API-style follow-up before v1.1.0 release #2292

Background

PR #2095 (design issue #2188) merged the texture/surface stack on 2026-06-27. I was cc'd on #2188 but didn't get a chance to review before it was merged/closed, my apology. The functional design (5 types, factory set, folded format + num_channels, copy-only interop, graph-capture parity, resource-handle lifetime rewrite) is sound. This issue captures API-style items to address before v1.1.0 ships (milestone due 2026-07-08).

Items

1. Allocation shape: Device.create_*(options=…) instead of classmethod factories

Every other user-allocatable resource in cuda.core is created via Device.create_* (create_stream, create_event, …) or mr.allocate(size, stream=…). OpaqueArray.from_descriptor(…) / MipmappedArray.from_descriptor(…) introduce a new per-type-classmethod pattern.

Move to:

• Device.create_opaque_array(options=OpaqueArrayOptions(…)) -> OpaqueArray
• Device.create_mipmapped_array(options=MipmappedArrayOptions(…)) -> MipmappedArray
• Device.create_texture_object(*, resource, options=TextureObjectOptions(…)) -> TextureObject
• Device.create_surface_object(*, resource) -> SurfaceObject

Ties the resource to whichever device/context is current at construction, mirroring Stream / Event. Removes the classmethod entry points from the types themselves (the private _from_handle graphics-interop escape hatch stays).

Current entry point:

2. Missing XxxOptions dataclasses

cuda.core convention: multi-field creation goes through an XxxOptions dataclass — StreamOptions, EventOptions, LaunchConfig, DeviceMemoryResourceOptions, PinnedMemoryResourceOptions, ManagedMemoryResourceOptions, VirtualMemoryResourceOptions, TensorMapDescriptorOptions. OpaqueArray.from_descriptor currently takes 4 loose kwargs; MipmappedArray.from_descriptor takes 5.

@dataclass
class OpaqueArrayOptions:
    shape: tuple[int, ...]
    format: numpy.dtype | ArrayFormatType    # see item 3
    num_channels: int
    is_surface_load_store: bool = False

@dataclass
class MipmappedArrayOptions:
    shape: tuple[int, ...]
    format: numpy.dtype | ArrayFormatType
    num_channels: int
    num_levels: int
    is_surface_load_store: bool = False

Also rename TextureDescriptor → TextureObjectOptions: CUDA_TEXTURE_DESC is pure creation input (not queryable back), so "descriptor" was borrowing the driver naming inappropriately. TextureObjectOptions matches TensorMapDescriptorOptions / StreamOptions / etc.

3. format accepts numpy.dtype (matches TensorMapDescriptor precedent)

TensorMapDescriptorOptions.data_type already accepts NumPy / ml_dtypes dtype objects with TensorMapDataType retained for compatibility:

The 8 current ArrayFormat values map 1:1 to numpy dtypes. Apply the same pattern to format: numpy.dtype | ml_dtypes.* | ArrayFormatType, prefer dtypes, keep the enum as fallback / escape-hatch for driver formats without numpy equivalents (BC1..BC7, UNORM_INTx in CTK 13+, BFLOAT16 via ml_dtypes).

4. Enum style: IntEnum in root namespace → StrEnum in cuda.core.typing

Every other cuda.core enum unified pre-1.0 lives in cuda.core.typing as a StrEnum with semantic string values and a Type suffix (SourceCodeType, GraphMemoryType, VirtualMemoryHandleType, ObjectCodeFormatType, PCHStatusType, CompilerBackendType, GraphConditionalType, ManagedMemoryLocationType, VirtualMemoryLocationType, VirtualMemoryGranularityType, VirtualMemoryAccessType, VirtualMemoryAllocationType).

Existing pattern (SourceCodeType):

The texture enums are IntEnum backed by cydriver.CU_TR_*, sit in cuda.core.texture root, and drop the Type suffix:

Bring them in line:

# cuda/core/typing.py
class AddressModeType(StrEnum):
    WRAP = "wrap"
    CLAMP = "clamp"
    MIRROR = "mirror"
    BORDER = "border"

class FilterModeType(StrEnum):
    POINT = "point"
    LINEAR = "linear"

class ReadModeType(StrEnum):
    ELEMENT_TYPE = "element_type"
    NORMALIZED_FLOAT = "normalized_float"

# Optional if item 3's numpy path covers everything:
class ArrayFormatType(StrEnum):
    UINT8 = "uint8"
    ...

5. ResourceDescriptor.from_array → from_opaque_array

The type rename Array → OpaqueArray (item 1 of #2188) was to remove "array" ambiguity; leaving ResourceDescriptor.from_array(array: OpaqueArray) puts it right back:

• from_array → from_opaque_array
• from_mipmapped_array — unchanged
• from_linear — unchanged (matches CUresourceType.LINEAR; renaming to from_buffer collides with from_pitch2d, which also takes a Buffer)
• from_pitch2d — unchanged

6. Drop SurfaceObject.from_array sugar

TextureObject has only from_descriptor. SurfaceObject has both from_array(array) and from_descriptor(resource=…):

from_array collapses from_descriptor(resource=ResourceDescriptor.from_array(a)) into one call — same speculative-sugar rule that killed the arr.to_buffer(mr, stream) helper in #2188 decision 2. Remove.

If item 1 lands, both go away (single entry point becomes Device.create_surface_object(*, resource)).

7. OpaqueArray.element_size → element_bytes

Byte-count accessors elsewhere on the type spell _bytes explicitly (size_bytes, pitch_bytes). element_size returns a byte count and should follow:

Not addressed here

• Descriptor round-trip introspection (cuTexObjectGetResourceDesc etc.) — deferred in the PR.

-- Leo's bot