Added option to have deterministic math.

When enabled, compiler optimizations to use fused multiply-add operations
are disabled. SIMD operations that can change behavior (FMA, approximate
reciprocal and reciprocal square root) are removed.

Unit tests for base math types now have strict equality tests when
determinism is enabled. This ensures that both the scalar and SIMD
operations give exactly the same results across platforms. Selective builds
enable deterministic math to ensure full test coverage while avoiding more
total builds than what are present today.

Author: akb825

.github/workflows/main.yml

@@ -24,7 +24,7 @@ jobs:
         - lib_type: Static
           cmake_args: "-DDEEPSEA_SHARED=OFF -DDEEPSEA_X86_ARCH_LEVEL=0"
         - lib_type: Shared
-          cmake_args: "-DDEEPSEA_SHARED=ON"
+          cmake_args: "-DDEEPSEA_SHARED=ON -DDEEPSEA_DETERMINISTIC_MATH=ON"
         - lib_type: Single-Shared
           cmake_args: "-DDEEPSEA_SINGLE_SHARED=ON"
     steps:
@@ -97,7 +97,7 @@ jobs:
         - lib_type: Static
           cmake_args: "-DDEEPSEA_SHARED=OFF"
         - lib_type: Shared
-          cmake_args: "-DDEEPSEA_SHARED=ON"
+          cmake_args: "-DDEEPSEA_SHARED=ON -DDEEPSEA_DETERMINISTIC_MATH=ON"
         - lib_type: Single-Shared
           cmake_args: "-DDEEPSEA_SINGLE_SHARED=ON"
     steps:
@@ -151,7 +151,7 @@ jobs:
         - arch: Win32
           libs: win32
           lib_type: Static
-          cmake_args: "-DDEEPSEA_SHARED=OFF -DDEEPSEA_X86_ARCH_LEVEL=0"
+          cmake_args: "-DDEEPSEA_SHARED=OFF -DDEEPSEA_X86_ARCH_LEVEL=0 -DDEEPSEA_DETERMINISTIC_MATH=ON"
         - arch: Win32
           libs: win32
           lib_type: Shared
@@ -167,7 +167,7 @@ jobs:
         - arch: x64
           libs: win64
           lib_type: Shared
-          cmake_args: "-DDEEPSEA_SHARED=ON"
+          cmake_args: "-DDEEPSEA_SHARED=ON -DDEEPSEA_DETERMINISTIC_MATH=ON"
         - arch: x64
           libs: win64
           lib_type: Single-Shared
@@ -183,7 +183,7 @@ jobs:
       run: |-
         mkdir build
         cd build
-        cmake ${{ matrix.cmake_args }} -A ${{ matrix.arch }} -T v142 ${{ github.workspace }}
+        cmake ${{ matrix.cmake_args }} -A ${{ matrix.arch }} -T v143 ${{ github.workspace }}
       working-directory: "${{ github.workspace }}"
     - name: Build debug
       run: cmake --build . --config Debug

CMakeLists.txt

