René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"cuda.core.texture: API-style follow-up before v1.1.0 release","articleBody":"## Background\n\nPR #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).\n\n## Items\n\n### 1. Allocation shape: `Device.create_*(options=…)` instead of classmethod factories\n\nEvery 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.\n\nMove to:\n\n- `Device.create_opaque_array(options=OpaqueArrayOptions(…)) -> OpaqueArray`\n- `Device.create_mipmapped_array(options=MipmappedArrayOptions(…)) -> MipmappedArray`\n- `Device.create_texture_object(*, resource, options=TextureObjectOptions(…)) -> TextureObject`\n- `Device.create_surface_object(*, resource) -> SurfaceObject`\n\nTies 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).\n\nCurrent entry point:\nhttps://github.com/NVIDIA/cuda-python/blob/2780efd4733e43ea5e40287e1a27feb119b3a568/cuda_core/cuda/core/texture/_array.pyi#L58-L79\n\n### 2. Missing `XxxOptions` dataclasses\n\n`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.\n\n```python\n@dataclass\nclass OpaqueArrayOptions:\n    shape: tuple[int, ...]\n    format: numpy.dtype | ArrayFormatType    # see item 3\n    num_channels: int\n    is_surface_load_store: bool = False\n\n@dataclass\nclass MipmappedArrayOptions:\n    shape: tuple[int, ...]\n    format: numpy.dtype | ArrayFormatType\n    num_channels: int\n    num_levels: int\n    is_surface_load_store: bool = False\n```\n\nAlso 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.\n\n### 3. `format` accepts `numpy.dtype` (matches `TensorMapDescriptor` precedent)\n\n`TensorMapDescriptorOptions.data_type` already accepts NumPy / `ml_dtypes` dtype objects with `TensorMapDataType` retained for compatibility:\nhttps://github.com/NVIDIA/cuda-python/blob/2780efd4733e43ea5e40287e1a27feb119b3a568/cuda_core/cuda/core/_tensor_map.pyi#L88-L102\n\nThe 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`).\n\n### 4. Enum style: `IntEnum` in root namespace → `StrEnum` in `cuda.core.typing`\n\nEvery 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`).\n\nExisting pattern (`SourceCodeType`):\nhttps://github.com/NVIDIA/cuda-python/blob/2780efd4733e43ea5e40287e1a27feb119b3a568/cuda_core/cuda/core/typing.py#L62-L72\n\nThe texture enums are `IntEnum` backed by `cydriver.CU_TR_*`, sit in `cuda.core.texture` root, and drop the `Type` suffix:\nhttps://github.com/NVIDIA/cuda-python/blob/2780efd4733e43ea5e40287e1a27feb119b3a568/cuda_core/cuda/core/texture/_texture.pyi#L11-L33\n\nBring them in line:\n\n```python\n# cuda/core/typing.py\nclass AddressModeType(StrEnum):\n    WRAP = \"wrap\"\n    CLAMP = \"clamp\"\n    MIRROR = \"mirror\"\n    BORDER = \"border\"\n\nclass FilterModeType(StrEnum):\n    POINT = \"point\"\n    LINEAR = \"linear\"\n\nclass ReadModeType(StrEnum):\n    ELEMENT_TYPE = \"element_type\"\n    NORMALIZED_FLOAT = \"normalized_float\"\n\n# Optional if item 3's numpy path covers everything:\nclass ArrayFormatType(StrEnum):\n    UINT8 = \"uint8\"\n    ...\n```\n\n### 5. `ResourceDescriptor.from_array` → `from_opaque_array`\n\nThe type rename `Array` → `OpaqueArray` (item 1 of #2188) was to remove \"array\" ambiguity; leaving `ResourceDescriptor.from_array(array: OpaqueArray)` puts it right back:\nhttps://github.com/NVIDIA/cuda-python/blob/2780efd4733e43ea5e40287e1a27feb119b3a568/cuda_core/cuda/core/texture/_texture.pyi#L58-L60\n\n- `from_array` → `from_opaque_array`\n- `from_mipmapped_array` — unchanged\n- `from_linear` — unchanged (matches `CUresourceType.LINEAR`; renaming to `from_buffer` collides with `from_pitch2d`, which also takes a `Buffer`)\n- `from_pitch2d` — unchanged\n\n### 6. Drop `SurfaceObject.from_array` sugar\n\n`TextureObject` has only `from_descriptor`. `SurfaceObject` has both `from_array(array)` and `from_descriptor(resource=…)`:\nhttps://github.com/NVIDIA/cuda-python/blob/2780efd4733e43ea5e40287e1a27feb119b3a568/cuda_core/cuda/core/texture/_surface.pyi#L32-L37\n\n`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.\n\nIf item 1 lands, both go away (single entry point becomes `Device.create_surface_object(*, resource)`).\n\n### 7. `OpaqueArray.element_size` → `element_bytes`\n\nByte-count accessors elsewhere on the type spell `_bytes` explicitly (`size_bytes`, `pitch_bytes`). `element_size` returns a byte count and should follow:\nhttps://github.com/NVIDIA/cuda-python/blob/2780efd4733e43ea5e40287e1a27feb119b3a568/cuda_core/cuda/core/texture/_array.pyi#L107-L109\n\n## Not addressed here\n\n- Descriptor round-trip introspection (`cuTexObjectGetResourceDesc` etc.) — deferred in the PR.\n\n-- Leo's bot","author":{"url":"https://github.com/leofang","@type":"Person","name":"leofang"},"datePublished":"2026-07-01T23:50:35Z","url":"https://github.com/NVIDIA/cuda-python/issues/2292"}