OpenKODE Core extension: KD_KHR

OpenKODE Core extension: KD_KHR_float64

Name	KHR_float64
Name strings	KD_KHR_float64
Contributors	Tim Renouf
Contacts	Khronos OpenKODE working group
Status	Approved by OpenKODE working group February 2008
Version	Version 7, 2008-09-12
Number	4
Dependencies	Requires OpenKODE Core 1.0. This extension is written based on the wording of the OpenKODE Core 1.0 specification.

1. Overview

This OpenKODE Core extension provides a 64-bit floating point data type and associated functions.

2. Rationale

OpenKODE Core provides only a 32-bit floating point type, KDfloat32. It has been found that many applications, particularly ones being ported from the PC/console world down to mobile, use double as a 64-bit floating point type. This extension brings this type and the functions that use it into the OpenKODE Core specification.

3. Header file

When this extension is present, its facilities are accessed by including its header file:

#include <KD/KHR_float64.h>

4. New types

This extension defines a type, which is intrinsic (i.e. it participates in C’s casting and promotion rules):

type	description
`KDfloat64KHR`	64-bit floating point value with [IEEE 754] behavior, and with a format which is either [IEEE 754] or [IEEE 754] with the halves swapped. It is implementation defined which format is used.

4.1. Rationale: “middle-endian” doubles

There are some ARM platforms with so-called “middle-endian” doubles: the platform is little endian, but a double is stored with its high word before its low word. The above definition of the format of a KDfloat64KHR allows for such platforms.

5. New constants

KD_E_KHR

#define KD_E_KHR 2.718281828459045235

The constant e.

KD_PI_KHR

#define KD_PI_KHR 3.141592653589793239

The constant pi.

KD_PI_2_KHR

#define KD_PI_2_KHR 1.570796326794896619

pi/2

KD_2PI_KHR

#define KD_2PI_KHR 6.283185307179586477

2 times pi

KD_LOG2E_KHR

#define KD_LOG2E_KHR 1.442695040888963407

Value of log2e.

KD_LOG10E_KHR

#define KD_LOG10E_KHR 0.4342944819032518276

Value of log10e.

KD_LN2_F_KHR

#define KD_LN2_KHR 0.6931471805599453094

Value of loge2.

KD_LN10_KHR

#define KD_LN10_KHR 2.302585092994045684

Value of loge10.

KD_PI_4_KHR

#define KD_PI_4_KHR 0.7853981633974483096

Value of PI/4.

KD_1_PI_KHR

#define KD_1_PI_KHR 0.3183098861837906715

Value of 1/PI.

KD_2_PI_KHR

#define KD_2_PI_KHR 0.6366197723675813431

Value of 2/PI.

KD_2_SQRTPI_KHR

#define KD_2_SQRTPI_KHR 1.128379167095512574

Value of 2/sqrt(PI).

KD_SQRT2_KHR

#define KD_SQRT2_KHR 1.414213562373095049

Value of sqrt(2).

KD_SQRT1_2_KHR

#define KD_SQRT1_2_KHR 0.7071067811865475244

Value of sqrt(1/2).

KD_DBL_EPSILON_KHR

#define KD_DBL_EPSILON_KHR 2.2204460492503131e-16

Difference between 1 and the smallest KDfloat64 greater than 1.

KD_DBL_MAX_KHR

#define KD_DBL_MAX_KHR 1.7976931348623157e+308

The largest possible finite KDfloat64.

KD_DBL_MIN_KHR

#define KD_DBL_MIN_KHR 2.2250738585072014e-308

The smallest possible positive normalized KDfloat64.

KD_HUGE_VAL_KHR

#define KD_HUGE_VAL_KHR (1.0/0.0)

Used as an error value by certain functions; equivalent to KD_INFINITY_KHR.

KD_DEG_TO_RAD_KHR

#define KD_DEG_TO_RAD_KHR 0.01745329251994329577

Multiply by this number to convert degrees to radians.

KD_RAD_TO_DEG_KHR

#define KD_RAD_TO_DEG_KHR 57.29577951308232088

Multiply by this number to convert radians to degrees.

5.1. Rationale

