René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Design: cuda.core Texture/Surface API surface ","articleBody":"## Purpose\n\nDesign discussion for the **texture / surface API** in `cuda.core` — to settle the API shape and\nnaming *before* code review of the implementation. Reviewers asked for design sign-off in an issue\nbefore we commit to a ~9k-line feature.\n\n- Implementation PR: #2095\n- Feature request: #467\n\ncc @leofang @mdboom @Andy-Jost @kkraus14 — you asked for a design pass; this is the home for it.\n\n## Proposed public surface (from #2095)\n\n- `Array` + `ArrayFormat` — opaque, hardware-laid-out GPU allocations backing textures/surfaces.\n- `MipmappedArray` — wraps `CUmipmappedArray`; `get_level` returns a non-owning `Array` kept alive\n  by a strong ref to the parent.\n- `TextureObject` + `TextureDescriptor` — bindless texture handle + sampling state. (read-only)\n- `SurfaceObject` — bindless surface handle; requires `Array(surface_load_store=True)`. (read/write)\n- `ResourceDescriptor` — factories `from_array`, `from_mipmapped_array`, `from_linear`, `from_pitch2d`.\n\n## Decisions to make\n\n1. **Name of `Array`. ✅ Decided — rename `Array` → `CUDAArray`.**\n\n   This type is an opaque `cudaArray_t` — the GPU stores it in a scrambled, hardware-defined layout\n   with no linear pointer, so it **cannot** expose `__cuda_array_interface__` / DLPack and cannot\n   share memory zero-copy with cupy / numba-cuda / torch. The name `Array` implies an n-dimensional\n   array that participates in that ecosystem — it can't. CuPy names the identical type `CUDAarray`,\n   and its whole `cupy.cuda.texture` module already matches this PR's surface 1:1.\n\n   **Resolution: use `CUDAArray`** — the PEP 8 CapWords form (deliberately differing from CuPy's exact\n   `CUDAarray` casing to follow Python's class-naming standard). The name signals \"CUDA texture/surface\n   backing store,\" not \"n-dimensional array.\"\n\n   **Open detail resolved: keep `ArrayFormat` (do *not* rename to `CUDAArrayFormat`).** The sibling\n   enums in these modules — `AddressMode`, `FilterMode`, `ReadMode` — are all unprefixed, so\n   `ArrayFormat` matches the established enum-naming pattern; and the \"`Array` implies an\n   ndarray/DLPack participant\" concern that motivated `CUDAArray` does not apply to a format enum\n   (nobody mistakes `ArrayFormat` for an n-dimensional array).\n\n2. **Interop path. ✅ Decided — ship only `copy_from` / `copy_to`; no allocation helper.**\n\n   Zero-copy is impossible (opaque layout, no linear pointer), so copying is the only option —\n   this was purely about how polished the path is. The copy path to/from linear `cuda.core`\n   `Buffer`s already exists: `copy_from` / `copy_to` accept a device `Buffer` or a host\n   buffer-protocol object, in both directions. The only thing an extra helper would add is\n   allocating the linear `Buffer` for the caller — folding `mr.allocate(arr.size_bytes, stream=s)`\n   + `arr.copy_to(buf, stream=s)` into a one-liner, i.e. ~2 lines of convenience.\n\n    The \"extra helper\" would collapse this:\n    ```\n    mr = DeviceMemoryResource(device)\n    buf = mr.allocate(arr.size_bytes, stream=s)\n    arr.copy_to(buf, stream=s)\n\n    into something like \n   buf = arr.to_buffer(mr, stream=s).\n    ```\n\n   **Resolution: ship `copy_from` / `copy_to` only, and document the copy-only contract.** We will\n   not add an allocating convenience helper now. It is purely additive and non-breaking, so we can\n   add one later if users request it.\n\n3. **Factory set. ✅ Not a real decision — driver-mandated, all four required.**\n\n   A texture can be backed by four kinds of memory — the PR exposes one factory per kind:\n   - `from_array` — texture over a `CUDAArray` *(the headline feature)*\n   - `from_mipmapped_array` — texture over a `MipmappedArray` *(the headline feature)*\n   - `from_linear` — texture over a plain 1D device buffer *(ordinary linear memory, no `CUDAArray`)*\n   - `from_pitch2d` — texture over a plain 2D pitched buffer *(ordinary linear memory, no `CUDAArray`)*\n\n   `ResourceDescriptor` binds `CUDA_RESOURCE_DESC`, a driver union whose `resType` is exactly one of\n   `ARRAY` / `MIPMAPPED_ARRAY` / `LINEAR` / `PITCH2D` — one factory per union arm. A faithful binding\n   of that type *must* cover all four; shipping only two would be an incomplete binding of a mandatory\n   driver struct, not a smaller-but-valid surface. So there was no real optionality here — the CTK\n   driver API dictates the set. (Listed only because it sat next to the genuine decisions.)\n\n   **Resolution: ship all four factories — required by the driver API, not a tradeoff.**\n\n4. **Channel format. ✅ Decided — keep the folded `format` + `num_channels` parameters.**\n\n   Each array element has a component type (e.g. 8-bit uint, 32-bit float) and a channel count\n   (1 = grayscale … 4 = RGBA). Two ways to surface that:\n   - **Folded (this PR):** `CUDAArray.from_descriptor(shape=..., format=ArrayFormat.FLOAT32, num_channels=4)`\n   - **Separate (CuPy):** one `ChannelFormatDescriptor(...)` object passed as a unit\n\n   The driver descriptor `cuda.core` actually fills in (`CUDA_ARRAY3D_DESCRIPTOR`) already stores\n   these as two separate fields — `Format` (a `CUarray_format`, mirrored 1:1 by `ArrayFormat`) and\n   `NumChannels`. So the folded form maps straight onto the driver struct with no translation, and\n   read-back is already exposed as two properties (`.format`, `.num_channels`). The bundled\n   `ChannelFormatDescriptor` is the *runtime* API's (`cudaChannelFormatDesc`) modeling — the form\n   CuPy wraps because its texture module sits on the runtime API. Adopting it in a driver-based\n   library would mean a translation wrapper the underlying API doesn't use (and the shapes don't even\n   map cleanly: the driver uses one uniform component format × channel count, while\n   `cudaChannelFormatDesc` allows per-channel bit widths).\n\n   **Resolution: keep folded `format` + `num_channels`.** It's the driver-faithful surface\n   (consistent with #1 favoring correctness over CuPy parity and #3 following the driver API); the\n   bundled form's only wins are CuPy look-alike and a single read-back object, neither worth a\n   runtime-style wrapper here.\n\n5. **Descriptor type consistency. ✅ Not a real decision — divergence is intentional and harmless.**\n\n   *Note: the original framing here was factually wrong.* `ResourceDescriptor` is **not** a `cdef\n   class` and holds **no** native C struct — it is a plain Python class with `__slots__`, storing a\n   reference to the backing resource plus a few Python fields. The `CUDA_RESOURCE_DESC` struct is\n   assembled later, in `TextureObject.from_descriptor`. So this was never a `@dataclass`-vs-`cdef\n   class` / performance question. Both descriptors are pure Python.\n\n   The genuine difference is only *how you construct each*, and it reflects what each type is:\n   - `TextureDescriptor` — a flat bag of independent sampling settings, built directly with keyword\n     args (`@dataclass` fits perfectly).\n   - `ResourceDescriptor` — a \"pick exactly one of four backings\" union (array / mipmap / linear /\n     pitch2d), built via `from_*` factories because each kind carries different fields. A single\n     `__init__` would be a pile of mutually-exclusive optional args plus a kind tag.\n\n   Consistency is not a goal in itself — it only matters when inconsistency makes the API harder to\n   learn or use, and here it doesn't: a user learns each type once and never has to reconcile them.\n   The only behavioral gap is equality (`TextureDescriptor` compares by value; `ResourceDescriptor`\n   by identity), which is essentially never exercised on these objects and is arguably correct since\n   `ResourceDescriptor` wraps a live device resource. Forcing both to the same *kind* of type would\n   be uniformity for its own sake and would make `ResourceDescriptor`'s constructor worse.\n\n   **Resolution: keep the split — the divergence is intentional and does not hurt usability.** Like\n   #3, this resolves to a non-issue once examined (and on a mistaken premise to begin with).\n\n6. **Bool naming. ✅ Decided — adopt the `is_\u003csomething>` convention.**\n\n   `surface_load_store` is a boolean on `Array`: it records whether the array was created with the\n   surface load/store capability (CUDA's `CUDA_ARRAY3D_SURFACE_LDST`), which a `SurfaceObject`\n   requires. Exposed both as a constructor keyword (`surface_load_store=True`) and a read-only\n   property (`arr.surface_load_store`).\n\n   The repo convention for boolean properties is `is_\u003csomething>`, so a property named\n   `surface_load_store` doesn't read as a boolean the way `arr.is_managed` does. **Resolution: rename\n   the property to follow the `is_\u003cx>` convention (e.g. `is_surface_load_store`) for consistency with\n   the cuda-python codebase.**\n\n   **Open detail resolved:** the property name is `is_surface_load_store` (already implemented), and\n   the constructor keyword is renamed to match — `from_descriptor(..., is_surface_load_store=False)` —\n   so one symmetric name serves both set and read-back. This follows the existing\n   `StridedMemoryView(is_readonly=...)` precedent in cuda.core, where an `is_\u003cx>` boolean is used as\n   both the constructor argument and the attribute. (The keyword rename is a small implementation\n   follow-up in the PR; the property is already done.)\n\n7. **Scope. ✅ Decided — split the examples into a follow-up PR.**\n\n   The nine `gl_interop_*.py` examples (~5k lines, not CI-wired, need a GL context CI lacks) are\n   orthogonal to the core API. **Resolution: drop them from this PR and land them in a separate\n   follow-up PR once this core texture/surface PR merges**, since the examples depend on the new API\n   it introduces.\n\n\n\n\n\n\n\n","author":{"url":"https://github.com/rparolin","@type":"Person","name":"rparolin"},"datePublished":"2026-06-09T23:04:40Z","url":"https://github.com/NVIDIA/cuda-python/issues/2188"}