Skip to content

Commit fa7cb36

Browse files
Andy-JostAndy-Jost
committed
cuda.core.texture: add versionadded markers and widen enum str annotations
Address review feedback (Ralf): - Add ``.. versionadded:: 1.1.0`` to the four new texture enums in typing.py (ArrayFormatType, AddressModeType, FilterModeType, ReadModeType) and to the texture classes that lacked a class-level marker (ResourceDescriptor, TextureObject, OpaqueArray, MipmappedArray, SurfaceObject). Remove the redundant method-level markers now covered at class level. - Widen the enum-bearing TextureObjectOptions field annotations to include ``str`` (address_mode, filter_mode, read_mode, mipmap_filter_mode), matching the runtime string coercion this PR adds and existing convention elsewhere in cuda.core. Note "Plain strings are accepted" on the affected fields. - Regenerate .pyi stubs.
1 parent 7afd188 commit fa7cb36

9 files changed

Lines changed: 50 additions & 36 deletions

File tree

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

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ class OpaqueArray:
5858
Construct via :meth:`cuda.core.Device.create_opaque_array`. Only plain
5959
1D/2D/3D allocations are supported in this initial version; layered/cubemap/
6060
sparse variants will follow once their shape semantics are settled.
61+
62+
.. versionadded:: 1.1.0
6163
"""
6264

6365
def close(self):
@@ -100,10 +102,7 @@ class OpaqueArray:
100102

101103
@property
102104
def element_bytes(self):
103-
"""Bytes per element (format size * channels).
104-
105-
.. versionadded:: 1.1.0
106-
"""
105+
"""Bytes per element (format size * channels)."""
107106

108107
@property
109108
def device(self):

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

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -336,6 +336,8 @@ cdef class OpaqueArray:
336336
Construct via :meth:`cuda.core.Device.create_opaque_array`. Only plain
337337
1D/2D/3D allocations are supported in this initial version; layered/cubemap/
338338
sparse variants will follow once their shape semantics are settled.
339+
340+
.. versionadded:: 1.1.0
339341
"""
340342

341343
def __init__(self, *args, **kwargs):
@@ -384,10 +386,7 @@ cdef class OpaqueArray:
384386

385387
@property
386388
def element_bytes(self):
387-
"""Bytes per element (format size * channels).
388-
389-
.. versionadded:: 1.1.0
390-
"""
389+
"""Bytes per element (format size * channels)."""
391390
return _FORMAT_ELEM_SIZE[self._format] * self._num_channels
392391

393392
@property

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ class MipmappedArray:
5151
are non-owning and hold a strong reference back to their parent.
5252
5353
Construct via :meth:`cuda.core.Device.create_mipmapped_array`.
54+
55+
.. versionadded:: 1.1.0
5456
"""
5557

5658
def close(self):

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,8 @@ cdef class MipmappedArray:
8484
are non-owning and hold a strong reference back to their parent.
8585
8686
Construct via :meth:`cuda.core.Device.create_mipmapped_array`.
87+
88+
.. versionadded:: 1.1.0
8789
"""
8890

8991
def __init__(self, *args, **kwargs):

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ class SurfaceObject:
1616
1717
Construct via :meth:`cuda.core.Device.create_surface_object`. Passes to
1818
kernels as a 64-bit handle (via the ``handle`` property).
19+
20+
.. versionadded:: 1.1.0
1921
"""
2022

2123
def close(self):

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ cdef class SurfaceObject:
3535
3636
Construct via :meth:`cuda.core.Device.create_surface_object`. Passes to
3737
kernels as a 64-bit handle (via the ``handle`` property).
38+
39+
.. versionadded:: 1.1.0
3840
"""
3941

