Skip to content

Commit 16940d7

Browse files
committed
cuda.core.texture: address API-review follow-ups (NVIDIA#2292)
Apply the review findings from the texture API-style follow-up: - Rename TextureObject.texture_descriptor -> options (and the internal _texture_desc slot -> _options) to drop the borrowed "descriptor" naming, matching the TextureObjectOptions rename. - Make options a required argument on create_opaque_array / create_mipmapped_array (shape/format/num_channels have no defaults), so omitting it raises a clear error instead of a raw dataclass TypeError. create_texture_object keeps options=None (all-default sampling state). - Add return and resource/options type annotations to the four Device.create_* texture factories via a TYPE_CHECKING texture import (mirroring the existing GraphBuilder pattern). - Clarify in the create_* docstrings that the resource is created in the current CUDA context (call set_current first), mirroring create_stream / create_event. - Add versionadded:: 1.1.0 to OpaqueArrayOptions, MipmappedArrayOptions, TextureObjectOptions, and the new options property. - Fix a stale negative-path test whose regex no longer matched the shared check_or_create_options message; rename stale from_descriptor test names to create_*; realign the gl_interop_fluid API-MAP comment table after the enum renames. - Regenerate .pyi stubs.
1 parent 0767000 commit 16940d7

11 files changed

Lines changed: 97 additions & 53 deletions

File tree

‎cuda_core/cuda/core/_device.pyi‎

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ from cuda.core._memory._buffer import Buffer, MemoryResource
1212
from cuda.core._stream import IsStreamType, Stream
1313
from cuda.core._utils.cuda_utils import ComputeCapability
1414
from cuda.core.graph import GraphBuilder
15+
from cuda.core.texture import (MipmappedArray, MipmappedArrayOptions,
16+
OpaqueArray, OpaqueArrayOptions,
17+
ResourceDescriptor, SurfaceObject,
18+
TextureObject, TextureObjectOptions)
1519

1620

1721
class DeviceProperties:
@@ -910,12 +914,13 @@ class Device:
910914
911915
"""
912916

913-
def create_opaque_array(self, options: object=None):
914-
"""Create an :obj:`~cuda.core.texture.OpaqueArray` on this device.
917+
def create_opaque_array(self, options: OpaqueArrayOptions) -> OpaqueArray:
918+
"""Create an :obj:`~cuda.core.texture.OpaqueArray` on the current device.
915919
916920
Allocates an opaque, hardware-laid-out CUDA array for texture/surface
917-
access. The array is bound to the device/context that is current at
918-
construction.
921+
access. The array is created in the current CUDA context, so make this
922+
device current with :meth:`set_current` before calling (mirroring
923+
:meth:`create_stream` / :meth:`create_event`).
919924
920925
Note
921926
----
@@ -934,12 +939,13 @@ class Device:
934939
.. versionadded:: 1.1.0
935940
"""
936941

937-
def create_mipmapped_array(self, options: object=None):
938-
"""Create a :obj:`~cuda.core.texture.MipmappedArray` on this device.
942+
def create_mipmapped_array(self, options: MipmappedArrayOptions) -> MipmappedArray:
943+
"""Create a :obj:`~cuda.core.texture.MipmappedArray` on the current device.
939944
940945
Allocates a mipmapped CUDA array for texture/surface access across
941-
levels. The array is bound to the device/context that is current at
942-
construction.
946+
levels. The array is created in the current CUDA context, so make this
947+
device current with :meth:`set_current` before calling (mirroring
948+
:meth:`create_stream` / :meth:`create_event`).
943949
944950
Note
945951
----
@@ -958,15 +964,16 @@ class Device:
958964
.. versionadded:: 1.1.0
959965
"""
960966

961-
def create_texture_object(self, *, resource, options: object=None):
962-
"""Create a :obj:`~cuda.core.texture.TextureObject` on this device.
967+
def create_texture_object(self, *, resource: ResourceDescriptor, options: TextureObjectOptions | None=None) -> TextureObject:
968+
"""Create a :obj:`~cuda.core.texture.TextureObject` on the current device.
963969
964970
Binds a resource (an :obj:`~cuda.core.texture.OpaqueArray` /
965971
:obj:`~cuda.core.texture.MipmappedArray` / linear or pitch2d
966972
:obj:`~cuda.core.Buffer`, wrapped in a
967973
:obj:`~cuda.core.texture.ResourceDescriptor`) as a bindless texture for
968-
kernel-side sampled reads. The object is bound to the device/context
969-
that is current at construction.
974+
kernel-side sampled reads. The object is created in the current CUDA
975+
context, so make this device current with :meth:`set_current` before
976+
calling (mirroring :meth:`create_stream` / :meth:`create_event`).
970977
971978
Note
972979
----
@@ -987,14 +994,16 @@ class Device:
987994
.. versionadded:: 1.1.0
988995
"""
989996

990-
def create_surface_object(self, *, resource):
991-
"""Create a :obj:`~cuda.core.texture.SurfaceObject` on this device.
997+
def create_surface_object(self, *, resource: ResourceDescriptor) -> SurfaceObject:
998+
"""Create a :obj:`~cuda.core.texture.SurfaceObject` on the current device.
992999
9931000
Binds an :obj:`~cuda.core.texture.OpaqueArray` (via a
9941001
:obj:`~cuda.core.texture.ResourceDescriptor`) as a bindless surface for
9951002
kernel-side typed load/store. The backing array must have been created
996-
with ``is_surface_load_store=True``. The object is bound to the
997-
device/context that is current at construction.
1003+
with ``is_surface_load_store=True``. The object is created in the
1004+
current CUDA context, so make this device current with
1005+
:meth:`set_current` before calling (mirroring :meth:`create_stream` /
1006+
:meth:`create_event`).
9981007
9991008
Note
10001009
----

‎cuda_core/cuda/core/_device.pyx‎

Lines changed: 33 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,16 @@ from typing import TYPE_CHECKING
4444
if TYPE_CHECKING:
4545
import cuda.core.system # no-cython-lint
4646
from cuda.core.graph import GraphBuilder
47+
from cuda.core.texture import (
48+
MipmappedArray,
49+
MipmappedArrayOptions,
50+
OpaqueArray,
51+
OpaqueArrayOptions,
52+
ResourceDescriptor,
53+
SurfaceObject,
54+
TextureObject,
55+
TextureObjectOptions,
56+
)
4757

4858
# TODO: I prefer to type these as "cdef object" and avoid accessing them from within Python,
4959
# but it seems it is very convenient to expose them for testing purposes...
@@ -1456,12 +1466,13 @@ class Device:
14561466
self._check_context_initialized()
14571467
return GraphBuilder._init(self.create_stream())
14581468

1459-
def create_opaque_array(self, options: object = None):
1460-
"""Create an :obj:`~cuda.core.texture.OpaqueArray` on this device.
1469+
def create_opaque_array(self, options: OpaqueArrayOptions) -> OpaqueArray:
1470+
"""Create an :obj:`~cuda.core.texture.OpaqueArray` on the current device.
14611471

14621472
Allocates an opaque, hardware-laid-out CUDA array for texture/surface
1463-
access. The array is bound to the device/context that is current at
1464-
construction.
1473+
access. The array is created in the current CUDA context, so make this
1474+
device current with :meth:`set_current` before calling (mirroring
1475+
:meth:`create_stream` / :meth:`create_event`).
14651476

14661477
Note
14671478
----
@@ -1484,12 +1495,13 @@ class Device:
14841495
self._check_context_initialized()
14851496
return _create_opaque_array(options)
14861497

1487-
def create_mipmapped_array(self, options: object = None):
1488-
"""Create a :obj:`~cuda.core.texture.MipmappedArray` on this device.
1498+
def create_mipmapped_array(self, options: MipmappedArrayOptions) -> MipmappedArray:
1499+
"""Create a :obj:`~cuda.core.texture.MipmappedArray` on the current device.
14891500

14901501
Allocates a mipmapped CUDA array for texture/surface access across
1491-
levels. The array is bound to the device/context that is current at
1492-
construction.
1502+
levels. The array is created in the current CUDA context, so make this
1503+
device current with :meth:`set_current` before calling (mirroring
1504+
:meth:`create_stream` / :meth:`create_event`).
14931505

14941506
Note
14951507
----
@@ -1512,15 +1524,18 @@ class Device:
15121524
self._check_context_initialized()
15131525
return _create_mipmapped_array(options)
15141526

1515-
def create_texture_object(self, *, resource, options: object = None):
1516-
"""Create a :obj:`~cuda.core.texture.TextureObject` on this device.
1527+
def create_texture_object(
1528+
self, *, resource: ResourceDescriptor, options: TextureObjectOptions | None = None
1529+
) -> TextureObject:
1530+
"""Create a :obj:`~cuda.core.texture.TextureObject` on the current device.
15171531

15181532
Binds a resource (an :obj:`~cuda.core.texture.OpaqueArray` /
15191533
:obj:`~cuda.core.texture.MipmappedArray` / linear or pitch2d
15201534
:obj:`~cuda.core.Buffer`, wrapped in a
15211535
:obj:`~cuda.core.texture.ResourceDescriptor`) as a bindless texture for
1522-
kernel-side sampled reads. The object is bound to the device/context
1523-
that is current at construction.
1536+
kernel-side sampled reads. The object is created in the current CUDA
1537+
context, so make this device current with :meth:`set_current` before
1538+
calling (mirroring :meth:`create_stream` / :meth:`create_event`).
15241539

15251540
Note
15261541
----
@@ -1545,14 +1560,16 @@ class Device:
15451560
self._check_context_initialized()
15461561
return _create_texture_object(resource, options)
15471562

1548-
def create_surface_object(self, *, resource):
1549-
"""Create a :obj:`~cuda.core.texture.SurfaceObject` on this device.
1563+
def create_surface_object(self, *, resource: ResourceDescriptor) -> SurfaceObject:
1564+
"""Create a :obj:`~cuda.core.texture.SurfaceObject` on the current device.
15501565

15511566
Binds an :obj:`~cuda.core.texture.OpaqueArray` (via a
15521567
:obj:`~cuda.core.texture.ResourceDescriptor`) as a bindless surface for
15531568
kernel-side typed load/store. The backing array must have been created
1554-
with ``is_surface_load_store=True``. The object is bound to the
1555-
device/context that is current at construction.
1569+
with ``is_surface_load_store=True``. The object is created in the
1570+
current CUDA context, so make this device current with
1571+
:meth:`set_current` before calling (mirroring :meth:`create_stream` /
1572+
:meth:`create_event`).
15561573

15571574
Note
15581575
----

‎cuda_core/cuda/core/texture/_array.pyi‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ class OpaqueArrayOptions:
2727
If True, allocate with ``CUDA_ARRAY3D_SURFACE_LDST`` so the array can be
2828
bound as a :class:`~cuda.core.texture.SurfaceObject` for kernel-side
2929
writes. Default False.
30+
31+
.. versionadded:: 1.1.0
3032
"""
3133
shape: tuple[int, ...]
3234
format: object

‎cuda_core/cuda/core/texture/_array.pyx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,8 @@ class OpaqueArrayOptions:
154154
If True, allocate with ``CUDA_ARRAY3D_SURFACE_LDST`` so the array can be
155155
bound as a :class:`~cuda.core.texture.SurfaceObject` for kernel-side
156156
writes. Default False.
157+
158+
.. versionadded:: 1.1.0
157159
"""
158160

159161
shape: tuple[int, ...]

‎cuda_core/cuda/core/texture/_mipmapped_array.pyi‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ class MipmappedArrayOptions:
2828
levels (obtained via :meth:`MipmappedArray.get_level`) can be bound as
2929
a :class:`~cuda.core.texture.SurfaceObject` for kernel-side writes.
3030
Default False.
31+
32+
.. versionadded:: 1.1.0
3133
"""
3234
shape: tuple[int, ...]
3335
format: object

‎cuda_core/cuda/core/texture/_mipmapped_array.pyx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ class MipmappedArrayOptions:
5555
levels (obtained via :meth:`MipmappedArray.get_level`) can be bound as
5656
a :class:`~cuda.core.texture.SurfaceObject` for kernel-side writes.
5757
Default False.
58+
59+
.. versionadded:: 1.1.0
5860
"""
5961

6062
shape: tuple[int, ...]

‎cuda_core/cuda/core/texture/_texture.pxd‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ cdef class TextureObject:
1313
# structurally by the C++ box behind this handle, not by _source_ref.
1414
TexObjectHandle _handle
1515
object _source_ref # ResourceDescriptor, retained for introspection
16-
object _texture_desc # original TextureObjectOptions for introspection
16+
object _options # original TextureObjectOptions for introspection
1717
int _device_id
1818

1919
cpdef close(self)

‎cuda_core/cuda/core/texture/_texture.pyi‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,8 @@ class TextureObjectOptions:
164164
border_color : tuple of float or None
165165
4-tuple used when ``address_mode`` includes ``BORDER``; ``None`` means
166166
zero.
167+
168+
.. versionadded:: 1.1.0
167169
"""
168170
address_mode: AddressModeType | tuple[AddressModeType, ...] = AddressModeType.CLAMP
169171
filter_mode: FilterModeType = FilterModeType.POINT
@@ -213,8 +215,11 @@ class TextureObject:
213215
"""The :class:`ResourceDescriptor` this texture was built from."""
214216

215217
@property
216-
def texture_descriptor(self):
217-
"""The :class:`TextureObjectOptions` this texture was built from."""
218+
def options(self):
219+
"""The :class:`TextureObjectOptions` this texture was built from.
220+
221+
.. versionadded:: 1.1.0
222+
"""
218223

219224
@property
220225
def device(self):

‎cuda_core/cuda/core/texture/_texture.pyx‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -354,6 +354,8 @@ class TextureObjectOptions:
354354
border_color : tuple of float or None
355355
4-tuple used when ``address_mode`` includes ``BORDER``; ``None`` means
356356
zero.
357+
358+
.. versionadded:: 1.1.0
357359
"""
358360

359361
address_mode: AddressModeType | tuple[AddressModeType, ...] = AddressModeType.CLAMP
@@ -431,9 +433,12 @@ cdef class TextureObject:
431433
return self._source_ref
432434

433435
@property
434-
def texture_descriptor(self):
435-
"""The :class:`TextureObjectOptions` this texture was built from."""
436-
return self._texture_desc
436+
def options(self):
437+
"""The :class:`TextureObjectOptions` this texture was built from.
438+
439+
.. versionadded:: 1.1.0
440+
"""
441+
return self._options
437442

438443
@property
439444
def device(self):
@@ -578,6 +583,6 @@ def _create_texture_object(resource, options):
578583
cdef TextureObject self = TextureObject.__new__(TextureObject)
579584
self._handle = h
580585
self._source_ref = resource
581-
self._texture_desc = opts
586+
self._options = opts
582587
self._device_id = _get_current_device_id()
583588
return self

‎cuda_core/examples/gl_interop_fluid.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -401,10 +401,10 @@ def draw_fullscreen_quad(gl, shader_prog, vao_id, tex_id):
401401
# TextureObjectOptions / TextureObject / SurfaceObject knob in this example is set.
402402
# Each visible setting maps to a concrete piece of cuda.core / CUDA behavior:
403403
#
404-
# Device().create_opaque_array(OpaqueArrayOptions(...)) -> allocates a CUDA *array* (opaque, tiled
404+
# Device.create_opaque_array(...) -> allocates a CUDA *array* (opaque, tiled
405405
# layout optimized for 2D texture fetches),
406406
# not linear device memory.
407-
# ArrayFormatType.FLOAT32 -> each channel is a 32-bit float texel.
407+
# ArrayFormatType.FLOAT32 -> each channel is a 32-bit float texel.
408408
# num_channels=2 / num_channels=1 -> float2 (vx, vy) vs scalar (pressure /
409409
# divergence / dye); also fixes the
410410
# surf2Dwrite byte offset per element.
@@ -414,17 +414,17 @@ def draw_fullscreen_quad(gl, shader_prog, vao_id, tex_id):
414414
# is what lets each field be sampled and
415415
# then written back in the ping-pong.
416416
#
417-
# ResourceDescriptor.from_opaque_array(arr) -> wraps the OpaqueArray as the resource a
418-
# TextureObject reads from.
419-
# FilterModeType.LINEAR -> free HARDWARE bilinear interpolation;
417+
# ResourceDescriptor.from_opaque_array -> wraps the OpaqueArray as the resource a
418+
# TextureObject reads from.
419+
# FilterModeType.LINEAR -> free HARDWARE bilinear interpolation;
420420
# this is what makes semi-Lagrangian
421421
# advection a single tex2D fetch at a
422422
# fractional back-traced position (no
423423
# manual lerp, no neighbor gather).
424-
# AddressModeType.CLAMP -> bounded box boundary: out-of-range traces
424+
# AddressModeType.CLAMP -> bounded box boundary: out-of-range traces
425425
# read the edge texel (ink piles up at the
426426
# walls instead of wrapping like a torus).
427-
# ReadModeType.ELEMENT_TYPE -> return the stored float value as-is (no
427+
# ReadModeType.ELEMENT_TYPE -> return the stored float value as-is (no
428428
# integer->[0,1] normalization of texels).
429429
# normalized_coords=True -> sample in [0, 1) so CLAMP is well-defined
430430
# and texel centers are (i + 0.5) / N.

0 commit comments

Comments
 (0)