leofang
diff --git a/‎cuda_core/cuda/core/__init__.py‎
Lines changed: 4 additions & 0 deletions b/‎cuda_core/cuda/core/__init__.py‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎cuda_core/cuda/core/_cpp/resource_handles.cpp‎
Lines changed: 167 additions & 0 deletions b/‎cuda_core/cuda/core/_cpp/resource_handles.cpp‎
Lines changed: 167 additions & 0 deletions
diff --git a/‎cuda_core/cuda/core/_cpp/resource_handles.hpp‎
Lines changed: 128 additions & 0 deletions b/‎cuda_core/cuda/core/_cpp/resource_handles.hpp‎
Lines changed: 128 additions & 0 deletions
@@ -110,8 +110,12 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
 from cuda.core._tensor_map import TensorMapDescriptor, TensorMapDescriptorOptions
 
 # isort: split
+# Texture/surface types live under the cuda.core.texture namespace (not the
+# flat cuda.core namespace); import the subpackage so it is available as
+# `cuda.core.texture` after `import cuda.core`.
 # Must come after the cuda.core._* extension imports above: loading graph
 # earlier interacts badly with the merged-wheel __path__ rewrite and leaves
 # Graph/GraphBuilder/GraphCompleteOptions/GraphDebugPrintOptions missing from
 # cuda.core.graph.
 import cuda.core.graph
+import cuda.core.texture
@@ -77,6 +77,16 @@ decltype(&cuLinkDestroy) p_cuLinkDestroy = nullptr;
 decltype(&cuGraphicsUnmapResources) p_cuGraphicsUnmapResources = nullptr;
 decltype(&cuGraphicsUnregisterResource) p_cuGraphicsUnregisterResource = nullptr;
 
+decltype(&cuArray3DCreate) p_cuArray3DCreate = nullptr;
+decltype(&cuArrayDestroy) p_cuArrayDestroy = nullptr;
+decltype(&cuMipmappedArrayCreate) p_cuMipmappedArrayCreate = nullptr;
+decltype(&cuMipmappedArrayDestroy) p_cuMipmappedArrayDestroy = nullptr;
+decltype(&cuMipmappedArrayGetLevel) p_cuMipmappedArrayGetLevel = nullptr;
+decltype(&cuTexObjectCreate) p_cuTexObjectCreate = nullptr;
+decltype(&cuTexObjectDestroy) p_cuTexObjectDestroy = nullptr;
+decltype(&cuSurfObjectCreate) p_cuSurfObjectCreate = nullptr;
+decltype(&cuSurfObjectDestroy) p_cuSurfObjectDestroy = nullptr;
+
 // SM resource split (13.1+ — may be null on older drivers/bindings)
 #if CUDA_VERSION >= 13010
 decltype(&cuDevSmResourceSplit) p_cuDevSmResourceSplit = nullptr;
@@ -1337,6 +1347,163 @@ FileDescriptorHandle create_fd_handle_ref(int fd) {
 #endif
 }
 
