Description

The built-in math functions are categorized into the following:

  • A list of built-in functions that have scalar or vector argument versions, and,

  • A list of built-in functions that only take scalar float arguments.

The vector versions of the math functions operate component-wise. The description is per-component.

The built-in math functions are not affected by the prevailing rounding mode in the calling environment, and always return the same value as they would if called with the round to nearest even rounding mode.

The Built-in Scalar and Vector Argument Math Functions table describes the list of built-in math functions that can take scalar or vector arguments.

The generic type name gentype indicates that the function can take any of

  • float, float2, float3, float4, float8, or float16

  • double [1], double2, double3, double4, double8 or double16

  • half [2], half2, half3, half4, half8 or half16

as the type for the arguments.

The generic type name gentypef indicates that the function can take any of

  • float, float2, float3, float4, float8, or float16

as the type for the arguments.

The generic type name gentyped [3] indicates that the function can take any of

  • double, double2, double3, double4, double8 or double16

as the type for the arguments.

The generic type name gentypeh [4] indicates that the function can take any of

  • half, half2, half3, half4, half8 or half16

as the type for the arguments.

All functions taking or returning half types are supported only when the cl_khr_fp16 extension macro is supported.

For any specific use of a function with gentype* arguments the actual type has to be the same for all arguments and the return type, unless they are explicitly specified as an actual type.

Table 1. Built-in Scalar and Vector Argument Math Functions
Function Description

gentype acos(gentype)

Arc cosine function. Returns an angle in radians.

gentype acosh(gentype)

Inverse hyperbolic cosine. Returns an angle in radians.

gentype acospi(gentype x)

Compute acos(x) / π.

gentype asin(gentype)

Arc sine function. Returns an angle in radians.

gentype asinh(gentype)

Inverse hyperbolic sine. Returns an angle in radians.

gentype asinpi(gentype x)

Compute asin(x) / π.

gentype atan(gentype y_over_x)

Arc tangent function. Returns an angle in radians.

gentype atan2(gentype y, gentype x)

Arc tangent of y / x. Returns an angle in radians.

gentype atanh(gentype)

Hyperbolic arc tangent. Returns an angle in radians.

gentype atanpi(gentype x)

Compute atan(x) / π.

gentype atan2pi(gentype y, gentype x)

Compute atan2(y, x) / π.

gentype cbrt(gentype)

Compute cube-root.

gentype ceil(gentype)

Round to integral value using the round to positive infinity rounding mode.

gentype copysign(gentype x, gentype y)

Returns x with its sign changed to match the sign of y.

gentype cos(gentype x)

Compute cosine, where x is an angle in radians.

gentype cosh(gentype x)

Compute hyperbolic cosine, where x is an angle in radians.

gentype cospi(gentype x)

Compute cos(π x).

gentype erfc(gentype)

Complementary error function.

gentype erf(gentype)

Error function encountered in integrating the normal distribution.

gentype exp(gentype x)

Compute the base-e exponential of x.

gentype exp2(gentype)

Exponential base 2 function.

gentype exp10(gentype)

Exponential base 10 function.

gentype expm1(gentype x)

Compute ex - 1.0.

gentype fabs(gentype)

Compute absolute value of a floating-point number.

gentype fdim(gentype x, gentype y)

x - y if x > y, +0 if x is less than or equal to y.

gentype floor(gentype)

Round to integral value using the round to negative infinity rounding mode.

gentype fma(gentype a, gentype b, gentype c)

Returns the correctly rounded floating-point representation of the sum of c with the infinitely precise product of a and b. Rounding of intermediate products shall not occur. Edge case behavior is per the IEEE 754-2008 standard.

gentype fmax(gentype x, gentype y)
gentypef fmax(gentypef x, float y)
gentyped fmax(gentyped x, double y)

gentypeh fmax(gentypeh x, half y)

Returns y if x < y, otherwise it returns x. If one argument is a NaN, fmax() returns the other argument. If both arguments are NaNs, fmax() returns a NaN.

gentype fmin(gentype x, gentype y)
gentypef fmin(gentypef x, float y)
gentyped fmin(gentyped x, double y)

