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 
108  constexpr half (const half& h) = default;
109 
110 
111  //--------------------
112  // Conversion to float
113  //--------------------
114 
115  operator float () const;
116 
117 
118  //------------
119  // Unary minus
120  //------------
121 
122  half operator - () const;
123 
124 
125  //-----------
126  // Assignment
127  //-----------
128 
129  half & operator = (const half &) = default;
130  half & operator = (float f);
131 
132  half & operator += (half h);
133  half & operator += (float f);
134 
135  half & operator -= (half h);
136  half & operator -= (float f);
137 
138  half & operator *= (half h);
139  half & operator *= (float f);
140 
141  half & operator /= (half h);
142  half & operator /= (float f);
143 
144 
145  //---------------------------------------------------------
146  // Round to n-bit precision (n should be between 0 and 10).
147  // After rounding, the significand's 10-n least significant
148  // bits will be zero.
149  //---------------------------------------------------------
150 
151  half round (unsigned int n) const;
152 
153 
154  //--------------------------------------------------------------------
155  // Classification:
156  //
157  // h.isFinite() returns true if h is a normalized number,
158  // a denormalized number or zero
159  //
160  // h.isNormalized() returns true if h is a normalized number
161  //
162  // h.isDenormalized() returns true if h is a denormalized number
163  //
164  // h.isZero() returns true if h is zero
165  //
166  // h.isNan() returns true if h is a NAN
167  //
168  // h.isInfinity() returns true if h is a positive
169  // or a negative infinity
170  //
171  // h.isNegative() returns true if the sign bit of h
172  // is set (negative)
173  //--------------------------------------------------------------------
174 
175  bool isFinite () const;
176  bool isNormalized () const;
177  bool isDenormalized () const;
178  bool isZero () const;
179  bool isNan () const;
180  bool isInfinity () const;
181  bool isNegative () const;
182 
183 
184  //--------------------------------------------
185  // Special values
186  //
187  // posInf() returns +infinity
188  //
189  // negInf() returns -infinity
190  //
191  // qNan() returns a NAN with the bit
192  // pattern 0111111111111111
193  //
194  // sNan() returns a NAN with the bit
195  // pattern 0111110111111111
196  //--------------------------------------------
197 
198  static half posInf ();
199  static half negInf ();
200  static half qNan ();
201  static half sNan ();
202 
203 
204  //--------------------------------------
205  // Access to the internal representation
206  //--------------------------------------
207 
208  GF_API unsigned short bits () const;
209  GF_API void setBits (unsigned short bits);
210 
211 
212  public:
213 
214  union uif
215  {
216  unsigned int i;
217  float f;
218  };
219 
220  private:
221 
222  GF_API static short convert (int i);
223  GF_API static float overflow ();
224 
225  unsigned short _h;
226 
227  GF_API static const uif _toFloat[1 << 16];
228  GF_API static const unsigned short _eLut[1 << 9];
229 };
230 
231 
232 
233 //-----------
234 // Stream I/O
235 //-----------
236 
237 GF_API std::ostream & operator << (std::ostream &os, half h);
238 GF_API std::istream & operator >> (std::istream &is, half &h);
239 
240 
241 //----------
242 // Debugging
243 //----------
244 
245 GF_API void printBits (std::ostream &os, half h);
246 GF_API void printBits (std::ostream &os, float f);
247 GF_API void printBits (char c[19], half h);
248 GF_API void printBits (char c[35], float f);
249 
250 
251 //-------------------------------------------------------------------------
252 // Limits
253 //
254 // Visual C++ will complain if HALF_MIN, HALF_NRM_MIN etc. are not float
255 // constants, but at least one other compiler (gcc 2.96) produces incorrect
256 // results if they are.
257 //-------------------------------------------------------------------------
258 
259 #if (defined _WIN32 || defined _WIN64) && defined _MSC_VER
260 
261  #define HALF_MIN 5.96046448e-08f // Smallest positive half
262 
263  #define HALF_NRM_MIN 6.10351562e-05f // Smallest positive normalized half
264 
265  #define HALF_MAX 65504.0f // Largest positive half
266 
267  #define HALF_EPSILON 0.00097656f // Smallest positive e for which
268  // half (1.0 + e) != half (1.0)
269 #else
270 
271  #define HALF_MIN 5.96046448e-08 // Smallest positive half
272 
273  #define HALF_NRM_MIN 6.10351562e-05 // Smallest positive normalized half
274 
275  #define HALF_MAX 65504.0 // Largest positive half
276 
277  #define HALF_EPSILON 0.00097656 // Smallest positive e for which
278  // half (1.0 + e) != half (1.0)
279 #endif
280 
281 
282 #define HALF_MANT_DIG 11 // Number of digits in mantissa
283  // (significand + hidden leading 1)
284 
285 //
286 // floor( (HALF_MANT_DIG - 1) * log10(2) ) => 3.01... -> 3
287 #define HALF_DIG 3 // Number of base 10 digits that
288  // can be represented without change
289 
290 // ceil(HALF_MANT_DIG * log10(2) + 1) => 4.31... -> 5
291 #define HALF_DECIMAL_DIG 5 // Number of base-10 digits that are
292  // necessary to uniquely represent all
293  // distinct values
294 
295 #define HALF_RADIX 2 // Base of the exponent
296 
297 #define HALF_MIN_EXP -13 // Minimum negative integer such that
298  // HALF_RADIX raised to the power of
299  // one less than that integer is a
300  // normalized half
301 
302 #define HALF_MAX_EXP 16 // Maximum positive integer such that
303  // HALF_RADIX raised to the power of
304  // one less than that integer is a
305  // normalized half
306 
307 #define HALF_MIN_10_EXP -4 // Minimum positive integer such
308  // that 10 raised to that power is
309  // a normalized half
310 
311 #define HALF_MAX_10_EXP 4 // Maximum positive integer such
312  // that 10 raised to that power is
313  // a normalized half
314 
315 
316 //---------------------------------------------------------------------------
317 //
318 // Implementation --
319 //
320 // Representation of a float:
321 //
322 // We assume that a float, f, is an IEEE 754 single-precision
323 // floating point number, whose bits are arranged as follows:
324 //
325 // 31 (msb)
326 // |
327 // | 30 23
328 // | | |
329 // | | | 22 0 (lsb)
330 // | | | | |
331 // X XXXXXXXX XXXXXXXXXXXXXXXXXXXXXXX
332 //
333 // s e m
334 //
335 // S is the sign-bit, e is the exponent and m is the significand.
336 //
337 // If e is between 1 and 254, f is a normalized number:
338 //
339 // s e-127
340 // f = (-1) * 2 * 1.m
341 //
342 // If e is 0, and m is not zero, f is a denormalized number:
343 //
344 // s -126
345 // f = (-1) * 2 * 0.m
346 //
347 // If e and m are both zero, f is zero:
348 //
349 // f = 0.0
350 //
351 // If e is 255, f is an "infinity" or "not a number" (NAN),
352 // depending on whether m is zero or not.
353 //
354 // Examples:
355 //
356 // 0 00000000 00000000000000000000000 = 0.0
357 // 0 01111110 00000000000000000000000 = 0.5
358 // 0 01111111 00000000000000000000000 = 1.0
359 // 0 10000000 00000000000000000000000 = 2.0
360 // 0 10000000 10000000000000000000000 = 3.0
361 // 1 10000101 11110000010000000000000 = -124.0625
362 // 0 11111111 00000000000000000000000 = +infinity
363 // 1 11111111 00000000000000000000000 = -infinity
364 // 0 11111111 10000000000000000000000 = NAN
365 // 1 11111111 11111111111111111111111 = NAN
366 //
367 // Representation of a half:
368 //
369 // Here is the bit-layout for a half number, h:
370 //
371 // 15 (msb)
372 // |
373 // | 14 10
374 // | | |
375 // | | | 9 0 (lsb)
376 // | | | | |
377 // X XXXXX XXXXXXXXXX
378 //
379 // s e m
380 //
381 // S is the sign-bit, e is the exponent and m is the significand.
382 //
383 // If e is between 1 and 30, h is a normalized number:
384 //
385 // s e-15
386 // h = (-1) * 2 * 1.m
387 //
388 // If e is 0, and m is not zero, h is a denormalized number:
389 //
390 // S -14
391 // h = (-1) * 2 * 0.m
392 //
393 // If e and m are both zero, h is zero:
394 //
395 // h = 0.0
396 //
397 // If e is 31, h is an "infinity" or "not a number" (NAN),
398 // depending on whether m is zero or not.
399 //
400 // Examples:
401 //
402 // 0 00000 0000000000 = 0.0
403 // 0 01110 0000000000 = 0.5
404 // 0 01111 0000000000 = 1.0
405 // 0 10000 0000000000 = 2.0
406 // 0 10000 1000000000 = 3.0
407 // 1 10101 1111000001 = -124.0625
408 // 0 11111 0000000000 = +infinity
409 // 1 11111 0000000000 = -infinity
410 // 0 11111 1000000000 = NAN
411 // 1 11111 1111111111 = NAN
412 //
413 // Conversion:
414 //
415 // Converting from a float to a half requires some non-trivial bit
416 // manipulations. In some cases, this makes conversion relatively
417 // slow, but the most common case is accelerated via table lookups.
418 //
419 // Converting back from a half to a float is easier because we don't
420 // have to do any rounding. In addition, there are only 65536
421 // different half numbers; we can convert each of those numbers once
422 // and store the results in a table. Later, all conversions can be
423 // done using only simple table lookups.
424 //
425 //---------------------------------------------------------------------------
426 
427 
428 //----------------------------
429 // Half-from-float constructor
430 //----------------------------
431 
432 inline
433 half::half (float f)
434 {
435  uif x;
436 
437  x.f = f;
438 
439  if (f == 0)
440  {
441  //
442  // Common special case - zero.
443  // Preserve the zero's sign bit.
444  //
445 
446  _h = (x.i >> 16);
447  }
448  else
449  {
450  //
451  // We extract the combined sign and exponent, e, from our
452  // floating-point number, f. Then we convert e to the sign
453  // and exponent of the half number via a table lookup.
454  //
455  // For the most common case, where a normalized half is produced,
456  // the table lookup returns a non-zero value; in this case, all
457  // we have to do is round f's significand to 10 bits and combine
458  // the result with e.
459  //
460  // For all other cases (overflow, zeroes, denormalized numbers
461  // resulting from underflow, infinities and NANs), the table
462  // lookup returns zero, and we call a longer, non-inline function
463  // to do the float-to-half conversion.
464  //
465 
466  int e = (x.i >> 23) & 0x000001ff;
467 
468  e = _eLut[e];
469 
470  if (e)
471  {
472  //
473  // Simple case - round the significand, m, to 10
474  // bits and combine it with the sign and exponent.
475  //
476 
477  int m = x.i & 0x007fffff;
478  _h = e + ((m + 0x00000fff + ((m >> 13) & 1)) >> 13);
479  }
480  else
481  {
482  //
483  // Difficult case - call a function.
484  //
485 
486  _h = convert (x.i);
487  }
488  }
489 }
490 
491 
492 //------------------------------------------
493 // Half-to-float conversion via table lookup
494 //------------------------------------------
495 
496 inline
497 half::operator float () const
498 {
499  return _toFloat[_h].f;
500 }
501 
502 
503 //-------------------------
504 // Round to n-bit precision
505 //-------------------------
506 
507 inline half
508 half::round (unsigned int n) const
509 {
510  //
511  // Parameter check.
512  //
513 
514  if (n >= 10)
515  return *this;
516 
517  //
518  // Disassemble h into the sign, s,
519  // and the combined exponent and significand, e.
520  //
521 
522  unsigned short s = _h & 0x8000;
523  unsigned short e = _h & 0x7fff;
524 
525  //
526  // Round the exponent and significand to the nearest value
527  // where ones occur only in the (10-n) most significant bits.
528  // Note that the exponent adjusts automatically if rounding
529  // up causes the significand to overflow.
530  //
531 
532  e >>= 9 - n;
533  e += e & 1;
534  e <<= 9 - n;
535 
536  //
537  // Check for exponent overflow.
538  //
539 
540  if (e >= 0x7c00)
541  {
542  //
543  // Overflow occurred -- truncate instead of rounding.
544  //
545 
546  e = _h;
547  e >>= 10 - n;
548  e <<= 10 - n;
549  }
550 
551  //
552  // Put the original sign bit back.
553  //
554 
555  half h;
556  h._h = s | e;
557 
558  return h;
559 }
560 
561 
562 //-----------------------
563 // Other inline functions
564 //-----------------------
565 
566 inline half
568 {
569  half h;
570  h._h = _h ^ 0x8000;
571  return h;
572 }
573 
574 
575 inline half &
577 {
578  *this = half (f);
579  return *this;
580 }
581 
582 
583 inline half &
585 {
586  *this = half (float (*this) + float (h));
587  return *this;
588 }
589 
590 
591 inline half &
593 {
594  *this = half (float (*this) + f);
595  return *this;
596 }
597 
598 
599 inline half &
601 {
602  *this = half (float (*this) - float (h));
603  return *this;
604 }
605 
606 
607 inline half &
609 {
610  *this = half (float (*this) - f);
611  return *this;
612 }
613 
614 
615 inline half &
617 {
618  *this = half (float (*this) * float (h));
619  return *this;
620 }
621 
622 
623 inline half &
625 {
626  *this = half (float (*this) * f);
627  return *this;
628 }
629 
630 
631 inline half &
633 {
634  *this = half (float (*this) / float (h));
635  return *this;
636 }
637 
638 
639 inline half &
641 {
642  *this = half (float (*this) / f);
643  return *this;
644 }
645 
646 
647 inline bool
649 {
650  unsigned short e = (_h >> 10) & 0x001f;
651  return e < 31;
652 }
653 
654 
655 inline bool
657 {
658  unsigned short e = (_h >> 10) & 0x001f;
659  return e > 0 && e < 31;
660 }
661 
662 
663 inline bool
665 {
666  unsigned short e = (_h >> 10) & 0x001f;
667  unsigned short m = _h & 0x3ff;
668  return e == 0 && m != 0;
669 }
670 
671 
672 inline bool
673 half::isZero () const
674 {
675  return (_h & 0x7fff) == 0;
676 }
677 
678 
679 inline bool
680 half::isNan () const
681 {
682  unsigned short e = (_h >> 10) & 0x001f;
683  unsigned short m = _h & 0x3ff;
684  return e == 31 && m != 0;
685 }
686 
687 
688 inline bool
690 {
691  unsigned short e = (_h >> 10) & 0x001f;
692  unsigned short m = _h & 0x3ff;
693  return e == 31 && m == 0;
694 }
695 
696 
697 inline bool
699 {
700  return (_h & 0x8000) != 0;
701 }
702 
703 
704 inline half
706 {
707  half h;
708  h._h = 0x7c00;
709  return h;
710 }
711 
712 
713 inline half
715 {
716  half h;
717  h._h = 0xfc00;
718  return h;
719 }
720 
721 
722 inline half
724 {
725  half h;
726  h._h = 0x7fff;
727  return h;
728 }
729 
730 
731 inline half
733 {
734  half h;
735  h._h = 0x7dff;
736  return h;
737 }
738 
739 
740 inline unsigned short
741 half::bits () const
742 {
743  return _h;
744 }
745 
746 
747 inline void
748 half::setBits (unsigned short bits)
749 {
750  _h = bits;
751 }
752 
753 } // namespace pxr_half
754 
756 
757 #endif
GLdouble s
Definition: glew.h:1390
GF_API std::istream & operator>>(std::istream &is, half &h)
half & operator/=(half h)
Definition: ilmbase_half.h:632
bool isDenormalized() const
Definition: ilmbase_half.h:664
bool isZero() const
Definition: ilmbase_half.h:673
static half negInf()
Definition: ilmbase_half.h:714
GF_API std::ostream & operator<<(std::ostream &os, half h)
const GLdouble * m
Definition: glew.h:9124
GF_API void printBits(std::ostream &os, half h)
bool isNormalized() const
Definition: ilmbase_half.h:656
bool isNegative() const
Definition: ilmbase_half.h:698
GLclampf f
Definition: glew.h:3499
GLint GLint GLint GLint GLint x
Definition: glew.h:1252
GLsizei n
Definition: glew.h:4040
const GLfloat * c
Definition: glew.h:16296
GF_API unsigned short bits() const
Definition: ilmbase_half.h:741
bool isNan() const
Definition: ilmbase_half.h:680
static half qNan()
Definition: ilmbase_half.h:723
GLfloat GLfloat GLfloat GLfloat h
Definition: glew.h:8011
half operator-() const
Definition: ilmbase_half.h:567
half round(unsigned int n) const
Definition: ilmbase_half.h:508
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
half & operator*=(half h)
Definition: ilmbase_half.h:616
half & operator-=(half h)
Definition: ilmbase_half.h:600
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
half & operator+=(half h)
Definition: ilmbase_half.h:584
bool isFinite() const
Definition: ilmbase_half.h:648
static half sNan()
Definition: ilmbase_half.h:732
bool isInfinity() const
Definition: ilmbase_half.h:689
static half posInf()
Definition: ilmbase_half.h:705
half & operator=(const half &)=default
half()=default
#define GF_API
Definition: api.h:40
GF_API void setBits(unsigned short bits)
Definition: ilmbase_half.h:748