cpp
/
JoltPhysics
огледало од https://github.com/jrouwe/JoltPhysics.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.12.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Jolt Physics: Building and Using Jolt Physics</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  extensions: ["tex2jax.js"],
  jax: ["input/TeX","output/HTML-CSS"],
});
</script>
<script type="text/javascript" async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectlogo"><img alt="Logo" src="LogoSmall.png"/></td>
  <td id="projectalign">
   <div id="projectname">Jolt Physics
   </div>
   <div id="projectbrief">A multi core friendly Game Physics Engine</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.12.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search',true);
  $(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){initNavTree('md__build_2_r_e_a_d_m_e.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Building and Using Jolt Physics</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="autotoc_md17"></a></p>
<h1><a class="anchor" id="autotoc_md18"></a>
Build Types</h1>
<p>Each platform supports multiple build targets</p>
<ul>
<li>Debug - Debug version of the library, turns on asserts</li>
<li>Release - Release version of the library, no asserts but includes profiling support and can draw the world and simulation properties</li>
<li>ReleaseASAN - As Release but turns on Address Sanitizer (clang only) to find bugs</li>
<li>ReleaseUBSAN - As Release but turns on Undefined Behavior Sanitizer (clang only) to find bugs</li>
<li>ReleaseTSAN - As Release but turns on the Thread Sanitizer (clang only) to find bugs</li>
<li>ReleaseCoverage - As Release but turns on Coverage reporting (clang only) to find which areas of the code are not executed</li>
<li>Distribution - Shippable version of the library, turns off all debugging support</li>
</ul>
<h1><a class="anchor" id="autotoc_md19"></a>
Includes</h1>
<p>The Jolt headers don't include <a class="el" href="_jolt_8h.html">Jolt/Jolt.h</a>. Always include <a class="el" href="_jolt_8h.html">Jolt/Jolt.h</a> before including any other Jolt header. You can use <a class="el" href="_jolt_8h.html">Jolt/Jolt.h</a> in your precompiled header to speed up compilation.</p>
<h1><a class="anchor" id="autotoc_md20"></a>
Defines</h1>
<p>There are a number of user configurable defines that turn on/off certain features: </p><details >
<summary >
General Options (click to see more)</summary>
<ul>
<li>
JPH_SHARED_LIBRARY - Use the Jolt library as a shared library. Use JPH_BUILD_SHARED_LIBRARY to build Jolt as a shared library. </li>
<li>
JPH_PROFILE_ENABLED - Turns on the internal profiler. </li>
<li>
JPH_EXTERNAL_PROFILE - Turns on the internal profiler but forwards the information to a user defined external system (see <a class="el" href="_profiler_8h.html">Profiler.h</a>). Use JPH_USE_EXTERNAL_PROFILE option to enable this from CMake config. </li>
<li>
JPH_DEBUG_RENDERER - Adds support to draw lines and triangles, used to be able to debug draw the state of the world. </li>
<li>
JPH_DISABLE_TEMP_ALLOCATOR - Disables the temporary memory allocator, used mainly to allow ASAN to do its job. </li>
<li>
JPH_DISABLE_CUSTOM_ALLOCATOR - Disables the ability to override the memory allocator. </li>
<li>
JPH_FLOATING_POINT_EXCEPTIONS_ENABLED - Turns on division by zero and invalid floating point exception support in order to detect bugs (Windows only). </li>
<li>
JPH_CROSS_PLATFORM_DETERMINISTIC - Turns on behavior to attempt cross platform determinism. If this is set, JPH_USE_FMADD is ignored. </li>
<li>
JPH_DET_LOG - Turn on a lot of extra logging to help debug determinism issues when JPH_CROSS_PLATFORM_DETERMINISTIC is turned on. </li>
<li>
JPH_ENABLE_ASSERTS - Compiles the library so that it rises an assert in case of failures. The library ignores these failures otherwise. </li>
<li>
JPH_DOUBLE_PRECISION - Compiles the library so that all positions are stored in doubles instead of floats. This makes larger worlds possible. </li>
<li>
JPH_OBJECT_LAYER_BITS - Defines the size of ObjectLayer, must be 16 or 32 bits. </li>
<li>
JPH_OBJECT_STREAM - Includes the code to serialize physics data in the <a class="el" href="class_object_stream.html" title="Base class for object stream input and output streams.">ObjectStream</a> format (mostly used by the examples). </li>
<li>
JPH_NO_FORCE_INLINE - Don't use force inlining but fall back to a regular 'inline'. </li>
<li>
JPH_USE_STD_VECTOR - Use std::vector instead of Jolt's own <a class="el" href="class_array.html">Array</a> class. </li>
<li>
CPP_RTTI_ENABLED - Enable C++ <a class="el" href="class_r_t_t_i.html">RTTI</a> for the library. Disabled by default. </li>
</ul>
</details>
<details >
<summary >
CPU Instruction Sets (click to see more)</summary>
<ul>
<li>
JPH_USE_SSE4_1 - Enable SSE4.1 CPU instructions (default: on, x86/x64 only) </li>
<li>
JPH_USE_SSE4_2 - Enable SSE4.2 CPU instructions (default: on, x86/x64 only) </li>
<li>
JPH_USE_F16C - Enable half float CPU instructions (default: on, x86/x64 only) </li>
<li>
JPH_USE_LZCNT - Enable the lzcnt CPU instruction (default: on, x86/x64 only) </li>
<li>
JPH_USE_TZCNT - Enable the tzcnt CPU instruction (default: on, x86/x64 only) </li>
<li>
JPH_USE_AVX - Enable AVX CPU instructions (default: on, x86/x64 only) </li>
<li>
JPH_USE_AVX2 - Enable AVX2 CPU instructions (default: on, x86/x64 only) </li>
<li>
JPH_USE_AVX512 - Enable AVX512F+AVX512VL CPU instructions (default: off, x86/x64 only) </li>
<li>
JPH_USE_FMADD - Enable fused multiply add CPU instructions (default: on, x86/x64 only) </li>
</ul>
</details>
<h1><a class="anchor" id="autotoc_md21"></a>
Logging &amp; Asserting</h1>
<p>To override the default trace and assert mechanism install your own custom handlers in Trace and AssertFailed (see <a class="el" href="_issue_reporting_8h.html">IssueReporting.h</a>).</p>
<h1><a class="anchor" id="autotoc_md22"></a>
Custom Memory Allocator</h1>
<p>To implement your custom memory allocator override Allocate, Free, Reallocate, AlignedAllocate and AlignedFree (see <a class="el" href="_memory_8h.html">Memory.h</a>).</p>
<h1><a class="anchor" id="autotoc_md23"></a>
Building</h1>
<details >
<summary >
Windows 10+</summary>
<ul style="list-style: none">
<li>
<details >
<summary >
MSVC CL (default compiler)</summary>
<ul>
<li>
Download Visual Studio 2022 (Community or other edition) </li>
<li>
Download CMake 3.20+ (<a href="https://cmake.org/download/">https://cmake.org/download/</a>) </li>
<li>
Run cmake_vs2022_cl.bat </li>
<li>
Open the resulting project file VS2022_CL\JoltPhysics.sln </li>
<li>
Compile and run either 'Samples' or 'UnitTests' </li>
</ul>
</details>
<details >
<summary >
MSVC CL - 32 bit</summary>
<ul>
<li>
Download Visual Studio 2022 (Community or other edition) </li>
<li>
Download CMake 3.20+ (<a href="https://cmake.org/download/">https://cmake.org/download/</a>) </li>
<li>
Run cmake_vs2022_cl_32bit.bat </li>
<li>
Open the resulting project file VS2022_CL_32BIT\JoltPhysics.sln </li>
<li>
Compile and run either 'Samples' or 'UnitTests' </li>
</ul>
</details>
<details >
<summary >
MSVC Clang compiler</summary>
<ul>
<li>
Download Visual Studio 2022 (Community or other edition) </li>
<li>
Make sure to install "C++ Clang Compiler for Windows 11.0.0+" and "C++ Clang-cl for v142+ build tools (x64/x86)" using the Visual Studio Installer </li>
<li>
Download CMake 3.20+ (<a href="https://cmake.org/download/">https://cmake.org/download/</a>) </li>
<li>
Run cmake_vs2022_clang.bat </li>
<li>
Open the resulting project file VS2022_Clang\JoltPhysics.sln </li>
<li>
Compile and run either 'Samples' or 'UnitTests' </li>
</ul>
</details>
<details >
<summary >
MSVC Universal Windows Platform</summary>
<ul>
<li>
Download Visual Studio 2022+ (Community or other edition) </li>
<li>
Make sure to install "Universal Windows Platform development" using the Visual Studio Installer </li>
<li>
Download CMake 3.20+ (<a href="https://cmake.org/download/">https://cmake.org/download/</a>) </li>
<li>
Run cmake_vs2022_uwp.bat </li>
<li>
Open the resulting project file VS2022_UWP\JoltPhysics.sln </li>
<li>
Compile and run 'UnitTests' </li>
</ul>
</details>
<details >
<summary >
MinGW</summary>
<ul>
<li>
Follow download instructions for MSYS2 (<a href="https://www.msys2.org/">https://www.msys2.org/</a>) </li>
<li>
From the MSYS2 MSYS app run: pacman -S &ndash;needed mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake </li>
<li>
From the MSYS2 MINGW x64 app, in the Build folder run: ./cmake_windows_mingw.sh </li>
<li>
Run: cmake &ndash;build MinGW_Debug </li>
<li>
Run: MinGW_Debug/UnitTests.exe </li>
</ul>
</details>
</li>
</ul>
</details>
<details >
<summary >
Linux (Ubuntu)</summary>
<ul>
<li>
Install clang (apt-get install clang) </li>
<li>
Install cmake (apt-get install cmake) </li>
<li>
If you want to build the Samples or JoltViewer, install the <a href="https://vulkan.lunarg.com/doc/view/latest/linux/getting_started_ubuntu.html">Vulkan SDK</a> </li>
<li>
Run: ./cmake_linux_clang_gcc.sh </li>
<li>
Go to the Linux_Debug folder </li>
<li>
Run: make -j$(nproc) &amp;&amp; ./UnitTests </li>
<li>
If you built the samples you can run: ./Samples </li>
</ul>
</details>
<details >
<summary >
Android</summary>
<ul>
<li>
Install Android Studio 2020.3.1+ (<a href="https://developer.android.com/studio/">https://developer.android.com/studio/</a>) </li>
<li>
Open the 'Android' folder in Android Studio and wait until gradle finishes </li>
<li>
Select 'Run' / 'Run...' and 'UnitTests' </li>
<li>
If the screen turns green after a while the unit tests succeeded, when red they failed (see the android log for details) </li>
</ul>
</details>
<details >
<summary >
macOS</summary>
<ul>
<li>
Install XCode </li>
<li>
Download CMake 3.23+ (<a href="https://cmake.org/download/">https://cmake.org/download/</a>) </li>
<li>
Run: ./cmake_xcode_macos.sh </li>
<li>
This will open XCode with a newly generated project </li>
<li>
Build and run the project </li>
<li>
Note that you can also follow the steps in the 'Linux' section if you wish to build without XCode. </li>
</ul>
</details>
<details >
<summary >
iOS</summary>
<ul>
<li>
Install XCode </li>
<li>
Download CMake 3.23+ (<a href="https://cmake.org/download/">https://cmake.org/download/</a>) </li>
<li>
Run: ./cmake_xcode.ios.sh </li>
<li>
This will open XCode with a newly generated project </li>
<li>
Build and run the project (note that this will only work in the simulator as the code signing information is not set up) </li>
</ul>
</details>
<details >
<summary >
Emscripten (tested only on Linux)</summary>
<ul>
<li>
Install Emscripten (<a href="https://emscripten.org/docs/getting_started/downloads.html">https://emscripten.org/docs/getting_started/downloads.html</a>) </li>
<li>
Install nodejs (apt-get install nodejs) </li>
<li>
Download CMake 3.23+ (<a href="https://cmake.org/download/">https://cmake.org/download/</a>) </li>
<li>
Run: ./cmake_linux_emscripten.sh </li>
<li>
Go to the WASM_Debug folder </li>
<li>
Run: make -j$(nproc) &amp;&amp; node UnitTests.js </li>
</ul>
</details>
<h1><a class="anchor" id="autotoc_md24"></a>
Other Build Tools</h1>
<ul>
<li>A vcpkg package is available <a href="https://github.com/microsoft/vcpkg/tree/master/ports/joltphysics">here</a>.</li>
<li>A xmake package is available <a href="https://github.com/xmake-io/xmake-repo/tree/dev/packages/j/joltphysics">here</a>.</li>
<li>A conan package is available <a href="https://conan.io/center/recipes/joltphysics">here</a></li>
<li>Jolt has been verified to build with <a href="https://ninja-build.org/">ninja</a> through CMake.</li>
</ul>
<h1><a class="anchor" id="autotoc_md25"></a>
Errors</h1>
<h2><a class="anchor" id="autotoc_md26"></a>
Link Error: File Format Not Recognized</h2>
<p>If you receive the following error when linking:</p>
<div class="fragment"><div class="line">/usr/bin/ld: libJolt.a: error adding symbols: file format not recognized</div>
</div><!-- fragment --><p>Then you have not enabled interprocedural optimizations (link time optimizations) for your own application. See the INTERPROCEDURAL_OPTIMIZATION option in CMakeLists.txt.</p>
<h2><a class="anchor" id="autotoc_md27"></a>
Link Error: Unresolved External Symbol</h2>
<p>If you receive a link error that looks like:</p>
<div class="fragment"><div class="line">error LNK2001: unresolved external symbol &quot;public: virtual void __cdecl JPH::ConvexShape::GetSubmergedVolume(...) const&quot;</div>
</div><!-- fragment --><p>you have a mismatch in defines between your own code and the Jolt library. In this case the mismatch is in the define <code>JPH_DEBUG_RENDERER</code> which is most likely defined in <code>Jolt.lib</code> and not in your own project. In <code>Debug</code> and <code>Release</code> builds, Jolt by default has <code>JPH_DEBUG_RENDERER</code> defined, in <code>Distribution</code> it is not defined. The cmake options <code>DEBUG_RENDERER_IN_DEBUG_AND_RELEASE</code> and <code>DEBUG_RENDERER_IN_DISTRIBUTION</code> override this behavior.</p>
<p>The <code>RegisterTypes</code> function (which you have to call to initialize the library) checks the other important defines and will trace and abort if there are more mismatches.</p>
<h2><a class="anchor" id="autotoc_md28"></a>
Link Error: Undefined Symbol</h2>
<p>If you receive a link error that looks like:</p>
<div class="fragment"><div class="line">error: undefined symbol: typeinfo for JPH::DebugRenderer</div>
</div><!-- fragment --><p>you have a mismatch between <a class="el" href="class_r_t_t_i.html">RTTI</a> settings (MSVC: <code>/GR</code>/<code>/GR-</code>, clang: <code>-frtti</code>/<code>-fno-rtti</code>). Jolt by default compiles without <a class="el" href="class_r_t_t_i.html">RTTI</a> and if your project compiles with <a class="el" href="class_r_t_t_i.html">RTTI</a> you can get this error. Either turn <a class="el" href="class_r_t_t_i.html">RTTI</a> off for your project or turn it on for Jolt using the CPP_RTTI_ENABLED cmake option.</p>
<h2><a class="anchor" id="autotoc_md29"></a>
DirectX Error</h2>
<p>The samples use DirectX for the graphics implementation, when attempting to run the samples you may get a DirectX error pop-up which may say "The GPU device instance has been suspended", in your debugger you may see the message "Using the Redistributable D3D12 SDKLayers dll also requires that the latest SDKLayers for Windows 10 is installed.".</p>
<p>Fix this by enabling "Graphics Tools" which is an optional Windows settings. To enable it you have to press the windows key, search for "Manage Optional Features", and then click "Add a Feature", and install "Graphics Tools".</p>
<h2><a class="anchor" id="autotoc_md30"></a>
Illegal Instruction Error</h2>
<p>If your CPU doesn't support all of the instructions you'll get an <code>Illegal instruction</code> exception.</p>
<p>On Linux to see what instructions your CPU supports run <code>lscpu</code> and then look at the flags section, on Windows you can use a program like <a href="https://learn.microsoft.com/en-us/sysinternals/downloads/coreinfo"><code>coreinfo</code></a>. Once you know what instructions your cpu supports you can configure the project through cmake and for example disable all special instructions:</p>
<div class="fragment"><div class="line">./cmake_linux_clang_gcc.sh Release clang++ -DUSE_SSE4_1=OFF -DUSE_SSE4_2=OFF -DUSE_AVX=OFF -DUSE_AVX2=OFF -DUSE_AVX512=OFF -DUSE_LZCNT=OFF -DUSE_TZCNT=OFF -DUSE_F16C=OFF -DUSE_FMADD=OFF</div>
</div><!-- fragment --><p>Note that this example is for Linux but the cmake settings work on Windows too.</p>
<h1><a class="anchor" id="autotoc_md31"></a>
Doxygen on Windows</h1>
<p>Documentation can be generated through doxygen:</p>
<ul>
<li>Install Doxygen (<a href="https://www.doxygen.nl/download.html">https://www.doxygen.nl/download.html</a>)</li>
<li>Run: run_doxygen.bat </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.12.0 </li>
  </ul>
</div>
</body>
</html>