@@ -70,6 +70,8 @@ set(DEEPSEA_INSTALL_SET_RPATH ON CACHE BOOL "Set rpath for library and tool on i
 set(DEEPSEA_ANDROID_ASSETS_DIR src/main/assets CACHE PATH
 	"Folder relative to project app directory to place assets for Android.")
 set(DEEPSEA_NO_PREBUILT_LIBS OFF CACHE BOOL "Don't use any pre-built library dependencies.")
+set(DEEPSEA_DETERMINISTIC_MATH OFF CACHE BOOL
+	"Ensure determinisitic math results across all platforms at the expense of performance.")
 
 if (CMAKE_SIZEOF_VOID_P EQUAL 8)
 	set(defaultX86ArchLevel 3)

README.md

@@ -169,6 +169,7 @@ To build the examples, an Android Studio project is provided in the android subd
 * `-DDEEPSEA_INSTALL_SET_RPATH=ON|OFF`: Set rpath during install for the library and tool on installation. Set to `OFF` if including in another project that wants to control the rpath. Default is `ON`.
 * `-DDEEPSEA_ANDROID_ASSETS_DIR=folder`: Folder relative to project app directory to place assets for Android. Defaults to `src/main/assets`.
 * `-DDEEPSEA_NO_PREBUILT_LIBS=ON|OFF`: Don't use any pre-built library dependencies. Default is `OFF`.
+* `-DDEEPSEA_DETERMINISTIC_MATH=ON|OFF`: Ensure deterministic math results across all platforms at the expense of performance. The most common use is to have fully deterministic physics simulations when combined with fixed update intervals. Default is `OFF`.
 * `-DDEEPSEA_X86_ARCH_LEVEL=level`: The [x86-64 architecture level](https://en.wikipedia.org/wiki/X86-64), valid for both 32 and 64 bit-targets. A value of 0 indicates the base level, which means that 32-bit targets will have no SSE instructions enabled and will be the same as level 1 for 64-bit targets. In many cases runtime checks are used to choose an implementation with instructions beyond the level set here, but raising the base architecture level allows for these instructions to be used where such checks aren't practical or possible, and also allows for more compiler optimizations. On 64-bit targets this defaults to 3, which supports Intel Haswell (released in 2013) and AMD Excavator (released in 2015) CPUs, and is expected to have the largest speedup beyond level 1. On 32-bit targets this defaults to 1, which has basic SSE1 and SSE2 support. This will be ignored for non-x86 platforms.
 * `-DCMAKE_OSX_DEPLOYMENT_TARGET=version`: Minimum version of macOS to target when building for Mac. Defaults to 10.13, or 11.0 for ARM only, but may be set as low as 10.11.
 

cmake/config.cmake

@@ -55,11 +55,20 @@ if (MSVC)
 				"It is not recommended to have DEEPSEA_SHARED and DEEPSEA_STATIC_RUNTIME both set to ON.")
 		endif()
 	endif()
-	# NOTE: Warning 5105 is to work around an (embarrassing) bug win the Windows headers for
+	# NOTE: Warning 5105 is to work around an (embarrassing) bug with the Windows headers for
 	# Visual Studio 2019 16.8.0.
 	add_compile_options(/W3 /WX /wd4146 /wd5105 /MP)
 	add_definitions(-D_CRT_SECURE_NO_WARNINGS -D_CRT_NONSTDC_NO_WARNINGS)
 
+	# Allow floating-point contractions when not determinsitic math, which matches GCC behavior.
+	# This option was added in Visual Studio 2022. For previous versions, contractions were enabled
+	# for all modes except strict.
+	if (DEEPSEA_DETERMINISTIC_MATH AND MSVC_VERSION LESS 1930)
+		add_compile_options(/fp:strict)
+	elseif (NOT DEEPSEA_DETERMINISTIC_MATH AND MSVC_VERSION GREATER_EQUAL 1930)
+		add_compile_options(/fp:contract)
+	endif()
+
 	# Disable RTTI, but enable exceptions
 	if (CMAKE_CXX_FLAGS MATCHES "/EHs-c- ")
 		string(REPLACE "/EHs-c-" "/EHsc" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
@@ -98,6 +107,9 @@ else()
 		add_compile_options(-fvisibility=hidden)
 		set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fvisibility-inlines-hidden")
 	endif()
+	if (DEEPSEA_DETERMINISTIC_MATH)
+		add_compile_options(-ffp-contract=off)
+	endif()
 
 	# GCC has problems determining array sizes in some versions.
 	if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND CMAKE_CXX_COMPILER_VERSION GREATER_EQUAL 11.0)

modules/Animation/include/DeepSea/Animation/AnimationTree.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022-2025 Aaron Barany
+ * Copyright 2022-2026 Aaron Barany
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,8 +44,8 @@ extern "C"
  *     nodes.
  * @return The animation tree or NULL if an error occurred.
  */
-DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_create(dsAllocator* allocator,
-	const dsAnimationBuildNode* const* rootNodes, uint32_t rootNodeCount);
+DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_create(
+	dsAllocator* allocator, const dsAnimationBuildNode* const* rootNodes, uint32_t rootNodeCount);
 
 /**
  * @brief Creates an animation tree of joints.
@@ -55,8 +55,8 @@ DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_create(dsAllocator* allocat
  * @param nodeCount The number of nodes. It is not valid to have an animation tree with no nodes.
  * @return The animation tree or NULL if an error occurred.
  */
-DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_createJoints(dsAllocator* allocator,
-	const dsAnimationJointBuildNode* nodes, uint32_t nodeCount);
+DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_createJoints(
+	dsAllocator* allocator, const dsAnimationJointBuildNode* nodes, uint32_t nodeCount);
 
 /**
  * @brief Loads an animation tree from a file.
@@ -67,8 +67,8 @@ DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_createJoints(dsAllocator* a
  * @param filePath The file path for the animation tree to load.
  * @return The loaded animation tree or NULL if it couldn't be loaded.
  */
-DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadFile(dsAllocator* allocator,
-	dsAllocator* scratchAllocator, const char* filePath);
+DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadFile(
+	dsAllocator* allocator, dsAllocator* scratchAllocator, const char* filePath);
 
 /**
  * @brief Loads an animation tree from a resource file.
@@ -106,8 +106,8 @@ DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadArchive(dsAllocator* al
  *     current position until the end.
  * @return The loaded animation tree or NULL if it couldn't be loaded.
  */
-DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadStream(dsAllocator* allocator,
-	dsAllocator* scratchAllocator, dsStream* stream);
+DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadStream(
+	dsAllocator* allocator, dsAllocator* scratchAllocator, dsStream* stream);
 
 /**
  * @brief Loads an animation tree from a data buffer.
@@ -119,8 +119,8 @@ DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadStream(dsAllocator* all
  * @param size The size of the data buffer.
  * @return The loaded animation tree or NULL if it couldn't be loaded.
  */
-DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadData(dsAllocator* allocator,
-	dsAllocator* scratchAllocator, const void* data, size_t size);
+DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadData(
+	dsAllocator* allocator, dsAllocator* scratchAllocator, const void* data, size_t size);
 
 /**
  * @brief Clones an animation tree.
@@ -133,8 +133,8 @@ DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_loadData(dsAllocator* alloc
  * @param tree The animation tree.
  * @return The cloned animation tree or NULL if an error occurred.
  */
-DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_clone(dsAllocator* allocator,
-	const dsAnimationTree* tree);
+DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_clone(
+	dsAllocator* allocator, const dsAnimationTree* tree);
 
 /**
  * @brief Finds an animation node by name.
@@ -143,8 +143,8 @@ DS_ANIMATION_EXPORT dsAnimationTree* dsAnimationTree_clone(dsAllocator* allocato
  * @param name The name of the node.
  * @return The found node or NULL if not found.
  */
-DS_ANIMATION_EXPORT const dsAnimationNode* dsAnimationTree_findNodeName(const dsAnimationTree* tree,
-	const char* name);
+DS_ANIMATION_EXPORT const dsAnimationNode* dsAnimationTree_findNodeName(
+	const dsAnimationTree* tree, const char* name);
 
 /**
  * @brief Finds an animation node by name ID.
@@ -153,8 +153,8 @@ DS_ANIMATION_EXPORT const dsAnimationNode* dsAnimationTree_findNodeName(const ds
  * @param nameID The hash of the name of the node.
  * @return The found node or NULL if not found.
  */
-DS_ANIMATION_EXPORT const dsAnimationNode* dsAnimationTree_findNodeID(const dsAnimationTree* tree,
-	uint32_t nameID);
+DS_ANIMATION_EXPORT const dsAnimationNode* dsAnimationTree_findNodeID(
+	const dsAnimationTree* tree, uint32_t nameID);
 
 /**
  * @brief Finds an animation node index by name.
@@ -163,8 +163,8 @@ DS_ANIMATION_EXPORT const dsAnimationNode* dsAnimationTree_findNodeID(const dsAn
  * @param name The name of the node.
  * @return The found node index or DS_NO_ANIMATION_NODE if not found.
  */
-DS_ANIMATION_EXPORT uint32_t dsAnimationTree_findNodeIndexName(const dsAnimationTree* tree,
-	const char* name);
+DS_ANIMATION_EXPORT uint32_t dsAnimationTree_findNodeIndexName(
+	const dsAnimationTree* tree, const char* name);
 
 /**
  * @brief Finds an animation node index by name ID.
@@ -173,8 +173,8 @@ DS_ANIMATION_EXPORT uint32_t dsAnimationTree_findNodeIndexName(const dsAnimation
  * @param nameID The hash of the name of the node.
  * @return The found node index or DS_NO_ANIMATION_NODE if not found.
  */
-DS_ANIMATION_EXPORT uint32_t dsAnimationTree_findNodeIndexID(const dsAnimationTree* tree,
-	uint32_t nameID);
+DS_ANIMATION_EXPORT uint32_t dsAnimationTree_findNodeIndexID(
+	const dsAnimationTree* tree, uint32_t nameID);
 
 /**
  * @brief Updates the transforms for an animation tree.