Add background and file/class-specific details to porting guide

docs/PortingGuide2-3.md

@@ -1,5 +1,4 @@
-OpenEXR/Imath 2.x to 3.x Porting Guide
-======================================
+# OpenEXR/Imath 2.x to 3.x Porting Guide
 
 This porting guide outlines the several areas where switching from OpenEXR
 2.x to OpenEXR 3.x + Imath 3.x will require source code or build changes of
@@ -9,9 +8,7 @@ In each case, we will often explain both how to change if you are expecting
 3.x only hereafter, or usually a more complex accommodation if you want to
 keep compatibility with both 2.x and 3.x.
 
-
-OpenEXR and Imath are different packages now
---------------------------------------------
+## OpenEXR and Imath Are Different Packages
 
 If your use of OpenEXR was only for the sake of using the math classes and
 utilities, maybe you were unhappy that you needed to download and build the
@@ -20,20 +17,128 @@ lightweight open source package. You can use Imath functionality without
 needing any of OpenEXR, which as of 3.x only includes the parts you need to
 read and write OpenEXR image files.
 
-The parts of "IlmBase" that were Imath and `half` are now repackaged as the
-`Imath` library. The IlmThread and Iex libraries have been folded into the
-OpenEXR package, since they were were not necessary to the rest of Imath.
+The parts of "IlmBase" that were `Imath` and `half` are now repackaged
+as the `Imath` library. The `IlmThread` and `Iex` libraries have been
+folded into the OpenEXR package, since they were were not necessary to
+the rest of Imath.
 
 When building OpenEXR 3.x, note that if Imath 3.x library is not found
 already installed at build time, it will be automatically downloaded and
 built as part of the OpenEXR build.
 
-
-
-Finding and using OpenEXR and Imath CMake configs
--------------------------------------------------
-
-**OpenEXR/Imath 3.x only**
+## Background
+
+Why is this happening? Here is the relevant history.
+
+The OpenEXR project has historically consisted of four separate subprojects:
+
+* OpenEXR - the Imf image format
+* IlmBase - supporint utilities (Imath, Half, Iex, IlmThread)
+* PyIlmBase - python bindings for the IlmBase libraries
+* OpenEXR_Viewers - code for an example EXR image viewer 
+
+Prior to the 2.4 release in 2019, OpenEXR relied primarily on the Gnu
+autotools build system and was released as four separate tarballs
+(ilmbase, pyilmbase, openexr, openexr_viewers) that were constructed
+via the Gnug tools. This gave direct access to the "IlmBase" libraries
+indepdendent of the OpenEXR format library. The project also included
+CMake files but CMake support was incomplete.
+
+With the adoption of OpenEXR by the Academy Software Foundation in
+2019, the technical steering committee made several key changes:
+
+1. Drop support for autotools in favor of CMake. A significant portion
+   of the OpenEXR user base uses Windows, which the Gnu autotools does
+   no support.  Supporting two build systems is a maintenance burden
+   that the TSC opted to avoid. We now assume that all modern users of
+   OpenEXR can reasonably be expected to rely on CMake.
+
+2. Rely on GitHub's automatic release packaging mechanism. This
+   packages the entire contents of package in a single
+   tarball. Separate tarballs are no longer generated by the Gnu
+   autotools setup.
+
+3. Deprecate the OpenEXR_Viewers code. It was impossibly out of date
+   and of litle modern value.
+
+Thus, with the 2.4 release, the "IlmBase" libraries are no longer
+distributed in a form that is readily separable from the rest of
+OpenEXR. The build and installation process for the overall OpenEXR
+project is complicated by the fact it consists of four separate
+projects, which added signifcant complexity to the CMake setup.
+
+Because Imath is generally useful to the community, the TSC decided to
+simply the configuration by separating Imath into its own indepdent
+project, maintained and released independently of OpenEXR, and
+introducing it as a new external dependency of OpenEXR.
+
+To further simply matters, the new Imath library includes the half
+data type directly, rather than maintaining it in a separate
+library. Also, the community at large has a strong desire for simple
+vector/matrix utilities that are unencumbered by Iex, the IlmBase
+library that provides higher-level exception classes, and even
+further, a clear delineation between functionality that (1) relies on
+exception handlings and (2) is free from exceptions. As a result,
+support for Iex has been removed from Imath, and the Iex library is
+now packaged as a component of OpenEXR.
+
+The Imath python bindings are a part of Imath as a configuration
+option, although support is off by default to simply the build process
+for most users.
+
+## New Library Names and Repository Structures
+
+The new repositories place all source code under the `src` top-level
+subdirectory.
+
+### Imath:
+
+    src
+    ├── Imath
+    ├── ImathTest
+    └── python
+        ├── config
+        ├── PyImath
+        ├── PyImathNumpy
+        ├── PyImathTest
+        ├── PyImathNumpyTest
+        └── PyImathSpeedTest
+
+
+### OpenEXR:
+
+The 'IlmImf' library has been renamed 'OpenEXR'. No header files have
+changed names, only their locations in the repo have changes.
+
+    src
+    ├── bin
+    │   ├── exr2aces
+    │   ├── exrbuild
+    │   ├── exrcheck
+    │   ├── exrenvmap
+    │   ├── exrheader
+    │   ├── exrmakepreview
+    │   ├── exrmaketiled
+    │   ├── exrmultipart
+    │   ├── exrmultiview
+    │   └── exrstdattr
+    ├── lib
+    │   ├── Iex
+    │   ├── IexMath
+    │   ├── IlmThread
+    │   ├── OpenEXR
+    │   └── OpenEXRUtil
+    ├── examples
+    └── test
+        ├── IexTest
+        ├── OpenEXRTest
+        ├── OpenEXRUtilTest
+        └── OpenEXRFuzzTest
+
+
+## Finding and Using OpenEXR and Imath CMake Configs
+
+### OpenEXR/Imath 3.x only
 
 If you are *only* concerned with OpenEXR/Imath 3.x going forward, this is
 the recommended way to find the libraries in a downstream project that uses
