HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ilmbase_half.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2002, Industrial Light & Magic, a division of Lucas
4 // Digital Ltd. LLC
5 //
6 // All rights reserved.
7 //
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
10 // met:
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
16 // distribution.
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.
20 //
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.
32 //
33 ///////////////////////////////////////////////////////////////////////////
34 
35 // Primary authors:
36 // Florian Kainz <kainz@ilm.com>
37 // Rod Bogart <rgb@ilm.com>
38 
39 //---------------------------------------------------------------------------
40 //
41 // half -- a 16-bit floating point number class:
42 //
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.
48 //
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:
52 //
53 // half a (3.5);
54 // float b (a + sqrt (a));
55 // a += b;
56 // b += a;
57 // b = a + 7;
58 //
59 // Conversions from half to float are lossless; all half numbers
60 // are exactly representable as floats.
61 //
62 // Conversions from float to half may not preserve a float's value
63 // exactly. If a float is not representable as a half, then the
64 // float value is rounded to the nearest representable half. If a
65 // float value is exactly in the middle between the two closest
66 // representable half values, then the float value is rounded to
67 // the closest half whose least significant bit is zero.
68 //
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.
73 //
74 // The implementation of type half makes the following assumptions
75 // about the implementation of the built-in C++ types:
76 //
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
82 //
83 //---------------------------------------------------------------------------
84 
85 #ifndef PXR_HALF_H
86 #define PXR_HALF_H
87 
88 #include "pxr/pxr.h"
89 #include "pxr/base/gf/api.h"
90 
91 #include <iosfwd>
92 
94 
95 namespace pxr_half {
96 
97 class half
98 {
99  public:
100 
101  //-------------
102  // Constructors
103  //-------------
104 
105  half () = default; // no initialization
106  half (float f);
107  // rule of 5
108  ~half () = default;
109  constexpr half (const half &) noexcept = default;
110  constexpr half (half &&) noexcept = default;
111 
112  //--------------------
113  // Conversion to float
114  //--------------------
115 
116  operator float () const;
117 
118 
119  //------------
120  // Unary minus
121  //------------
122 
123  half operator - () const;
124 
125 
126  //-----------
127  // Assignment
128  //-----------
129 
130  half & operator = (const half &h) = default;
131  half & operator = (half &&h) noexcept = default;
132  half & operator = (float f);
133 
134  half & operator += (half h);
135  half & operator += (float f);
136 
137  half & operator -= (half h);
138  half & operator -= (float f);
139 
140  half & operator *= (half h);
141  half & operator *= (float f);
142 
143  half & operator /= (half h);
144  half & operator /= (float f);
145 
146 
147  //---------------------------------------------------------
148  // Round to n-bit precision (n should be between 0 and 10).
149  // After rounding, the significand's 10-n least significant
150  // bits will be zero.
151  //---------------------------------------------------------
152 
153  half round (unsigned int n) const;
154 
155 
156  //--------------------------------------------------------------------
157  // Classification:
158  //
159  // h.isFinite() returns true if h is a normalized number,
160  // a denormalized number or zero
161  //
162  // h.isNormalized() returns true if h is a normalized number
163  //
164  // h.isDenormalized() returns true if h is a denormalized number
165  //
166  // h.isZero() returns true if h is zero
167  //
168  // h.isNan() returns true if h is a NAN
169  //
170  // h.isInfinity() returns true if h is a positive
171  // or a negative infinity
172  //
173  // h.isNegative() returns true if the sign bit of h
174  // is set (negative)
175  //--------------------------------------------------------------------
176 
177  bool isFinite () const;
178  bool isNormalized () const;
179  bool isDenormalized () const;
180  bool isZero () const;
181  bool isNan () const;
182  bool isInfinity () const;
183  bool isNegative () const;
184 
185 
186  //--------------------------------------------
187  // Special values
188  //
189  // posInf() returns +infinity
190  //
191  // negInf() returns -infinity
192  //
193  // qNan() returns a NAN with the bit
194  // pattern 0111111111111111
195  //
196  // sNan() returns a NAN with the bit
197  // pattern 0111110111111111
198  //--------------------------------------------
199 
200  static half posInf ();
201  static half negInf ();
202  static half qNan ();
203  static half sNan ();
204 
205 
206  //--------------------------------------
207  // Access to the internal representation
208  //--------------------------------------
209 
210  GF_API unsigned short bits () const;
211  GF_API void setBits (unsigned short bits);
212 
213 
214  public:
215 
216  union uif
217  {
218  unsigned int i;
219  float f;
220  };
221 
222  private:
223 
224  GF_API static short convert (int i);
225  GF_API static float overflow ();
226 
227  unsigned short _h;
228 
229  GF_API static const uif _toFloat[1 << 16];
230  GF_API static const unsigned short _eLut[1 << 9];
231 };
232 
233 
234 
235 //-----------
236 // Stream I/O
237 //-----------
238 
239 GF_API std::ostream & operator << (std::ostream &os, half h);
240 GF_API std::istream & operator >> (std::istream &is, half &h);
241 
242 
243 //----------
244 // Debugging
245 //----------
246 
247 GF_API void printBits (std::ostream &os, half h);
248 GF_API void printBits (std::ostream &os, float f);
249 GF_API void printBits (char c[19], half h);
250 GF_API void printBits (char c[35], float f);
251 
252 
253 //-------------------------------------------------------------------------
254 // Limits
255 //
256 // Visual C++ will complain if PXR_HALF_MIN, PXR_HALF_NRM_MIN etc. are not float
257 // constants, but at least one other compiler (gcc 2.96) produces incorrect
258 // results if they are.
259 //-------------------------------------------------------------------------
260 
261 #if (defined _WIN32 || defined _WIN64) && defined _MSC_VER
262 
263  #define PXR_HALF_MIN 5.96046448e-08f // Smallest positive half
264 
265  #define PXR_HALF_NRM_MIN 6.10351562e-05f // Smallest positive normalized half
266 
267  #define PXR_HALF_MAX 65504.0f // Largest positive half
268 
269  #define PXR_HALF_EPSILON 0.00097656f // Smallest positive e for which
270  // half (1.0 + e) != half (1.0)
271 #else
272 
273  #define PXR_HALF_MIN 5.96046448e-08 // Smallest positive half
274 
275  #define PXR_HALF_NRM_MIN 6.10351562e-05 // Smallest positive normalized half
276 
277  #define PXR_HALF_MAX 65504.0 // Largest positive half
278 
279  #define PXR_HALF_EPSILON 0.00097656 // Smallest positive e for which
280  // half (1.0 + e) != half (1.0)
281 #endif
282 
283 
284 #define PXR_HALF_MANT_DIG 11 // Number of digits in mantissa
285  // (significand + hidden leading 1)
286 
287 //
288 // floor( (PXR_HALF_MANT_DIG - 1) * log10(2) ) => 3.01... -> 3
289 #define PXR_HALF_DIG 3 // Number of base 10 digits that
290  // can be represented without change
291 
292 // ceil(PXR_HALF_MANT_DIG * log10(2) + 1) => 4.31... -> 5
293 #define PXR_HALF_DECIMAL_DIG 5 // Number of base-10 digits that are
294  // necessary to uniquely represent all
295  // distinct values
296 
297 #define PXR_HALF_RADIX 2 // Base of the exponent
298 
299 #define PXR_HALF_MIN_EXP -13 // Minimum negative integer such that
300  // PXR_HALF_RADIX raised to the power of
301  // one less than that integer is a
302  // normalized half
303 
304 #define PXR_HALF_MAX_EXP 16 // Maximum positive integer such that
305  // PXR_HALF_RADIX raised to the power of
306  // one less than that integer is a
307  // normalized half
308 
309 #define PXR_HALF_MIN_10_EXP -4 // Minimum positive integer such
310  // that 10 raised to that power is
311  // a normalized half
312 
313 #define PXR_HALF_MAX_10_EXP 4 // Maximum positive integer such
314  // that 10 raised to that power is
315  // a normalized half
316 
317 
318 //---------------------------------------------------------------------------
319 //
320 // Implementation --
321 //
322 // Representation of a float:
323 //
324 // We assume that a float, f, is an IEEE 754 single-precision
325 // floating point number, whose bits are arranged as follows:
326 //
327 // 31 (msb)
328 // |
329 // | 30 23
330 // | | |
331 // | | | 22 0 (lsb)
332 // | | | | |
333 // X XXXXXXXX XXXXXXXXXXXXXXXXXXXXXXX
334 //
335 // s e m
336 //
337 // S is the sign-bit, e is the exponent and m is the significand.
338 //
339 // If e is between 1 and 254, f is a normalized number:
340 //
341 // s e-127
342 // f = (-1) * 2 * 1.m
343 //
344 // If e is 0, and m is not zero, f is a denormalized number:
345 //
346 // s -126
347 // f = (-1) * 2 * 0.m
348 //
349 // If e and m are both zero, f is zero:
350 //
351 // f = 0.0
352 //
353 // If e is 255, f is an "infinity" or "not a number" (NAN),
354 // depending on whether m is zero or not.
355 //
356 // Examples:
357 //
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
368 //
369 // Representation of a half:
370 //
371 // Here is the bit-layout for a half number, h:
372 //
373 // 15 (msb)
374 // |
375 // | 14 10
376 // | | |
377 // | | | 9 0 (lsb)
378 // | | | | |
379 // X XXXXX XXXXXXXXXX
380 //
381 // s e m
382 //
383 // S is the sign-bit, e is the exponent and m is the significand.
384 //
385 // If e is between 1 and 30, h is a normalized number:
386 //
387 // s e-15
388 // h = (-1) * 2 * 1.m
389 //
390 // If e is 0, and m is not zero, h is a denormalized number:
391 //
392 // S -14
393 // h = (-1) * 2 * 0.m
394 //
395 // If e and m are both zero, h is zero:
396 //
397 // h = 0.0
398 //
399 // If e is 31, h is an "infinity" or "not a number" (NAN),
400 // depending on whether m is zero or not.
401 //
402 // Examples:
403 //
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
414 //
415 // Conversion:
416 //
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.
420 //
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.
426 //
427 //---------------------------------------------------------------------------
428 
429 
430 //----------------------------
431 // Half-from-float constructor
432 //----------------------------
433 
434 inline
435 half::half (float f)
436 {
437  uif x;
438 
439  x.f = f;
440 
441  if (f == 0)
442  {
443  //
444  // Common special case - zero.
445  // Preserve the zero's sign bit.
446  //
447 
448  _h = (x.i >> 16);
449  }
450  else
451  {
452  //
453  // We extract the combined sign and exponent, e, from our
454  // floating-point number, f. Then we convert e to the sign
455  // and exponent of the half number via a table lookup.
456  //
457  // For the most common case, where a normalized half is produced,
458  // the table lookup returns a non-zero value; in this case, all
459  // we have to do is round f's significand to 10 bits and combine
460  // the result with e.
461  //
462  // For all other cases (overflow, zeroes, denormalized numbers
463  // resulting from underflow, infinities and NANs), the table
464  // lookup returns zero, and we call a longer, non-inline function
465  // to do the float-to-half conversion.
466  //
467 
468  int e = (x.i >> 23) & 0x000001ff;
469 
470  e = _eLut[e];
471 
472  if (e)
473  {
474  //
475  // Simple case - round the significand, m, to 10
476  // bits and combine it with the sign and exponent.
477  //
478 
479  int m = x.i & 0x007fffff;
480  _h = e + ((m + 0x00000fff + ((m >> 13) & 1)) >> 13);
481  }
482  else
483  {
484  //
485  // Difficult case - call a function.
486  //
487 
488  _h = convert (x.i);
489  }
490  }
491 }
492 
493 
494 //------------------------------------------
495 // Half-to-float conversion via table lookup
496 //------------------------------------------
497 
498 inline
499 half::operator float () const
500 {
501  return _toFloat[_h].f;
502 }
503 
504 
505 //-------------------------
506 // Round to n-bit precision
507 //-------------------------
508 
509 inline half
510 half::round (unsigned int n) const
511 {
512  //
513  // Parameter check.
514  //
515 
516  if (n >= 10)
517  return *this;
518 
519  //
520  // Disassemble h into the sign, s,
521  // and the combined exponent and significand, e.
522  //
523 
524  unsigned short s = _h & 0x8000;
525  unsigned short e = _h & 0x7fff;
526 
527  //
528  // Round the exponent and significand to the nearest value
529  // where ones occur only in the (10-n) most significant bits.
530  // Note that the exponent adjusts automatically if rounding
531  // up causes the significand to overflow.
532  //
533 
534  e >>= 9 - n;
535  e += e & 1;
536  e <<= 9 - n;
537 
538  //
539  // Check for exponent overflow.
540  //
541 
542  if (e >= 0x7c00)
543  {
544  //
545  // Overflow occurred -- truncate instead of rounding.
546  //
547 
548  e = _h;
549  e >>= 10 - n;
550  e <<= 10 - n;
551  }
552 
553  //
554  // Put the original sign bit back.
555  //
556 
557  half h;
558  h._h = s | e;
559 
560  return h;
561 }
562 
563 
564 //-----------------------
565 // Other inline functions
566 //-----------------------
567 
568 inline half
570 {
571  half h;
572  h._h = _h ^ 0x8000;
573  return h;
574 }
575 
576 
577 inline half &
579 {
580  *this = half (f);
581  return *this;
582 }
583 
584 
585 inline half &
587 {
588  *this = half (float (*this) + float (h));
589  return *this;
590 }
591 
592 
593 inline half &
595 {
596  *this = half (float (*this) + f);
597  return *this;
598 }
599 
600 
601 inline half &
603 {
604  *this = half (float (*this) - float (h));
605  return *this;
606 }
607 
608 
609 inline half &
611 {
612  *this = half (float (*this) - f);
613  return *this;
614 }
615 
616 
617 inline half &
619 {
620  *this = half (float (*this) * float (h));
621  return *this;
622 }
623 
624 
625 inline half &
627 {
628  *this = half (float (*this) * f);
629  return *this;
630 }
631 
632 
633 inline half &
635 {
636  *this = half (float (*this) / float (h));
637  return *this;
638 }
639 
640 
641 inline half &
643 {
644  *this = half (float (*this) / f);
645  return *this;
646 }
647 
648 
649 inline bool
651 {
652  unsigned short e = (_h >> 10) & 0x001f;
653  return e < 31;
654 }
655 
656 
657 inline bool
659 {
660  unsigned short e = (_h >> 10) & 0x001f;
661  return e > 0 && e < 31;
662 }
663 
664 
665 inline bool
667 {
668  unsigned short e = (_h >> 10) & 0x001f;
669  unsigned short m = _h & 0x3ff;
670  return e == 0 && m != 0;
671 }
672 
673 
674 inline bool
675 half::isZero () const
676 {
677  return (_h & 0x7fff) == 0;
678 }
679 
680 
681 inline bool
682 half::isNan () const
683 {
684  unsigned short e = (_h >> 10) & 0x001f;
685  unsigned short m = _h & 0x3ff;
686  return e == 31 && m != 0;
687 }
688 
689 
690 inline bool
692 {
693  unsigned short e = (_h >> 10) & 0x001f;
694  unsigned short m = _h & 0x3ff;
695  return e == 31 && m == 0;
696 }
697 
698 
699 inline bool
701 {
702  return (_h & 0x8000) != 0;
703 }
704 
705 
706 inline half
708 {
709  half h;
710  h._h = 0x7c00;
711  return h;
712 }
713 
714 
715 inline half
717 {
718  half h;
719  h._h = 0xfc00;
720  return h;
721 }
722 
723 
724 inline half
726 {
727  half h;
728  h._h = 0x7fff;
729  return h;
730 }
731 
732 
733 inline half
735 {
736  half h;
737  h._h = 0x7dff;
738  return h;
739 }
740 
741 
742 inline unsigned short
743 half::bits () const
744 {
745  return _h;
746 }
747 
748 
749 inline void
750 half::setBits (unsigned short bits)
751 {
752  _h = bits;
753 }
754 
755 } // namespace pxr_half
756 
758 
759 #endif
GF_API std::istream & operator>>(std::istream &is, half &h)
half & operator-=(half h)
Definition: ilmbase_half.h:602
GF_API unsigned short bits() const
Definition: ilmbase_half.h:743
half & operator+=(half h)
Definition: ilmbase_half.h:586
bool isFinite() const
Definition: ilmbase_half.h:650
bool isZero() const
Definition: ilmbase_half.h:675
GLdouble s
Definition: glad.h:3009
half operator-() const
Definition: ilmbase_half.h:569
GF_API std::ostream & operator<<(std::ostream &os, half h)
~half()=default
GF_API void printBits(std::ostream &os, half h)
GLdouble n
Definition: glcorearb.h:2008
GLfloat f
Definition: glcorearb.h:1926
bool isNegative() const
Definition: ilmbase_half.h:700
IMATH_NAMESPACE::V2f float
half & operator/=(half h)
Definition: ilmbase_half.h:634
bool isInfinity() const
Definition: ilmbase_half.h:691
static half sNan()
Definition: ilmbase_half.h:734
bool isDenormalized() const
Definition: ilmbase_half.h:666
static half posInf()
Definition: ilmbase_half.h:707
bool isNan() const
Definition: ilmbase_half.h:682
GLint GLenum GLint x
Definition: glcorearb.h:409
half round(unsigned int n) const
Definition: ilmbase_half.h:510
static half qNan()
Definition: ilmbase_half.h:725
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2002
half & operator=(const half &h)=default
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
static half negInf()
Definition: ilmbase_half.h:716
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
bool isNormalized() const
Definition: ilmbase_half.h:658
half()=default
half & operator*=(half h)
Definition: ilmbase_half.h:618
#define GF_API
Definition: api.h:40
GF_API void setBits(unsigned short bits)
Definition: ilmbase_half.h:750