+// ============================================================================
+// Array / mipmapped-array / texture / surface handles (PR #467)
+// ============================================================================
+
+namespace {
+struct ArrayBox {
+    CUarray resource;
+    // Non-null only for a mipmap-level view: keeps the parent mipmap (the real
+    // owner of the level's storage) alive for as long as the level is held.
+    MipmappedArrayHandle h_parent;
+};
+
+struct MipmappedArrayBox {
+    CUmipmappedArray resource;
+};
+
+struct TexObjectBox {
+    // Tagged so TexObjectHandle is a distinct C++ type from DevicePtrHandle /
+    // SurfObjectHandle (all wrap `unsigned long long`).
+    TexObjectValue resource;
+    // Type-erased backing dependency (OpaqueArrayHandle / MipmappedArrayHandle /
+    // DevicePtrHandle). The texture's resource is a union; we only need to keep
+    // whichever backing it was built from alive, never to dereference it.
+    std::shared_ptr<const void> h_backing;
+};
+
+struct SurfObjectBox {
+    SurfObjectValue resource;
+    OpaqueArrayHandle h_array;  // surfaces are always array-backed
+};
+}  // namespace
+
+OpaqueArrayHandle create_array_handle(const CUDA_ARRAY3D_DESCRIPTOR& desc) {
+    GILReleaseGuard gil;
+    CUarray arr;
+    if (CUDA_SUCCESS != (err = p_cuArray3DCreate(&arr, &desc))) {
+        return {};
+    }
+    // Allocation and adoption share the same owning lifetime; the only
+    // difference is who calls cuArray3DCreate. Delegate so the owning box and
+    // its destroy-on-last-ref deleter are defined in exactly one place.
+    return create_array_handle_owning(arr);
+}
+
+OpaqueArrayHandle create_array_handle_ref(CUarray arr) {
+    if (!arr) {
+        return {};
+    }
+    auto box = std::make_shared<const ArrayBox>(ArrayBox{arr, {}});
+    return OpaqueArrayHandle(box, &box->resource);
+}
+
+OpaqueArrayHandle create_array_handle_owning(CUarray arr) {
+    if (!arr) {
+        return {};
+    }
+    auto box = std::shared_ptr<const ArrayBox>(
+        new ArrayBox{arr, {}},
+        [](const ArrayBox* b) {
+            GILReleaseGuard gil;
+            p_cuArrayDestroy(b->resource);
+            delete b;
+        }
+    );
+    return OpaqueArrayHandle(box, &box->resource);
+}
+
+OpaqueArrayHandle create_array_level_handle(const MipmappedArrayHandle& h_mip, unsigned int level) {
+    GILReleaseGuard gil;
+    CUarray arr;
+    if (CUDA_SUCCESS != (err = p_cuMipmappedArrayGetLevel(&arr, as_cu(h_mip), level))) {
+        return {};
+    }
+    // Non-owning level view: storage belongs to the mipmap. Embed the mipmap
+    // handle so the parent outlives this level; the deleter does not destroy.
+    auto box = std::shared_ptr<const ArrayBox>(
+        new ArrayBox{arr, h_mip},
+        [](const ArrayBox* b) { delete b; }
+    );
+    return OpaqueArrayHandle(box, &box->resource);
+}
+
+MipmappedArrayHandle create_mipmapped_array_handle(const CUDA_ARRAY3D_DESCRIPTOR& desc,
+                                                   unsigned int num_levels) {
+    GILReleaseGuard gil;
+    CUmipmappedArray mip;
+    if (CUDA_SUCCESS != (err = p_cuMipmappedArrayCreate(&mip, &desc, num_levels))) {
+        return {};
+    }
+    auto box = std::shared_ptr<const MipmappedArrayBox>(
+        new MipmappedArrayBox{mip},
+        [](const MipmappedArrayBox* b) {
+            GILReleaseGuard gil;
+            p_cuMipmappedArrayDestroy(b->resource);
+            delete b;
+        }
+    );
+    return MipmappedArrayHandle(box, &box->resource);
+}
+
+namespace {
+TexObjectHandle make_tex_object_handle(const CUDA_RESOURCE_DESC& res,
+                                       const CUDA_TEXTURE_DESC& tex,
+                                       std::shared_ptr<const void> h_backing) {
+    GILReleaseGuard gil;
+    CUtexObject obj;
+    if (CUDA_SUCCESS != (err = p_cuTexObjectCreate(&obj, &res, &tex, nullptr))) {
+        return {};
+    }
+    auto box = std::shared_ptr<const TexObjectBox>(
+        new TexObjectBox{TexObjectValue{obj}, std::move(h_backing)},
+        [](const TexObjectBox* b) {
+            GILReleaseGuard gil;
+            p_cuTexObjectDestroy(b->resource.raw);
+            delete b;
+        }
+    );
+    return TexObjectHandle(box, &box->resource);
+}
+}  // namespace
+
+TexObjectHandle create_tex_object_handle_array(const CUDA_RESOURCE_DESC& res,
+                                               const CUDA_TEXTURE_DESC& tex,
+                                               const OpaqueArrayHandle& h_backing) {
+    return make_tex_object_handle(res, tex, h_backing);
+}
+
+TexObjectHandle create_tex_object_handle_mipmap(const CUDA_RESOURCE_DESC& res,
+                                                const CUDA_TEXTURE_DESC& tex,
+                                                const MipmappedArrayHandle& h_backing) {
+    return make_tex_object_handle(res, tex, h_backing);
+}
+
+TexObjectHandle create_tex_object_handle_linear(const CUDA_RESOURCE_DESC& res,
+                                                const CUDA_TEXTURE_DESC& tex,
+                                                const DevicePtrHandle& h_backing) {
+    return make_tex_object_handle(res, tex, h_backing);
+}
+
+SurfObjectHandle create_surf_object_handle(const CUDA_RESOURCE_DESC& res,
+                                           const OpaqueArrayHandle& h_backing) {
+    GILReleaseGuard gil;
+    CUsurfObject obj;
+    if (CUDA_SUCCESS != (err = p_cuSurfObjectCreate(&obj, &res))) {
+        return {};
+    }
+    auto box = std::shared_ptr<const SurfObjectBox>(
+        new SurfObjectBox{SurfObjectValue{obj}, h_backing},
+        [](const SurfObjectBox* b) {
+            GILReleaseGuard gil;
+            p_cuSurfObjectDestroy(b->resource.raw);
+            delete b;
+        }
+    );
+    return SurfObjectHandle(box, &box->resource);
+}
+
 // ============================================================================
 // SM resource split wrapper
 // ============================================================================
 
