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 following 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, 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 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. Scalar and Vector Argument Built-in Math Function Table

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 fmin29(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.

gentype fmod(gentype x, gentype y)

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

gentype fract(gentype x, gentype *iptr)30

Returns fmin(x - floor(x), 0x1.fffffep-1f). floor(x) is returned in iptr.

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, intn *exp)
double frexp(double 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.

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, 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 SPIR-V OpenCL environment specification for details. On some hardware the mad instruction may provide better performance than expanded computation of a * b + c.31

gentype maxmag(gentype x, gentype y)

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

gentype minmag(gentype x, gentype y)

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

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 single-precision 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, 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, 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)
doublen 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, 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.

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

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

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

The following table describes the following functions:

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. Scalar and Vector Argument Built-in 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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.