Skip to content

Commit 2227a96

Browse files
committed
api: add image_span, deprecate image_view
* `image_span<T,Rank>` is a 2D-to-4D bounded span with byte-measured strides (describing data layout with dimensions for channel, x, y, z) for us to have future APIs deal with bounded+strided regions rather than YOLOing raw pointers. Among other advantages, image_span will have robust bounds checking in debug builds. It also simplifies interfaces to pass a single image_span that encapsulates everything about an up-to-4D data layout, rather than needing to pass a function a long list of individual pointers, sizes, and strides. * I've templated image_span on Rank, but default to Rank=4 and am using that version. The templating allows future expansion to describe one scanline (2D) or image plane (3D) if we want to do so for certain API calls, but I'm not sure yet whether to bother with that, so for now, the ability to template by Rank is just flexibility for the future. * Add image_span based versions of copy_image() and contiguize() utilities. I added tests and benchmarks to verify their correctness and that they have similar performance to the pointer based versions. * Deprecate image_view, which we did not ever use internally to OIIO or in its APIs. But since we published the headers, there's a chance it's used downstream and would be unwise to change its behavior or data layout. The new image_span is what we will use moving forward so that we are free to modify it and start with a fresh slate. Keeping the definition/header for now, but marking it with a deprecation warning. Signed-off-by: Larry Gritz <lg@larrygritz.com>
1 parent 3b69478 commit 2227a96

9 files changed

Lines changed: 809 additions & 64 deletions

File tree

src/doc/imageioapi.rst

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,8 +95,8 @@ Efficient unique strings: ``ustring``
9595
9696
.. _sec-span:
9797

98-
Non-owning array views: ``span`` / ``cspan``
99-
============================================
98+
Non-owning contiguous array views: ``span`` / ``cspan``
99+
=======================================================
100100

101101
.. doxygenclass:: OIIO::span
102102
:members:
@@ -111,6 +111,18 @@ Additionally, there is a convenience template:
111111
|
112112
113113

114+
.. _sec-span:
115+
116+
Non-owning image array views: ``image_span``
117+
============================================
118+
119+
.. doxygenclass:: OIIO::image_span
120+
:members:
121+
122+
123+
|
124+
125+
114126

115127
.. _sec-ROI:
116128

0 commit comments

Comments
 (0)