@@ -36,6 +36,14 @@ struct TaggedHandle {
 using NvvmProgramValue = TaggedHandle<nvvmProgram, 0>;
 using NvJitLinkValue = TaggedHandle<nvJitLink_t, 1>;
 
+// CUtexObject, CUsurfObject and CUdeviceptr are all `unsigned long long`, so
+// shared_ptr<const CUtexObject> et al. would be the *same* C++ type as
+// DevicePtrHandle (and each other), collapsing the as_cu/as_intptr/as_py
+// overload sets. Tag them to keep each handle type distinct, exactly as the
+// NVVM / nvJitLink handles above do.
+using TexObjectValue = TaggedHandle<CUtexObject, 2>;
+using SurfObjectValue = TaggedHandle<CUsurfObject, 3>;
+
 // ============================================================================
 // Thread-local error handling
 // ============================================================================
@@ -108,6 +116,17 @@ extern decltype(&cuLinkDestroy) p_cuLinkDestroy;
 extern decltype(&cuGraphicsUnmapResources) p_cuGraphicsUnmapResources;
 extern decltype(&cuGraphicsUnregisterResource) p_cuGraphicsUnregisterResource;
 
+// Texture / surface / array (PR #467)
+extern decltype(&cuArray3DCreate) p_cuArray3DCreate;
+extern decltype(&cuArrayDestroy) p_cuArrayDestroy;
+extern decltype(&cuMipmappedArrayCreate) p_cuMipmappedArrayCreate;
+extern decltype(&cuMipmappedArrayDestroy) p_cuMipmappedArrayDestroy;
+extern decltype(&cuMipmappedArrayGetLevel) p_cuMipmappedArrayGetLevel;
+extern decltype(&cuTexObjectCreate) p_cuTexObjectCreate;
+extern decltype(&cuTexObjectDestroy) p_cuTexObjectDestroy;
+extern decltype(&cuSurfObjectCreate) p_cuSurfObjectCreate;
+extern decltype(&cuSurfObjectDestroy) p_cuSurfObjectDestroy;
+
 // SM resource split (13.1+ — may be null on older drivers/bindings)
 #if CUDA_VERSION >= 13010
 extern decltype(&cuDevSmResourceSplit) p_cuDevSmResourceSplit;
@@ -171,6 +190,10 @@ using NvvmProgramHandle = std::shared_ptr<const NvvmProgramValue>;
 using NvJitLinkHandle = std::shared_ptr<const NvJitLinkValue>;
 using CuLinkHandle = std::shared_ptr<const CUlinkState>;
 using FileDescriptorHandle = std::shared_ptr<const int>;
+using OpaqueArrayHandle = std::shared_ptr<const CUarray>;
+using MipmappedArrayHandle = std::shared_ptr<const CUmipmappedArray>;
+using TexObjectHandle = std::shared_ptr<const TexObjectValue>;
+using SurfObjectHandle = std::shared_ptr<const SurfObjectValue>;
 
 
 // ============================================================================
@@ -530,6 +553,61 @@ FileDescriptorHandle create_fd_handle(int fd);
 // Create a non-owning file descriptor handle (caller manages the fd).
 FileDescriptorHandle create_fd_handle_ref(int fd);
 
+// ============================================================================
+// Array / mipmapped-array / texture / surface handle functions (PR #467)
+//
+// These resources are managed exactly like every other cuda.core resource:
+// the owning handle's deleter calls the matching cu*Destroy with the GIL
+// released, structural dependencies are embedded in the box (so a backing
+// resource always outlives a texture/surface/level built on it), and
+// creation returns an empty handle + thread-local error on failure.
+// ============================================================================
+
+// Create an owning CUDA array via cuArray3DCreate.
+// When the last reference is released, cuArrayDestroy is called automatically.
+// Returns empty handle on error (caller must check).
+OpaqueArrayHandle create_array_handle(const CUDA_ARRAY3D_DESCRIPTOR& desc);
+
+// Create a non-owning array handle (references an existing CUarray).
+// Use for arrays owned elsewhere (e.g. graphics interop). Never destroyed here.
+OpaqueArrayHandle create_array_handle_ref(CUarray arr);
+
+// Create an owning array handle adopting an existing CUarray.
+// When the last reference is released, cuArrayDestroy is called automatically.
+OpaqueArrayHandle create_array_handle_owning(CUarray arr);
+
+// Create a non-owning handle to a mipmap level via cuMipmappedArrayGetLevel.
+// The level CUarray is owned by the mipmap; the parent MipmappedArrayHandle is
+// embedded in the box so it outlives the level view. No destroy in the deleter.
+// Returns empty handle on error (caller must check).
+OpaqueArrayHandle create_array_level_handle(const MipmappedArrayHandle& h_mip, unsigned int level);
+
+// Create an owning mipmapped array via cuMipmappedArrayCreate.
+// When the last reference is released, cuMipmappedArrayDestroy is called.
+// Returns empty handle on error (caller must check).
+MipmappedArrayHandle create_mipmapped_array_handle(const CUDA_ARRAY3D_DESCRIPTOR& desc,
+                                                   unsigned int num_levels);
+
+// Create an owning texture object via cuTexObjectCreate, embedding the backing
+// resource handle (array / mipmapped array / linear-or-pitch2d device pointer)
+// so the backing always outlives the texture. cuTexObjectDestroy runs in the
+// deleter. Returns empty handle on error (caller must check).
+TexObjectHandle create_tex_object_handle_array(const CUDA_RESOURCE_DESC& res,
+                                               const CUDA_TEXTURE_DESC& tex,
+                                               const OpaqueArrayHandle& h_backing);
+TexObjectHandle create_tex_object_handle_mipmap(const CUDA_RESOURCE_DESC& res,
+                                                const CUDA_TEXTURE_DESC& tex,
+                                                const MipmappedArrayHandle& h_backing);
+TexObjectHandle create_tex_object_handle_linear(const CUDA_RESOURCE_DESC& res,
+                                                const CUDA_TEXTURE_DESC& tex,
+                                                const DevicePtrHandle& h_backing);
+
+// Create an owning surface object via cuSurfObjectCreate, embedding the backing
+// array handle so it outlives the surface. cuSurfObjectDestroy runs in the
+// deleter. Returns empty handle on error (caller must check).
+SurfObjectHandle create_surf_object_handle(const CUDA_RESOURCE_DESC& res,
+                                           const OpaqueArrayHandle& h_backing);
+
 // ============================================================================
 // Overloaded helper functions to extract raw resources from handles
 // ============================================================================
@@ -595,6 +673,24 @@ inline CUlinkState as_cu(const CuLinkHandle& h) noexcept {
     return h ? *h : nullptr;
 }
 
+inline CUarray as_cu(const OpaqueArrayHandle& h) noexcept {
+    return h ? *h : nullptr;
+}
+
+inline CUmipmappedArray as_cu(const MipmappedArrayHandle& h) noexcept {
+    return h ? *h : nullptr;
+}
+
+// CUtexObject / CUsurfObject are integer-valued (like CUdeviceptr); null is 0.
+// The raw value lives in the tagged wrapper's `raw` field.
+inline CUtexObject as_cu(const TexObjectHandle& h) noexcept {
+    return h ? h->raw : 0;
+}
+
+inline CUsurfObject as_cu(const SurfObjectHandle& h) noexcept {
+    return h ? h->raw : 0;
+}
+
 // as_intptr() - extract handle as intptr_t for Python interop
 // Using signed intptr_t per C standard convention and issue #1342
 inline std::intptr_t as_intptr(const ContextHandle& h) noexcept {
@@ -661,6 +757,22 @@ inline std::intptr_t as_intptr(const FileDescriptorHandle& h) noexcept {
     return h ? static_cast<std::intptr_t>(*h) : -1;
 }
 
+inline std::intptr_t as_intptr(const OpaqueArrayHandle& h) noexcept {
+    return reinterpret_cast<std::intptr_t>(as_cu(h));
+}
+
+inline std::intptr_t as_intptr(const MipmappedArrayHandle& h) noexcept {
+    return reinterpret_cast<std::intptr_t>(as_cu(h));
+}
+
+inline std::intptr_t as_intptr(const TexObjectHandle& h) noexcept {
+    return static_cast<std::intptr_t>(as_cu(h));
+}
+
+inline std::intptr_t as_intptr(const SurfObjectHandle& h) noexcept {
+    return static_cast<std::intptr_t>(as_cu(h));
+}
+
 // as_py() - convert handle to Python wrapper object (returns new reference)
 #if PY_VERSION_HEX < 0x030D0000
 extern "C" int _Py_IsFinalizing(void);
@@ -776,6 +888,22 @@ inline PyObject* as_py(const FileDescriptorHandle& h) noexcept {
     return PyLong_FromSsize_t(as_intptr(h));
 }
 
+inline PyObject* as_py(const OpaqueArrayHandle& h) noexcept {
+    return detail::make_py("cuda.bindings.driver", "CUarray", as_intptr(h));
+}
+
+inline PyObject* as_py(const MipmappedArrayHandle& h) noexcept {
+    return detail::make_py("cuda.bindings.driver", "CUmipmappedArray", as_intptr(h));
+}
+
+inline PyObject* as_py(const TexObjectHandle& h) noexcept {
+    return detail::make_py("cuda.bindings.driver", "CUtexObject", as_intptr(h));
+}
+
+inline PyObject* as_py(const SurfObjectHandle& h) noexcept {
+    return detail::make_py("cuda.bindings.driver", "CUsurfObject", as_intptr(h));
+}
+
 // ============================================================================
 // SM resource split wrapper (13.1+)
 //