gentypeh fmax(gentypeh x, half y)

Returns y if y < x, otherwise it returns x. If one argument is a NaN, fmin() returns the other argument. If both arguments are NaNs, fmin() returns a NaN. [5]

gentype fmod(gentype x, gentype y)

Modulus. Returns x - y * trunc(x/y).

gentype fract(gentype x, __global gentype *iptr)
gentype fract(gentype x, __local gentype *iptr)
gentype fract(gentype x, __private gentype *iptr)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

gentype fract(gentype x, gentype *iptr)

Returns fmin(x - floor(x), C), where C is the constant 0x1.fffffep-1f for float aguments, 0x1.fffffffffffffp-1 for double arguments, and 0x1.ffcp-1h for half arguments. floor(x) is returned in iptr. [6]

halfn frexp(halfn x, __global intn *exp)
half frexp(half x, __global int *exp)

halfn frexp(halfn x, __local intn *exp)
half frexp(half x, __local int *exp)

halfn frexp(halfn x, __private intn *exp)
half frexp(half x, __private int *exp)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

halfn frexp(halfn x, intn *exp)
half frexp(half x, int *exp)

Extract mantissa and exponent from x. For each component the mantissa returned is a half with magnitude in the interval [1/2, 1) or 0. Each component of x equals mantissa returned * 2exp.

floatn frexp(floatn x, __global intn *exp)
float frexp(float x, __global int *exp)

floatn frexp(floatn x, __local intn *exp)
float frexp(float x, __local int *exp)

floatn frexp(floatn x, __private intn *exp)
float frexp(float x, __private int *exp)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

floatn frexp(floatn x, intn *exp)
float frexp(float x, int *exp)

Extract mantissa and exponent from x. For each component the mantissa returned is a float with magnitude in the interval [1/2, 1) or 0. Each component of x equals mantissa returned * 2exp.

doublen frexp(doublen x, __global intn *exp)
double frexp(double x, __global int *exp)

doublen frexp(doublen x, __local intn *exp)
double frexp(double x, __local int *exp)

doublen frexp(doublen x, __private intn *exp)
double frexp(double x, __private int *exp)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

doublen frexp(doublen x, intn *exp)
double frexp(double x, int *exp)

Extract mantissa and exponent from x. For each component the mantissa returned is a double with magnitude in the interval [1/2, 1) or 0. Each component of x equals mantissa returned * 2exp.

gentype hypot(gentype x, gentype y)

Compute the value of the square root of x2+ y2 without undue overflow or underflow.

intn ilogb(floatn x)
int ilogb(float x)
intn ilogb(doublen x)
int ilogb(double x)

intn ilogb(halfn x)
int ilogb(half x)

Return the exponent as an integer value.

floatn ldexp(floatn x, intn k)
floatn ldexp(floatn x, int k)
float ldexp(float x, int k)
doublen ldexp(doublen x, intn k)
doublen ldexp(doublen x, int k)
double ldexp(double x, int k)

halfn ldexp(halfn x, intn k)
halfn ldexp(halfn x, int k)
half ldexp(half x, int k)

Multiply x by 2 to the power k.

gentype lgamma(gentype x)
floatn lgamma_r(floatn x, __global intn *signp)
float lgamma_r(float x, __global int *signp)
doublen lgamma_r(doublen x, __global intn *signp)
double lgamma_r(double x, __global int *signp)

halfn lgamma_r(halfn x, __global intn *signp)
half lgamma_r(half x, __global int *signp)

floatn lgamma_r(floatn x, __local intn *signp)
float lgamma_r(float x, __local int *signp)
doublen lgamma_r(doublen x, __local intn *signp)
double lgamma_r(double x, __local int *signp)

halfn lgamma_r(halfn x, __local intn *signp)
half lgamma_r(half x, __local int *signp)

floatn lgamma_r(floatn x, __private intn *signp)
float lgamma_r(float x, __private int *signp)
doublen lgamma_r(doublen x, __private intn *signp)
double lgamma_r(double x, __private int *signp)

halfn lgamma_r(halfn x, __private intn *signp)
half lgamma_r(half x, __private int *signp)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