The constants above appear in [C99] (without the KD_ prefix and _KHR suffix, except for KD_2PI_KHR, KD_DEG_TO_RAD_KHR and KD_RAD_TO_DEG_KHR.

6. New macros

6.1. KD_VA_ARG_FLOAT64_KHR

Get the next argument from a variable argument list.

Synopsis

KD_VA_ARG_FLOAT64_KHR(ap)

Description

This macro is provided by this extension only if the KD_KHR_formatted extension is also present. It is analogous to the other KD_VA_ARG_*_KHR macros in that extension, for the case when the argument is of type KDfloat64.

7. New math functions

This extension provides KDfloat64KHR versions of all of the OpenKODE Core KDfloat32 math functions. Each has the same name with the final 'f' dropped and with an 'KHR' suffix added, and each has the same semantics except for the parameter and return types becoming KDfloat64KHR. Where the existing KDfloat32 function indicates a range error by returning KD_HUGE_VALF, the equivalent here returns KD_HUGE_VAL_KHR.

The OpenKODE Core 1.0.1 specification contains clarifications over OpenKODE Core 1.0 about the results of kdLogf(-0.0) and kdAtan2f(±0.0,±0.0). The same clarifications apply to kdLog and kdAtan2 here when this extension is used with OpenKODE Core 1.0.1.

KDfloat64KHR kdAcosKHR( KDfloat64KHR x);

KDfloat64KHR kdAsinKHR( KDfloat64KHR x);

KDfloat64KHR kdAtanKHR( KDfloat64KHR x);

`KDfloat64KHR kdAtan2KHR(`	KDfloat64KHR	`y`,
	KDfloat64KHR	`x)`;

KDfloat64KHR kdCosKHR( KDfloat64KHR x);

KDfloat64KHR kdSinKHR( KDfloat64KHR x);

KDfloat64KHR kdTanKHR( KDfloat64KHR x);

KDfloat64KHR kdExpKHR( KDfloat64KHR x);

KDfloat64KHR kdLogKHR( KDfloat64KHR x);

KDfloat64KHR kdFabsKHR( KDfloat64KHR x);

`KDfloat64KHR kdPowKHR(`	KDfloat64KHR	`x`,
	KDfloat64KHR	`y)`;

KDfloat64KHR kdSqrtKHR( KDfloat64KHR x);

KDfloat64KHR kdCeilKHR( KDfloat64KHR x);

KDfloat64KHR kdFloorKHR( KDfloat64KHR x);

KDfloat64KHR kdRoundKHR( KDfloat64KHR x);

KDfloat64KHR kdInvsqrtKHR( KDfloat64KHR x);

`KDfloat64KHR kdFmodKHR(`	KDfloat64KHR	`x`,
	KDfloat64KHR	`y)`;

8. New utility library functions

8.1. kdStrtodKHR

Convert a string to a 64-bit floating point number.

Synopsis

`KDfloat64KHR kdStrtodKHR(`	const KDchar *	`s`,
	KDchar **	`endptr)`;

Description

This function has the same semantics as kdStrtof, except that it results in a KDfloat64KHR value, and can therefore read a value with the range and accuracy of that type.

The OpenKODE Core 1.0.1 specification contains changes over OpenKODE Core 1.0 about kdStrtof, in that the forms it accepts for infinity and NaN are stricter, and it is defined not to accept hexadecimal floating point. The same changes apply to kdStrtodKHR here when this extension is used with OpenKODE Core 1.0.1.

The OpenKODE Core 1.0.2 specification contains a change over OpenKODE Core 1.0.1 about kdStrtof, in that it is undefined whether a number that could be represented as a denormal in the return type causes underflow or not. The analogous change applies to kdStrtodKHR here when this extension is used with OpenKODE Core 1.0.2.

8.2. kdDtostrKHR

Convert a 64-bit float to a string.

Synopsis

#define KD_DTOSTR_MAXLEN_KHR 25

`KDssize kdDtostrKHR(`	KDchar *	`buffer`,
	KDsize	`buflen`,
	KDfloat64KHR	`number)`;

Description

This function has the same semantics as kdFtostr, except that the number to convert is a KDfloat64, 17 significant digits are used, and the exponent is rendered (where applicable) with three digits as long as the first digit is not 0.

The maximum length of the result, including its null termination character, is KD_DTOSTR_MAXLEN_KHR.

For a non-zero finite number, the “correct” value of the seventeen significant mantissa digits is determined by successively multiplying or dividing the number by 10 until (ignoring the sign) it is in the range [1e16,1e17), and then obtaining an integer by rounding to nearest, with tiebreak case rounded to even. However it is permitted for the output of the function to have mantissa digits one out from this “correct” value.

The OpenKODE Core 1.0.1 specification contains changes over OpenKODE Core 1.0 about kdFtostr, in that the results for infinity and NaN are more tightly specified. The same changes apply to kdDtostrKHR here when this extension is used with OpenKODE Core 1.0.1.

Rationale

kdDtostrKHR is intended to provide a subset of snprintf’s functionality regarding double conversion (assuming C locale). The conversion rules above are intended to be equivalent to the snprintf format "%.17g". Note the difference in return value when the buffer is not large enough; [C99] snprintf returns the length the string would have been if the buffer had been long enough, whereas kdDtostrKHR returns -1.

Seventeen significant digits are specified because this is the minimum that guarantees that the original value can be recovered by a conversion with kdStrtodKHR.

9. Revision history

9.1. Version 7, 2008-09-12

OpenKODE Core 1.0.2 has a clarification that it is undefined whether kdStrtof reports underflow or not for a number that could be represented as a denormal. This version of the KHR_float64 extension specification points out that this change applies analogously to kdStrtodKHR.

9.2. Version 6, 2008-06-20

Fixed leftover “19” missed when number of significant digits of kdDtostrKHR was changed from 19 to 17, and fixed its description of how to obtain the “correct” result.
Changed back to be based on OpenKODE Core 1.0 specification, and pointed out cases where changes in OpenKODE Core 1.0.1 implicitly change the semantics of functions in this extension.

9.3. Version 5, 2008-03-31

Allowed KDfloat64KHR representation to have its halves swapped.
Clarified accuracy of kdDtostrKHR. Now based on OpenKODE Core 1.0.1 specification.

9.4. Version 4, 2008-02-01

Changed kdDtostrKHR to give 17 digits rather than 19.
Clarified accuracy of kdDtostrKHR.

9.5. Version 3, 2008-01-24

Fixed incorrect function name occurrences in kdDtostrKHR.
Clarified accuracy of kdDtostrKHR.

9.6. Version 2, 2007-10-15

Added KD_VA_ARG_FLOAT64_KHR macro.

9.7. Version 1, 2007-10-08

Initial version of official Khronos extension.

Bibliography

[C89] ANSI X3.159-1989 “Programming Language C” .

[C99] ISO/IEC 9899:TC2 “Programming Language C” .

[IEEE 754] IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985) .

[POSIX] IEEE Std 1003.1, 2004 Edition (“Single Unix Specification version 3”) .