// Copyright 2017-2023 The Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[cl_khr_select_fprounding_mode]]
== Selecting the Rounding Mode **(DEPRECATED)**

This section describes the *cl_khr_select_fprounding_mode* extension.
It allows an application to specify the rounding mode for an instruction or group of instructions in the program source.

**This extension was deprecated in OpenCL 1.1 and its use is not recommended.**

=== General information

==== Version history

[cols="1,1,3",options="header",]
|====
| *Date*     | *Version* | *Description*
| 2020-04-21 | 1.0.0     | First assigned version.
|====

=== Changes to OpenCL C specification

With this extension, the rounding mode may be specified using the following *#pragma* in the OpenCL program source:

[source,opencl_c]
----
#pragma OPENCL SELECT_ROUNDING_MODE <rounding-mode>
----

The _<rounding-mode>_ may be one of the following values:

* *rte* - round to nearest even
* *rtz* - round to zero
* *rtp* - round to positive infinity
* *rtn* - round to negative infinity

If this extensions is supported then the OpenCL implementation must support all four rounding modes for single precision floating-point.

The *#pragma* sets the rounding mode for all instructions that operate on floating-point types (scalar or vector types) or produce floating-point values that follow this pragma in the program source until the next *#pragma*.
Note that the rounding mode specified for a block of code is known at compile time.
When inside a compound statement, the pragma takes effect from its occurrence until another *#pragma* is encountered (including within a nested compound statement), or until the end of the compound statement; at the end of a compound statement the state for the pragma is restored to its condition just before the compound statement.
Except where otherwise documented, the callee functions do not inherit the rounding mode of the caller function.

If this extension is enabled, the `\\__ROUNDING_MODE__` preprocessor symbol shall be defined to be one of the following according to the current rounding mode:

[source,opencl_c]
----
#define __ROUNDING_MODE__ rte
#define __ROUNDING_MODE__ rtz
#define __ROUNDING_MODE__ rtp
#define __ROUNDING_MODE__ rtz
----

This is intended to enable remapping `foo()` to `foo_rte()` by the preprocessor by using:

[source,opencl_c]
----
#define foo foo ## __ROUNDING_MODE__
----

The default rounding mode is round to nearest even.
The built-in math functions described in _section 6.11.2_, the common functions described in _section 6.11.4_ and the geometric functions described in _section 6.11.5_ are implemented with the round to nearest even rounding mode.
Various built-in conversions and the *vstore_half* and *vstorea_half* built-in functions that do not specify a rounding mode inherit the current rounding mode.
Conversions from floating-point to integer type always use `rtz` mode, except where the user specifically asks for another rounding mode.