floatn lgamma_r(floatn x, intn *signp)
float lgamma_r(float x, int *signp)
doublen lgamma_r(doublen x, intn *signp)
double lgamma_r(double x, int *signp)

halfn lgamma_r(halfn x, intn *signp)
half lgamma_r(half x, int *signp)

Log gamma function. Returns the natural logarithm of the absolute value of the gamma function. The sign of the gamma function is returned in the signp argument of lgamma_r.

gentype log(gentype)

Compute natural logarithm.

gentype log2(gentype)

Compute a base 2 logarithm.

gentype log10(gentype)

Compute a base 10 logarithm.

gentype log1p(gentype x)

Compute loge(1.0 + x).

gentype logb(gentype x)

Compute the exponent of x, which is the integral part of logr(|x|).

gentype mad(gentype a, gentype b, gentype c)

mad computes a * b + c. The function may compute a * b + c with reduced accuracy in the embedded profile. See the OpenCL SPIR-V Environment Specification for details. On some hardware the mad instruction may provide better performance than expanded computation of a * b + c. [7]

gentype maxmag(gentype x, gentype y)

Returns x if |x| > |y|, y if |y| > |x|, otherwise fmax(x, y).

Requires support for OpenCL C 1.1 or newer.

gentype minmag(gentype x, gentype y)

Returns x if |x| < |y|, y if |y| < |x|, otherwise fmin(x, y).

Requires support for OpenCL C 1.1 or newer.

gentype modf(gentype x, __global gentype *iptr)
gentype modf(gentype x, __local gentype *iptr)
gentype modf(gentype x, __private gentype *iptr)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

gentype modf(gentype x, gentype *iptr)

Decompose a floating-point number. The modf function breaks the argument x into integral and fractional parts, each of which has the same sign as the argument. It stores the integral part in the object pointed to by iptr.

floatn nan(uintn nancode)
float nan(uint nancode)
doublen nan(ulongn nancode)
double nan(ulong nancode)

halfn nan(ushortn nancode)
half nan(ushort nancode)

Returns a quiet NaN. The nancode may be placed in the significand of the resulting NaN.

gentype nextafter(gentype x, gentype y)

Computes the next representable floating-point value following x in the direction of y. Thus, if y is less than x, nextafter() returns the largest representable floating-point number less than x.

gentype pow(gentype x, gentype y)

Compute x to the power y.

floatn pown(floatn x, intn y)
float pown(float x, int y)
doublen pown(doublen x, intn y)
double pown(double x, int y)

halfn pown(halfn x, intn y)
half pown(half x, int y)

Compute x to the power y, where y is an integer.

gentype powr(gentype x, gentype y)

Compute x to the power y, where x is >= 0.

gentype remainder(gentype x, gentype y)

Compute the value r such that r = x - n*y, where n is the integer nearest the exact value of x/y. If there are two integers closest to x/y, n shall be the even one. If r is zero, it is given the same sign as x.

floatn remquo(floatn x, floatn y, __global intn *quo)
float remquo(float x, float y, __global int *quo)

floatn remquo(floatn x, floatn y, __local intn *quo)
float remquo(float x, float y, __local int *quo)

floatn remquo(floatn x, floatn y, __private intn *quo)
float remquo(float x, float y, __private int *quo)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

floatn remquo(floatn x, floatn y, intn *quo)
float remquo(float x, float y, int *quo)

The remquo function computes the value r such that r = x - k*y, where k is the integer nearest the exact value of x/y. If there are two integers closest to x/y, k shall be the even one. If r is zero, it is given the same sign as x. This is the same value that is returned by the remainder function. remquo also calculates the lower seven bits of the integral quotient x/y, and gives that value the same sign as x/y. It stores this signed value in the object pointed to by quo.

doublen remquo(doublen x, doublen y, __global intn *quo)
double remquo(double x, double y, __global int *quo)

doublen remquo(doublen x, doublen y, __local intn *quo)
double remquo(double x, double y, __local int *quo)

doublen remquo(doublen x, doublen y, __private intn *quo)
double remquo(double x, double y, __private int *quo)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