@@ -60,7 +165,7 @@ we have used the `PRIVATE` label, but you should specify them as `PUBLIC` if
 you are exposing those classes in your own package's public interface.
 
 
-**Accommodating OpenEXR/Imath 3.x or OpenEXR 2.x**
+### Accommodating OpenEXR/Imath 3.x or OpenEXR 2.x
 
 On the other hand, to accommodate both 2.x and 3.x, it's admittedly
 inconvenient because the packages and the import targets have changed their
@@ -98,14 +203,12 @@ corresponding to the package version that was found.
 Again, you can eliminate the references to any of the individual libaries
 that you don't actually need for your application.
 
-
-Imath include files are in a different subdirectory
----------------------------------------------------
+## Imath Include Files Are in a Different Subdirectory
 
 Imath 3.0 will copy its headers to some `include/Imath` subdirectory
 instead of the old `include/OpenEXR`.
 
-**OpenEXR/Imath 3.x only**
+### OpenEXR/Imath 3.x only
 
 If you know that you are only using Imath 3.x, then just change any
 include directions, like this:
@@ -118,7 +221,7 @@ to the new locations:
     #include <Imath/ImathVec.h>
     #include <Imath/half.h>
 
-**Accommodating OpenEXR/Imath 3.x or OpenEXR 2.x**
+### Accommodating OpenEXR/Imath 3.x or OpenEXR 2.x
 
 If you want your software to be able to build against either OpenEXR 2.x or
 3.x (depending on which dependency is available at build time), we recommend
@@ -144,8 +247,7 @@ using a more complicated idiom:
     #endif
 
 
-Imath now uses standard C++ exceptions and uses `noexcept`
-----------------------------------------------------------
+## Imath Now Uses Standard C++ Exceptions and `noexcept`
 
 In OpenEXR 2.x, the Imath functions that threw exceptions used to throw
 various Iex varieties.
@@ -162,8 +264,7 @@ that it may be used from code where exceptions are avoided). The functions
 that do not throw exceptions are now marked `noexcept`.
 
 
-Some headers and classes have been removed from Imath 3.x
----------------------------------------------------------
+## Some Headers and Classes Have Been Removed from Imath 3.x
 
 The `Math<T>` class (and `ImathMath.h` header file) are deprecated. All of
 the `Math<T>` functionality is subsumed by C++11 `std::` math functions. For
@@ -185,3 +286,188 @@ been removed. Also the standalone `project()` and `orthogonal()` functions
 are no longer defined for vectors made of integer elements. These all had
 behavior that was hard to understand and probably useless. They still work
 as expected for vectors of floating-point types.