4042
def __init__(self, *args, **kwargs):

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

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ class ResourceDescriptor:
2525
2626
Linear and pitch2D resources cannot back a :class:`SurfaceObject` — those
2727
require an :class:`OpaqueArray` allocated with ``is_surface_load_store=True``.
28+
29+
.. versionadded:: 1.1.0
2830
"""
2931
__slots__ = ('_kind', '_source', '_format', '_num_channels', '_size_bytes', '_width', '_height', '_pitch_bytes')
3032

@@ -33,10 +35,7 @@ class ResourceDescriptor:
3335

3436
@classmethod
3537
def from_opaque_array(cls, array):
36-
"""Build a resource descriptor backed by a :class:`OpaqueArray`.
37-
38-
.. versionadded:: 1.1.0
39-
"""
38+
"""Build a resource descriptor backed by a :class:`OpaqueArray`."""
4039

4140
@classmethod
4241
def from_mipmapped_array(cls, mipmapped_array):
@@ -143,9 +142,10 @@ class TextureObjectOptions:
143142
:class:`~cuda.core.typing.AddressModeType` (applied to all axes) or a
144143
tuple of 1-3 entries (one per dimension). Plain strings are accepted.
145144
filter_mode : FilterModeType
146-
Texel sampling mode. Default ``POINT``.
145+
Texel sampling mode. Default ``POINT``. Plain strings are accepted.
147146
read_mode : ReadModeType
148147
How sampled integer values are returned. Default ``ELEMENT_TYPE``.
148+
Plain strings are accepted.
149149
normalized_coords : bool
150150
If True, coordinates are in ``[0, 1]`` instead of pixel indices.
151151
srgb : bool
@@ -157,7 +157,8 @@ class TextureObjectOptions:
157157
max_anisotropy : int
158158
Maximum anisotropy; 0 disables anisotropic filtering.
159159
mipmap_filter_mode : FilterModeType
160-
Filtering between mipmap levels. Default ``POINT``.
160+
Filtering between mipmap levels. Default ``POINT``. Plain strings are
161+
accepted.
161162
mipmap_level_bias : float
162163
min_mipmap_level_clamp : float
163164
max_mipmap_level_clamp : float
@@ -167,15 +168,15 @@ class TextureObjectOptions:
167168
168169
.. versionadded:: 1.1.0
169170
"""
170-
address_mode: AddressModeType | tuple[AddressModeType, ...] = AddressModeType.CLAMP
171-
filter_mode: FilterModeType = FilterModeType.POINT
172-
read_mode: ReadModeType = ReadModeType.ELEMENT_TYPE
171+
address_mode: AddressModeType | str | tuple[AddressModeType | str, ...] = AddressModeType.CLAMP
172+
filter_mode: FilterModeType | str = FilterModeType.POINT
173+
read_mode: ReadModeType | str = ReadModeType.ELEMENT_TYPE
173174
normalized_coords: bool = False
174175
srgb: bool = False
175176
disable_trilinear_optimization: bool = False
176177
seamless_cubemap: bool = False
177178
max_anisotropy: int = 0
178-
mipmap_filter_mode: FilterModeType = FilterModeType.POINT
179+
mipmap_filter_mode: FilterModeType | str = FilterModeType.POINT
179180
mipmap_level_bias: float = 0.0
180181
min_mipmap_level_clamp: float = 0.0
181182
max_mipmap_level_clamp: float = 0.0
@@ -193,6 +194,8 @@ class TextureObject:
193194
194195
Construct via :meth:`cuda.core.Device.create_texture_object`. Passes to
195196
kernels as a 64-bit handle (via the ``handle`` property).
197+
198+
.. versionadded:: 1.1.0
196199
"""
197200

198201
def close(self):
@@ -216,10 +219,7 @@ class TextureObject:
216219

217220
@property
218221
def options(self):
219-
"""The :class:`TextureObjectOptions` this texture was built from.
220-
221-
.. versionadded:: 1.1.0
222-
"""
222+
"""The :class:`TextureObjectOptions` this texture was built from."""
223223

224224
@property
225225
def device(self):

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

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,8 @@ class ResourceDescriptor:
9090
9191
Linear and pitch2D resources cannot back a :class:`SurfaceObject` — those
9292
require an :class:`OpaqueArray` allocated with ``is_surface_load_store=True``.
93+
94+
.. versionadded:: 1.1.0
9395
"""
9496