doublen remquo(doublen x, doublen y, intn *quo)
double remquo(double x, double y, int *quo)

The remquo function computes the value r such that r = x - k*y, where k is the integer nearest the exact value of x/y. If there are two integers closest to x/y, k shall be the even one. If r is zero, it is given the same sign as x. This is the same value that is returned by the remainder function. remquo also calculates the lower seven bits of the integral quotient x/y, and gives that value the same sign as x/y. It stores this signed value in the object pointed to by quo.

halfn remquo(halfn x, halfn y, __global intn *quo)
half remquo(half x, half y, __global int *quo)

halfn remquo(halfn x, halfn y, __local intn *quo)
half remquo(half x, half y, __local int *quo)

halfn remquo(halfn x, halfn y, __private intn *quo)
half remquo(half x, half y, __private int *quo)

For OpenCL C 2.0 or with the __opencl_c_generic_address_space feature:

halfn remquo(halfn x, halfn y, intn *quo)
half remquo(half x, half y, int *quo)

The remquo function computes the value r such that r = x - k*y, where k is the integer nearest the exact value of x/y. If there are two integers closest to x/y, k shall be the even one. If r is zero, it is given the same sign as x. This is the same value that is returned by the remainder function. remquo also calculates the lower seven bits of the integral quotient x/y, and gives that value the same sign as x/y. It stores this signed value in the object pointed to by quo.

gentype rint(gentype)

Round to integral value (using round to nearest even rounding mode) in floating-point format. Refer to section 7.1 for description of rounding modes.

floatn rootn(floatn x, intn y)
float rootn(float x, int y)
doublen rootn(doublen x, intn y)
double rootn(double x, int y)

halfn rootn(halfn x, intn y)
half rootn(half x, int y)

Compute x to the power 1/y.

gentype round(gentype x)

Return the integral value nearest to x rounding halfway cases away from zero, regardless of the current rounding direction.

gentype rsqrt(gentype)

Compute inverse square root.

gentype sin(gentype x)

Compute sine, where x is an angle in radians.

gentype sincos(gentype x, __global gentype *cosval)
gentype sincos(gentype x, __local gentype *cosval)
gentype sincos(gentype x, __private gentype *cosval)

For OpenCL C 2.0, or OpenCL C 3.0 or newer with the __opencl_c_generic_address_space feature:

gentype sincos(gentype x, gentype *cosval)

Compute sine and cosine of x. The computed sine is the return value and computed cosine is returned in cosval, where x is an angle in radians.

gentype sinh(gentype x)

Compute hyperbolic sine, where x is an angle in radians

gentype sinpi(gentype x)

Compute sin(π x).

gentype sqrt(gentype)

Compute square root.

gentype tan(gentype x)

Compute tangent, where x is an angle in radians.

gentype tanh(gentype x)

Compute hyperbolic tangent, where x is an angle in radians.

gentype tanpi(gentype x)

Compute tan(π x).

gentype tgamma(gentype)

Compute the gamma function.

gentype trunc(gentype)

Round to integral value using the round to zero rounding mode.

The following table describes the following functions:

  • A subset of functions from Built-in Scalar and Vector Argument Math Functions that are defined with the half_ prefix . These functions are implemented with a minimum of 10-bits of accuracy, i.e. the maximum error value <= 8192 ulp.

  • A subset of functions from Built-in Scalar and Vector Argument Math Functions that are defined with the native_ prefix. These functions may map to one or more native device instructions and will typically have better performance compared to the corresponding functions without the native_ prefix). The accuracy (and in some cases the input range(s)) of these functions is implementation-defined.

  • half_ and native_ functions for following basic operations: divide and reciprocal.

We use the generic type name gentype to indicate that the functions in the following table can take float, float2, float3, float4, float8 or float16 as the type for the arguments.

The use of half in this table does not refer to the argument and return types, which are 32-bit floating-point values, but to the accuracy requirements of the function results.
Table 2. Built-in Scalar and Vector half and native Math Functions
Function Description

gentype half_cos(gentype x)

Compute cosine. x is an angle in radians, and must be in the range [-216, +216].

gentype half_divide(gentype x, gentype y)

