This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
ilmbase_half.h
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//
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
93PXR_NAMESPACE_OPEN_SCOPE
94
95namespace pxr_half {
96
97class 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
239GF_API std::ostream & operator << (std::ostream &os, half h);
240GF_API std::istream & operator >> (std::istream &is, half &h);
241
242
243//----------
244// Debugging
245//----------
246
247GF_API void printBits (std::ostream &os, half h);
248GF_API void printBits (std::ostream &os, float f);
249GF_API void printBits (char c[19], half h);
250GF_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
434inline
435half::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
498inline
499half::operator float () const
500{
501 return _toFloat[_h].f;
502}
503
504
505//-------------------------
506// Round to n-bit precision
507//-------------------------
508
509inline half
510half::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
568inline half
569half::operator - () const
570{
571 half h;
572 h._h = _h ^ 0x8000;
573 return h;
574}
575
576
577inline half &
578half::operator = (float f)
579{
580 *this = half (f);
581 return *this;
582}
583
584
585inline half &
586half::operator += (half h)
587{
588 *this = half (float (*this) + float (h));
589 return *this;
590}
591
592
593inline half &
594half::operator += (float f)
595{
596 *this = half (float (*this) + f);
597 return *this;
598}
599
600
601inline half &
602half::operator -= (half h)
603{
604 *this = half (float (*this) - float (h));
605 return *this;
606}
607
608
609inline half &
610half::operator -= (float f)
611{
612 *this = half (float (*this) - f);
613 return *this;
614}
615
616
617inline half &
618half::operator *= (half h)
619{
620 *this = half (float (*this) * float (h));
621 return *this;
622}
623
624
625inline half &
626half::operator *= (float f)
627{
628 *this = half (float (*this) * f);
629 return *this;
630}
631
632
633inline half &
634half::operator /= (half h)
635{
636 *this = half (float (*this) / float (h));
637 return *this;
638}
639
640
641inline half &
642half::operator /= (float f)
643{
644 *this = half (float (*this) / f);
645 return *this;
646}
647
648
649inline bool
650half::isFinite () const
651{
652 unsigned short e = (_h >> 10) & 0x001f;
653 return e < 31;
654}
655
656
657inline bool
658half::isNormalized () const
659{
660 unsigned short e = (_h >> 10) & 0x001f;
661 return e > 0 && e < 31;
662}
663
664
665inline bool
666half::isDenormalized () const
667{
668 unsigned short e = (_h >> 10) & 0x001f;
669 unsigned short m = _h & 0x3ff;
670 return e == 0 && m != 0;
671}
672
673
674inline bool
675half::isZero () const
676{
677 return (_h & 0x7fff) == 0;
678}
679
680
681inline bool
682half::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
690inline bool
691half::isInfinity () const
692{
693 unsigned short e = (_h >> 10) & 0x001f;
694 unsigned short m = _h & 0x3ff;
695 return e == 31 && m == 0;
696}
697
698
699inline bool
700half::isNegative () const
701{
702 return (_h & 0x8000) != 0;
703}
704
705
706inline half
707half::posInf ()
708{
709 half h;
710 h._h = 0x7c00;
711 return h;
712}
713
714
715inline half
716half::negInf ()
717{
718 half h;
719 h._h = 0xfc00;
720 return h;
721}
722
723
724inline half
725half::qNan ()
726{
727 half h;
728 h._h = 0x7fff;
729 return h;
730}
731
732
733inline half
734half::sNan ()
735{
736 half h;
737 h._h = 0x7dff;
738 return h;
739}
740
741
742inline unsigned short
743half::bits () const
744{
745 return _h;
746}
747
748
749inline void
750half::setBits (unsigned short bits)
751{
752 _h = bits;
753}
754
755} // namespace pxr_half
756
757PXR_NAMESPACE_CLOSE_SCOPE
758
759#endif