Simd Improvements & Docs

doc/build.txt

@@ -10,6 +10,7 @@
   - @ref buildBloscSupport
   - @ref buildZLibSupport
   - @ref buildVCPKG
+  - @ref buildSimd
 - @ref buildComponents
 - @ref buildGuide
   - @ref buildBuildTypes
@@ -170,6 +171,49 @@ It is recommended to set the VCPKG_DEFAULT_TRIPLET=x64-windows environment
 variable to use 64-bit libraries by default as even on a 64-bit Windows OS,
 VCPKG builds and installs 32-bit libraries by default.
 
+@subsection buildSimd Building With Target ISA Support
+
+@warning OpenVDB does not perform host CPU ISA detection during configuration
+or build. The selected ISA is treated as a deployment target and must be chosen
+explicitly by the user.
+
+OpenVDB currently only natively supports targeted ISA selection on x86. You can
+continue to provide any flags you like via `-DCXXFLAGS`, but we recommend using
+the available options to better specify intent, when building for a specific
+x86 ISA. The following table lists the available x86 ISA controls.
+
+Build Flag                    | Description                                               |
+----------------------------- | --------------------------------------------------------- |
+`-DUSE_VCL=ON`                | Use the internal copy of Agner Fog's VCL                  |
+`-DOPENVDB_X86_INSTRSET=0`    | Unknown or unspecified                                    |
+`-DOPENVDB_X86_INSTRSET=1`    | SSE, `-msse`                                              |
+`-DOPENVDB_X86_INSTRSET=2`    | ^, SSE2, `-msse2` # Minimum on x86_64                     |
+`-DOPENVDB_X86_INSTRSET=3`    | ^, SSE3, `-msse3`                                         |
+`-DOPENVDB_X86_INSTRSET=4`    | ^, SSSE3, `-mssse3`                                       |
+`-DOPENVDB_X86_INSTRSET=5`    | ^, SSE4.1, `-msse4.1`                                     |
+`-DOPENVDB_X86_INSTRSET=6`    | ^, SSE4.2, `-msse4.2`                                     |
+`-DOPENVDB_X86_INSTRSET=7`    | ^, AVX, `-mavx`                                           |
+`-DOPENVDB_X86_INSTRSET=8`    | ^, AVX2, `-mavx2`                                         |
+`-DOPENVDB_X86_INSTRSET=9`    | ^, AVX512F, `-mavx512f`                                   |
+`-DOPENVDB_X86_INSTRSET=10`   | ^, AVX512BW/DQ/VL, `-mavx512bw` `-mavx512dq` `-mavx512vl` |
+
+The recommended configuration depends on the intended deployment target. See also the
+section on [SIMD in OpenVDB](@ref simdInOpenVDB) for more details.
+
+Deployment Target                        | Recommended Options                        |
+---------------------------------------- | -------------------------------------------|
+Maximum runtime deployment compatibility | Default configuration                      |
+Modern x86 CPUs                          | `-DOPENVDB_X86_INSTRSET=6`                 |
+Explicit SIMD on x86                     | `-DUSE_VCL=ON` `-DOPENVDB_X86_INSTRSET=6`  |
+Explicit SIMD on AVX hardware            | `-DUSE_VCL=ON` `-DOPENVDB_X86_INSTRSET=7`  |
+Explicit SIMD on AVX2 hardware           | `-DUSE_VCL=ON` `-DOPENVDB_X86_INSTRSET=8`  |
+Explicit SIMD on AVX512 hardware         | `-DUSE_VCL=ON` `-DOPENVDB_X86_INSTRSET=10` |
+
+In general, users are encouraged to target the oldest ISA that is known to be
+available on all deployment systems. Building for a newer ISA than is supported
+by the target CPU may result in illegal instruction at runtime.
+
+
 @section buildComponents OpenVDB Components
 
 The following table lists all targets (mainly library and binary components)

doc/doc.txt

@@ -66,7 +66,7 @@ Contributors, please familiarize yourselves with our
   - @ref subsecTreeIter
   - @ref subsecNodeIter
   - @ref subsecValueAccessor
-  - @ref subsecTraversal
+- @ref simdInOpenVDB
 - @subpage transformsAndMaps "Transforms and Maps"
 
 
@@ -529,8 +529,60 @@ a callback mechanism, but developers must be careful to call
 whenever deleting nodes directly.
 
 
