From 6ab9b6037d6516b771a8479cd0cbc3720a9cecf2 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Tue, 10 Dec 2024 14:49:18 +0000 Subject: [PATCH] Add x, y, and z shorthands to id and range classes The numbering of dimensions in SYCL is aligned with the numbering of dimensions in ISO C++, such that the highest-numbered dimension is the fastest-moving. This numbering is inconvenient when working with generic functions compatible with one-, two-, or three-dimensional ranges, since developers must account somehow for differences in the numbering of the dimensions. One common solution is to define helper functions called x(), y() and z() to encapsulate this logic. This solution can also assist with the migration of code from other languages (e.g., OpenCL and CUDA), and may provide a simpler mental model for SYCL developers working with images or other forms of graphics interop. This commit adds x(), y() and z() functions directly to the id and range classes, providing a consistent way for SYCL developers to use this indexing pattern, rather than relying on each SYCL code base to define and maintain compatible index abstractions. --- adoc/chapters/programming_interface.adoc | 48 ++++++++++++++++++++++++ adoc/headers/id.h | 4 ++ adoc/headers/range.h | 4 ++ 3 files changed, 56 insertions(+) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 1418e45f..4e437e86 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -11977,6 +11977,30 @@ size_t operator[](int dimension) const a@ Return the value of the specified dimension of the [code]#range#. +a@ +[source] +---- +size_t x() const noexcept; +---- + a@ Return the value of dimension [code]#Dimensions - 1# of the [code]#range# + object. + +a@ +[source] +---- +size_t y() const noexcept; +---- + a@ Return the value of dimension [code]#Dimensions - 2# of the [code]#range# + object, or 1 if [code]#Dimensions < 2#. + +a@ +[source] +---- +size_t z() const noexcept; +---- + a@ Return the value of dimension [code]#Dimensions - 3# of the [code]#range# + object, or 1 if [code]#Dimensions < 3#. + a@ [source] ---- @@ -12322,6 +12346,30 @@ size_t operator[](int dimension) const a@ Return the value of the requested dimension of the [code]#id# object. +a@ +[source] +---- +size_t x() const noexcept; +---- + a@ Return the value of dimension [code]#Dimensions - 1# of the [code]#id# + object. + +a@ +[source] +---- +size_t y() const noexcept; +---- + a@ Return the value of dimension [code]#Dimensions - 2# of the [code]#id# + object, or 1 if [code]#Dimensions < 2#. + +a@ +[source] +---- +size_t z() const noexcept; +---- + a@ Return the value of dimension [code]#Dimensions - 3# of the [code]#id# + object, or 1 if [code]#Dimensions < 3#. + a@ [source] ---- diff --git a/adoc/headers/id.h b/adoc/headers/id.h index 65bbe0b2..6bb89cb0 100644 --- a/adoc/headers/id.h +++ b/adoc/headers/id.h @@ -27,6 +27,10 @@ template class id { size_t& operator[](int dimension); size_t operator[](int dimension) const; + size_t x() const noexcept; + size_t y() const noexcept; + size_t z() const noexcept; + // only available if Dimensions == 1 operator size_t() const; diff --git a/adoc/headers/range.h b/adoc/headers/range.h index abe664e9..10d34d78 100644 --- a/adoc/headers/range.h +++ b/adoc/headers/range.h @@ -24,6 +24,10 @@ template class range { size_t& operator[](int dimension); size_t operator[](int dimension) const; + size_t x() const noexcept; + size_t y() const noexcept; + size_t z() const noexcept; + size_t size() const; // OP is: +, -, *, /, %, <<, >>, &, |, ^, &&, ||, <, >, <=, >=