Build-time half-float Conversion Configuration Options¶
The Imath library supports three options for conversion between 16-bit half and 32-bit float:
Conversion from half to float via a 16-bit lookup table. Prior to Imath v3.1, this was the only method supported.
F16C SSE instructions: single-instruction conversion for machine architectures that support it. When available, this is the fastest option, by far.
Bit-shift conversion algorithm.
To use the F16C SSE instruction set on an architecture that supports
it, simply provide the appropriate compiler flags when building an
application that includes half.h
. For g++ and clang,
for example:
$ cmake -DCMAKE_CXX_FLAGS="-m16fc" <source directory>
When code including half.h
is compiled with F16C enabled, it will
automatically perform conversions using the instruction set. F16C
compiler flags take precedence over other lookup-table-related Imath
CMake settings.
On architectures that do not support F16C, you may choose at
compile-time between the bit-shift conversion and lookup table
conversion via the IMATH_HALF_USE_LOOKUP_TABLE
CMake option:
$ cmake -DIMATH_HALF_USE_LOOKUP_TABLE=OFF <source directory>
Note that when building and installing the Imath library itself, the
65,536-entry lookup table symbol will be compiled into the library
even if the IMATH_HALF_USE_LOOKUP_TABLE
setting is false. This
allows applications using that installed Imath library downstream to
choose at compile time which conversion method to use.
Applications with memory limitations that cannot accomodate the
conversion lookup table can eliminate it from the library by building
Imath with the C preprocessor define IMATH_HALF_NO_LOOKUP_TABLE
defined. Note that this is a compile-time option, not a CMake setting
(making it possible for application code to choose the desired
behavior). Simply add:
#define IMATH_HALF_NO_LOOKUP_TABLE
before including half.h
, or define the symbol on the compile
command line.
Furthermore, an implementation wishing to receive FE_OVERFLOW
and
FE_UNDERFLOW
floating point exceptions when converting float to
half by the bit-shift algorithm can define the preprocessor symbol
IMATH_HALF_ENABLE_FP_EXCEPTIONS
prior to including half.h
:
#define IMATH_HALF_ENABLE_FP_EXCEPTIONS
By default, no exceptions are raised on overflow and underflow.