+
+## File/Class-specific changes:
+
+### `half` in half.h
+
+* The half type is now in the `Imath` namespace, but a compile-time
+  option puts it in the global namespace, except when compiling for
+  CUDA, in which case the 'half' type refers to the CUDA type:
+
+    #ifndef __CUDACC__
+    using half = IMATH_INTERNAL_NAMESPACE::half;
+    #else
+    #include <cuda_fp16.h>
+    #endif
+
+  If you desire to use Imath::half inside a CUDA kernal, you can refer
+  to it via the namespace, or define `CUDA_NO_HALF` to avoid the CUDA
+  type altogether.
+
+* `HALF_MIN` has changed value. It is now the smallest **normalized**
+   positive value, returned by `std::numeric_limits<half>::min()`.
+
+* New constructor from a bit pattern:
+
+    enum FromBitsTag
+    {
+        FromBits
+    };
+
+    constexpr half(FromBitsTag, unsigned short bits) noexcept;
+
+### `Imath::Box<T>` in ImathBox.h
+
+* `baseTypeMin()` is replaced with `baseTypeLowest()`
+
+### `Color3<T>`, `Color4<T>` in ImathColor.h
+
+* `baseTypeMin()` is replaced with `baseTypeLowest()`
+
+### `Imath::Frustum<T>` in ImathFrustum.h
+
+Akin to the `Vec` classes, there are now seperate API calls for
+throwing and non-throwing functions:
+
+These functions previously threw exceptions but now do not throw and
+are marked `noexcept`:
+
+* `Frustum<T>::projectionMatrix() noexcept`
+
+* `Frustum<T>::aspect() noexcept`
+
+* `Frustum<T>::set() noexcept`
+
+* `Frustum<T>::projectPointToScreen() noexcept`
+
+* `Frustum<T>::ZToDepth() noexcept`
+
+* `Frustum<T>::DepthToZ() noexcept`
+
+* `Frustum<T>::screenRadius() noexcept`
+
+* `Frustum<T>::localToScreen() noexcept`
+
+These functions throw `std::domain_error` exceptions when the
+associated frustum is degenerate:
+
+* `Frustum<T>::projectionMatrixExc()`
+
+* `Frustum<T>::aspectExc()`
+
+* `Frustum<T>::setExc()`
+
+* `Frustum<T>::projectPointToScreenExc()`
+
+* `Frustum<T>::ZToDepthExc()`
+
+* `Frustum<T>::DepthToZExc()`
+
+* `Frustum<T>::screenRadiusExc()`
+
+* `Frustum<T>::localToScreenExc()`
+
+### `Imath::Interval<T>` in ImathInterval.h
+
+New methods/functions: 
+
+* `Interval<T>::operator !=`
+
+* `Interval<T>::makeInfinite()`
+
+* `Interval<T>isInfinite()`
+
+* `operator<< (std::ostream& s, const Interval<T>&)`
+
+### ImathMatrixAlgo.h
+
+* `checkForZeroScaleInRow()` and `extractAndRemoveScalingAndShear()`
+   throw `std::domain_error` exceptions instead of `Iex::ZeroScale`
+
+### `Matrix22<T>`, `Matrix33<T>`, `Matrix44<T>` in ImathMatrix.h
+
+* `baseTypeMin()` is replaced with `baseTypeLowest()`
+
+* `invert(bool singExc = false)` is replace by:
+
+  - `invert() noexcept`
+
+  - `invert(bool)` which optionally throws an `std::invalid_argument`
+    exception.
+
+* `inverse(bool singExc = false)` is replace by:
+
+  - `inverse() noexcept`
+
+  - `inverse(bool)` which optionally throws an `std::invalid_argument`
+    exception.
+
+* `gjInvert(bool singExc = false)` is replace by:
+
+  - `gjInvert()` noexcept
+
+  - `gjInvert(bool)` which optionally throws an
+    `std::invalid_argument` exception.
+
+* `gJinverse(bool singExc = false)` is replace by:
+
+  - `gjInverse()` noexcept
+
+  - `gjInverse(bool)` which optionally throws an
+    `std::invalid_argument` exception.
+
+New functions:
+
+* `operator<< (std::ostream& s, const Matrix22<T>&)`
+
+* `operator<< (std::ostream& s, const Matrix33<T>&)`
+
+* `operator<< (std::ostream& s, const Matrix44<T>&)`
+
+Other changes:
+
+* Initialization loops unrolled for efficiency
+
+* inline added where appropriate
+
+### ImathRoots.h
+
+* When compiling for CUDA, the `complex` type comes from `thrust`
+  rather than `std`
+
+### ImathVecAlgo.h
+
+The following functions are no longer defined for integer-based
+vecgtors, because such behavior is not clearly defined:
+
+* `project (const Vec& s, const Vec& t)`
+
+* `orgthogonal (const Vec& s, const Vec& t)`
+
+* `reflect (const Vec& s, const Vec& t)`
+
+### `Vec2<T>`, `Vec3<T>`, `Vec4<T>` in ImathVec.h
+
+* `baseTypeMin()` is replaced with `baseTypeLowest()`
+
+* The following methods are removed (via `= delete`) for integer-based
+  vectors because the behavior is not clearly defined and thus prone
+  to confusion:
+
+  - `length()` - although the length is indeed defined, its proper value
+    is floating point and can thus not be represented by the 'T'
+    return type.
+
+  - `normalize()`
+
+  - `normalizeExc()`
+
+  - `normalizeNonNull()`
+
+  - `normalized()`
+
+  - `normalizedExc()`
+
+  - `normalizedNonNull()`
+