-
Notifications
You must be signed in to change notification settings - Fork 649
api: add image_span, deprecate image_view #4703
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
api: add image_span, deprecate image_view #4703
Conversation
|
Related design question: By adding new span- and image_span-based equivalents for many utility functions we have that currently take raw pointers and lengths, we have the opportunity to change some design decisions because it's not a backward compatibility break. In particular, we regrettably have some functions that look like
Thoughts? |
* `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 <[email protected]>
Signed-off-by: Larry Gritz <[email protected]>
api(imageio.h): Add span/image_span functions * span convert_pixel_values * image_span convert_image and parallel_convert_image Signed-off-by: Larry Gritz <[email protected]>
1faa4cf to
9f668c7
Compare
|
Any comments on this? If anybody has objections or comments on the basic design of In this PR, I'm just proposing the image_span itself and using it in a few trivial ways with some utility functions that previously took raw pointers and dimensions. The next step, which I have ready to follow, is adding image_span based versions of core ImageOutput methods, which is really what's going to affect user APIs. |
|
This has been lingering for 2 weeks, plus mention at 1 or maybe 2 TSC meetings. In the absence of any objections, I will merge this by the end of the weekend and move on to the next piece of this puzzle that is queued up. |
EmilDohne
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Havent had time to look into it deeply as im out on holiday this month but I like this and think its the right direction!
src/include/OpenImageIO/image_span.h
Outdated
| /// Note that the optional template parameter `Rank` includes the channels as | ||
| /// the first dimension. When no Rank template parameter is provided, it | ||
| /// defaults to 4, meaning it's an image span that can describe any choice of | ||
| /// a scanline, 2D image, or volume. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[nit] associate these woth their respective tparam values 2, 3, 4 just to make the concept easier to understand
Signed-off-by: Larry Gritz <[email protected]>
Signed-off-by: Larry Gritz <[email protected]>
…4703) * `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 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 only in practice. The templating by rank allows future expansion to describe one scanline (rank 2) or 2D image plane (Rank 3) 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(), contiguize(), convert_pixel_values(), convert_image(), and parallel_convert_image() 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 <[email protected]> Signed-off-by: Scott Wilson <[email protected]>
…4703) * `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 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 only in practice. The templating by rank allows future expansion to describe one scanline (rank 2) or 2D image plane (Rank 3) 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(), contiguize(), convert_pixel_values(), convert_image(), and parallel_convert_image() 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 <[email protected]> Signed-off-by: Scott Wilson <[email protected]>
…4703) * `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 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 only in practice. The templating by rank allows future expansion to describe one scanline (rank 2) or 2D image plane (Rank 3) 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(), contiguize(), convert_pixel_values(), convert_image(), and parallel_convert_image() 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 <[email protected]>
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 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 only in practice. The templating by rank allows future expansion to describe one scanline (rank 2) or 2D image plane (Rank 3) 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(), contiguize(), convert_pixel_values(), convert_image(), and parallel_convert_image() 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.