-@subsection subsecTraversal Tree Traversal
+@section simdInOpenVDB SIMD in OpenVDB
+
+Many data structures and tools provided with OpenVDB either inherently exhibit
+Single Instruction Multiple Data (SIMD) control flow patterns or are
+purposefully written in such a way that allows them to utilize SIMD
+instructions. OpenVDB provides a unified interface that encourages algorithms
+to be written in a vectorization-friendly manner such that SIMD instructions
+can be heavily utilized. However, to support all hardware and platforms, this
+interface allows for aliasing to the underlying ISA in use. This provides a
+common point of entry for targeted SIMD emission while allowing the underlying
+implementation to vary between scalar code paths and ISA specific SIMD
+implementations. In other words, tools can be written once while generating
+code for the most appropriate instruction set, depending on the target
+hardware.
+
+In this way, OpenVDB targets SIMD instruction generation both implicitly and
+explicitly. The implicit approach simply relies entirely on the compiler's
+auto-vectorizer. However, because use of the SIMD interface is inherently
+auto-vectorizable, improved code generation can often be observed in tools that
+utilize said interface. You can then simply provide your desired ISA flags
+at compile time, with the idea being that C++ compilers can often recognise the
+vectorization patterns exposed by the SIMD interface and can generate efficient
+instructions when appropriate ISA flags are enabled.
+
+This works well for simple usage and typically guarantees a speed-up for tools
+that are already very easy to vectorize. It falls down for more complicated
+programs, especially for programs that rely on more involved mathematical
+operations. For the best performance possible, the SIMD interface also allows
+for explicit instruction set implementations. This means directly calling the inbuilt
+intrinsics that are provided from the various vendors to achieve the most
+optimal code generation possible for the desired ISA.
+
+OpenVDB currently only supports explicit SIMD emission on x86 via the use of
+Agner Fog's Vectorclass (VCL) library. This library provides an extensive set
+of SIMD compatible vector types and mathematical operations that automatically
+map to the selected x86 instruction set at compile time. For example, the
+table below demonstrates what a simd::Vec4f (4 x floats) and a simd::Vec8f
+(8 x floats) represent with various build configurations.
+
+Build Flags                                | OPENVDB_X86_INSTRSET  | simd::Vec4f            | simd::Vec8f            | Notes                                       |
+------------------------------------------ | --------------------- | ---------------------- | ---------------------- | ------------------------------------------- |
+Vanilla CMake Build                        | 0 (Unspecified)       | `math::Tuple<4,float>` | `math::Tuple<8,float>` | No targeting, relies on auto-vectorizer     |
+`-DOPENVDB_X86_INSTRSET=6`                 | 6 (SSE42)             | `math::Tuple<4,float>` | `math::Tuple<8,float>` | `-msse42` relies on auto-vectorizer         |
+`-DUSE_VCL=ON`                             | 2 (SSE2)              | VCL's Vec4f            | VCL's Vec8f (emulated) | `-msse` `-msse2`                            |
+`-DUSE_VCL=ON` `-DOPENVDB_X86_INSTRSET=6`  | 6 (SSE42)             | VCL's Vec4f            | VCL's Vec8f (emulated) | ^, `-msse3` `-mssse3` `-msse4.1` `-msse4.2` |
+`-DUSE_VCL=ON` `-DOPENVDB_X86_INSTRSET=7`  | 7 (AVX)               | VCL's Vec4f            | VCL's Vec8f            | ^, `-mavx`                                  |
+
+Importantly, OpenVDB's CMake performs @b NO host ISA detection at build time.
+It is expected that the user selects the x86 ISA they know to be compatible for
+their deployment and provide it via the `OPENVDB_X86_INSTRSET` enumerated type.
+USE_VCL is OFF by default. When enabled, OpenVDB's CMake will determine the
+available ISA from either the value of `OPENVDB_X86_INSTRSET` or any manually
+provided CXXFLAGS. Note that `OPENVDB_X86_INSTRSET` is never automatically
+inferred and is only defined when explicitly supplied.
 
-<I>To be written</I>
 
 */

ext/THIRD-PARTY.md

@@ -81,9 +81,13 @@ Apache 2.0
 * VCL (c) Copyright 2012-2022 Agner Fog.
   https://github.com/vectorclass/version2
 
