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. We use the generic type name gentype to indicate that the function can take float, float2, float3, float4, float8, float16, double [1], double2, double3, double4, double8 or double16 as the type for the arguments. We use the generic type name gentypef to indicate that the function can take float, float2, float3, float4, float8, or float16 as the type for the arguments. We use the generic type name gentyped [1] to indicate that the function can take double, double2, double3, double4, double8 or double16 as the type for the arguments. For any specific use of a function, the actual type has to be the same for all arguments and the return type, unless otherwise specified.

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 cosx).

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)

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)

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. [2]

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), 0x1.fffffep-1f). floor(x) is returned in iptr. [3]

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)

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)

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)

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)

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)

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)

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. [4]

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)

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)

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.

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)

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 sinx).

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 tanx).

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.

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

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 2014-2023 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. 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.
3. 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.
4. 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 that almost any result is allowed from mad() for some values of a and b.