1 ///////////////////////////////////////////////////////////////////////////
3 // Copyright (c) 2002, Industrial Light & Magic, a division of Lucas
6 // All rights reserved.
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
17 // * Neither the name of Industrial Light & Magic nor the names of
18 // its contributors may be used to endorse or promote products derived
19 // from this software without specific prior written permission.
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 ///////////////////////////////////////////////////////////////////////////
36 // Florian Kainz <kainz@ilm.com>
37 // Rod Bogart <rgb@ilm.com>
39 //---------------------------------------------------------------------------
41 // half -- a 16-bit floating point number class:
43 // Type half can represent positive and negative numbers, whose
44 // magnitude is between roughly 6.1e-5 and 6.5e+4, with a relative
45 // error of 9.8e-4; numbers smaller than 6.1e-5 can be represented
46 // with an absolute error of 6.0e-8. All integers from -2048 to
47 // +2048 can be represented exactly.
49 // Type half behaves (almost) like the built-in C++ floating point
50 // types. In arithmetic expressions, half, float and double can be
51 // mixed freely. Here are a few examples:
54 // float b (a + sqrt (a));
59 // Conversions from half to float are lossless; all half numbers
60 // are exactly representable as floats.
62 // Conversions from float to half may not preserve the float's
63 // value exactly. If a float is not representable as a half, the
64 // float value is rounded to the nearest representable half. If
65 // a float value is exactly in the middle between the two closest
66 // representable half values, then the float value is rounded to
67 // the half with the greater magnitude.
69 // Overflows during float-to-half conversions cause arithmetic
70 // exceptions. An overflow occurs when the float value to be
71 // converted is too large to be represented as a half, or if the
72 // float value is an infinity or a NAN.
74 // The implementation of type half makes the following assumptions
75 // about the implementation of the built-in C++ types:
77 // float is an IEEE 754 single-precision number
78 // sizeof (float) == 4
79 // sizeof (unsigned int) == sizeof (float)
80 // alignof (unsigned int) == alignof (float)
81 // sizeof (unsigned short) == 2
83 //---------------------------------------------------------------------------
98 half (); // no initialization
102 //--------------------
103 // Conversion to float
104 //--------------------
106 operator float () const;
113 half operator - () const;
120 half & operator = (half h);
121 half & operator = (float f);
123 half & operator += (half h);
124 half & operator += (float f);
126 half & operator -= (half h);
127 half & operator -= (float f);
129 half & operator *= (half h);
130 half & operator *= (float f);
132 half & operator /= (half h);
133 half & operator /= (float f);
136 //---------------------------------------------------------
137 // Round to n-bit precision (n should be between 0 and 10).
138 // After rounding, the significand's 10-n least significant
139 // bits will be zero.
140 //---------------------------------------------------------
142 half round (unsigned int n) const;
145 //--------------------------------------------------------------------
148 // h.isFinite() returns true if h is a normalized number,
149 // a denormalized number or zero
151 // h.isNormalized() returns true if h is a normalized number
153 // h.isDenormalized() returns true if h is a denormalized number
155 // h.isZero() returns true if h is zero
157 // h.isNan() returns true if h is a NAN
159 // h.isInfinity() returns true if h is a positive
160 // or a negative infinity
162 // h.isNegative() returns true if the sign bit of h
164 //--------------------------------------------------------------------
166 bool isFinite () const;
167 bool isNormalized () const;
168 bool isDenormalized () const;
169 bool isZero () const;
171 bool isInfinity () const;
172 bool isNegative () const;
175 //--------------------------------------------
178 // posInf() returns +infinity
180 // negInf() returns +infinity
182 // qNan() returns a NAN with the bit
183 // pattern 0111111111111111
185 // sNan() returns a NAN with the bit
186 // pattern 0111110111111111
187 //--------------------------------------------
189 static half posInf ();
190 static half negInf ();
195 //--------------------------------------
196 // Access to the internal representation
197 //--------------------------------------
199 unsigned short bits () const;
200 void setBits (unsigned short bits);
213 static short convert (int i);
214 static float overflow ();
218 //---------------------------------------------------
219 // Windows dynamic libraries don't like static
221 //---------------------------------------------------
223 static const uif _toFloat[1 << 16];
224 static const unsigned short _eLut[1 << 9];
228 #if defined(OPENEXR_DLL)
229 //--------------------------------------
230 // Lookup tables defined for Windows DLL
231 //--------------------------------------
232 #if defined(HALF_EXPORTS)
233 extern __declspec(dllexport) half::uif _toFloat[1 << 16];
234 extern __declspec(dllexport) unsigned short _eLut[1 << 9];
236 extern __declspec(dllimport) half::uif _toFloat[1 << 16];
237 extern __declspec(dllimport) unsigned short _eLut[1 << 9];
246 std::ostream & operator << (std::ostream &os, half h);
247 std::istream & operator >> (std::istream &is, half &h);
254 void printBits (std::ostream &os, half h);
255 void printBits (std::ostream &os, float f);
256 void printBits (char c[19], half h);
257 void printBits (char c[35], float f);
260 //-------------------------------------------------------------------------
263 // Visual C++ will complain if HALF_MIN, HALF_NRM_MIN etc. are not float
264 // constants, but at least one other compiler (gcc 2.96) produces incorrect
265 // results if they are.
266 //-------------------------------------------------------------------------
268 #if (defined _WIN32 || defined _WIN64) && defined _MSC_VER
270 #define HALF_MIN 5.96046448e-08f // Smallest positive half
272 #define HALF_NRM_MIN 6.10351562e-05f // Smallest positive normalized half
274 #define HALF_MAX 65504.0f // Largest positive half
276 #define HALF_EPSILON 0.00097656f // Smallest positive e for which
277 // half (1.0 + e) != half (1.0)
280 #define HALF_MIN 5.96046448e-08 // Smallest positive half
282 #define HALF_NRM_MIN 6.10351562e-05 // Smallest positive normalized half
284 #define HALF_MAX 65504.0 // Largest positive half
286 #define HALF_EPSILON 0.00097656 // Smallest positive e for which
287 // half (1.0 + e) != half (1.0)
291 #define HALF_MANT_DIG 11 // Number of digits in mantissa
292 // (significand + hidden leading 1)
294 #define HALF_DIG 2 // Number of base 10 digits that
295 // can be represented without change
297 #define HALF_RADIX 2 // Base of the exponent
299 #define HALF_MIN_EXP -13 // Minimum negative integer such that
300 // HALF_RADIX raised to the power of
301 // one less than that integer is a
304 #define HALF_MAX_EXP 16 // Maximum positive integer such that
305 // HALF_RADIX raised to the power of
306 // one less than that integer is a
309 #define HALF_MIN_10_EXP -4 // Minimum positive integer such
310 // that 10 raised to that power is
313 #define HALF_MAX_10_EXP 4 // Maximum positive integer such
314 // that 10 raised to that power is
318 //---------------------------------------------------------------------------
322 // Representation of a float:
324 // We assume that a float, f, is an IEEE 754 single-precision
325 // floating point number, whose bits are arranged as follows:
333 // X XXXXXXXX XXXXXXXXXXXXXXXXXXXXXXX
337 // S is the sign-bit, e is the exponent and m is the significand.
339 // If e is between 1 and 254, f is a normalized number:
342 // f = (-1) * 2 * 1.m
344 // If e is 0, and m is not zero, f is a denormalized number:
347 // f = (-1) * 2 * 0.m
349 // If e and m are both zero, f is zero:
353 // If e is 255, f is an "infinity" or "not a number" (NAN),
354 // depending on whether m is zero or not.
358 // 0 00000000 00000000000000000000000 = 0.0
359 // 0 01111110 00000000000000000000000 = 0.5
360 // 0 01111111 00000000000000000000000 = 1.0
361 // 0 10000000 00000000000000000000000 = 2.0
362 // 0 10000000 10000000000000000000000 = 3.0
363 // 1 10000101 11110000010000000000000 = -124.0625
364 // 0 11111111 00000000000000000000000 = +infinity
365 // 1 11111111 00000000000000000000000 = -infinity
366 // 0 11111111 10000000000000000000000 = NAN
367 // 1 11111111 11111111111111111111111 = NAN
369 // Representation of a half:
371 // Here is the bit-layout for a half number, h:
379 // X XXXXX XXXXXXXXXX
383 // S is the sign-bit, e is the exponent and m is the significand.
385 // If e is between 1 and 30, h is a normalized number:
388 // h = (-1) * 2 * 1.m
390 // If e is 0, and m is not zero, h is a denormalized number:
393 // h = (-1) * 2 * 0.m
395 // If e and m are both zero, h is zero:
399 // If e is 31, h is an "infinity" or "not a number" (NAN),
400 // depending on whether m is zero or not.
404 // 0 00000 0000000000 = 0.0
405 // 0 01110 0000000000 = 0.5
406 // 0 01111 0000000000 = 1.0
407 // 0 10000 0000000000 = 2.0
408 // 0 10000 1000000000 = 3.0
409 // 1 10101 1111000001 = -124.0625
410 // 0 11111 0000000000 = +infinity
411 // 1 11111 0000000000 = -infinity
412 // 0 11111 1000000000 = NAN
413 // 1 11111 1111111111 = NAN
417 // Converting from a float to a half requires some non-trivial bit
418 // manipulations. In some cases, this makes conversion relatively
419 // slow, but the most common case is accelerated via table lookups.
421 // Converting back from a half to a float is easier because we don't
422 // have to do any rounding. In addition, there are only 65536
423 // different half numbers; we can convert each of those numbers once
424 // and store the results in a table. Later, all conversions can be
425 // done using only simple table lookups.
427 //---------------------------------------------------------------------------
430 //--------------------
431 // Simple constructors
432 //--------------------
441 //----------------------------
442 // Half-from-float constructor
443 //----------------------------
451 // Common special case - zero.
452 // For speed, we don't preserve the zero's sign.
460 // We extract the combined sign and exponent, e, from our
461 // floating-point number, f. Then we convert e to the sign
462 // and exponent of the half number via a table lookup.
464 // For the most common case, where a normalized half is produced,
465 // the table lookup returns a non-zero value; in this case, all
466 // we have to do, is round f's significand to 10 bits and combine
467 // the result with e.
469 // For all other cases (overflow, zeroes, denormalized numbers
470 // resulting from underflow, infinities and NANs), the table
471 // lookup returns zero, and we call a longer, non-inline function
472 // to do the float-to-half conversion.
479 register int e = (x.i >> 23) & 0x000001ff;
486 // Simple case - round the significand and
487 // combine it with the sign and exponent.
490 _h = e + (((x.i & 0x007fffff) + 0x00001000) >> 13);
495 // Difficult case - call a function.
504 //------------------------------------------
505 // Half-to-float conversion via table lookup
506 //------------------------------------------
509 half::operator float () const
511 return _toFloat[_h].f;
515 //-------------------------
516 // Round to n-bit precision
517 //-------------------------
520 half::round (unsigned int n) const
530 // Disassemble h into the sign, s,
531 // and the combined exponent and significand, e.
534 unsigned short s = _h & 0x8000;
535 unsigned short e = _h & 0x7fff;
538 // Round the exponent and significand to the nearest value
539 // where ones occur only in the (10-n) most significant bits.
540 // Note that the exponent adjusts automatically if rounding
541 // up causes the significand to overflow.
549 // Check for exponent overflow.
555 // Overflow occurred -- truncate instead of rounding.
564 // Put the original sign bit back.
574 //-----------------------
575 // Other inline functions
576 //-----------------------
579 half::operator - () const
588 half::operator = (half h)
596 half::operator = (float f)
604 half::operator += (half h)
606 *this = half (float (*this) + float (h));
612 half::operator += (float f)
614 *this = half (float (*this) + f);
620 half::operator -= (half h)
622 *this = half (float (*this) - float (h));
628 half::operator -= (float f)
630 *this = half (float (*this) - f);
636 half::operator *= (half h)
638 *this = half (float (*this) * float (h));
644 half::operator *= (float f)
646 *this = half (float (*this) * f);
652 half::operator /= (half h)
654 *this = half (float (*this) / float (h));
660 half::operator /= (float f)
662 *this = half (float (*this) / f);
668 half::isFinite () const
670 unsigned short e = (_h >> 10) & 0x001f;
676 half::isNormalized () const
678 unsigned short e = (_h >> 10) & 0x001f;
679 return e > 0 && e < 31;
684 half::isDenormalized () const
686 unsigned short e = (_h >> 10) & 0x001f;
687 unsigned short m = _h & 0x3ff;
688 return e == 0 && m != 0;
693 half::isZero () const
695 return (_h & 0x7fff) == 0;
702 unsigned short e = (_h >> 10) & 0x001f;
703 unsigned short m = _h & 0x3ff;
704 return e == 31 && m != 0;
709 half::isInfinity () const
711 unsigned short e = (_h >> 10) & 0x001f;
712 unsigned short m = _h & 0x3ff;
713 return e == 31 && m == 0;
718 half::isNegative () const
720 return (_h & 0x8000) != 0;
760 inline unsigned short
768 half::setBits (unsigned short bits)
773 #undef HALF_EXPORT_CONST