-  OpenVDB includes a copy of vectorclass for x86 SIMD intrinsic usage. Usage
-  of VCL is disabled by default and requires the VCL headers to be shipped with
-  OpenVDB installations. This behaviour and usage of VCL can be controlled
+  OpenVDB includes a copy of vectorclass for x86 SIMD intrinsic usage. It
+  includes the following modifications:
+    > Header guards and namespaces have been renamed or prefixed with
+      OPENVDB_VCL defines.
+    > Examples and runtime instruction set detection have been removed.
+  Use of VCL is disabled by default and requires the VCL headers to be shipped
+  with OpenVDB installations. This behaviour and usage of VCL can be controlled
   during OpenVDB configuration. See the full LICENSE terms in:
 
     vcl/openvdb/ext/vcl/LICENSE

ext/vcl/openvdb/ext/vcl/instrset.h

@@ -18,10 +18,20 @@
 *
 * (c) Copyright 2012-2023 Agner Fog.
 * Apache License version 2.0 or later.
+*
+* -----------------------------------------------------------------------------
+*
+* This file has been modified from the original in the following ways:
+*  > Various defines and guards have been prefixed with OPENVDB_VCL_.
+*  > VCL_NAMESPACE has been removed in favour of an explicit OPENVDB_VCL_NAMESPACE.
+*  > The const_int and const_uint macros have been removed
+* Copyright Contributors to the OpenVDB Project
+* SPDX-License-Identifier: Apache-2.0*
+*
 ******************************************************************************/
 
-#ifndef INSTRSET_H
-#define INSTRSET_H 20200
+#ifndef OPENVDB_VCL_INSTRSET_H
+#define OPENVDB_VCL_INSTRSET_H 20200
 
 // check if compiled for C++17
 #if defined(_MSVC_LANG)  // MS compiler has its own version of __cplusplus with different value
@@ -172,9 +182,7 @@ We need different version checks with and whithout __apple_build_version__
 #endif
 
 
