From b462ecf1f3f86ee04b7083524bf4fa41696414e8 Mon Sep 17 00:00:00 2001 From: Samaresh Kumar Singh Date: Fri, 3 Apr 2026 19:35:24 -0500 Subject: [PATCH 1/2] Add sycl::convert free function as scalar equivalent of vec::convert vec::convert supports explicit rounding modes but there was no way to do the same for scalar types. This adds a sycl::convert(value) free function and documents it in a new section alongside the updated rounding modes table. --- adoc/chapters/programming_interface.adoc | 37 ++++++++++++++++++++++-- adoc/headers/vec.h | 7 +++++ 2 files changed, 41 insertions(+), 3 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 6a00a8de5..0a2300da9 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -19930,11 +19930,12 @@ _Returns:_ A [code]#vec# object that represents the result of the operation. ==== Rounding modes The various rounding modes that can be used in the [code]#convert# member -function template are described in <>. +function of [code]#vec# and in the [code]#sycl::convert# free function are +described in <>. [[table.vec.roundingmodes]] -.Rounding modes for the SYCL [code]#vec# class template +.Rounding modes for conversions using [code]#sycl::rounding_mode# [width="100%",options="header",separator="@",cols="65%,35%"] |==== @ Rounding mode @ Description @@ -19943,7 +19944,7 @@ a@ ---- automatic ---- - a@ Default rounding mode for the SYCL [code]#vec# class element type. [code]#rtz# (round toward zero) for integer types and [code]#rte# (round to nearest even) for floating-point types. + a@ Default rounding mode for the converted type. [code]#rtz# (round toward zero) for integer types and [code]#rte# (round to nearest even) for floating-point types. a@ [source] @@ -19977,6 +19978,36 @@ rtn +[[sec:scalar.convert]] +==== Scalar type conversion + +The [code]#sycl::convert# free function template provides a scalar equivalent +of the [code]#vec::convert# member function, allowing scalar values to be +converted between types with an explicit rounding mode. +This makes it possible to ensure that scalar conversion results match the results +produced by [code]#vec::convert# for the corresponding element types. + +[frame=all,grid=none,separator="@"] +|==== +a@ +[source] +---- +template +ConvertT convert(T value) +---- + a@ _Constraints:_ [code]#T# is a scalar type that is one of the built-in + scalar data types listed in <>, [code]#half#, + [code]#sycl::byte#, or [code]#std::byte#. + +Converts [code]#value# from type [code]#T# to type [code]#ConvertT# using +the rounding mode specified by [code]#RoundingMode#. +The different rounding modes are described in <>. + +|==== + + [[memory-layout-and-alignment]] ==== Memory layout and alignment diff --git a/adoc/headers/vec.h b/adoc/headers/vec.h index 63a44a4e1..31259ba68 100644 --- a/adoc/headers/vec.h +++ b/adoc/headers/vec.h @@ -260,4 +260,11 @@ template class vec { // Available only when: (std::is_same_v && ...) template vec(T, U...) -> vec; +// Available only when: T is a scalar type that is one of the built-in scalar +// data types, half, sycl::byte, or std::byte. +template +ConvertT convert(T value); + } // namespace sycl From 565f3465fb4d1498df0892320c29085e05737f78 Mon Sep 17 00:00:00 2001 From: Samaresh Kumar Singh Date: Mon, 13 Apr 2026 14:26:17 -0500 Subject: [PATCH 2/2] Rework scalar convert as sycl_khr_convert extension --- adoc/chapters/programming_interface.adoc | 37 +----------- adoc/extensions/index.adoc | 1 + adoc/extensions/sycl_khr_convert.adoc | 77 ++++++++++++++++++++++++ adoc/headers/vec.h | 7 --- 4 files changed, 81 insertions(+), 41 deletions(-) create mode 100644 adoc/extensions/sycl_khr_convert.adoc diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 0a2300da9..6a00a8de5 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -19930,12 +19930,11 @@ _Returns:_ A [code]#vec# object that represents the result of the operation. ==== Rounding modes The various rounding modes that can be used in the [code]#convert# member -function of [code]#vec# and in the [code]#sycl::convert# free function are -described in <>. +function template are described in <>. [[table.vec.roundingmodes]] -.Rounding modes for conversions using [code]#sycl::rounding_mode# +.Rounding modes for the SYCL [code]#vec# class template [width="100%",options="header",separator="@",cols="65%,35%"] |==== @ Rounding mode @ Description @@ -19944,7 +19943,7 @@ a@ ---- automatic ---- - a@ Default rounding mode for the converted type. [code]#rtz# (round toward zero) for integer types and [code]#rte# (round to nearest even) for floating-point types. + a@ Default rounding mode for the SYCL [code]#vec# class element type. [code]#rtz# (round toward zero) for integer types and [code]#rte# (round to nearest even) for floating-point types. a@ [source] @@ -19978,36 +19977,6 @@ rtn -[[sec:scalar.convert]] -==== Scalar type conversion - -The [code]#sycl::convert# free function template provides a scalar equivalent -of the [code]#vec::convert# member function, allowing scalar values to be -converted between types with an explicit rounding mode. -This makes it possible to ensure that scalar conversion results match the results -produced by [code]#vec::convert# for the corresponding element types. - -[frame=all,grid=none,separator="@"] -|==== -a@ -[source] ----- -template -ConvertT convert(T value) ----- - a@ _Constraints:_ [code]#T# is a scalar type that is one of the built-in - scalar data types listed in <>, [code]#half#, - [code]#sycl::byte#, or [code]#std::byte#. - -Converts [code]#value# from type [code]#T# to type [code]#ConvertT# using -the rounding mode specified by [code]#RoundingMode#. -The different rounding modes are described in <>. - -|==== - - [[memory-layout-and-alignment]] ==== Memory layout and alignment diff --git a/adoc/extensions/index.adoc b/adoc/extensions/index.adoc index d16bc954b..b8769bead 100644 --- a/adoc/extensions/index.adoc +++ b/adoc/extensions/index.adoc @@ -18,3 +18,4 @@ include::sycl_khr_queue_flush.adoc[leveloffset=2] include::sycl_khr_work_item_queries.adoc[leveloffset=2] include::sycl_khr_static_addrspace_cast.adoc[leveloffset=2] include::sycl_khr_dynamic_addrspace_cast.adoc[leveloffset=2] +include::sycl_khr_convert.adoc[leveloffset=2] diff --git a/adoc/extensions/sycl_khr_convert.adoc b/adoc/extensions/sycl_khr_convert.adoc new file mode 100644 index 000000000..279276432 --- /dev/null +++ b/adoc/extensions/sycl_khr_convert.adoc @@ -0,0 +1,77 @@ +[[sec:khr-convert]] += sycl_khr_convert + +This extension provides a scalar equivalent of the [code]#vec::convert# member +function, allowing scalar values to be converted between types with an explicit +rounding mode. +This makes it possible to ensure that scalar conversion results match those +produced by [code]#vec::convert# for the corresponding element types. + +[[sec:khr-convert-dependencies]] +== Dependencies + +This extension has no dependencies on other extensions. + +[[sec:khr-convert-feature-test]] +== Feature test macro + +An implementation supporting this extension must predefine the macro +[code]#SYCL_KHR_CONVERT# to one of the values defined in the table below. + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|Initial version of this extension. +|=== + +[[sec:khr-convert-function]] +== Scalar type conversion function + +.[apidef]#khr::convert# +[source,role=synopsis,id=api:khr-convert] +---- +namespace sycl::khr { + +template +ConvertT convert(T value); + +} // namespace sycl::khr +---- + +_Constraints:_ [code]#T# is a scalar type that is one of the built-in scalar +data types listed in <>, [code]#half#, [code]#sycl::byte#, +or [code]#std::byte#. +[code]#ConvertT# must be one of the same set of scalar types. + +_Returns:_ [code]#value# converted from type [code]#T# to type [code]#ConvertT# +using the rounding mode specified by [code]#RoundingMode#. +The rounding modes are described in <>. + +[[sec:khr-convert-example]] +== Example + +The example below demonstrates converting a scalar value using an explicit +rounding mode, matching the behavior of [code]#vec::convert# for a single +element. + +[source,c++,linenums] +---- +#include + +int main() { + float f = 1.7f; + + // Scalar conversion with explicit rounding mode + int i = sycl::khr::convert(f); // truncates to 1 + + // Matches vec::convert behavior for the same element type and rounding mode + sycl::vec vf{f}; + auto vi = vf.convert(); + // i == vi[0] +} +---- diff --git a/adoc/headers/vec.h b/adoc/headers/vec.h index 31259ba68..63a44a4e1 100644 --- a/adoc/headers/vec.h +++ b/adoc/headers/vec.h @@ -260,11 +260,4 @@ template class vec { // Available only when: (std::is_same_v && ...) template vec(T, U...) -> vec; -// Available only when: T is a scalar type that is one of the built-in scalar -// data types, half, sycl::byte, or std::byte. -template -ConvertT convert(T value); - } // namespace sycl