9597
__slots__ = (
@@ -107,10 +109,7 @@ class ResourceDescriptor:
107109

108110
@classmethod
109111
def from_opaque_array(cls, array):
110-
"""Build a resource descriptor backed by a :class:`OpaqueArray`.
111-
112-
.. versionadded:: 1.1.0
113-
"""
112+
"""Build a resource descriptor backed by a :class:`OpaqueArray`."""
114113
if not isinstance(array, OpaqueArray):
115114
raise TypeError(f"array must be a OpaqueArray, got {type(array).__name__}")
116115
self = cls.__new__(cls)
@@ -333,9 +332,10 @@ class TextureObjectOptions:
333332
:class:`~cuda.core.typing.AddressModeType` (applied to all axes) or a
334333
tuple of 1-3 entries (one per dimension). Plain strings are accepted.
335334
filter_mode : FilterModeType
336-
Texel sampling mode. Default ``POINT``.
335+
Texel sampling mode. Default ``POINT``. Plain strings are accepted.
337336
read_mode : ReadModeType
338337
How sampled integer values are returned. Default ``ELEMENT_TYPE``.
338+
Plain strings are accepted.
339339
normalized_coords : bool
340340
If True, coordinates are in ``[0, 1]`` instead of pixel indices.
341341
srgb : bool
@@ -347,7 +347,8 @@ class TextureObjectOptions:
347347
max_anisotropy : int
348348
Maximum anisotropy; 0 disables anisotropic filtering.
349349
mipmap_filter_mode : FilterModeType
350-
Filtering between mipmap levels. Default ``POINT``.
350+
Filtering between mipmap levels. Default ``POINT``. Plain strings are
351+
accepted.
351352
mipmap_level_bias : float
352353
min_mipmap_level_clamp : float
353354
max_mipmap_level_clamp : float
@@ -358,15 +359,15 @@ class TextureObjectOptions:
358359
.. versionadded:: 1.1.0
359360
"""
360361

361-
address_mode: AddressModeType | tuple[AddressModeType, ...] = AddressModeType.CLAMP
362-
filter_mode: FilterModeType = FilterModeType.POINT
363-
read_mode: ReadModeType = ReadModeType.ELEMENT_TYPE
362+
address_mode: AddressModeType | str | tuple[AddressModeType | str, ...] = AddressModeType.CLAMP
363+
filter_mode: FilterModeType | str = FilterModeType.POINT
364+
read_mode: ReadModeType | str = ReadModeType.ELEMENT_TYPE
364365
normalized_coords: bool = False
365366
srgb: bool = False
366367
disable_trilinear_optimization: bool = False
367368
seamless_cubemap: bool = False
368369
max_anisotropy: int = 0
369-
mipmap_filter_mode: FilterModeType = FilterModeType.POINT
370+
mipmap_filter_mode: FilterModeType | str = FilterModeType.POINT
370371
mipmap_level_bias: float = 0.0
371372
min_mipmap_level_clamp: float = 0.0
372373
max_mipmap_level_clamp: float = 0.0
@@ -414,6 +415,8 @@ cdef class TextureObject:
414415
415416
Construct via :meth:`cuda.core.Device.create_texture_object`. Passes to
416417
kernels as a 64-bit handle (via the ``handle`` property).
418+
419+
.. versionadded:: 1.1.0
417420
"""
418421

419422
def __init__(self, *args, **kwargs):
@@ -434,10 +437,7 @@ cdef class TextureObject:
434437

435438
@property
436439
def options(self):
437-
"""The :class:`TextureObjectOptions` this texture was built from.
438-
439-
.. versionadded:: 1.1.0
440-
"""
440+
"""The :class:`TextureObjectOptions` this texture was built from."""
441441
return self._options
442442

443443
@property

‎cuda_core/cuda/core/typing.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -232,6 +232,8 @@ class ArrayFormatType(StrEnum):
232232
* ``UINT8`` / ``UINT16`` / ``UINT32`` — unsigned integer elements.
233233
* ``INT8`` / ``INT16`` / ``INT32`` — signed integer elements.
234234
* ``FLOAT16`` / ``FLOAT32`` — half- and single-precision float elements.
235+
236+
.. versionadded:: 1.1.0
235237
"""
236238

237239
UINT8 = "uint8"
@@ -253,6 +255,8 @@ class AddressModeType(StrEnum):
253255
* ``CLAMP`` — clamp to the edge texel.
254256
* ``MIRROR`` — reflect coordinates at the boundary.
255257
* ``BORDER`` — return the configured border color.
258+
259+
.. versionadded:: 1.1.0
256260
"""
257261

258262
WRAP = "wrap"
@@ -268,6 +272,8 @@ class FilterModeType(StrEnum):
268272
269273
* ``POINT`` — nearest-texel sampling.
270274
* ``LINEAR`` — (bi/tri)linear interpolation.
275+
276+
.. versionadded:: 1.1.0
271277
"""
272278

273279
POINT = "point"
@@ -282,6 +288,8 @@ class ReadModeType(StrEnum):
282288
* ``NORMALIZED_FLOAT`` — integer formats are promoted to a normalized
283289
``float`` in ``[0, 1]`` (unsigned) or ``[-1, 1]`` (signed). Float
284290
formats are unaffected.
291+
292+
.. versionadded:: 1.1.0
285293
"""
286294

287295
ELEMENT_TYPE = "element_type"

0 commit comments

Comments
 (0)