-#ifdef VCL_NAMESPACE
-namespace VCL_NAMESPACE {
-#endif
+namespace OPENVDB_VCL_NAMESPACE {
 
 // Constant for indicating don't care in permute and blend functions.
 // V_DC is -256 in Vector class library version 1.xx
@@ -361,17 +369,8 @@ constexpr int bit_scan_reverse_const(uint64_t const n) {
 *
 *****************************************************************************/
 
-#ifdef VCL_NAMESPACE
-#define NAMESPACEPREFIX VCL_NAMESPACE::
-#else 
-#define NAMESPACEPREFIX
-#endif
-
 template <int32_t  n> class Const_int_t {};                // represent compile-time signed integer constant
 template <uint32_t n> class Const_uint_t {};               // represent compile-time unsigned integer constant
-#define const_int(n)  (NAMESPACEPREFIX Const_int_t <n>())  // n must be compile-time integer constant
-#define const_uint(n) (NAMESPACEPREFIX Const_uint_t<n>())  // n must be compile-time unsigned integer constant
-
 
 // template for producing quiet NAN
 template <class VTYPE>
@@ -1446,9 +1445,7 @@ auto blend_half(W const& a, W const& b) {
 }
 
 
-#ifdef VCL_NAMESPACE
 }
-#endif
 
 
-#endif // INSTRSET_H
+#endif // OPENVDB_VCL_INSTRSET_H

ext/vcl/openvdb/ext/vcl/vector_convert.h

@@ -10,22 +10,29 @@
 *
 * (c) Copyright 2012-2022 Agner Fog.
 * Apache License version 2.0 or later.
+*
+* -----------------------------------------------------------------------------
+*
+* This file has been modified from the original in the following ways:
+*  > Various defines and guards have been prefixed with OPENVDB_VCL_.
+*  > VCL_NAMESPACE has been removed in favour of an explicit OPENVDB_VCL_NAMESPACE.
+* Copyright Contributors to the OpenVDB Project
+* SPDX-License-Identifier: Apache-2.0*
+*
 *****************************************************************************/
 
-#ifndef VECTOR_CONVERT_H
-#define VECTOR_CONVERT_H
+#ifndef OPENVDB_VCL_VECTOR_CONVERT_H
+#define OPENVDB_VCL_VECTOR_CONVERT_H
 
-#ifndef VECTORCLASS_H
+#ifndef OPENVDB_VCL_VECTORCLASS_H
 #include "vectorclass.h"
 #endif
 
-#if VECTORCLASS_H < 20200
+#if OPENVDB_VCL_VECTORCLASS_H < 20200
 #error Incompatible versions of vector class library mixed
 #endif
 
-#ifdef VCL_NAMESPACE
-namespace VCL_NAMESPACE {
-#endif
+namespace OPENVDB_VCL_NAMESPACE {
 
 #if MAX_VECTOR_SIZE >= 256
 
@@ -821,8 +828,6 @@ static inline V fmodulo(V const numerator, double const denominator) {
     }
 }
 
-#ifdef VCL_NAMESPACE
 }
-#endif
 
-#endif // VECTOR_CONVERT_H
+#endif // OPENVDB_VCL_VECTOR_CONVERT_H

ext/vcl/openvdb/ext/vcl/vectorclass.h

@@ -24,10 +24,19 @@
 *
 * (c) Copyright 2012-2026 Agner Fog.
 * Apache License version 2.0 or later.
+*
+* -----------------------------------------------------------------------------
+*
+* This file has been modified from the original in the following ways:
+*  > Various defines and guards have been prefixed with OPENVDB_VCL_.
+*  > VCL_NAMESPACE has been removed in favour of an explicit OPENVDB_VCL_NAMESPACE.
+* Copyright Contributors to the OpenVDB Project
+* SPDX-License-Identifier: Apache-2.0*
+*
 ******************************************************************************/
 
-#ifndef VECTORCLASS_H
-#define VECTORCLASS_H  20203
+#ifndef OPENVDB_VCL_VECTORCLASS_H
+#define OPENVDB_VCL_VECTORCLASS_H  20203
 
 // Maximum vector size, bits. Allowed values are 128, 256, 512
 #ifndef MAX_VECTOR_SIZE
@@ -78,10 +87,10 @@
 #endif  // INSTRSET >= 2
 
 
-#else   // VECTORCLASS_H
+#else   // OPENVDB_VCL_VECTORCLASS_H
 
-#if VECTORCLASS_H < 20000
+#if OPENVDB_VCL_VECTORCLASS_H < 20000
 #error Mixed versions of vector class library
 #endif
 
-#endif  // VECTORCLASS_H
+#endif  // OPENVDB_VCL_VECTORCLASS_H

ext/vcl/openvdb/ext/vcl/vectorf128.h

@@ -20,23 +20,30 @@
 *
 * (c) Copyright 2012-2023 Agner Fog.
 * Apache License version 2.0 or later.
+*
+* -----------------------------------------------------------------------------
+*
+* This file has been modified from the original in the following ways:
+*  > Various defines and guards have been prefixed with OPENVDB_VCL_.
+*  > VCL_NAMESPACE has been removed in favour of an explicit OPENVDB_VCL_NAMESPACE.
+* Copyright Contributors to the OpenVDB Project
+* SPDX-License-Identifier: Apache-2.0*
+*
 *****************************************************************************/
 
-#ifndef VECTORF128_H
-#define VECTORF128_H
+#ifndef OPENVDB_VCL_VECTORF128_H
+#define OPENVDB_VCL_VECTORF128_H
 
-#ifndef VECTORCLASS_H
+#ifndef OPENVDB_VCL_VECTORCLASS_H
 #include "vectorclass.h"
 #endif
 
-#if VECTORCLASS_H < 20200
+#if OPENVDB_VCL_VECTORCLASS_H < 20200
 #error Incompatible versions of vector class library mixed
 #endif
 
 
-#ifdef VCL_NAMESPACE
-namespace VCL_NAMESPACE {
-#endif
+namespace OPENVDB_VCL_NAMESPACE {
 
 /*****************************************************************************
 *
@@ -1180,11 +1187,7 @@ static inline Vec4f pow(Vec4f const a, Const_int_t<n>) {
 }
 
 // implement the same as macro pow_const(vector, int)
-#ifdef VCL_NAMESPACE
-#define pow_const(x,n) pow(x, VCL_NAMESPACE::Const_int_t<n>())
-#else
-#define pow_const(x,n) pow(x,Const_int_t<n>())
-#endif
+#define pow_const(x,n) pow(x, OPENVDB_VCL_NAMESPACE::Const_int_t<n>())
 
 static inline Vec4f round(Vec4f const a) {
 #if INSTRSET >= 5   // SSE4.1 supported
@@ -2974,8 +2977,6 @@ static inline uint8_t to_bits(Vec2db const x) {
 #endif  // INSTRSET < 10
 
 
-#ifdef VCL_NAMESPACE
 }
-#endif
 
-#endif // VECTORF128_H
+#endif // OPENVDB_VCL_VECTORF128_H