Compute x / y.

gentype half_exp(gentype x)

Compute the base-e exponential of x.

gentype half_exp2(gentype x)

Compute the base- 2 exponential of x.

gentype half_exp10(gentype x)

Compute the base- 10 exponential of x.

gentype half_log(gentype x)

Compute natural logarithm.

gentype half_log2(gentype x)

Compute a base 2 logarithm.

gentype half_log10(gentype x)

Compute a base 10 logarithm.

gentype half_powr(gentype x, gentype y)

Compute x to the power y, where x is >= 0.

gentype half_recip(gentype x)

Compute reciprocal.

gentype half_rsqrt(gentype x)

Compute inverse square root.

gentype half_sin(gentype x)

Compute sine. x is an angle in radians, and must be in the range [-216, +216].

gentype half_sqrt(gentype x)

Compute square root.

gentype half_tan(gentype x)

Compute tangent. x is an angle in radians, and must be in the range [-216, +216].

gentype native_cos(gentype x)

Compute cosine over an implementation-defined range, where x is an angle in radians. The maximum error is implementation-defined.

gentype native_divide(gentype x, gentype y)

Compute x / y over an implementation-defined range. The maximum error is implementation-defined.

gentype native_exp(gentype x)

Compute the base-e exponential of x over an implementation-defined range. The maximum error is implementation-defined.

gentype native_exp2(gentype x)

Compute the base-2 exponential of x over an implementation-defined range. The maximum error is implementation-defined.

gentype native_exp10(gentype x)

Compute the base-10 exponential of x over an implementation-defined range. The maximum error is implementation-defined.

gentype native_log(gentype x)

Compute natural logarithm over an implementation-defined range. The maximum error is implementation-defined.

gentype native_log2(gentype x)

Compute a base 2 logarithm over an implementation-defined range. The maximum error is implementation-defined.

gentype native_log10(gentype x)

Compute a base 10 logarithm over an implementation-defined range. The maximum error is implementation-defined.

gentype native_powr(gentype x, gentype y)

Compute x to the power y, where x is >= 0. The range of x and y are implementation-defined. The maximum error is implementation-defined.

gentype native_recip(gentype x)

Compute reciprocal over an implementation-defined range. The maximum error is implementation-defined.

gentype native_rsqrt(gentype x)

Compute inverse square root over an implementation-defined range. The maximum error is implementation-defined.

gentype native_sin(gentype x)

Compute sine over an implementation-defined range, where x is an angle in radians. The maximum error is implementation-defined.

gentype native_sqrt(gentype x)

Compute square root over an implementation-defined range. The maximum error is implementation-defined.

gentype native_tan(gentype x)

Compute tangent over an implementation-defined range, where x is an angle in radians. The maximum error is implementation-defined.

Support for denormal values is optional for half_ functions. The half_ functions may return any result allowed by Edge Case Behavior, even when -cl-denorms-are-zero (see section 5.8.4.2 of the OpenCL Specification) is not in force. Support for denormal values is implementation-defined for native_ functions.

See Also

commonFunctions, integerFunctions

Document Notes

For more information, see the OpenCL C Specification

This page is extracted from the OpenCL C Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0

1. Only if double precision is supported. In OpenCL C 3.0 this will be indicated by the presence of the __opencl_c_fp64 feature macro.
2. Only if the cl_khr_fp16 extension is supported and has been enabled.
3. Only if double precision is supported. In OpenCL C 3.0 this will be indicated by the presence of the __opencl_c_fp64 feature macro.
4. Only if the cl_khr_fp16 extension is supported and has been enabled.
5. fmin and fmax behave as defined by C99 and may not match the IEEE 754-2008 definition for minNum and maxNum with regard to signaling NaNs. Specifically, signaling NaNs may behave as quiet NaNs.
6. The min() operator is there to prevent fract(-small) from returning 1.0. It returns the largest positive floating-point number less than 1.0.
7. The user is cautioned that for some usages, e.g. mad(a, b, -a*b), the definition of mad() is loose enough in the embedded profile or with half-precision arguments that almost any result is allowed from mad() for some values of a and b.