1% Embree: High Performance Ray Tracing Kernels 3.13.2 2% Intel Corporation 3 4Embree Overview 5=============== 6 7Intel® Embree is a collection of high-performance ray tracing kernels, 8developed at Intel. The target users of Intel® Embree are graphics application 9engineers who want to improve the performance of their 10photo-realistic rendering application by leveraging Embree's 11performance-optimized ray tracing kernels. The kernels are optimized 12for the latest Intel® processors with support for SSE, AVX, AVX2, and 13AVX-512 instructions. Intel® Embree supports runtime code selection to choose 14the traversal and build algorithms that best matches the instruction 15set of your CPU. We recommend using Intel® Embree through its API to get the 16highest benefit from future improvements. Intel® Embree is released as Open 17Source under the 18[Apache 2.0 license](http://www.apache.org/licenses/LICENSE-2.0). 19 20Intel® Embree supports applications written with the Intel® SPMD Program 21Compiler (ISPC, <https://ispc.github.io/>) by also providing an ISPC 22interface to the core ray tracing algorithms. This makes it possible 23to write a renderer in ISPC that automatically vectorizes and 24leverages SSE, AVX, AVX2, and AVX-512 instructions. ISPC also supports 25runtime code selection, thus ISPC will select the best code path for 26your application. 27 28Intel® Embree contains algorithms optimized for incoherent workloads (e.g. 29Monte Carlo ray tracing algorithms) and coherent workloads 30(e.g. primary visibility and hard shadow rays). 31 32The single-ray traversal kernels of Intel® Embree provide high performance 33for incoherent workloads and are very easy to integrate into existing 34rendering applications. Using the stream kernels, even higher 35performance for incoherent rays is possible, but integration might 36require significant code changes to the application to use the stream 37paradigm. In general for coherent workloads, the stream mode with 38coherent flag set gives the best performance. 39 40Intel® Embree also supports dynamic scenes by implementing high-performance 41two-level spatial index structure construction algorithms. 42 43In addition to the ray tracing kernels, Intel® Embree provides some 44[Embree Tutorials] to demonstrate how to use the 45[Embree API]. 46 47Supported Platforms 48------------------- 49 50Embree supports Windows (32-bit and 64-bit), Linux (64-bit), and macOS 51(64-bit) both x86 and Apple M1 based. The code compiles with the Intel® 52Compiler, GCC, Clang, and the Microsoft Compiler. 53 54Using the Intel® Compiler improves performance by approximately 5510%. Performance also varies across different operating 56systems, with Linux typically performing best as it supports 57transparently transitioning to 2MB pages. 58 59Embree is optimized for Intel CPUs supporting SSE, AVX, AVX2, and 60AVX-512 instructions. Embree requires at least an x86 CPU with support for 61SSE2 or an Apple M1 CPU. 62Embree Support and Contact 63-------------------------- 64 65If you encounter bugs please report them via [Embree's GitHub Issue 66Tracker](https://github.com/embree/embree/issues). 67 68For questions and feature requests please write us at 69<embree_support@intel.com>. 70 71To receive notifications of updates and new features of Embree please 72subscribe to the [Embree mailing 73list](https://groups.google.com/d/forum/embree/). 74 75Installation of Embree 76====================== 77 78Windows MSI Installer 79--------------------- 80 81You can install the Embree library using the Windows MSI installer 82[embree-3.13.2-x64.vc14.msi](https://github.com/embree/embree/releases/download/v3.13.2/embree-3.13.2.x64.vc14.msi). This 83will install the 64-bit Embree version by default in `Program 84Files\Intel\Embree3`. 85 86You have to set the path to the `bin` folders manually to your `PATH` 87environment variable for applications to find Embree. 88 89To compile applications with Embree using CMake, please have a look at 90the `find_embree` tutorial. To compile this tutorial, you need to set 91the `embree_DIR` CMake variable of this tutorial to `Program 92Files\Intel\Embree3`. 93 94To uninstall Embree, open `Programs and Features` by clicking the 95`Start button`, clicking `Control Panel`, clicking `Programs`, and 96then clicking `Programs and Features`. Select `Embree 973.13.2 x64` and uninstall it. 98 99Windows ZIP File 100----------------- 101 102Embree linked against Visual Studio 2015 are provided as a ZIP file 103[embree-3.13.2.x64.vc14.windows.zip](https://github.com/embree/embree/releases/download/v3.13.2/embree-3.13.2.x64.vc14.windows.zip). After 104unpacking this ZIP file, you should set the path to the `lib` folder 105manually to your `PATH` environment variable for applications to find 106Embree. To compile applications with Embree, you also have to set the 107`Include Directories` path in Visual Studio to the `include` folder of 108the Embree installation. 109 110If you plan to ship Embree with your application, best use the Embree 111version from this ZIP file. 112 113Linux tar.gz Files 114------------------ 115 116The Linux version of Embree is also delivered as a `tar.gz` file: 117[embree-3.13.2.x86_64.linux.tar.gz](https://github.com/embree/embree/releases/download/v3.13.2/embree-3.13.2.x86_64.linux.tar.gz). Unpack 118this file using `tar` and source the provided `embree-vars.sh` (if you 119are using the bash shell) or `embree-vars.csh` (if you are using the C 120shell) to set up the environment properly: 121 122 tar xzf embree-3.13.2.x86_64.linux.tar.gz 123 source embree-3.13.2.x86_64.linux/embree-vars.sh 124 125If you want to ship Embree with your application, best use the Embree 126version provided in the `tar.gz` file. 127 128We recommend adding a relative `RPATH` to your application that points 129to the location where Embree (and TBB) can be found, e.g. `$ORIGIN/../lib`. 130 131macOS PKG Installer 132------------------- 133 134To install the Embree library on your macOS system use the 135provided package installer inside 136[embree-3.13.2.x86_64.pkg](https://github.com/embree/embree/releases/download/v3.13.2/embree-3.13.2.x86_64.pkg). This 137will install Embree by default into `/opt/local/lib` and 138`/opt/local/include` directories. The Embree tutorials are installed 139into the `/Applications/Embree3` directory. 140 141You also have to install the Intel® Threading Building Blocks (TBB) 142using [MacPorts](http://www.macports.org/): 143 144 sudo port install tbb 145 146Alternatively you can download the latest TBB version from 147[https://www.threadingbuildingblocks.org/download](https://www.threadingbuildingblocks.org/download) 148and set the `DYLD_LIBRARY_PATH` environment variable to point 149to the TBB library. 150 151To uninstall Embree, execute the uninstaller script 152`/Applications/Embree3/uninstall.command`. 153 154macOS ZIP file 155----------------- 156 157The macOS version of Embree is also delivered as a ZIP file: 158[embree-3.13.2.x86_64.macosx.zip](https://github.com/embree/embree/releases/download/v3.13.2/embree-3.13.2.x86_64.macosx.zip). Unpack 159this file using `tar` and source the provided `embree-vars.sh` (if you 160are using the bash shell) or `embree-vars.csh` (if you are using the C 161shell) to set up the environment properly: 162 163 unzip embree-3.13.2.x64.macosx.zip 164 source embree-3.13.2.x64.macosx/embree-vars.sh 165 166If you want to ship Embree with your application, please use the Embree 167library of the provided ZIP file. The library name of that Embree 168library is of the form `@rpath/libembree.3.dylib` 169(and similar also for the included TBB library). This ensures that you 170can add a relative `RPATH` to your application that points to the location 171where Embree (and TBB) can be found, e.g. `@loader_path/../lib`. 172 173Compiling Embree 174================ 175 176We recommend to use CMake to build Embree. Do not enable fast-math 177optimizations; these might break Embree. 178 179Linux and macOS 180--------------- 181 182To compile Embree you need a modern C++ compiler that supports 183C++11. Embree is tested with the following compilers: 184 185Linux 186 187 - Intel® Compiler 2020 Update 1 188 - Intel® Compiler 2019 Update 4 189 - Intel® Compiler 2017 Update 1 190 - Intel® Compiler 2016 Update 3 191 - Intel® Compiler 2015 Update 3 192 - Clang 5.0.0 193 - Clang 4.0.0 194 - GCC 10.0.1 (Fedora 32) AVX512 support 195 - GCC 8.3.1 (Fedora 28) AVX512 support 196 - GCC 7.3.1 (Fedora 27) AVX2 support 197 - GCC 7.3.1 (Fedora 26) AVX2 support 198 - GCC 6.4.1 (Fedora 25) AVX2 support 199 200macOS x86 201 202 - Intel® Compiler 2020 Update 1 203 - Intel® Compiler 2019 Update 4 204 - Apple LLVM 10.0.1 (macOS 10.14.6) 205 206macOS M1 207 208 - Apple Clang 12.0.0 209 210Embree supports using the Intel® Threading Building Blocks (TBB) as the 211tasking system. For performance and flexibility reasons we recommend 212to use Embree with the Intel® Threading Building Blocks (TBB) and best 213also use TBB inside your application. Optionally you can disable TBB 214in Embree through the `EMBREE_TASKING_SYSTEM` CMake variable. 215 216Embree supports the Intel® SPMD Program Compiler (ISPC), which allows 217straightforward parallelization of an entire renderer. If you do not 218want to use ISPC then you can disable `EMBREE_ISPC_SUPPORT` in 219CMake. Otherwise, download and install the ISPC binaries (we have 220tested ISPC version 1.9.1) from 221[ispc.github.io](https://ispc.github.io/downloads.html). After 222installation, put the path to `ispc` permanently into your `PATH` 223environment variable or you need to correctly set the 224`ISPC_EXECUTABLE` variable during CMake configuration. 225 226You additionally have to install CMake 3.1.0 or higher and the developer 227version of GLUT. 228 229Under macOS, all these dependencies can be installed 230using [MacPorts](http://www.macports.org/): 231 232 sudo port install cmake tbb-devel glfw-devel 233 234Depending on your Linux distribution you can install these dependencies 235using `yum` or `apt-get`. Some of these packages might already be 236installed or might have slightly different names. 237 238Type the following to install the dependencies using `yum`: 239 240 sudo yum install cmake 241 sudo yum install tbb-devel 242 sudo yum install glfw-devel 243 244Type the following to install the dependencies using `apt-get`: 245 246 sudo apt-get install cmake-curses-gui 247 sudo apt-get install libtbb-dev 248 sudo apt-get install libglfw3-dev 249 250Finally you can compile Embree using CMake. Create a build directory 251inside the Embree root directory and execute `ccmake ..` inside this 252build directory. 253 254 mkdir build 255 cd build 256 ccmake .. 257 258Per default CMake will use the compilers specified with the `CC` and 259`CXX` environment variables. Should you want to use a different 260compiler, run `cmake` first and set the `CMAKE_CXX_COMPILER` and 261`CMAKE_C_COMPILER` variables to the desired compiler. For example, to 262use the Intel® Compiler instead of the default GCC on most Linux machines 263(`g++` and `gcc`), execute 264 265 cmake -DCMAKE_CXX_COMPILER=icpc -DCMAKE_C_COMPILER=icc .. 266 267Similarly, to use Clang set the variables to `clang++` and `clang`, 268respectively. Note that the compiler variables cannot be changed anymore 269after the first run of `cmake` or `ccmake`. 270 271Running `ccmake` will open a dialog where you can perform various 272configurations as described below in [CMake Configuration]. After having 273configured Embree, press `c` (for configure) and `g` (for generate) to 274generate a Makefile and leave the configuration. The code can be 275compiled by executing make. 276 277 make 278 279The executables will be generated inside the build folder. We recommend 280to finally install the Embree library and header files on your 281system. Therefore set the `CMAKE_INSTALL_PREFIX` to `/usr` in cmake 282and type: 283 284 sudo make install 285 286If you keep the default `CMAKE_INSTALL_PREFIX` of `/usr/local` then 287you have to make sure the path `/usr/local/lib` is in your 288`LD_LIBRARY_PATH`. 289 290You can also uninstall Embree again by executing: 291 292 sudo make uninstall 293 294If you cannot install Embree on your system (e.g. when you don't have 295administrator rights) you need to add embree_root_directory/build to 296your `LD_LIBRARY_PATH`. 297 298 299Windows 300------- 301 302Embree is tested using the following compilers under Windows: 303 304 - Visual Studio 2019 305 - Visual Studio 2017 306 - Visual Studio 2015 (Update 1) 307 - Intel® Compiler 2019 Update 6 308 - Intel® Compiler 2017 Update 8 309 - LLVM Clang 9.0.0 310 311To compile Embree for AVX-512 you have to use the Intel® Compiler. 312 313Embree supports using the Intel® Threading Building Blocks (TBB) as the 314tasking system. For performance and flexibility reasons we recommend 315to use Embree with the Intel® Threading Building Blocks (TBB) and best 316also use TBB inside your application. Optionally you can disable TBB 317in Embree through the `EMBREE_TASKING_SYSTEM` CMake variable. 318 319Embree will either find the Intel® Threading Building Blocks (TBB) 320installation that comes with the Intel® Compiler, or you can install the 321binary distribution of TBB directly from 322[www.threadingbuildingblocks.org](https://www.threadingbuildingblocks.org/download) 323into a folder named `tbb` into your Embree root directory. You also have 324to make sure that the libraries `tbb.dll` and `tbb_malloc.dll` can be 325found when executing your Embree applications, e.g. by putting the path 326to these libraries into your `PATH` environment variable. 327 328Embree supports the Intel® SPMD Program Compiler (ISPC), which allows 329straightforward parallelization of an entire renderer. When installing 330ISPC, make sure to download an ISPC version from 331[ispc.github.io](https://ispc.github.io/downloads.html) that is 332compatible with your Visual Studio version. After installation, put 333the path to `ispc.exe` permanently into your `PATH` environment 334variable or you need to correctly set the `ISPC_EXECUTABLE` variable 335during CMake configuration. If you do not want to use ISPC then you 336can disable `EMBREE_ISPC_SUPPORT` in CMake. 337 338We have tested Embree with the following ISPC versions: 339 340 - ISPC 1.14.1 341 - ISPC 1.13.0 342 - ISPC 1.12.0 343 - ISPC 1.9.2 344 345You additionally have to install [CMake](http://www.cmake.org/download/) 346(version 2.8.11 or higher). Note that you need a native Windows CMake 347installation, because CMake under Cygwin cannot generate solution files 348for Visual Studio. 349 350### Using the IDE 351 352Run `cmake-gui`, browse to the Embree sources, set the build directory 353and click Configure. Now you can select the Generator, e.g. "Visual 354Studio 12 2013" for a 32-bit build or "Visual Studio 12 2013 Win64" 355for a 64-bit build. 356 357To use a different compiler than the Microsoft Visual C++ compiler, you 358additionally need to specify the proper compiler toolset through the 359option "Optional toolset to use (-T parameter)". E.g. to use Clang for 360compilation set the toolset to "LLVM_v142", to use the Intel® 361Compiler 2017 for compilation set the toolset to "Intel C++ 362Compiler 17.0". 363 364Do not change the toolset manually in a solution file (neither through 365the project properties dialog, nor through the "Use Intel Compiler" 366project context menu), because then some compiler specific command line 367options cannot be set by CMake. 368 369Most configuration parameters described in the [CMake Configuration] 370can be set under Windows as well. Finally, click "Generate" to create 371the Visual Studio solution files. 372 373The following CMake options are only available under Windows: 374 375+ `CMAKE_CONFIGURATION_TYPE`: List of generated 376 configurations. Default value is Debug;Release;RelWithDebInfo. 377 378+ `USE_STATIC_RUNTIME`: Use the static version of the C/C++ runtime 379 library. This option is turned OFF by default. 380 381Use the generated Visual Studio solution file `embree2.sln` to compile 382the project. To build Embree with support for the AVX2 instruction set 383you need at least Visual Studio 2013 (Update 4). 384 385We recommend enabling syntax highlighting for the `.ispc` source and 386`.isph` header files. To do so open Visual Studio, go to Tools ⇒ 387Options ⇒ Text Editor ⇒ File Extension and add the `isph` and `ispc` 388extensions for the "Microsoft Visual C++" editor. 389 390### Using the Command Line 391 392Embree can also be configured and built without the IDE using the Visual 393Studio command prompt: 394 395 cd path\to\embree 396 mkdir build 397 cd build 398 cmake -G "Visual Studio 12 2013 Win64" .. 399 cmake --build . --config Release 400 401To use the Intel® Compiler, set the proper toolset, e.g. for Intel 402Compiler 17.0: 403 404 cmake -G "Visual Studio 12 2013 Win64" -T "Intel C++ Compiler 17.0" .. 405 cmake --build . --config Release 406 407You can also build only some projects with the `--target` switch. 408Additional parameters after "`--`" will be passed to `msbuild`. For 409example, to build the Embree library in parallel use 410 411 cmake --build . --config Release --target embree -- /m 412 413 414CMake Configuration 415------------------- 416 417The default CMake configuration in the configuration dialog should be 418appropriate for most usages. The following list describes all 419parameters that can be configured in CMake: 420 421+ `CMAKE_BUILD_TYPE`: Can be used to switch between Debug mode 422 (Debug), Release mode (Release) (default), and Release mode with 423 enabled assertions and debug symbols (RelWithDebInfo). 424 425+ `EMBREE_STACK_PROTECTOR`: Enables protection of return address 426 from buffer overwrites. This option is OFF by default. 427 428+ `EMBREE_ISPC_SUPPORT`: Enables ISPC support of Embree. This option 429 is ON by default. 430 431+ `EMBREE_STATIC_LIB`: Builds Embree as a static library (OFF by 432 default). Further multiple static libraries are generated for the 433 different ISAs selected (e.g. `embree3.a`, `embree3_sse42.a`, 434 `embree3_avx.a`, `embree3_avx2.a`, `embree3_avx512.a`). You have 435 to link these libraries in exactly this order of increasing ISA. 436 437+ `EMBREE_API_NAMESPACE`: Specifies a namespace name to put all Embree 438 API symbols inside. By default no namespace is used and plain C symbols 439 exported. 440 441+ `EMBREE_LIBRARY_NAME`: Specifies the name of the Embree library file 442 created. By default the name embree3 is used. 443 444+ `EMBREE_IGNORE_CMAKE_CXX_FLAGS`: When enabled, Embree ignores 445 default CMAKE_CXX_FLAGS. This option is turned ON by default. 446 447+ `EMBREE_TUTORIALS`: Enables build of Embree tutorials (default ON). 448 449+ `EMBREE_BACKFACE_CULLING`: Enables backface culling, i.e. only 450 surfaces facing a ray can be hit. This option is turned OFF by 451 default. 452 453+ `EMBREE_COMPACT_POLYS`: Enables compact tris/quads, i.e. only 454 geomIDs and primIDs are stored inside the leaf nodes. 455 456+ `EMBREE_FILTER_FUNCTION`: Enables the intersection filter function 457 feature (ON by default). 458 459+ `EMBREE_RAY_MASK`: Enables the ray masking feature (OFF by default). 460 461+ `EMBREE_RAY_PACKETS`: Enables ray packet traversal kernels. This 462 feature is turned ON by default. When turned on packet traversal is 463 used internally and packets passed to rtcIntersect4/8/16 are kept 464 intact in callbacks (when the ISA of appropiate width is enabled). 465 466+ `EMBREE_IGNORE_INVALID_RAYS`: Makes code robust against the risk of 467 full-tree traversals caused by invalid rays (e.g. rays containing 468 INF/NaN as origins). This option is turned OFF by default. 469 470+ `EMBREE_TASKING_SYSTEM`: Chooses between Intel® Threading TBB 471 Building Blocks (TBB), Parallel Patterns Library (PPL) (Windows 472 only), or an internal tasking system (INTERNAL). By default TBB is 473 used. 474 475+ `EMBREE_TBB_ROOT`: If Intel® Threading TBB Building Blocks (TBB) 476 is used as a tasking system, search the library in this directory 477 tree. 478 479+ `EMBREE_TBB_POSTFIX`: If Intel® Threading TBB Building Blocks (TBB) 480 is used as a tasking system, link to tbb<EMBREE_TBB_POSTFIX>.(so,dll,lib). 481 Defaults to the empty string. 482 483+ `EMBREE_TBB_DEBUG_ROOT`: If Intel® Threading TBB Building Blocks (TBB) 484 is used as a tasking system, search the library in this directory 485 tree in Debug mode. Defaults to `EMBREE_TBB_ROOT`. 486 487+ `EMBREE_TBB_DEBUG_POSTFIX`: If Intel® Threading TBB Building Blocks (TBB) 488 is used as a tasking system, link to tbb<EMBREE_TBB_DEBUG_POSTFIX>.(so,dll,lib) 489 in Debug mode. Defaults to "_debug". 490 491+ `EMBREE_MAX_ISA`: Select highest supported ISA (SSE2, SSE4.2, AVX, 492 AVX2, AVX512, or NONE). When set to NONE the 493 EMBREE_ISA_* variables can be used to enable ISAs individually. By 494 default the option is set to AVX2. 495 496+ `EMBREE_ISA_SSE2`: Enables SSE2 when EMBREE_MAX_ISA is set to 497 NONE. By default this option is turned OFF. 498 499+ `EMBREE_ISA_SSE42`: Enables SSE4.2 when EMBREE_MAX_ISA is set to 500 NONE. By default this option is turned OFF. 501 502+ `EMBREE_ISA_AVX`: Enables AVX when EMBREE_MAX_ISA is set to NONE. By 503 default this option is turned OFF. 504 505+ `EMBREE_ISA_AVX2`: Enables AVX2 when EMBREE_MAX_ISA is set to 506 NONE. By default this option is turned OFF. 507 508+ `EMBREE_ISA_AVX512`: Enables AVX-512 for Skylake when 509 EMBREE_MAX_ISA is set to NONE. By default this option is turned OFF. 510 511+ `EMBREE_GEOMETRY_TRIANGLE`: Enables support for trianglegeometries 512 (ON by default). 513 514+ `EMBREE_GEOMETRY_QUAD`: Enables support for quad geometries (ON by 515 default). 516 517+ `EMBREE_GEOMETRY_CURVE`: Enables support for curve geometries (ON by 518 default). 519 520+ `EMBREE_GEOMETRY_SUBDIVISION`: Enables support for subdivision 521 geometries (ON by default). 522 523+ `EMBREE_GEOMETRY_INSTANCE`: Enables support for instances (ON by 524 default). 525 526+ `EMBREE_GEOMETRY_USER`: Enables support for user defined geometries 527 (ON by default). 528 529+ `EMBREE_GEOMETRY_POINT`: Enables support for point geometries 530 (ON by default). 531 532+ `EMBREE_CURVE_SELF_INTERSECTION_AVOIDANCE_FACTOR`: Specifies a 533 factor that controls the self intersection avoidance feature for flat 534 curves. Flat curve intersections which are closer than 535 curve_radius*`EMBREE_CURVE_SELF_INTERSECTION_AVOIDANCE_FACTOR` to 536 the ray origin are ignored. A value of 0.0f disables self 537 intersection avoidance while 2.0f is the default value. 538 539+ `EMBREE_MIN_WIDTH`: Enabled the min-width feature, which allows 540 increasing the radius of curves and points to match some amount of 541 pixels. See [rtcSetGeometryMaxRadiusScale] for more details. 542 543+ `EMBREE_MAX_INSTANCE_LEVEL_COUNT`: Specifies the maximum number of nested 544 instance levels. Should be greater than 0; the default value is 1. 545 Instances nested any deeper than this value will silently disappear in 546 release mode, and cause assertions in debug mode. 547 548 549Using Embree 550============= 551 552The most convenient way of using Embree is through CMake. Just let 553CMake find Embree using the `FIND_PACKAGE` function inside your 554`CMakeLists.txt` file: 555 556 FIND_PACKAGE(embree 3.0 REQUIRED) 557 558If you installed Embree using the Linux RPM or macOS PKG installer, 559this will automatically find Embree. If you used the `zip` or `tar.gz` 560files to extract Embree, you need to set the `embree_DIR` variable to 561the folder you extracted Embree to. If you used the Windows MSI 562installer, you need to set `embree_DIR` to point to the Embree install 563location (e.g. `C:\Program Files\Intel\Embree3`). 564 565The `FIND_PACKAGE` function will create an embree target that 566you can add to your target link libraries: 567 568 TARGET_LINK_LIBRARIES(application embree) 569 570Now please have a look at the [Embree Tutorials] source code and the 571[Embree API] section to get started. 572 573 574 575Embree API 576========== 577 578The Embree API is a low-level C99 ray tracing API which can be used to 579construct 3D scenes and perform ray queries of different types inside 580these scenes. All API calls carry the prefix `rtc` (or `RTC` for types) 581which stands for **r**ay **t**racing **c**ore. 582 583The API also exists in an ISPC version, which is almost identical but 584contains additional functions that operate on ray packets with a size 585of the native SIMD width used by ISPC. For simplicity this document 586refers to the C99 version of the API functions. For changes when 587upgrading from the Embree 2 to the current Embree 3 API see Section 588[Upgrading from Embree 2 to Embree 3]. 589 590The API supports scenes consisting of different geometry types such as 591triangle meshes, quad meshes (triangle pairs), grid meshes, flat 592curves, round curves, oriented curves, subdivision meshes, instances, 593and user-defined geometries. See Section [Scene Object](#scene-object) 594for more information. 595 596Finding the closest hit of a ray segment with the scene 597(`rtcIntersect`-type functions), and determining whether any hit 598between a ray segment and the scene exists (`rtcOccluded`-type 599functions) are both supported. The API supports queries for single 600rays, ray packets, and ray streams. See Section [Ray 601Queries](#ray-queries) for more information. 602 603The API is designed in an object-oriented manner, e.g. it contains 604device objects (`RTCDevice` type), scene objects (`RTCScene` type), 605geometry objects (`RTCGeometry` type), buffer objects (`RTCBuffer` 606type), and BVH objects (`RTCBVH` type). All objects are reference 607counted, and handles can be released by calling the appropriate release 608function (e.g. `rtcReleaseDevice`) or retained by incrementing the 609reference count (e.g. `rtcRetainDevice`). In general, API calls that 610access the same object are not thread-safe, unless specified 611differently. However, attaching geometries to the same scene and 612performing ray queries in a scene is thread-safe. 613 614Device Object 615------------- 616 617Embree supports a device concept, which allows different components of 618the application to use the Embree API without interfering with each 619other. An application typically first creates a device using the 620[rtcNewDevice] function. This device can then be used to construct 621further objects, such as scenes and geometries. Before the application 622exits, it should release all devices by invoking [rtcReleaseDevice]. 623An application typically creates only a single device. If required 624differently, it should only use a small number of devices at any given 625time. 626 627Each user thread has its own error flag per device. If an error occurs 628when invoking an API function, this flag is set to an error code (if it 629isn't already set by a previous error). See Section 630[rtcGetDeviceError] for information on how to read the error code and 631Section [rtcSetDeviceErrorFunction] on how to register a callback 632that is invoked for each error encountered. It is recommended to always 633set a error callback function, to detect all errors. 634 635Scene Object 636------------ 637 638A scene is a container for a set of geometries, and contains a spatial 639acceleration structure which can be used to perform different types of 640ray queries. 641 642A scene is created using the `rtcNewScene` function call, and released 643using the `rtcReleaseScene` function call. To populate a scene with 644geometries use the `rtcAttachGeometry` call, and to detach them use the 645`rtcDetachGeometry` call. Once all scene geometries are attached, an 646`rtcCommitScene` call (or `rtcJoinCommitScene` call) will finish the 647scene description and trigger building of internal data structures. 648After the scene got committed, it is safe to perform ray queries (see 649Section [Ray Queries](#ray-queries)) or to query the scene bounding box 650(see [rtcGetSceneBounds] and [rtcGetSceneLinearBounds]). 651 652If scene geometries get modified or attached or detached, the 653`rtcCommitScene` call must be invoked before performing any further ray 654queries for the scene; otherwise the effect of the ray query is 655undefined. The modification of a geometry, committing the scene, and 656tracing of rays must always happen sequentially, and never at the same 657time. Any API call that sets a property of the scene or geometries 658contained in the scene count as scene modification, e.g. including 659setting of intersection filter functions. 660 661Scene flags can be used to configure a scene to use less memory 662(`RTC_SCENE_FLAG_COMPACT`), use more robust traversal algorithms 663(`RTC_SCENE_FLAG_ROBUST`), and to optimize for dynamic content. See 664Section [rtcSetSceneFlags] for more details. 665 666A build quality can be specified for a scene to balance between 667acceleration structure build performance and ray query performance. See 668Section [rtcSetSceneBuildQuality] for more details on build quality. 669 670Geometry Object 671--------------- 672 673A new geometry is created using the `rtcNewGeometry` function. 674Depending on the geometry type, different buffers must be bound (e.g. 675using `rtcSetSharedGeometryBuffer`) to set up the geometry data. In 676most cases, binding of a vertex and index buffer is required. The 677number of primitives and vertices of that geometry is typically 678inferred from the size of these bound buffers. 679 680Changes to the geometry always must be committed using the 681`rtcCommitGeometry` call before using the geometry. After committing, a 682geometry is not included in any scene. A geometry can be added to a 683scene by using the `rtcAttachGeometry` function (to automatically 684assign a geometry ID) or using the `rtcAttachGeometryById` function (to 685specify the geometry ID manually). A geometry can get attached to 686multiple scenes. 687 688All geometry types support multi-segment motion blur with an arbitrary 689number of equidistant time steps (in the range of 2 to 129) inside a 690user specified time range. Each geometry can have a different number of 691time steps and a different time range. The motion blur geometry is 692defined by linearly interpolating the geometries of neighboring time 693steps. To construct a motion blur geometry, first the number of time 694steps of the geometry must be specified using the 695`rtcSetGeometryTimeStepCount` function, and then a vertex buffer for 696each time step must be bound, e.g. using the 697`rtcSetSharedGeometryBuffer` function. Optionally, a time range 698defining the start (and end time) of the first (and last) time step can 699be set using the `rtcSetGeometryTimeRange` function. This feature will 700also allow geometries to appear and disappear during the camera shutter 701time if the time range is a sub range of [0,1]. 702 703The API supports per-geometry filter callback functions (see 704`rtcSetGeometryIntersectFilterFunction` and 705`rtcSetGeometryOccludedFilterFunction`) that are invoked for each 706intersection found during the `rtcIntersect`-type or `rtcOccluded`-type 707calls. The former ones are called geometry intersection filter 708functions, the latter ones geometry occlusion filter functions. These 709filter functions are designed to be used to ignore intersections 710outside of a user-defined silhouette of a primitive, e.g. to model tree 711leaves using transparency textures. 712 713Ray Queries 714----------- 715 716The API supports finding the closest hit of a ray segment with the 717scene (`rtcIntersect`-type functions), and determining whether any hit 718between a ray segment and the scene exists (`rtcOccluded`-type 719functions). 720 721Supported are single ray queries (`rtcIntersect1` and `rtcOccluded1`) 722as well as ray packet queries for ray packets of size 4 723(`rtcIntersect4` and `rtcOccluded4`), ray packets of size 8 724(`rtcIntersect8` and `rtcOccluded8`), and ray packets of size 16 725(`rtcIntersect16` and `rtcOccluded16`). 726 727Ray streams in a variety of layouts are supported as well, such as 728streams of single rays (`rtcIntersect1M` and `rtcOccluded1M`), streams 729of pointers to single rays (`rtcIntersect1p` and `rtcOccluded1p`), 730streams of ray packets (`rtcIntersectNM` and `rtcOccludedNM`), and 731large packet-like streams in structure of pointer layout 732(`rtcIntersectNp` and `rtcOccludedNp`). 733 734See Sections [rtcIntersect1] and [rtcOccluded1] for a detailed 735description of how to set up and trace a ray. 736 737See tutorial [Triangle Geometry] for a complete example of how to 738trace single rays and ray packets. Also have a look at the tutorial 739[Stream Viewer] for an example of how to trace ray streams. 740 741Point Queries 742------------- 743 744The API supports traversal of the BVH using a point query object that 745specifies a location and a query radius. For all primitives 746intersecting the according domain, a user defined callback function is 747called which allows queries such as finding the closest point on the 748surface geometries of the scene (see Tutorial [Closest Point]) or 749nearest neighbour queries (see Tutorial [Voronoi]). 750 751See Section [rtcPointQuery] for a detailed description of how to set 752up point queries. 753 754Collision Detection 755------------------- 756 757The Embree API also supports collision detection queries between two 758scenes consisting only of user geometries. Embree only performs 759broadphase collision detection, the narrow phase detection can be 760performed through a callback function. 761 762See Section [rtcCollide] for a detailed description of how to set up 763collision detection. 764 765Seen tutorial [Collision Detection](#collision-detection) for a 766complete example of collsion detection being used on a simple cloth 767solver. 768 769Miscellaneous 770------------- 771 772A context filter function, which can be set per ray query is supported 773(see `rtcInitIntersectContext`). This filter function is designed to 774change the semantics of the ray query, e.g. to accumulate opacity for 775transparent shadows, count the number of surfaces along a ray, collect 776all hits along a ray, etc. 777 778The internal algorithms to build a BVH are exposed through the `RTCBVH` 779object and `rtcBuildBVH` call. This call makes it possible to build a 780BVH in a user-specified format over user-specified primitives. See the 781documentation of the `rtcBuildBVH` call for more details. 782 783For getting the most performance out of Embree, see the Section 784[Performance Recommendations]. 785 786Upgrading from Embree 2 to Embree 3 787=================================== 788 789We decided to introduce an improved API in Embree 3 that is not 790backward compatible with the Embree 2 API. This step was required to 791remove various deprecated API functions that accumulated over time, 792improve extensibility of the API, fix suboptimal design decisions, fix 793design mistakes (such as incompatible single ray and ray packet 794layouts), clean up inconsistent naming, and increase flexibility. 795 796To make porting to the new API easy, we provide a conversion script 797that can do most of the work, and will annotate the code with remaining 798changes required. The script can be invoked the following way for CPP 799files: 800 801 ./scripts/cpp-patch.py --patch embree2_to_embree3.patch 802 --in infile.cpp --out outfile.cpp 803 804When invoked for ISPC files, add the `--ispc` option: 805 806 ./scripts/cpp-patch.py --ispc --patch embree2_to_embree3.patch 807 --in infile.ispc --out outfile.ispc 808 809Apply the script to each source file of your project that contains 810Embree API calls or types. The input file and output file can also be 811identical to perform the patch in-place. Please always backup your 812original code before running the script, and inspect the code changes 813done by the script using diff (e.g. `git diff`), to make sure no 814undesired code locations got changed. Grep the code for comments 815containing `EMBREE_FIXME` and perform the action described in the 816comment. 817 818The following changes need to be performed when switching from Embree 2 819to Embree 3. Most of these changes are automatically done by the script 820if not described differently. 821 822We strongly recommend to set an error callback function (see 823`rtcSetDeviceErrorFunction`) when porting to Embree 3 to detect all 824runtime errors early. 825 826Device 827------ 828 829- `rtcInit` and `rtcExit` got removed. Please use the device concept 830 using the `rtcNewDevice` and `rtcReleaseDevice` functions instead. 831 832- Functions that conceptually should operate on a device but did not 833 get a device argument got removed. The upgrade script replaces 834 these functions by the proper functions that operate on a device, 835 however, manually propagating the device handle to these function 836 calls might still be required. 837 838Scene 839----- 840 841- The API no longer distinguishes between a static and a dynamic 842 scene. Some users had issues as they wanted to do minor 843 modifications to static scenes, but maintain high traversal 844 performance. 845 846 The new approach gives more flexibility, as each scene is 847 changeable, and build quality settings can be changed on a commit 848 basis to balance between build performance and render performance. 849 850- The `rtcCommitThread` function got removed; use 851 `rtcJoinCommitScene` instead. 852 853- The scene now supports different build quality settings. Please use 854 those instead of the previous way of `RTC_SCENE_STATIC`, 855 `RTC_SCENE_DYNAMIC`, and `RTC_SCENE_HIGH_QUALITY` flags. 856 857Geometry 858-------- 859 860- There is now only one `rtcNewGeometry` function to create 861 geometries which gets passed an enum to specify the type of 862 geometry to create. The number of vertices and primitives of the 863 geometries is inferred from the size of data buffers. 864 865- We introduced an object type `RTCGeometry` for all geometries. 866 Previously a geometry was not a standalone object and could only 867 exist inside a scene. The new approach comes with more flexibility 868 and more readable code. 869 870 Operations like `rtcInterpolate` can now be performed on the 871 geometry object directly without the need of a scene. Further, an 872 application can choose to create its geometries independent of a 873 scene, e.g. each time a geometry node is added to its scene graph. 874 875 This modification changed many API functions to get passed one 876 `RTCGeometry` object instead of a `RTCScene` and `geomID`. The 877 script does all required changed automatically. However, in some 878 cases the script may introduce `rtcGetGeometry(scene, geomID)` 879 calls to retrieve the geometry handle. Best store the geometry 880 handle inside your scene representation (and release it in the 881 destructor) and access the handle directly instead of calling 882 `rtcGetGeometry`. 883 884- Geometries are not included inside a scene anymore but can be 885 attached to a multiple scenes using the `rtcAttachGeomety` or 886 `rtcAttachGeometryByID` functions. 887 888- As geometries are separate objects, commit semantics got introduced 889 for them too. Thus geometries must be committed through the 890 `rtcCommitGeometry` call before getting used. This allows for 891 earlier error checking and pre-calculating internal data per 892 geometry object. 893 894 Such commit points were previously not required in the Embree 2 895 API. The upgrade script attempts to insert the commits 896 automatically, but cannot do so properly under all circumstances. 897 Thus please check if every `rtcCommitGeometry` call inserted by the 898 script is properly placed, and if a `rtcCommitGeometry` call is 899 placed after a sequence of changes to a geometry. 900 901- Only the latest version of the previous displacement function call 902 (`RTCDisplacementFunc2`) is now supported, and the callback is 903 passed as a structure containing all arguments. 904 905- The deprecated `RTCBoundaryMode` type and `rtcSetBoundaryMode` 906 function got removed and replaced by `RTCSubdivisionMode` enum and 907 the `rtcSetGeometrySubdivisionMode` function. The script does this 908 replacement automatically. 909 910- Ribbon curves and lines now avoid self-intersections automatically 911 The application can be simplified by removing special code paths 912 that previously did the self-intersection handling. 913 914- The previous Embree 2 way of instancing was suboptimal as it 915 required user geometries to update the `instID` field of the ray 916 differently when used inside an instanced scene or inside a 917 top-level scene. The user geometry intersection code now just has 918 to copy the `context.instID` field into the `ray.instID` field to 919 function properly under all circumstances. 920 921- The internal instancing code will update the `context.instID` field 922 properly when entering or leaving an instance. When instancing is 923 implemented manually through user geometries, the code must be 924 modified to set the `context.instID` field properly and no longer 925 pass `instID` through the ray. This change must done manually and 926 cannot be performed by the script. 927 928- We flipped the direction of the geometry normal to the widely used 929 convention that a shape with counter-clockwise layout of vertices 930 has the normal pointing upwards (right-hand rule). Most modeling 931 tools follow that convention. 932 933 The conversion script does not perform this change, thus if 934 required adjust your code to flip `Ng` for triangle, quad, and 935 subdivision surfaces. 936 937Buffers 938------- 939 940- With Embree 3 we are introducing explicit `RTCBuffer` objects. 941 However, you can still use the short way of sharing buffers with 942 Embree through the `rtcSetSharedGeometryBuffer` call. 943 944- The `rtcMapBuffer` and `rtcUnmapBuffer` API calls were removed, and 945 we added the `rtcGetBufferData` call instead. 946 947 Previously the `rtcMapBuffer` call had the semantics of creating an 948 internal buffer when no buffer was shared for the corresponding 949 buffer slot. These invocations of `rtcMapBuffer` must be replaced 950 by an explicit creation of an internally managed buffer using the 951 `rtcNewGeometryBuffer` function. 952 953 The upgrade script cannot always detect if the `rtcMapBuffer` call 954 would create an internal buffer or just map the buffer pointer. 955 Thus check whether the `rtcNewGeometryBuffer` and 956 `rtcGetBufferData` calls are correct after the conversion. 957 958- The `rtcUpdateGeometryBuffer` function now must be called for every 959 buffer that got modified by the application. Note that the 960 conversion script cannot automatically detect each location where a 961 buffer update is now required. 962 963- The buffer type no longer encodes the time step or user vertex 964 buffer index. Now `RTC_VERTEX_BUFFER_TYPE` and additional `slot` 965 specifies the vertex buffer for a specific time step, and 966 `RTC_USER_VERTEX_BUFFER_TYPE` and additional `slot` specifies a 967 vertex attribute. 968 969Miscellaneous {#miscellaneous} 970------------- 971 972- The header files for Embree 3 are now inside the `embree3` folder 973 (instead of `embree2` folder) and `libembree.so` is now called 974 `libembree3.so` to be able to install multiple Embree versions side 975 by side. We made the headers C99 compliant. 976 977- All API objects are now reference counted with release functions to 978 decrement and retain functions to increment the reference count (if 979 required). 980 981- Most callback functions no longer get different arguments as input, 982 but a pointer to a structure containing all arguments. This results 983 in more readable code, faster callback invocation (as some 984 arguments do not change between invocations) and is extensible, as 985 new members to the structure can be later added in a backward 986 compatible way (if required). 987 988 The conversion script can convert the definition and declaration of 989 the old callback functions in most cases. Before running the 990 script, make sure that you never type-cast a callback function when 991 assigning it (as this has the danger of assigning a callback 992 function with a wrong type if the conversion did not detect some 993 callbacks as such). If the script does not detect a callback 994 function, make sure the argument types match exactly the types in 995 the header (e.g. write `const int` instead of `int const` or 996 convert the callback manually). 997 998- An intersection context is now required for each ray query 999 invocation. The context should be initialized using the 1000 `rtcInitIntersectContext` function. 1001 1002- The `rtcIntersect`-type functions get as input an `RTCRayHit` type, 1003 which is similar to before, but has the ray and hit parts split 1004 into two sub-structures. 1005 1006 The `rtcOccluded`-type functions get as input an `RTCRay` type, 1007 which does not contain hit data anymore. When an occlusion is 1008 found, the `tfar` element of the ray is set to `-inf`. 1009 1010 Required code changes cannot be done by the upgrade script and need 1011 to be done manually. 1012 1013- The ray layout for single rays and packets of rays had certain 1014 incompatibilities (alignment of `org` and `dir` for single rays 1015 caused gaps in the single ray layout that were not in the ray 1016 packet layout). This issue never showed up because single rays and 1017 ray packets were separate in the system initially. This layout 1018 issue is now fixed, and a single ray has the same layout as a ray 1019 packet of size 1. 1020 1021- Previously Embree supported placing additional data at the end of 1022 the ray structure, and accessing that data inside user geometry 1023 callbacks and filter callback functions. 1024 1025 With Embree 3 this is no longer supported, and the ray passed to a 1026 callback function may be copied to a different memory location. To 1027 attach additional data to your ray, simply extend the intersection 1028 context with a pointer to that data. 1029 1030 This change cannot be done by the script. Further, code will still 1031 work if you extend the ray as the implementation did not change 1032 yet. 1033 1034- The ray structure now contains an additional `id` and `flags` 1035 field. The `id` can be used to store the index of the ray with 1036 respect to a ray packet or ray stream. The `flags` is reserved for 1037 future use, and currently must be set to 0. 1038 1039- All previous intersection filter callback variants have been 1040 removed, except for the `RTCFilterFuncN` which gets a varying size 1041 ray packet as input. The semantics of this filter function type 1042 have changed from copying the hit on acceptance to clearing the 1043 ray's valid argument in case of non-acceptance. This way, chaining 1044 multiple filters is more efficient. 1045 1046 We kept the guarantee that for `rtcIntersect1/4/8/16` and 1047 `rtcOccluded1/4/8/16` calls the packet size and ray order will not 1048 change from the initial size and ordering when entering a filter 1049 callback. 1050 1051- We no longer export ISPC-specific symbols. This has the advantage 1052 that certain linking issues went away, e.g. it is now possible to 1053 link an ISPC application compiled for any combination of ISAs, and 1054 link this to an Embree library compiled with a different set of 1055 ISAs. Previously the ISAs of the application had to be a subset of 1056 the ISAs of Embree, and when the user enabled exactly one ISA, they 1057 had to do this in Embree and the application. 1058 1059- We no longer export the ISPC tasking system, which means that the 1060 application has the responsibility to implement the ISPC tasking 1061 system itself. ISPC comes with example code on how to do this. This 1062 change is not performed by the script and must be done manually. 1063 1064- Fixed many naming inconsistencies, and changed names of further API 1065 functions. All these renamings are properly done by the script and 1066 need no further attention. 1067 1068 1069 1070Embree API Reference 1071==================== 1072 1073rtcNewDevice 1074------------ 1075 1076#### NAME 1077 1078 rtcNewDevice - creates a new device 1079 1080#### SYNOPSIS 1081 1082 #include <embree3/rtcore.h> 1083 1084 RTCDevice rtcNewDevice(const char* config); 1085 1086#### DESCRIPTION 1087 1088This function creates a new device and returns a handle to this device. 1089The device object is reference counted with an initial reference count 1090of 1. The handle can be released using the `rtcReleaseDevice` API call. 1091 1092The device object acts as a class factory for all other object types. 1093All objects created from the device (like scenes, geometries, etc.) 1094hold a reference to the device, thus the device will not be destroyed 1095unless these objects are destroyed first. 1096 1097Objects are only compatible if they belong to the same device, e.g it 1098is not allowed to create a geometry in one device and attach it to a 1099scene created with a different device. 1100 1101A configuration string (`config` argument) can be passed to the device 1102construction. This configuration string can be `NULL` to use the 1103default configuration. 1104 1105The following configuration is supported: 1106 1107- `threads=[int]`: Specifies a number of build threads to use. A 1108 value of 0 enables all detected hardware threads. By default all 1109 hardware threads are used. 1110 1111- `user_threads=[int]`: Sets the number of user threads that can be 1112 used to join and participate in a scene commit using 1113 `rtcJoinCommitScene`. The tasking system will only use 1114 threads-user\_threads many worker threads, thus if the app wants to 1115 solely use its threads to commit scenes, just set threads equal to 1116 user\_threads. This option only has effect with the Intel(R) 1117 Threading Building Blocks (TBB) tasking system. 1118 1119- `set_affinity=[0/1]`: When enabled, build threads are affinitized 1120 to hardware threads. This option is disabled by default on standard 1121 CPUs, and enabled by default on Xeon Phi Processors. 1122 1123- `start_threads=[0/1]`: When enabled, the build threads are started 1124 upfront. This can be useful for benchmarking to exclude thread 1125 creation time. This option is disabled by default. 1126 1127- `isa=[sse2,sse4.2,avx,avx2,avx512]`: Use specified ISA. By default 1128 the ISA is selected automatically. 1129 1130- `max_isa=[sse2,sse4.2,avx,avx2,avx512]`: Configures the automated 1131 ISA selection to use maximally the specified ISA. 1132 1133- `hugepages=[0/1]`: Enables or disables usage of huge pages. Under 1134 Linux huge pages are used by default but under Windows and macOS 1135 they are disabled by default. 1136 1137- `enable_selockmemoryprivilege=[0/1]`: When set to 1, this enables 1138 the `SeLockMemoryPrivilege` privilege with is required to use huge 1139 pages on Windows. This option has an effect only under Windows and 1140 is ignored on other platforms. See Section [Huge Page Support] 1141 for more details. 1142 1143- `verbose=[0,1,2,3]`: Sets the verbosity of the output. When set to 1144 0, no output is printed by Embree, when set to a higher level more 1145 output is printed. By default Embree does not print anything on the 1146 console. 1147 1148- `frequency_level=[simd128,simd256,simd512]`: Specifies the 1149 frequency level the application want to run on, which can be 1150 either: 1151 a) simd128 to run at highest frequency 1152 b) simd256 to run at AVX2-heavy frequency level 1153 c) simd512 to run at heavy AVX512 frequency level. When some 1154 frequency level is specified, Embree will avoid doing 1155 optimizations that may reduce the frequency level below the 1156 level specified. E.g. if your app does not use AVX instructions 1157 setting "frequency\_level=simd128" will cause some CPUs to run 1158 at highest frequency, which may result in higher application 1159 performance if you do much shading. If you application heavily 1160 uses AVX code, you should best set the frequency level to 1161 simd256. Per default Embree tries to avoid reducing the 1162 frequency of the CPU by setting the simd256 level only when the 1163 CPU has no significant down clocking. 1164 1165Different configuration options should be separated by commas, e.g.: 1166 1167 rtcNewDevice("threads=1,isa=avx"); 1168 1169#### EXIT STATUS 1170 1171On success returns a handle of the created device. On failure returns 1172`NULL` as device and sets a per-thread error code that can be queried 1173using `rtcGetDeviceError(NULL)`. 1174 1175#### SEE ALSO 1176 1177[rtcRetainDevice], [rtcReleaseDevice] 1178 1179 1180 1181rtcRetainDevice 1182--------------- 1183 1184#### NAME {#name} 1185 1186 rtcRetainDevice - increments the device reference count 1187 1188#### SYNOPSIS {#synopsis} 1189 1190 #include <embree3/rtcore.h> 1191 1192 void rtcRetainDevice(RTCDevice device); 1193 1194#### DESCRIPTION {#description} 1195 1196Device objects are reference counted. The `rtcRetainDevice` function 1197increments the reference count of the passed device object (`device` 1198argument). This function together with `rtcReleaseDevice` allows to use 1199the internal reference counting in a C++ wrapper class to manage the 1200ownership of the object. 1201 1202#### EXIT STATUS {#exit-status} 1203 1204On failure an error code is set that can be queried using 1205`rtcGetDeviceError`. 1206 1207#### SEE ALSO {#see-also} 1208 1209[rtcNewDevice], [rtcReleaseDevice] 1210 1211 1212 1213rtcReleaseDevice 1214---------------- 1215 1216#### NAME {#name} 1217 1218 rtcReleaseDevice - decrements the device reference count 1219 1220#### SYNOPSIS {#synopsis} 1221 1222 #include <embree3/rtcore.h> 1223 1224 void rtcReleaseDevice(RTCDevice device); 1225 1226#### DESCRIPTION {#description} 1227 1228Device objects are reference counted. The `rtcReleaseDevice` function 1229decrements the reference count of the passed device object (`device` 1230argument). When the reference count falls to 0, the device gets 1231destroyed. 1232 1233All objects created from the device (like scenes, geometries, etc.) 1234hold a reference to the device, thus the device will not get destroyed 1235unless these objects are destroyed first. 1236 1237#### EXIT STATUS {#exit-status} 1238 1239On failure an error code is set that can be queried using 1240`rtcGetDeviceError`. 1241 1242#### SEE ALSO {#see-also} 1243 1244[rtcNewDevice], [rtcRetainDevice] 1245 1246 1247 1248rtcGetDeviceProperty 1249-------------------- 1250 1251#### NAME {#name} 1252 1253 rtcGetDeviceProperty - queries properties of the device 1254 1255#### SYNOPSIS {#synopsis} 1256 1257 #include <embree3/rtcore.h> 1258 1259 ssize_t rtcGetDeviceProperty( 1260 RTCDevice device, 1261 enum RTCDeviceProperty prop 1262 ); 1263 1264#### DESCRIPTION {#description} 1265 1266The `rtcGetDeviceProperty` function can be used to query properties 1267(`prop` argument) of a device object (`device` argument). The returned 1268property is an integer of type `ssize_t`. 1269 1270Possible properties to query are: 1271 1272- `RTC_DEVICE_PROPERTY_VERSION`: Queries the combined version number 1273 (MAJOR.MINOR.PATCH) with two decimal digits per component. E.g. for 1274 Embree 2.8.3 the integer 208003 is returned. 1275 1276- `RTC_DEVICE_PROPERTY_VERSION_MAJOR`: Queries the major version 1277 number of Embree. 1278 1279- `RTC_DEVICE_PROPERTY_VERSION_MINOR`: Queries the minor version 1280 number of Embree. 1281 1282- `RTC_DEVICE_PROPERTY_VERSION_PATCH`: Queries the patch version 1283 number of Embree. 1284 1285- `RTC_DEVICE_PROPERTY_NATIVE_RAY4_SUPPORTED`: Queries whether the 1286 `rtcIntersect4` and `rtcOccluded4` functions preserve packet size 1287 and ray order when invoking callback functions. This is only the 1288 case if Embree is compiled with `EMBREE_RAY_PACKETS` and `SSE2` (or 1289 `SSE4.2`) enabled, and if the machine it is running on supports 1290 `SSE2` (or `SSE4.2`). 1291 1292- `RTC_DEVICE_PROPERTY_NATIVE_RAY8_SUPPORTED`: Queries whether the 1293 `rtcIntersect8` and `rtcOccluded8` functions preserve packet size 1294 and ray order when invoking callback functions. This is only the 1295 case if Embree is compiled with `EMBREE_RAY_PACKETS` and `AVX` (or 1296 `AVX2`) enabled, and if the machine it is running on supports `AVX` 1297 (or `AVX2`). 1298 1299- `RTC_DEVICE_PROPERTY_NATIVE_RAY16_SUPPORTED`: Queries whether the 1300 `rtcIntersect16` and `rtcOccluded16` functions preserve packet size 1301 and ray order when invoking callback functions. This is only the 1302 case if Embree is compiled with `EMBREE_RAY_PACKETS` and `AVX512` 1303 enabled, and if the machine it is running on supports `AVX512`. 1304 1305- `RTC_DEVICE_PROPERTY_RAY_STREAM_SUPPORTED`: Queries whether 1306 `rtcIntersect1M`, `rtcIntersect1Mp`, `rtcIntersectNM`, 1307 `rtcIntersectNp`, `rtcOccluded1M`, `rtcOccluded1Mp`, 1308 `rtcOccludedNM`, and `rtcOccludedNp` are supported. This is only 1309 the case if Embree is compiled with `EMBREE_RAY_PACKETS` enabled. 1310 1311- `RTC_DEVICE_PROPERTY_RAY_MASK_SUPPORTED`: Queries whether ray masks 1312 are supported. This is only the case if Embree is compiled with 1313 `EMBREE_RAY_MASK` enabled. 1314 1315- `RTC_DEVICE_PROPERTY_BACKFACE_CULLING_ENABLED`: Queries whether 1316 back face culling is enabled. This is only the case if Embree is 1317 compiled with `EMBREE_BACKFACE_CULLING` enabled. 1318 1319- `RTC_DEVICE_PROPERTY_COMPACT_POLYS_ENABLED`: Queries whether 1320 compact polys is enabled. This is only the case if Embree is 1321 compiled with `EMBREE_COMPACT_POLYS` enabled. 1322 1323- `RTC_DEVICE_PROPERTY_FILTER_FUNCTION_SUPPORTED`: Queries whether 1324 filter functions are supported, which is the case if Embree is 1325 compiled with `EMBREE_FILTER_FUNCTION` enabled. 1326 1327- `RTC_DEVICE_PROPERTY_IGNORE_INVALID_RAYS_ENABLED`: Queries whether 1328 invalid rays are ignored, which is the case if Embree is compiled 1329 with `EMBREE_IGNORE_INVALID_RAYS` enabled. 1330 1331- `RTC_DEVICE_PROPERTY_TRIANGLE_GEOMETRY_SUPPORTED`: Queries whether 1332 triangles are supported, which is the case if Embree is compiled 1333 with `EMBREE_GEOMETRY_TRIANGLE` enabled. 1334 1335- `RTC_DEVICE_PROPERTY_QUAD_GEOMETRY_SUPPORTED`: Queries whether 1336 quads are supported, which is the case if Embree is compiled with 1337 `EMBREE_GEOMETRY_QUAD` enabled. 1338 1339- `RTC_DEVICE_PROPERTY_SUBDIVISION_GEOMETRY_SUPPORTED`: Queries 1340 whether subdivision meshes are supported, which is the case if 1341 Embree is compiled with `EMBREE_GEOMETRY_SUBDIVISION` enabled. 1342 1343- `RTC_DEVICE_PROPERTY_CURVE_GEOMETRY_SUPPORTED`: Queries whether 1344 curves are supported, which is the case if Embree is compiled with 1345 `EMBREE_GEOMETRY_CURVE` enabled. 1346 1347- `RTC_DEVICE_PROPERTY_POINT_GEOMETRY_SUPPORTED`: Queries whether 1348 points are supported, which is the case if Embree is compiled with 1349 `EMBREE_GEOMETRY_POINT` enabled. 1350 1351- `RTC_DEVICE_PROPERTY_USER_GEOMETRY_SUPPORTED`: Queries whether user 1352 geometries are supported, which is the case if Embree is compiled 1353 with `EMBREE_GEOMETRY_USER` enabled. 1354 1355- `RTC_DEVICE_PROPERTY_TASKING_SYSTEM`: Queries the tasking system 1356 Embree is compiled with. Possible return values are: 1357 1358 0. internal tasking system 1359 1. Intel Threading Building Blocks (TBB) 1360 2. Parallel Patterns Library (PPL) 1361 1362- `RTC_DEVICE_PROPERTY_JOIN_COMMIT_SUPPORTED`: Queries whether 1363 `rtcJoinCommitScene` is supported. This is not the case when Embree 1364 is compiled with PPL or older versions of TBB. 1365 1366- `RTC_DEVICE_PROPERTY_PARALLEL_COMMIT_SUPPORTED`: Queries whether 1367 `rtcCommitScene` can get invoked from multiple TBB worker threads 1368 concurrently. This feature is only supported starting with TBB 2019 1369 Update 9. 1370 1371#### EXIT STATUS {#exit-status} 1372 1373On success returns the value of the queried property. For properties 1374returning a boolean value, the return value 0 denotes `false` and 1 1375denotes `true`. 1376 1377On failure zero is returned and an error code is set that can be 1378queried using `rtcGetDeviceError`. 1379 1380 1381 1382rtcGetDeviceError 1383----------------- 1384 1385#### NAME {#name} 1386 1387 rtcGetDeviceError - returns the error code of the device 1388 1389#### SYNOPSIS {#synopsis} 1390 1391 #include <embree3/rtcore.h> 1392 1393 RTCError rtcGetDeviceError(RTCDevice device); 1394 1395#### DESCRIPTION {#description} 1396 1397Each thread has its own error code per device. If an error occurs when 1398calling an API function, this error code is set to the occurred error 1399if it stores no previous error. The `rtcGetDeviceError` function reads 1400and returns the currently stored error and clears the error code. This 1401assures that the returned error code is always the first error occurred 1402since the last invocation of `rtcGetDeviceError`. 1403 1404Possible error codes returned by `rtcGetDeviceError` are: 1405 1406- `RTC_ERROR_NONE`: No error occurred. 1407 1408- `RTC_ERROR_UNKNOWN`: An unknown error has occurred. 1409 1410- `RTC_ERROR_INVALID_ARGUMENT`: An invalid argument was specified. 1411 1412- `RTC_ERROR_INVALID_OPERATION`: The operation is not allowed for the 1413 specified object. 1414 1415- `RTC_ERROR_OUT_OF_MEMORY`: There is not enough memory left to 1416 complete the operation. 1417 1418- `RTC_ERROR_UNSUPPORTED_CPU`: The CPU is not supported as it does 1419 not support the lowest ISA Embree is compiled for. 1420 1421- `RTC_ERROR_CANCELLED`: The operation got canceled by a memory 1422 monitor callback or progress monitor callback function. 1423 1424When the device construction fails, `rtcNewDevice` returns `NULL` as 1425device. To detect the error code of a such a failed device 1426construction, pass `NULL` as device to the `rtcGetDeviceError` 1427function. For all other invocations of `rtcGetDeviceError`, a proper 1428device pointer must be specified. 1429 1430#### EXIT STATUS {#exit-status} 1431 1432Returns the error code for the device. 1433 1434#### SEE ALSO {#see-also} 1435 1436[rtcSetDeviceErrorFunction] 1437 1438 1439 1440rtcSetDeviceErrorFunction 1441------------------------- 1442 1443#### NAME {#name} 1444 1445 rtcSetDeviceErrorFunction - sets an error callback function for the device 1446 1447#### SYNOPSIS {#synopsis} 1448 1449 #include <embree3/rtcore.h> 1450 1451 typedef void (*RTCErrorFunction)( 1452 void* userPtr, 1453 RTCError code, 1454 const char* str 1455 ); 1456 1457 void rtcSetDeviceErrorFunction( 1458 RTCDevice device, 1459 RTCErrorFunction error, 1460 void* userPtr 1461 ); 1462 1463#### DESCRIPTION {#description} 1464 1465Using the `rtcSetDeviceErrorFunction` call, it is possible to set a 1466callback function (`error` argument) with payload (`userPtr` argument), 1467which is called whenever an error occurs for the specified device 1468(`device` argument). 1469 1470Only a single callback function can be registered per device, and 1471further invocations overwrite the previously set callback function. 1472Passing `NULL` as function pointer disables the registered callback 1473function. 1474 1475When the registered callback function is invoked, it gets passed the 1476user-defined payload (`userPtr` argument as specified at registration 1477time), the error code (`code` argument) of the occurred error, as well 1478as a string (`str` argument) that further describes the error. 1479 1480The error code is also set if an error callback function is registered. 1481 1482#### EXIT STATUS {#exit-status} 1483 1484On failure an error code is set that can be queried using 1485`rtcGetDeviceError`. 1486 1487#### SEE ALSO {#see-also} 1488 1489[rtcGetDeviceError] 1490 1491 1492 1493rtcSetDeviceMemoryMonitorFunction 1494--------------------------------- 1495 1496#### NAME {#name} 1497 1498 rtcSetDeviceMemoryMonitorFunction - registers a callback function 1499 to track memory consumption 1500 1501#### SYNOPSIS {#synopsis} 1502 1503 #include <embree3/rtcore.h> 1504 1505 typedef bool (*RTCMemoryMonitorFunction)( 1506 void* userPtr, 1507 ssize_t bytes, 1508 bool post 1509 ); 1510 1511 void rtcSetDeviceMemoryMonitorFunction( 1512 RTCDevice device, 1513 RTCMemoryMonitorFunction memoryMonitor, 1514 void* userPtr 1515 ); 1516 1517#### DESCRIPTION {#description} 1518 1519Using the `rtcSetDeviceMemoryMonitorFunction` call, it is possible to 1520register a callback function (`memoryMonitor` argument) with payload 1521(`userPtr` argument) for a device (`device` argument), which is called 1522whenever internal memory is allocated or deallocated by objects of that 1523device. Using this memory monitor callback mechanism, the application 1524can track the memory consumption of an Embree device, and optionally 1525terminate API calls that consume too much memory. 1526 1527Only a single callback function can be registered per device, and 1528further invocations overwrite the previously set callback function. 1529Passing `NULL` as function pointer disables the registered callback 1530function. 1531 1532Once registered, the Embree device will invoke the memory monitor 1533callback function before or after it allocates or frees important 1534memory blocks. The callback function gets passed the payload as 1535specified at registration time (`userPtr` argument), the number of 1536bytes allocated or deallocated (`bytes` argument), and whether the 1537callback is invoked after the allocation or deallocation took place 1538(`post` argument). The callback function might get called from multiple 1539threads concurrently. 1540 1541The application can track the current memory usage of the Embree device 1542by atomically accumulating the `bytes` input parameter provided to the 1543callback function. This parameter will be \>0 for allocations and \<0 1544for deallocations. 1545 1546Embree will continue its operation normally when returning `true` from 1547the callback function. If `false` is returned, Embree will cancel the 1548current operation with the `RTC_ERROR_OUT_OF_MEMORY` error code. 1549Issuing multiple cancel requests from different threads is allowed. 1550Canceling will only happen when the callback was called for allocations 1551(bytes \> 0), otherwise the cancel request will be ignored. 1552 1553If a callback to cancel was invoked before the allocation happens 1554(`post == false`), then the `bytes` parameter should not be 1555accumulated, as the allocation will never happen. If the callback to 1556cancel was invoked after the allocation happened (`post == true`), then 1557the `bytes` parameter should be accumulated, as the allocation properly 1558happened and a deallocation will later free that data block. 1559 1560#### EXIT STATUS {#exit-status} 1561 1562On failure an error code is set that can be queried using 1563`rtcGetDeviceError`. 1564 1565#### SEE ALSO {#see-also} 1566 1567[rtcNewDevice] 1568 1569 1570 1571rtcNewScene 1572----------- 1573 1574#### NAME {#name} 1575 1576 rtcNewScene - creates a new scene 1577 1578#### SYNOPSIS {#synopsis} 1579 1580 #include <embree3/rtcore.h> 1581 1582 RTCScene rtcNewScene(RTCDevice device); 1583 1584#### DESCRIPTION {#description} 1585 1586This function creates a new scene bound to the specified device 1587(`device` argument), and returns a handle to this scene. The scene 1588object is reference counted with an initial reference count of 1. The 1589scene handle can be released using the `rtcReleaseScene` API call. 1590 1591#### EXIT STATUS {#exit-status} 1592 1593On success a scene handle is returned. On failure `NULL` is returned 1594and an error code is set that can be queried using `rtcGetDeviceError`. 1595 1596#### SEE ALSO {#see-also} 1597 1598[rtcRetainScene], [rtcReleaseScene] 1599 1600 1601 1602rtcGetSceneDevice 1603----------------- 1604 1605#### NAME {#name} 1606 1607 rtcGetSceneDevice - returns the device the scene got created in 1608 1609#### SYNOPSIS {#synopsis} 1610 1611 #include <embree3/rtcore.h> 1612 1613 RTCDevice rtcGetSceneDevice(RTCScene scene); 1614 1615#### DESCRIPTION {#description} 1616 1617This function returns the device object the scene got created in. The 1618returned handle own one additional reference to the device object, thus 1619you should need to call `rtcReleaseDevice` when the returned handle is 1620no longer required. 1621 1622#### EXIT STATUS {#exit-status} 1623 1624On failure an error code is set that can be queried using 1625`rtcGetDeviceError`. 1626 1627#### SEE ALSO {#see-also} 1628 1629[rtcReleaseDevice] 1630 1631 1632 1633rtcRetainScene 1634-------------- 1635 1636#### NAME {#name} 1637 1638 rtcRetainScene - increments the scene reference count 1639 1640#### SYNOPSIS {#synopsis} 1641 1642 #include <embree3/rtcore.h> 1643 1644 void rtcRetainScene(RTCScene scene); 1645 1646#### DESCRIPTION {#description} 1647 1648Scene objects are reference counted. The `rtcRetainScene` function 1649increments the reference count of the passed scene object (`scene` 1650argument). This function together with `rtcReleaseScene` allows to use 1651the internal reference counting in a C++ wrapper class to handle the 1652ownership of the object. 1653 1654#### EXIT STATUS {#exit-status} 1655 1656On failure an error code is set that can be queried using 1657`rtcGetDeviceError`. 1658 1659#### SEE ALSO {#see-also} 1660 1661[rtcNewScene], [rtcReleaseScene] 1662 1663 1664 1665rtcReleaseScene 1666--------------- 1667 1668#### NAME {#name} 1669 1670 rtcReleaseScene - decrements the scene reference count 1671 1672#### SYNOPSIS {#synopsis} 1673 1674 #include <embree3/rtcore.h> 1675 1676 void rtcReleaseScene(RTCScene scene); 1677 1678#### DESCRIPTION {#description} 1679 1680Scene objects are reference counted. The `rtcReleaseScene` function 1681decrements the reference count of the passed scene object (`scene` 1682argument). When the reference count falls to 0, the scene gets 1683destroyed. 1684 1685The scene holds a reference to all attached geometries, thus if the 1686scene gets destroyed, all geometries get detached and their reference 1687count decremented. 1688 1689#### EXIT STATUS {#exit-status} 1690 1691On failure an error code is set that can be queried using 1692`rtcGetDeviceError`. 1693 1694#### SEE ALSO {#see-also} 1695 1696[rtcNewScene], [rtcRetainScene] 1697 1698 1699 1700rtcAttachGeometry 1701----------------- 1702 1703#### NAME {#name} 1704 1705 rtcAttachGeometry - attaches a geometry to the scene 1706 1707#### SYNOPSIS {#synopsis} 1708 1709 #include <embree3/rtcore.h> 1710 1711 unsigned int rtcAttachGeometry( 1712 RTCScene scene, 1713 RTCGeometry geometry 1714 ); 1715 1716#### DESCRIPTION {#description} 1717 1718The `rtcAttachGeometry` function attaches a geometry (`geometry` 1719argument) to a scene (`scene` argument) and assigns a geometry ID to 1720that geometry. All geometries attached to a scene are defined to be 1721included inside the scene. A geometry can get attached to multiplee 1722scene. The geometry ID is unique for the scene, and is used to identify 1723the geometry when hit by a ray during ray queries. 1724 1725This function is thread-safe, thus multiple threads can attach 1726geometries to a scene in parallel. 1727 1728The geometry IDs are assigned sequentially, starting from 0, as long as 1729no geometry got detached. If geometries got detached, the 1730implementation will reuse IDs in an implementation dependent way. 1731Consequently sequential assignment is no longer guaranteed, but a 1732compact range of IDs. 1733 1734These rules allow the application to manage a dynamic array to 1735efficiently map from geometry IDs to its own geometry representation. 1736Alternatively, the application can also use per-geometry user data to 1737map to its geometry representation. See `rtcSetGeometryUserData` and 1738`rtcGetGeometryUserData` for more information. 1739 1740#### EXIT STATUS {#exit-status} 1741 1742On failure an error code is set that can be queried using 1743`rtcGetDeviceError`. 1744 1745#### SEE ALSO {#see-also} 1746 1747[rtcSetGeometryUserData], [rtcGetGeometryUserData] 1748 1749 1750 1751rtcAttachGeometryByID 1752--------------------- 1753 1754#### NAME {#name} 1755 1756 rtcAttachGeometryByID - attaches a geometry to the scene 1757 using a specified geometry ID 1758 1759#### SYNOPSIS {#synopsis} 1760 1761 #include <embree3/rtcore.h> 1762 1763 void rtcAttachGeometryByID( 1764 RTCScene scene, 1765 RTCGeometry geometry, 1766 unsigned int geomID 1767 ); 1768 1769#### DESCRIPTION {#description} 1770 1771The `rtcAttachGeometryByID` function attaches a geometry (`geometry` 1772argument) to a scene (`scene` argument) and assigns a user provided 1773geometry ID (`geomID` argument) to that geometry. All geometries 1774attached to a scene are defined to be included inside the scene. A 1775geometry can get attached to multiple scenes. The passed user-defined 1776geometry ID is used to identify the geometry when hit by a ray during 1777ray queries. Using this function, it is possible to share the same IDs 1778to refer to geometries inside the application and Embree. 1779 1780This function is thread-safe, thus multiple threads can attach 1781geometries to a scene in parallel. 1782 1783The user-provided geometry ID must be unused in the scene, otherwise 1784the creation of the geometry will fail. Further, the user-provided 1785geometry IDs should be compact, as Embree internally creates a vector 1786which size is equal to the largest geometry ID used. Creating very 1787large geometry IDs for small scenes would thus cause a memory 1788consumption and performance overhead. 1789 1790#### EXIT STATUS {#exit-status} 1791 1792On failure an error code is set that can be queried using 1793`rtcGetDeviceError`. 1794 1795#### SEE ALSO {#see-also} 1796 1797[rtcAttachGeometry] 1798 1799 1800 1801rtcDetachGeometry 1802----------------- 1803 1804#### NAME {#name} 1805 1806 rtcDetachGeometry - detaches a geometry from the scene 1807 1808#### SYNOPSIS {#synopsis} 1809 1810 #include <embree3/rtcore.h> 1811 1812 void rtcDetachGeometry(RTCScene scene, unsigned int geomID); 1813 1814#### DESCRIPTION {#description} 1815 1816This function detaches a geometry identified by its geometry ID 1817(`geomID` argument) from a scene (`scene` argument). When detached, the 1818geometry is no longer contained in the scene. 1819 1820This function is thread-safe, thus multiple threads can detach 1821geometries from a scene at the same time. 1822 1823#### EXIT STATUS {#exit-status} 1824 1825On failure an error code is set that can be queried using 1826`rtcGetDeviceError`. 1827 1828#### SEE ALSO {#see-also} 1829 1830[rtcAttachGeometry], [rtcAttachGeometryByID] 1831 1832 1833 1834rtcGetGeometry 1835-------------- 1836 1837#### NAME {#name} 1838 1839 rtcGetGeometry - returns the geometry bound to 1840 the specified geometry ID 1841 1842#### SYNOPSIS {#synopsis} 1843 1844 #include <embree3/rtcore.h> 1845 1846 RTCGeometry rtcGetGeometry(RTCScene scene, unsigned int geomID); 1847 1848#### DESCRIPTION {#description} 1849 1850The `rtcGetGeometry` function returns the geometry that is bound to the 1851specified geometry ID (`geomID` argument) for the specified scene 1852(`scene` argument). This function just looks up the handle and does 1853*not* increment the reference count. If you want to get ownership of 1854the handle, you need to additionally call `rtcRetainGeometry`. 1855 1856This function is not thread safe and thus can be used during rendering. 1857However, it is generally recommended to store the geometry handle 1858inside the application's geometry representation and look up the 1859geometry handle from that representation directly. 1860 1861If you need a thread safe version of this function please use 1862[rtcGetGeometryThreadSafe]. 1863 1864#### EXIT STATUS {#exit-status} 1865 1866On failure `NULL` is returned and an error code is set that can be 1867queried using `rtcGetDeviceError`. 1868 1869#### SEE ALSO {#see-also} 1870 1871[rtcAttachGeometry], [rtcAttachGeometryByID], 1872[rtcGetGeometryThreadSafe] 1873 1874 1875 1876rtcGetGeometryThreadSafe 1877------------------------ 1878 1879#### NAME {#name} 1880 1881 rtcGetGeometryThreadSafe - returns the geometry bound to 1882 the specified geometry ID 1883 1884#### SYNOPSIS {#synopsis} 1885 1886 #include <embree3/rtcore.h> 1887 1888 RTCGeometry rtcGetGeometryThreadSafe(RTCScene scene, unsigned int geomID); 1889 1890#### DESCRIPTION {#description} 1891 1892The `rtcGetGeometryThreadSafe` function returns the geometry that is 1893bound to the specified geometry ID (`geomID` argument) for the 1894specified scene (`scene` argument). This function just looks up the 1895handle and does *not* increment the reference count. If you want to get 1896ownership of the handle, you need to additionally call 1897`rtcRetainGeometry`. 1898 1899This function is thread safe and should NOT get used during rendering. 1900If you need a fast non-thread safe version during rendering please use 1901the [rtcGetGeometry] function. 1902 1903#### EXIT STATUS {#exit-status} 1904 1905On failure `NULL` is returned and an error code is set that can be 1906queried using `rtcGetDeviceError`. 1907 1908#### SEE ALSO {#see-also} 1909 1910[rtcAttachGeometry], [rtcAttachGeometryByID], [rtcGetGeometry] 1911 1912 1913 1914rtcCommitScene 1915-------------- 1916 1917#### NAME {#name} 1918 1919 rtcCommitScene - commits scene changes 1920 1921#### SYNOPSIS {#synopsis} 1922 1923 #include <embree3/rtcore.h> 1924 1925 void rtcCommitScene(RTCScene scene); 1926 1927#### DESCRIPTION {#description} 1928 1929The `rtcCommitScene` function commits all changes for the specified 1930scene (`scene` argument). This internally triggers building of a 1931spatial acceleration structure for the scene using all available worker 1932threads. Ray queries can be performed only after committing all scene 1933changes. 1934 1935If the application uses TBB 2019 Update 9 or later for parallelization 1936of rendering, lazy scene construction during rendering is supported by 1937`rtcCommitScene`. Therefore `rtcCommitScene` can get called from 1938multiple TBB worker threads concurrently for the same scene. The 1939`rtcCommitScene` function will then internally isolate the scene 1940construction using a tbb::isolated\_task\_group. The alternative 1941approach of using `rtcJoinCommitScene` which uses an tbb:task\_arena 1942internally, is not recommended due to it's high runtime overhead. 1943 1944If scene geometries get modified or attached or detached, the 1945`rtcCommitScene` call must be invoked before performing any further ray 1946queries for the scene; otherwise the effect of the ray query is 1947undefined. The modification of a geometry, committing the scene, and 1948tracing of rays must always happen sequentially, and never at the same 1949time. Any API call that sets a property of the scene or geometries 1950contained in the scene count as scene modification, e.g. including 1951setting of intersection filter functions. 1952 1953The kind of acceleration structure built can be influenced using scene 1954flags (see `rtcSetSceneFlags`), and the quality can be specified using 1955the `rtcSetSceneBuildQuality` function. 1956 1957Embree silently ignores primitives during spatial acceleration 1958structure construction that would cause numerical issues, 1959e.g. primitives containing NaNs, INFs, or values greater than 1.844E18f 1960(as no reasonable calculations can be performed with such values 1961without causing overflows). 1962 1963#### EXIT STATUS {#exit-status} 1964 1965On failure an error code is set that can be queried using 1966`rtcGetDeviceError`. 1967 1968#### SEE ALSO {#see-also} 1969 1970[rtcJoinCommitScene] 1971 1972 1973 1974rtcJoinCommitScene 1975------------------ 1976 1977#### NAME {#name} 1978 1979 rtcJoinCommitScene - commits the scene from multiple threads 1980 1981#### SYNOPSIS {#synopsis} 1982 1983 #include <embree3/rtcore.h> 1984 1985 void rtcJoinCommitScene(RTCScene scene); 1986 1987#### DESCRIPTION {#description} 1988 1989The `rtcJoinCommitScene` function commits all changes for the specified 1990scene (`scene` argument). The scene commit internally triggers building 1991of a spatial acceleration structure for the scene. Ray queries can be 1992performed after scene changes got properly committed. 1993 1994The `rtcJoinCommitScene` function can get called from multiple user 1995threads which will all cooperate in the build operation. All threads 1996calling into this function will return from `rtcJoinCommitScene` after 1997the scene commit is finished. All threads must consistently call 1998`rtcJoinCommitScene` and not `rtcCommitScene`. 1999 2000In contrast to the `rtcCommitScene` function, the `rtcJoinCommitScene` 2001function can be called from multiple user threads, while the 2002`rtcCommitScene` can only get called from multiple TBB worker threads 2003when used concurrently. For optimal performance we strongly recommend 2004using TBB inside the application together with the `rtcCommitScene` 2005function and to avoid using the `rtcJoinCommitScene` function. 2006 2007The `rtcJoinCommitScene` feature allows a flexible way to lazily create 2008hierarchies during rendering. A thread reaching a not-yet-constructed 2009sub-scene of a two-level scene can generate the sub-scene geometry and 2010call `rtcJoinCommitScene` on that just generated scene. During 2011construction, further threads reaching the not-yet-built scene can join 2012the build operation by also invoking `rtcJoinCommitScene`. A thread 2013that calls `rtcJoinCommitScene` after the build finishes will directly 2014return from the `rtcJoinCommitScene` call. 2015 2016Multiple scene commit operations on different scenes can be running at 2017the same time, hence it is possible to commit many small scenes in 2018parallel, distributing the commits to many threads. 2019 2020When using Embree with the Intel® Threading Building Blocks (which is 2021the default), threads that call `rtcJoinCommitScene` will join the 2022build operation, but other TBB worker threads might also participate in 2023the build. To avoid thread oversubscription, we recommend using TBB 2024also inside the application. Further, the join mode only works properly 2025starting with TBB v4.4 Update 1. For earlier TBB versions, threads that 2026call `rtcJoinCommitScene` to join a running build will just trigger the 2027build and wait for the build to finish. Further, old TBB versions with 2028`TBB_INTERFACE_VERSION_MAJOR < 8` do not support `rtcJoinCommitScene`, 2029and invoking this function will result in an error. 2030 2031When using Embree with the internal tasking system, only threads that 2032call `rtcJoinCommitScene` will perform the build operation, and no 2033additional worker threads will be scheduled. 2034 2035When using Embree with the Parallel Patterns Library (PPL), 2036`rtcJoinCommitScene` is not supported and calling that function will 2037result in an error. 2038 2039To detect whether `rtcJoinCommitScene` is supported, use the 2040`rtcGetDeviceProperty` function. 2041 2042#### EXIT STATUS {#exit-status} 2043 2044On failure an error code is set that can be queried using 2045`rtcGetDeviceError`. 2046 2047#### SEE ALSO {#see-also} 2048 2049[rtcCommitScene], [rtcGetDeviceProperty] 2050 2051 2052 2053rtcSetSceneProgressMonitorFunction 2054---------------------------------- 2055 2056#### NAME {#name} 2057 2058 rtcSetSceneProgressMonitorFunction - registers a callback 2059 to track build progress 2060 2061#### SYNOPSIS {#synopsis} 2062 2063 #include <embree3/rtcore.h> 2064 2065 typedef bool (*RTCProgressMonitorFunction)( 2066 void* ptr, 2067 double n 2068 ); 2069 2070 void rtcSetSceneProgressMonitorFunction( 2071 RTCScene scene, 2072 RTCProgressMonitorFunction progress, 2073 void* userPtr 2074 ); 2075 2076#### DESCRIPTION {#description} 2077 2078Embree supports a progress monitor callback mechanism that can be used 2079to report progress of hierarchy build operations and to cancel build 2080operations. 2081 2082The `rtcSetSceneProgressMonitorFunction` registers a progress monitor 2083callback function (`progress` argument) with payload (`userPtr` 2084argument) for the specified scene (`scene` argument). 2085 2086Only a single callback function can be registered per scene, and 2087further invocations overwrite the previously set callback function. 2088Passing `NULL` as function pointer disables the registered callback 2089function. 2090 2091Once registered, Embree will invoke the callback function multiple 2092times during hierarchy build operations of the scene, by passing the 2093payload as set at registration time (`userPtr` argument), and a double 2094in the range $[0, 1]$ which estimates the progress of the operation 2095(`n` argument). The callback function might be called from multiple 2096threads concurrently. 2097 2098When returning `true` from the callback function, Embree will continue 2099the build operation normally. When returning `false`, Embree will 2100cancel the build operation with the `RTC_ERROR_CANCELLED` error code. 2101Issuing multiple cancel requests for the same build operation is 2102allowed. 2103 2104#### EXIT STATUS {#exit-status} 2105 2106On failure an error code is set that can be queried using 2107`rtcGetDeviceError`. 2108 2109#### SEE ALSO {#see-also} 2110 2111[rtcNewScene] 2112 2113 2114 2115rtcSetSceneBuildQuality 2116----------------------- 2117 2118#### NAME {#name} 2119 2120 rtcSetSceneBuildQuality - sets the build quality for 2121 the scene 2122 2123#### SYNOPSIS {#synopsis} 2124 2125 #include <embree3/rtcore.h> 2126 2127 void rtcSetSceneBuildQuality( 2128 RTCScene scene, 2129 enum RTCBuildQuality quality 2130 ); 2131 2132#### DESCRIPTION {#description} 2133 2134The `rtcSetSceneBuildQuality` function sets the build quality 2135(`quality` argument) for the specified scene (`scene` argument). 2136Possible values for the build quality are: 2137 2138- `RTC_BUILD_QUALITY_LOW`: Create lower quality data structures, 2139 e.g. for dynamic scenes. A two-level spatial index structure is 2140 built when enabling this mode, which supports fast partial scene 2141 updates, and allows for setting a per-geometry build quality 2142 through the `rtcSetGeometryBuildQuality` function. 2143 2144- `RTC_BUILD_QUALITY_MEDIUM`: Default build quality for most usages. 2145 Gives a good compromise between build and render performance. 2146 2147- `RTC_BUILD_QUALITY_HIGH`: Create higher quality data structures for 2148 final-frame rendering. For certain geometry types this enables a 2149 spatial split BVH. 2150 2151Selecting a higher build quality results in better rendering 2152performance but slower scene commit times. The default build quality 2153for a scene is `RTC_BUILD_QUALITY_MEDIUM`. 2154 2155#### EXIT STATUS {#exit-status} 2156 2157On failure an error code is set that can be queried using 2158`rtcGetDeviceError`. 2159 2160#### SEE ALSO {#see-also} 2161 2162[rtcSetGeometryBuildQuality] 2163 2164 2165 2166rtcSetSceneFlags 2167---------------- 2168 2169#### NAME {#name} 2170 2171 rtcSetSceneFlags - sets the flags for the scene 2172 2173#### SYNOPSIS {#synopsis} 2174 2175 #include <embree3/rtcore.h> 2176 2177 void rtcSetSceneFlags(RTCScene scene, enum RTCSceneFlags flags); 2178 2179#### DESCRIPTION {#description} 2180 2181The `rtcSetSceneFlags` function sets the scene flags (`flags` argument) 2182for the specified scene (`scene` argument). Possible scene flags are: 2183 2184- `RTC_SCENE_FLAG_NONE`: No flags set. 2185 2186- `RTC_SCENE_FLAG_DYNAMIC`: Provides better build performance for 2187 dynamic scenes (but also higher memory consumption). 2188 2189- `RTC_SCENE_FLAG_COMPACT`: Uses compact acceleration structures and 2190 avoids algorithms that consume much memory. 2191 2192- `RTC_SCENE_FLAG_ROBUST`: Uses acceleration structures that allow 2193 for robust traversal, and avoids optimizations that reduce 2194 arithmetic accuracy. This mode is typically used for avoiding 2195 artifacts caused by rays shooting through edges of neighboring 2196 primitives. 2197 2198- `RTC_SCENE_FLAG_CONTEXT_FILTER_FUNCTION`: Enables support for a 2199 filter function inside the intersection context for this scene. See 2200 Section [rtcInitIntersectContext] for more details. 2201 2202Multiple flags can be enabled using an `or` operation, 2203e.g. `RTC_SCENE_FLAG_COMPACT | RTC_SCENE_FLAG_ROBUST`. 2204 2205#### EXIT STATUS {#exit-status} 2206 2207On failure an error code is set that can be queried using 2208`rtcGetDeviceError`. 2209 2210#### SEE ALSO {#see-also} 2211 2212[rtcGetSceneFlags] 2213 2214 2215 2216rtcGetSceneFlags 2217---------------- 2218 2219#### NAME {#name} 2220 2221 rtcGetSceneFlags - returns the flags of the scene 2222 2223#### SYNOPSIS {#synopsis} 2224 2225 #include <embree3/rtcore.h> 2226 2227 enum RTCSceneFlags rtcGetSceneFlags(RTCScene scene); 2228 2229#### DESCRIPTION {#description} 2230 2231Queries the flags of a scene. This function can be useful when setting 2232individual flags, e.g. to just set the robust mode without changing 2233other flags the following way: 2234 2235 RTCSceneFlags flags = rtcGetSceneFlags(scene); 2236 rtcSetSceneFlags(scene, RTC_SCENE_FLAG_ROBUST | flags); 2237 2238#### EXIT STATUS {#exit-status} 2239 2240On failure `RTC_SCENE_FLAG_NONE` is returned and an error code is set 2241that can be queried using `rtcGetDeviceError`. 2242 2243#### SEE ALSO {#see-also} 2244 2245[rtcSetSceneFlags] 2246 2247 2248 2249rtcGetSceneBounds 2250----------------- 2251 2252#### NAME {#name} 2253 2254 rtcGetSceneBounds - returns the axis-aligned bounding box of the scene 2255 2256#### SYNOPSIS {#synopsis} 2257 2258 #include <embree3/rtcore.h> 2259 2260 struct RTCORE_ALIGN(16) RTCBounds 2261 { 2262 float lower_x, lower_y, lower_z, align0; 2263 float upper_x, upper_y, upper_z, align1; 2264 }; 2265 2266 void rtcGetSceneBounds( 2267 RTCScene scene, 2268 struct RTCBounds* bounds_o 2269 ); 2270 2271#### DESCRIPTION {#description} 2272 2273The `rtcGetSceneBounds` function queries the axis-aligned bounding box 2274of the specified scene (`scene` argument) and stores that bounding box 2275to the provided destination pointer (`bounds_o` argument). The stored 2276bounding box consists of lower and upper bounds for the x, y, and z 2277dimensions as specified by the `RTCBounds` structure. 2278 2279The provided destination pointer must be aligned to 16 bytes. The 2280function may be invoked only after committing the scene; otherwise the 2281result is undefined. 2282 2283#### EXIT STATUS {#exit-status} 2284 2285On failure an error code is set that can be queried using 2286`rtcGetDeviceError`. 2287 2288#### SEE ALSO {#see-also} 2289 2290[rtcGetSceneLinearBounds], [rtcCommitScene], [rtcJoinCommitScene] 2291 2292 2293 2294rtcGetSceneLinearBounds 2295----------------------- 2296 2297#### NAME {#name} 2298 2299 rtcGetSceneLinearBounds - returns the linear bounds of the scene 2300 2301#### SYNOPSIS {#synopsis} 2302 2303 #include <embree3/rtcore.h> 2304 2305 struct RTCORE_ALIGN(16) RTCLinearBounds 2306 { 2307 RTCBounds bounds0; 2308 RTCBounds bounds1; 2309 }; 2310 2311 void rtcGetSceneLinearBounds( 2312 RTCScene scene, 2313 struct RTCLinearBounds* bounds_o 2314 ); 2315 2316#### DESCRIPTION {#description} 2317 2318The `rtcGetSceneLinearBounds` function queries the linear bounds of the 2319specified scene (`scene` argument) and stores them to the provided 2320destination pointer (`bounds_o` argument). The stored linear bounds 2321consist of bounding boxes for time 0 (`bounds0` member) and time 1 2322(`bounds1` member) as specified by the `RTCLinearBounds` structure. 2323Linearly interpolating these bounds to a specific time `t` yields 2324bounds for the geometry at that time. 2325 2326The provided destination pointer must be aligned to 16 bytes. The 2327function may be called only after committing the scene, otherwise the 2328result is undefined. 2329 2330#### EXIT STATUS {#exit-status} 2331 2332On failure an error code is set that can be queried using 2333`rtcGetDeviceError`. 2334 2335#### SEE ALSO {#see-also} 2336 2337[rtcGetSceneBounds], [rtcCommitScene], [rtcJoinCommitScene] 2338 2339 2340 2341rtcNewGeometry 2342-------------- 2343 2344#### NAME {#name} 2345 2346 rtcNewGeometry - creates a new geometry object 2347 2348#### SYNOPSIS {#synopsis} 2349 2350 #include <embree3/rtcore.h> 2351 2352 enum RTCGeometryType 2353 { 2354 RTC_GEOMETRY_TYPE_TRIANGLE, 2355 RTC_GEOMETRY_TYPE_QUAD, 2356 RTC_GEOMETRY_TYPE_SUBDIVISION, 2357 RTC_GEOMETRY_TYPE_FLAT_LINEAR_CURVE, 2358 RTC_GEOMETRY_TYPE_FLAT_BEZIER_CURVE, 2359 RTC_GEOMETRY_TYPE_FLAT_BSPLINE_CURVE, 2360 RTC_GEOMETRY_TYPE_FLAT_HERMITE_CURVE, 2361 RTC_GEOMETRY_TYPE_FLAT_CATMULL_ROM_CURVE, 2362 RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_BEZIER_CURVE, 2363 RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_BSPLINE_CURVE, 2364 RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_HERMITE_CURVE, 2365 RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_CATMULL_ROM_CURVE, 2366 RTC_GEOMETRY_TYPE_CONE_LINEAR_CURVE, 2367 RTC_GEOMETRY_TYPE_ROUND_LINEAR_CURVE, 2368 RTC_GEOMETRY_TYPE_ROUND_BEZIER_CURVE, 2369 RTC_GEOMETRY_TYPE_ROUND_BSPLINE_CURVE, 2370 RTC_GEOMETRY_TYPE_ROUND_HERMITE_CURVE, 2371 RTC_GEOMETRY_TYPE_ROUND_CATMULL_ROM_CURVE, 2372 RTC_GEOMETRY_TYPE_GRID, 2373 RTC_GEOMETRY_TYPE_SPHERE_POINT, 2374 RTC_GEOMETRY_TYPE_DISC_POINT, 2375 RTC_GEOMETRY_TYPE_ORIENTED_DISC_POINT, 2376 RTC_GEOMETRY_TYPE_USER, 2377 RTC_GEOMETRY_TYPE_INSTANCE 2378 }; 2379 2380 RTCGeometry rtcNewGeometry( 2381 RTCDevice device, 2382 enum RTCGeometryType type 2383 ); 2384 2385#### DESCRIPTION {#description} 2386 2387Geometries are objects that represent an array of primitives of the 2388same type. The `rtcNewGeometry` function creates a new geometry of 2389specified type (`type` argument) bound to the specified device 2390(`device` argument) and returns a handle to this geometry. The geometry 2391object is reference counted with an initial reference count of 1. The 2392geometry handle can be released using the `rtcReleaseGeometry` API 2393call. 2394 2395Supported geometry types are triangle meshes 2396(`RTC_GEOMETRY_TYPE_TRIANGLE` type), quad meshes (triangle pairs) 2397(`RTC_GEOMETRY_TYPE_QUAD` type), Catmull-Clark subdivision surfaces 2398(`RTC_GEOMETRY_TYPE_SUBDIVISION` type), curve geometries with different 2399bases (`RTC_GEOMETRY_TYPE_FLAT_LINEAR_CURVE`, 2400`RTC_GEOMETRY_TYPE_FLAT_BEZIER_CURVE`,\ 2401`RTC_GEOMETRY_TYPE_FLAT_BSPLINE_CURVE`, 2402`RTC_GEOMETRY_TYPE_FLAT_HERMITE_CURVE`,\ 2403`RTC_GEOMETRY_TYPE_FLAT_CATMULL_ROM_CURVE`, 2404`RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_BEZIER_CURVE`, 2405`RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_BSPLINE_CURVE`, 2406`RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_HERMITE_CURVE`, 2407`RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_CATMULL_ROM_CURVE`, 2408`RTC_GEOMETRY_TYPE_CONE_LINEAR_CURVE`, 2409`RTC_GEOMETRY_TYPE_ROUND_LINEAR_CURVE`, 2410`RTC_GEOMETRY_TYPE_ROUND_BEZIER_CURVE`, 2411`RTC_GEOMETRY_TYPE_ROUND_BSPLINE_CURVE`, 2412`RTC_GEOMETRY_TYPE_ROUND_HERMITE_CURVE`, 2413`RTC_GEOMETRY_TYPE_ROUND_CATMULL_ROM_CURVE` types) grid meshes 2414(`RTC_GEOMETRY_TYPE_GRID`), point geometries 2415(`RTC_GEOMETRY_TYPE_SPHERE_POINT`, `RTC_GEOMETRY_TYPE_DISC_POINT`, 2416`RTC_TYPE_ORIENTED_DISC_POINT`), user-defined geometries 2417(`RTC_GEOMETRY_TYPE_USER`), and instances 2418(`RTC_GEOMETRY_TYPE_INSTANCE`). 2419 2420The types `RTC_GEOMETRY_TYPE_ROUND_BEZIER_CURVE`, 2421`RTC_GEOMETRY_TYPE_ROUND_BSPLINE_CURVE`, and 2422`RTC_GEOMETRY_TYPE_ROUND_CATMULL_ROM_CURVE` will treat the curve as a 2423sweep surface of a varying-radius circle swept tangentially along the 2424curve. The types `RTC_GEOMETRY_TYPE_FLAT_BEZIER_CURVE`, 2425`RTC_GEOMETRY_TYPE_FLAT_BSPLINE_CURVE`, and 2426`RTC_GEOMETRY_TYPE_FLAT_CATMULL_ROM_CURVE` use ray-facing ribbons as a 2427faster-to-intersect approximation. 2428 2429After construction, geometries are enabled by default and not attached 2430to any scene. Geometries can be disabled (`rtcDisableGeometry` call), 2431and enabled again (`rtcEnableGeometry` call). A geometry can be 2432attached to multiple scenes using the `rtcAttachGeometry` call (or 2433`rtcAttachGeometryByID` call), and detached using the 2434`rtcDetachGeometry` call. During attachment, a geometry ID is assigned 2435to the geometry (or assigned by the user when using the 2436`rtcAttachGeometryByID` call), which uniquely identifies the geometry 2437inside that scene. This identifier is returned when primitives of the 2438geometry are hit in later ray queries for the scene. 2439 2440Geometries can also be modified, including their vertex and index 2441buffers. After modifying a buffer, `rtcUpdateGeometryBuffer` must be 2442called to notify that the buffer got modified. 2443 2444The application can use the `rtcSetGeometryUserData` function to set a 2445user data pointer to its own geometry representation, and later read 2446out this pointer using the `rtcGetGeometryUserData` function. 2447 2448After setting up the geometry or modifying it, `rtcCommitGeometry` must 2449be called to finish the geometry setup. After committing the geometry, 2450vertex data interpolation can be performed using the `rtcInterpolate` 2451and `rtcInterpolateN` functions. 2452 2453A build quality can be specified for a geometry using the 2454`rtcSetGeometryBuildQuality` function, to balance between acceleration 2455structure build performance and ray query performance. The build 2456quality per geometry will be used if a two-level acceleration structure 2457is built internally, which is the case if the `RTC_BUILD_QUALITY_LOW` 2458is set as the scene build quality. See Section 2459[rtcSetSceneBuildQuality] for more details. 2460 2461#### EXIT STATUS {#exit-status} 2462 2463On failure `NULL` is returned and an error code is set that can be 2464queried using `rtcGetDeviceError`. 2465 2466#### SEE ALSO {#see-also} 2467 2468[rtcEnableGeometry], [rtcDisableGeometry], [rtcAttachGeometry], 2469[rtcAttachGeometryByID], [rtcUpdateGeometryBuffer], 2470[rtcSetGeometryUserData], [rtcGetGeometryUserData], 2471[rtcCommitGeometry], [rtcInterpolate], [rtcInterpolateN], 2472[rtcSetGeometryBuildQuality], [rtcSetSceneBuildQuality], 2473[RTC\_GEOMETRY\_TYPE\_TRIANGLE], [RTC\_GEOMETRY\_TYPE\_QUAD], 2474[RTC\_GEOMETRY\_TYPE\_SUBDIVISION], [RTC\_GEOMETRY\_TYPE\_CURVE], 2475[RTC\_GEOMETRY\_TYPE\_GRID], [RTC\_GEOMETRY\_TYPE\_POINT], 2476[RTC\_GEOMETRY\_TYPE\_USER], [RTC\_GEOMETRY\_TYPE\_INSTANCE] 2477 2478 2479 2480RTC\_GEOMETRY\_TYPE\_TRIANGLE 2481----------------------------- 2482 2483#### NAME {#name} 2484 2485 RTC_GEOMETRY_TYPE_TRIANGLE - triangle geometry type 2486 2487#### SYNOPSIS {#synopsis} 2488 2489 #include <embree3/rtcore.h> 2490 2491 RTCGeometry geometry = 2492 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_TRIANGLE); 2493 2494#### DESCRIPTION {#description} 2495 2496Triangle meshes are created by passing `RTC_GEOMETRY_TYPE_TRIANGLE` to 2497the `rtcNewGeometry` function call. The triangle indices can be 2498specified by setting an index buffer (`RTC_BUFFER_TYPE_INDEX` type) and 2499the triangle vertices by setting a vertex buffer 2500(`RTC_BUFFER_TYPE_VERTEX` type). See `rtcSetGeometryBuffer` and 2501`rtcSetSharedGeometryBuffer` for more details on how to set buffers. 2502The index buffer must contain an array of three 32-bit indices per 2503triangle (`RTC_FORMAT_UINT3` format) and the number of primitives is 2504inferred from the size of that buffer. The vertex buffer must contain 2505an array of single precision `x`, `y`, `z` floating point coordinates 2506(`RTC_FORMAT_FLOAT3` format), and the number of vertices are inferred 2507from the size of that buffer. The vertex buffer can be at most 16 GB 2508large. 2509 2510The parametrization of a triangle uses the first vertex `p0` as base 2511point, the vector `p1 - p0` as u-direction and the vector `p2 - p0` as 2512v-direction. Thus vertex attributes `t0,t1,t2` can be linearly 2513interpolated over the triangle the following way: 2514 2515 t_uv = (1-u-v)*t0 + u*t1 + v*t2 2516 = t0 + u*(t1-t0) + v*(t2-t0) 2517 2518A triangle whose vertices are laid out counter-clockwise has its 2519geometry normal pointing upwards outside the front face, like 2520illustrated in the following picture: 2521 2522![][imgTriangleUV] 2523 2524For multi-segment motion blur, the number of time steps must be first 2525specified using the `rtcSetGeometryTimeStepCount` call. Then a vertex 2526buffer for each time step can be set using different buffer slots, and 2527all these buffers have to have the same stride and size. 2528 2529Also see tutorial [Triangle Geometry] for an example of how to create 2530triangle meshes. 2531 2532#### EXIT STATUS {#exit-status} 2533 2534On failure `NULL` is returned and an error code is set that be get 2535queried using `rtcGetDeviceError`. 2536 2537#### SEE ALSO {#see-also} 2538 2539[rtcNewGeometry] 2540 2541 2542 2543RTC\_GEOMETRY\_TYPE\_QUAD 2544------------------------- 2545 2546#### NAME {#name} 2547 2548 RTC_GEOMETRY_TYPE_QUAD - quad geometry type 2549 2550#### SYNOPSIS {#synopsis} 2551 2552 #include <embree3/rtcore.h> 2553 2554 RTCGeometry geometry = 2555 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_QUAD); 2556 2557#### DESCRIPTION {#description} 2558 2559Quad meshes are created by passing `RTC_GEOMETRY_TYPE_QUAD` to the 2560`rtcNewGeometry` function call. The quad indices can be specified by 2561setting an index buffer (`RTC_BUFFER_TYPE_INDEX` type) and the quad 2562vertices by setting a vertex buffer (`RTC_BUFFER_TYPE_VERTEX` type). 2563See `rtcSetGeometryBuffer` and `rtcSetSharedGeometryBuffer` for more 2564details on how to set buffers. The index buffer contains an array of 2565four 32-bit indices per quad (`RTC_FORMAT_UINT4` format), and the 2566number of primitives is inferred from the size of that buffer. The 2567vertex buffer contains an array of single precision `x`, `y`, `z` 2568floating point coordinates (`RTC_FORMAT_FLOAT3` format), and the number 2569of vertices is inferred from the size of that buffer. The vertex buffer 2570can be at most 16 GB large. 2571 2572A quad is internally handled as a pair of two triangles `v0,v1,v3` and 2573`v2,v3,v1`, with the `u'`/`v'` coordinates of the second triangle 2574corrected by `u = 1-u'` and `v = 1-v'` to produce a quad 2575parametrization where `u` and `v` are in the range 0 to 1. Thus the 2576parametrization of a quad uses the first vertex `p0` as base point, and 2577the vector `p1 - p0` as `u`-direction, and `p3 - p0` as v-direction. 2578Thus vertex attributes `t0,t1,t2,t3` can be bilinearly interpolated 2579over the quadrilateral the following way: 2580 2581 t_uv = (1-v)((1-u)*t0 + u*t1) + v*((1-u)*t3 + u*t2) 2582 2583Mixed triangle/quad meshes are supported by encoding a triangle as a 2584quad, which can be achieved by replicating the last triangle vertex 2585(`v0,v1,v2` -\> `v0,v1,v2,v2`). This way the second triangle is a line 2586(which can never get hit), and the parametrization of the first 2587triangle is compatible with the standard triangle parametrization. 2588 2589A quad whose vertices are laid out counter-clockwise has its geometry 2590normal pointing upwards outside the front face, like illustrated in the 2591following picture. 2592 2593![][imgQuadUV] 2594 2595For multi-segment motion blur, the number of time steps must be first 2596specified using the `rtcSetGeometryTimeStepCount` call. Then a vertex 2597buffer for each time step can be set using different buffer slots, and 2598all these buffers must have the same stride and size. 2599 2600#### EXIT STATUS {#exit-status} 2601 2602On failure `NULL` is returned and an error code is set that can be 2603queried using `rtcGetDeviceError`. 2604 2605#### SEE ALSO {#see-also} 2606 2607[rtcNewGeometry] 2608 2609 2610 2611RTC\_GEOMETRY\_TYPE\_GRID 2612------------------------- 2613 2614#### NAME {#name} 2615 2616 RTC_GEOMETRY_TYPE_GRID - grid geometry type 2617 2618#### SYNOPSIS {#synopsis} 2619 2620 #include <embree3/rtcore.h> 2621 2622 RTCGeometry geometry = 2623 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_GRID); 2624 2625#### DESCRIPTION {#description} 2626 2627Grid meshes are created by passing `RTC_GEOMETRY_TYPE_GRID` to the 2628`rtcNewGeometry` function call, and contain an array of grid 2629primitives. This array of grids can be specified by setting up a grid 2630buffer (with `RTC_BUFFER_TYPE_GRID` type and `RTC_FORMAT_GRID` format) 2631and the grid mesh vertices by setting a vertex buffer 2632(`RTC_BUFFER_TYPE_VERTEX` type). See `rtcSetGeometryBuffer` and 2633`rtcSetSharedGeometryBuffer` for more details on how to set buffers. 2634The number of grid primitives in the grid mesh is inferred from the 2635size of the grid buffer. 2636 2637The vertex buffer contains an array of single precision `x`, `y`, `z` 2638floating point coordinates (`RTC_FORMAT_FLOAT3` format), and the number 2639of vertices is inferred from the size of that buffer. 2640 2641Each grid in the grid buffer is of the type `RTCGrid`: 2642 2643 struct RTCGrid 2644 { 2645 unsigned int startVertexID; 2646 unsigned int stride; 2647 unsigned short width,height; 2648 }; 2649 2650The `RTCGrid` structure describes a 2D grid of vertices (with respect 2651to the vertex buffer of the grid mesh). The `width` and `height` 2652members specify the number of vertices in u and v direction, 2653e.g. setting both `width` and `height` to 3 sets up a 3×3 vertex grid. 2654The maximum allowed `width` and `height` is 32767. The `startVertexID` 2655specifies the ID of the top-left vertex in the vertex grid, while the 2656`stride` parameter specifies a stride (in number of vertices) used to 2657step to the next row. 2658 2659A vertex grid of dimensions `width` and `height` is treated as a 2660`(width-1)` x `(height-1)` grid of `quads` (triangle-pairs), with the 2661same shared edge handling as for regular quad meshes. However, the 2662`u`/`v` coordinates have the uniform range `[0..1]` for an entire 2663vertex grid. The `u` direction follows the `width` of the grid while 2664the `v` direction the `height`. 2665 2666For multi-segment motion blur, the number of time steps must be first 2667specified using the `rtcSetGeometryTimeStepCount` call. Then a vertex 2668buffer for each time step can be set using different buffer slots, and 2669all these buffers must have the same stride and size. 2670 2671#### EXIT STATUS {#exit-status} 2672 2673On failure `NULL` is returned and an error code is set that can be 2674queried using `rtcGetDeviceError`. 2675 2676#### SEE ALSO {#see-also} 2677 2678[rtcNewGeometry] 2679 2680 2681 2682RTC\_GEOMETRY\_TYPE\_SUBDIVISION 2683-------------------------------- 2684 2685#### NAME {#name} 2686 2687 RTC_GEOMETRY_TYPE_SUBDIVISION - subdivision geometry type 2688 2689#### SYNOPSIS {#synopsis} 2690 2691 #include <embree3/rtcore.h> 2692 2693 RTCGeometry geometry = 2694 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_SUBDIVISION); 2695 2696#### DESCRIPTION {#description} 2697 2698Catmull-Clark subdivision meshes are supported, including support for 2699edge creases, vertex creases, holes, non-manifold geometry, and 2700face-varying interpolation. The number of vertices per face can be in 2701the range of 3 to 15 vertices (triangles, quadrilateral, pentagons, 2702etc). 2703 2704Subdivision meshes are created by passing 2705`RTC_GEOMETRY_TYPE_SUBDIVISION` to the `rtcNewGeometry` function. 2706Various buffers need to be set by the application to set up the 2707subdivision mesh. See `rtcSetGeometryBuffer` and 2708`rtcSetSharedGeometryBuffer` for more details on how to set buffers. 2709The face buffer (`RTC_BUFFER_TYPE_FACE` type and `RTC_FORMAT_UINT` 2710format) contains the number of edges/indices of each face (3 to 15), 2711and the number of faces is inferred from the size of this buffer. The 2712index buffer (`RTC_BUFFER_TYPE_INDEX` type) contains multiple (3 to 15) 271332-bit vertex indices (`RTC_FORMAT_UINT` format) for each face, and the 2714number of edges is inferred from the size of this buffer. The vertex 2715buffer (`RTC_BUFFER_TYPE_VERTEX` type) stores an array of single 2716precision `x`, `y`, `z` floating point coordinates (`RTC_FORMAT_FLOAT3` 2717format), and the number of vertices is inferred from the size of this 2718buffer. 2719 2720Optionally, the application may set additional index buffers using 2721different buffer slots if multiple topologies are required for 2722face-varying interpolation. The standard vertex buffers 2723(`RTC_BUFFER_TYPE_VERTEX`) are always bound to the geometry topology 2724(topology 0) thus use `RTC_BUFFER_TYPE_INDEX` with buffer slot 0. User 2725vertex data interpolation may use different topologies as described 2726later. 2727 2728Optionally, the application can set up the hole buffer 2729(`RTC_BUFFER_TYPE_HOLE`) which contains an array of 32-bit indices 2730(`RTC_FORMAT_UINT` format) of faces that should be considered 2731non-existing in all topologies. The number of holes is inferred from 2732the size of this buffer. 2733 2734Optionally, the application can fill the level buffer 2735(`RTC_BUFFER_TYPE_LEVEL`) with a tessellation rate for each of the 2736edges of each face. This buffer must have the same size as the index 2737buffer. The tessellation level is a positive floating point value 2738(`RTC_FORMAT_FLOAT` format) that specifies how many quads along the 2739edge should be generated during tessellation. If no level buffer is 2740specified, a level of 1 is used. The maximally supported edge level is 27414096, and larger levels are clamped to that value. Note that edges may 2742be shared between (typically 2) faces. To guarantee a watertight 2743tessellation, the level of these shared edges should be identical. A 2744uniform tessellation rate for an entire subdivision mesh can be set by 2745using the `rtcSetGeometryTessellationRate` function. The existence of a 2746level buffer has precedence over the uniform tessellation rate. 2747 2748Optionally, the application can fill the sparse edge crease buffers to 2749make edges appear sharper. The edge crease index buffer 2750(`RTC_BUFFER_TYPE_EDGE_CREASE_INDEX`) contains an array of pairs of 275132-bit vertex indices (`RTC_FORMAT_UINT2` format) that specify 2752unoriented edges in the geometry topology. The edge crease weight 2753buffer (`RTC_BUFFER_TYPE_EDGE_CREASE_WEIGHT`) stores for each of these 2754crease edges a positive floating point weight (`RTC_FORMAT_FLOAT` 2755format). The number of edge creases is inferred from the size of these 2756buffers, which has to be identical. The larger a weight, the sharper 2757the edge. Specifying a weight of infinity is supported and marks an 2758edge as infinitely sharp. Storing an edge multiple times with the same 2759crease weight is allowed, but has lower performance. Storing an edge 2760multiple times with different crease weights results in undefined 2761behavior. For a stored edge (i,j), the reverse direction edges (j,i) do 2762not have to be stored, as both are considered the same unoriented edge. 2763Edge crease features are shared between all topologies. 2764 2765Optionally, the application can fill the sparse vertex crease buffers 2766to make vertices appear sharper. The vertex crease index buffer 2767(`RTC_BUFFER_TYPE_VERTEX_CREASE_INDEX`), contains an array of 32-bit 2768vertex indices (`RTC_FORMAT_UINT` format) to specify a set of vertices 2769from the geometry topology. The vertex crease weight buffer 2770(`RTC_BUFFER_TYPE_VERTEX_CREASE_WEIGHT`) specifies for each of these 2771vertices a positive floating point weight (`RTC_FORMAT_FLOAT` format). 2772The number of vertex creases is inferred from the size of these 2773buffers, and has to be identical. The larger a weight, the sharper the 2774vertex. Specifying a weight of infinity is supported and makes the 2775vertex infinitely sharp. Storing a vertex multiple times with the same 2776crease weight is allowed, but has lower performance. Storing a vertex 2777multiple times with different crease weights results in undefined 2778behavior. Vertex crease features are shared between all topologies. 2779 2780Subdivision modes can be used to force linear interpolation for parts 2781of the subdivision mesh; see `rtcSetGeometrySubdivisionMode` for more 2782details. 2783 2784For multi-segment motion blur, the number of time steps must be first 2785specified using the `rtcSetGeometryTimeStepCount` call. Then a vertex 2786buffer for each time step can be set using different buffer slots, and 2787all these buffers have to have the same stride and size. 2788 2789Also see tutorial [Subdivision Geometry] for an example of how to 2790create subdivision surfaces. 2791 2792#### Parametrization 2793 2794The parametrization for subdivision faces is different for 2795quadrilaterals and non-quadrilateral faces. 2796 2797The parametrization of a quadrilateral face uses the first vertex `p0` 2798as base point, and the vector `p1 - p0` as u-direction and `p3 - p0` as 2799v-direction. 2800 2801The parametrization for all other face types (with number of vertices 2802not equal 4), have a special parametrization where the subpatch ID `n` 2803(of the `n`-th quadrilateral that would be obtained by a single 2804subdivision step) and the local hit location inside this quadrilateral 2805are encoded in the UV coordinates. The following code extracts the 2806sub-patch ID `i` and local UVs of this subpatch: 2807 2808 unsigned int l = floorf(0.5f*U); 2809 unsigned int h = floorf(0.5f*V); 2810 unsigned int i = 4*h+l; 2811 float u = 2.0f*fracf(0.5f*U)-0.5f; 2812 float v = 2.0f*fracf(0.5f*V)-0.5f; 2813 2814This encoding allows local subpatch UVs to be in the range `[-0.5,1.5[` 2815thus negative subpatch UVs can be passed to `rtcInterpolate` to sample 2816subpatches slightly out of bounds. This can be useful to calculate 2817derivatives using finite differences if required. The encoding further 2818has the property that one can just move the value `u` (or `v`) on a 2819subpatch by adding `du` (or `dv`) to the special UV encoding as long as 2820it does not fall out of the `[-0.5,1.5[` range. 2821 2822To smoothly interpolate vertex attributes over the subdivision surface 2823we recommend using the `rtcInterpolate` function, which will apply the 2824standard subdivision rules for interpolation and automatically takes 2825care of the special UV encoding for non-quadrilaterals. 2826 2827#### Face-Varying Data 2828 2829Face-varying interpolation is supported through multiple topologies per 2830subdivision mesh and binding such topologies to vertex attribute 2831buffers to interpolate. This way, texture coordinates may use a 2832different topology with additional boundaries to construct separate UV 2833regions inside one subdivision mesh. 2834 2835Each such topology `i` has a separate index buffer (specified using 2836`RTC_BUFFER_TYPE_INDEX` with buffer slot `i`) and separate subdivision 2837mode that can be set using `rtcSetGeometrySubdivisionMode`. A vertex 2838attribute buffer `RTC_BUFFER_TYPE_VERTEX_ATTRIBUTE` bound to a buffer 2839slot `j` can be assigned to use a topology for interpolation using the 2840`rtcSetGeometryVertexAttributeTopology` call. 2841 2842The face buffer (`RTC_BUFFER_TYPE_FACE` type) is shared between all 2843topologies, which means that the `n`-th primitive always has the same 2844number of vertices (e.g. being a triangle or a quad) for each topology. 2845However, the indices of the topologies themselves may be different. 2846 2847#### EXIT STATUS {#exit-status} 2848 2849On failure `NULL` is returned and an error code is set that can be 2850queried using `rtcGetDeviceError`. 2851 2852#### SEE ALSO {#see-also} 2853 2854[rtcNewGeometry] 2855 2856 2857 2858RTC\_GEOMETRY\_TYPE\_CURVE 2859-------------------------- 2860 2861#### NAME {#name} 2862 2863 RTC_GEOMETRY_TYPE_FLAT_LINEAR_CURVE - 2864 flat curve geometry with linear basis 2865 2866 RTC_GEOMETRY_TYPE_FLAT_BEZIER_CURVE - 2867 flat curve geometry with cubic Bézier basis 2868 2869 RTC_GEOMETRY_TYPE_FLAT_BSPLINE_CURVE - 2870 flat curve geometry with cubic B-spline basis 2871 2872 RTC_GEOMETRY_TYPE_FLAT_HERMITE_CURVE - 2873 flat curve geometry with cubic Hermite basis 2874 2875 RTC_GEOMETRY_TYPE_FLAT_CATMULL_ROM_CURVE - 2876 flat curve geometry with Catmull-Rom basis 2877 2878 RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_BEZIER_CURVE - 2879 flat normal oriented curve geometry with cubic Bézier basis 2880 2881 RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_BSPLINE_CURVE - 2882 flat normal oriented curve geometry with cubic B-spline basis 2883 2884 RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_HERMITE_CURVE - 2885 flat normal oriented curve geometry with cubic Hermite basis 2886 2887 RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_CATMULL_ROM_CURVE - 2888 flat normal oriented curve geometry with Catmull-Rom basis 2889 2890 RTC_GEOMETRY_TYPE_CONE_LINEAR_CURVE - 2891 capped cone curve geometry with linear basis - discontinous at edge boundaries 2892 2893 RTC_GEOMETRY_TYPE_ROUND_LINEAR_CURVE - 2894 capped cone curve geometry with linear basis and spherical ending 2895 2896 RTC_GEOMETRY_TYPE_ROUND_BEZIER_CURVE - 2897 swept surface curve geometry with cubic Bézier basis 2898 2899 RTC_GEOMETRY_TYPE_ROUND_BSPLINE_CURVE - 2900 swept surface curve geometry with cubic B-spline basis 2901 2902 RTC_GEOMETRY_TYPE_ROUND_HERMITE_CURVE - 2903 swept surface curve geometry with cubic Hermite basis 2904 2905 RTC_GEOMETRY_TYPE_ROUND_CATMULL_ROM_CURVE - 2906 swept surface curve geometry with Catmull-Rom basis 2907 2908#### SYNOPSIS {#synopsis} 2909 2910 #include <embree3/rtcore.h> 2911 2912 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_FLAT_LINEAR_CURVE); 2913 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_FLAT_BEZIER_CURVE); 2914 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_FLAT_BSPLINE_CURVE); 2915 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_FLAT_HERMITE_CURVE); 2916 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_FLAT_CATMULL_ROM_CURVE); 2917 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_BEZIER_CURVE); 2918 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_BSPLINE_CURVE); 2919 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_HERMITE_CURVE); 2920 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_CATMULL_ROM_CURVE); 2921 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_CONE_LINEAR_CURVE); 2922 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_ROUND_LINEAR_CURVE); 2923 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_ROUND_BEZIER_CURVE); 2924 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_ROUND_BSPLINE_CURVE); 2925 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_ROUND_HERMITE_CURVE); 2926 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_ROUND_CATMULL_ROM_CURVE); 2927 2928#### DESCRIPTION {#description} 2929 2930Curves with per vertex radii are supported with linear, cubic Bézier, 2931cubic B-spline, and cubic Hermite bases. Such curve geometries are 2932created by passing `RTC_GEOMETRY_TYPE_FLAT_LINEAR_CURVE`, 2933`RTC_GEOMETRY_TYPE_FLAT_BEZIER_CURVE`, 2934`RTC_GEOMETRY_TYPE_FLAT_BSPLINE_CURVE`, 2935`RTC_GEOMETRY_TYPE_FLAT_HERMITE_CURVE`, 2936`RTC_GEOMETRY_TYPE_FLAT_CATMULL_ROM_CURVE`, 2937`RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_FLAT_BEZIER_CURVE`, 2938`RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_FLAT_BSPLINE_CURVE`, 2939`RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_FLAT_HERMITE_CURVE`, 2940`RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_FLAT_CATMULL_ROM_CURVE`, 2941`RTC_GEOMETRY_TYPE_CONE_LINEAR_CURVE`, 2942`RTC_GEOMETRY_TYPE_ROUND_LINEAR_CURVE`, 2943`RTC_GEOMETRY_TYPE_ROUND_BEZIER_CURVE`, 2944`RTC_GEOMETRY_TYPE_ROUND_BSPLINE_CURVE`, 2945`RTC_GEOMETRY_TYPE_ROUND_HERMITE_CURVE`, or 2946`RTC_GEOMETRY_TYPE_ROUND_CATMULL_ROM_CURVE` to the `rtcNewGeometry` 2947function. The curve indices can be specified through an index buffer 2948(`RTC_BUFFER_TYPE_INDEX`) and the curve vertices through a vertex 2949buffer (`RTC_BUFFER_TYPE_VERTEX`). For the Hermite basis a tangent 2950buffer (`RTC_BUFFER_TYPE_TANGENT`), normal oriented curves a normal 2951buffer (`RTC_BUFFER_TYPE_NORMAL`), and for normal oriented Hermite 2952curves a normal derivative buffer (`RTC_BUFFER_TYPE_NORMAL_DERIVATIVE`) 2953has to get specified additionally. See `rtcSetGeometryBuffer` and 2954`rtcSetSharedGeometryBuffer` for more details on how to set buffers. 2955 2956The index buffer contains an array of 32-bit indices (`RTC_FORMAT_UINT` 2957format), each pointing to the first control vertex in the vertex 2958buffer, but also to the first tangent in the tangent buffer, and first 2959normal in the normal buffer if these buffers are present. 2960 2961The vertex buffer stores each control vertex in the form of a single 2962precision position and radius stored in (`x`, `y`, `z`, `r`) order in 2963memory (`RTC_FORMAT_FLOAT4` format). The number of vertices is inferred 2964from the size of this buffer. The radii may be smaller than zero but 2965the interpolated radii should always be greater or equal to zero. 2966Similarly, the tangent buffer stores the derivative of each control 2967vertex (`x`, `y`, `z`, `r` order and `RTC_FORMAT_FLOAT4` format) and 2968the normal buffer stores a single precision normal per control vertex 2969(`x`, `y`, `z` order and `RTC_FORMAT_FLOAT3` format). 2970 2971##### Linear Basis 2972 2973For the linear basis the indices point to the first of 2 consecutive 2974control points in the vertex buffer. The first control point is the 2975start and the second control point the end of the line segment. When 2976constructing hair strands in this basis, the end-point can be shared 2977with the start of the next line segment. 2978 2979For the linear basis the user optionally can provide a flags buffer of 2980type `RTC_BUFFER_TYPE_FLAGS` which contains bytes that encode if the 2981left neighbor segment (`RTC_CURVE_FLAG_NEIGHBOR_LEFT` flag) and/or 2982right neighbor segment (`RTC_CURVE_FLAG_NEIGHBOR_RIGHT` flags) exist 2983(see [RTCCurveFlags]). If this buffer is not set, than the left/right 2984neighbor bits are automatically calculated base on the index buffer 2985(left segment exists if segment(id-1)+1 == segment(id) and right 2986segment exists if segment(id+1)-1 == segment(id)). 2987 2988A left neighbor segment is assumed to end at the start vertex of the 2989current segement, and to start at the previous vertex in the vertex 2990buffer. Similarly, the right neighbor segment is assumed to start at 2991the end vertex of the current segment, and to end at the next vertex in 2992the vertex buffer. 2993 2994Only when the left and right bits are properly specified the current 2995segment can properly attach to the left and/or right neighbor, 2996otherwise the touching area may not get rendererd properly. 2997 2998##### Bézier Basis 2999 3000For the cubic Bézier basis the indices point to the first of 4 3001consecutive control points in the vertex buffer. These control points 3002use the cubic Bézier basis, where the first control point represents 3003the start point of the curve, and the 4th control point the end point 3004of the curve. The Bézier basis is interpolating, thus the curve does go 3005exactly through the first and fourth control vertex. 3006 3007##### B-spline Basis 3008 3009For the cubic B-spline basis the indices point to the first of 4 3010consecutive control points in the vertex buffer. These control points 3011make up a cardinal cubic B-spline (implicit equidistant knot vector). 3012This basis is not interpolating, thus the curve does in general not go 3013through any of the control points directly. A big advantage of this 3014basis is that 3 control points can be shared for two continuous 3015neighboring curve segments, e.g. the curves (p0,p1,p2,p3) and 3016(p1,p2,p3,p4) are C1 continuous. This feature make this basis a good 3017choise to construct continuous multi-segment curves, as memory 3018consumption can be kept minimal. 3019 3020##### Hermite Basis 3021 3022For the cubic Hermite basis the indices point to the first of 2 3023consecutive points in the vertex buffer, and the first of 2 consecutive 3024tangents in the tangent buffer. These two points and two tangents make 3025up a cubic Hermite curve. This basis is interpolating, thus does 3026exactly go through the first and second control point, and the first 3027order derivative at the begin and end matches exactly the value 3028specified in the tangent buffer. When connecting two segments 3029continuously, the end point and tangent of the previous segment can be 3030shared. Different versions of Catmull-Rom splines can be easily 3031constructed usig the Hermite basis, by calculating a proper tangent 3032buffer from the control points. 3033 3034##### Catmull-Rom Basis 3035 3036For the Catmull-Rom basis the indices point to the first of 4 3037consecutive control points in the vertex buffer. This basis goes 3038through p1 and p2, with tangents (p2-p0)/2 and (p3-p1)/2. 3039 3040##### Flat Curves 3041 3042The `RTC_GEOMETRY_TYPE_FLAT_*` flat mode is a fast mode designed to 3043render distant hair. In this mode the curve is rendered as a connected 3044sequence of ray facing quads. Individual quads are considered to have 3045subpixel size, and zooming onto the curve might show geometric 3046artifacts. The number of quads to subdivide into can be specified 3047through the `rtcSetGeometryTessellationRate` function. By default the 3048tessellation rate is 4. 3049 3050##### Normal Oriented Curves 3051 3052The `RTC_GEOMETRY_TYPE_NORMAL_ORIENTED_*` mode is a mode designed to 3053render blades of grass. In this mode a vertex spline has to get 3054specified as for the previous modes, but additionally a normal spline 3055is required. If the Hermite basis is used, the `RTC_BUFFER_TYPE_NORMAL` 3056and `RTC_BUFFER_TYPE_NORMAL_DERIVATIVE` buffers have both to be set. 3057 3058The curve is rendered as a flat band whose center approximately follows 3059the provided vertex spline, whose half width approximately follows the 3060provided radius spline, and whose normal orientation approximately 3061follows the provided normal spline. 3062 3063To intersect the normal oriented curve, we perform a newton-raphson 3064style intersection of a ray with a tensor product surface of a linear 3065basis (perpendicular to the curve) and cubic Bézier basis (along the 3066curve). We use a guide curve and its derivatives to construct the 3067control points of that surface. The guide curve is defined by a sweep 3068surface defined by sweeping a line centered at the vertex spline 3069location along the curve. At each parameter value the half width of the 3070line matches the radius spline, and the direction matches the cross 3071product of the normal from the normal spline and tangent of the vertex 3072spline. Note that this construction does not work when the provided 3073normals are parallel to the curve direction. For this reason the 3074provided normals should best be kept as perpendicular to the curve 3075direction as possible. 3076 3077##### Round Curves 3078 3079In the `RTC_GEOMETRY_TYPE_ROUND_*` round mode, a real geometric surface 3080is rendered for the curve, which is more expensive but allows closeup 3081views. 3082 3083For the linear basis the round mode renders a cone that tangentially 3084touches a start-sphere and end-sphere. The start sphere is rendered 3085when no previous segments is indicated by the neighbor bits. The end 3086sphere is always rendered but parts that lie inside the next segment 3087are clipped away (if that next segment exists). This way a curve is 3088closed on both ends and the interiour will render properly as long as 3089only neighboring segments penetrate into a segment. For this to work 3090properly it is important that the flags buffer is properly populated 3091with neighbor information. 3092 3093For the cubic polynomial bases, the round mode renders a sweep surface 3094by sweeping a varying radius circle tangential along the curve. As a 3095limitation, the radius of the curve has to be smaller than the 3096curvature radius of the curve at each location on the curve. 3097 3098The intersection with the curve segment stores the parametric hit 3099location along the curve segment as u-coordinate (range 0 to +1). 3100 3101For flat curves, the v-coordinate is set to the normalized distance in 3102the range -1 to +1. For normal oriented curves the v-coordinate is in 3103the range 0 to 1. For the linear basis and in round mode the 3104v-coordinate is set to zero. 3105 3106In flat mode, the geometry normal `Ng` is set to the tangent of the 3107curve at the hit location. In round mode and for normal oriented 3108curves, the geometry normal `Ng` is set to the non-normalized geometric 3109normal of the surface. 3110 3111For multi-segment motion blur, the number of time steps must be first 3112specified using the `rtcSetGeometryTimeStepCount` call. Then a vertex 3113buffer for each time step can be set using different buffer slots, and 3114all these buffers must have the same stride and size. For the Hermite 3115basis also a tangent buffer has to be set for each time step and for 3116normal oriented curves a normal buffer has to get specified for each 3117time step. 3118 3119Also see tutorials [Hair] and [Curves] for examples of how to 3120create and use curve geometries. 3121 3122#### EXIT STATUS {#exit-status} 3123 3124On failure `NULL` is returned and an error code is set that can be 3125queried using `rtcGetDeviceError`. 3126 3127#### SEE ALSO {#see-also} 3128 3129[rtcNewGeometry], [RTCCurveFlags] 3130 3131 3132 3133RTC\_GEOMETRY\_TYPE\_POINT 3134-------------------------- 3135 3136#### NAME {#name} 3137 3138 RTC_GEOMETRY_TYPE_SPHERE_POINT - 3139 point geometry spheres 3140 3141 RTC_GEOMETRY_TYPE_DISC_POINT - 3142 point geometry with ray-oriented discs 3143 3144 RTC_GEOMETRY_TYPE_ORIENTED_DISC_POINT - 3145 point geometry with normal-oriented discs 3146 3147#### SYNOPSIS {#synopsis} 3148 3149 #include <embree3/rtcore.h> 3150 3151 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_SPHERE_POINT); 3152 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_DISC_POINT); 3153 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_ORIENTED_DISC_POINT); 3154 3155#### DESCRIPTION {#description} 3156 3157Points with per vertex radii are supported with sphere, ray-oriented 3158discs, and normal-oriented discs geometric representations. Such point 3159geometries are created by passing `RTC_GEOMETRY_TYPE_SPHERE_POINT`, 3160`RTC_GEOMETRY_TYPE_DISC_POINT`, or 3161`RTC_GEOMETRY_TYPE_ORIENTED_DISC_POINT` to the `rtcNewGeometry` 3162function. The point vertices can be specified t through a vertex buffer 3163(`RTC_BUFFER_TYPE_VERTEX`). For the normal oriented discs a normal 3164buffer (`RTC_BUFFER_TYPE_NORMAL`) has to get specified additionally. 3165See `rtcSetGeometryBuffer` and `rtcSetSharedGeometryBuffer` for more 3166details on how to set buffers. 3167 3168The vertex buffer stores each control vertex in the form of a single 3169precision position and radius stored in (`x`, `y`, `z`, `r`) order in 3170memory (`RTC_FORMAT_FLOAT4` format). The number of vertices is inferred 3171from the size of this buffer. Similarly, the normal buffer stores a 3172single precision normal per control vertex (`x`, `y`, `z` order and 3173`RTC_FORMAT_FLOAT3` format). 3174 3175In the `RTC_GEOMETRY_TYPE_SPHERE_POINT` mode, a real geometric surface 3176is rendered for the curve, which is more expensive but allows closeup 3177views. 3178 3179The `RTC_GEOMETRY_TYPE_DISC_POINT` flat mode is a fast mode designed to 3180render distant points. In this mode the point is rendered as a ray 3181facing disc. 3182 3183The `RTC_GEOMETRY_TYPE_ORIENTED_DISC_POINT` mode is a mode designed as 3184a midpoint geometrically between ray facing discs and spheres. In this 3185mode the point is rendered as a normal oriented disc. 3186 3187For all point types, only the hit distance and geometry normal is 3188returned as hit information, u and v are set to zero. 3189 3190For multi-segment motion blur, the number of time steps must be first 3191specified using the `rtcSetGeometryTimeStepCount` call. Then a vertex 3192buffer for each time step can be set using different buffer slots, and 3193all these buffers must have the same stride and size. 3194 3195Also see tutorial [Points] for an example of how to create and use 3196point geometries. 3197 3198#### EXIT STATUS {#exit-status} 3199 3200On failure `NULL` is returned and an error code is set that can be 3201queried using `rtcGetDeviceError`. 3202 3203#### SEE ALSO {#see-also} 3204 3205[rtcNewGeometry] 3206 3207 3208 3209RTC\_GEOMETRY\_TYPE\_USER 3210------------------------- 3211 3212#### NAME {#name} 3213 3214 RTC_GEOMETRY_TYPE_USER - user geometry type 3215 3216#### SYNOPSIS {#synopsis} 3217 3218 #include <embree3/rtcore.h> 3219 3220 RTCGeometry geometry = 3221 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_USER); 3222 3223#### DESCRIPTION {#description} 3224 3225User-defined geometries contain a number of user-defined primitives, 3226just like triangle meshes contain multiple triangles. The shape of the 3227user-defined primitives is specified through registered callback 3228functions, which enable extending Embree with arbitrary types of 3229primitives. 3230 3231User-defined geometries are created by passing `RTC_GEOMETRY_TYPE_USER` 3232to the `rtcNewGeometry` function call. One has to set the number of 3233primitives (see `rtcSetGeometryUserPrimitiveCount`), a user data 3234pointer (see `rtcSetGeometryUserData`), a bounding function closure 3235(see `rtcSetGeometryBoundsFunction`), as well as user-defined intersect 3236(see `rtcSetGeometryIntersectFunction`) and occluded (see 3237`rtcSetGeometryOccludedFunction`) callback functions. The bounding 3238function is used to query the bounds of all time steps of a user 3239primitive, while the intersect and occluded callback functions are 3240called to intersect the primitive with a ray. The user data pointer is 3241passed to each callback invocation and can be used to point to the 3242application's representation of the user geometry. 3243 3244The creation of a user geometry typically looks the following: 3245 3246 RTCGeometry geometry = rtcNewGeometry(device, RTC_GEOMETRY_TYPE_USER); 3247 rtcSetGeometryUserPrimitiveCount(geometry, numPrimitives); 3248 rtcSetGeometryUserData(geometry, userGeometryRepresentation); 3249 rtcSetGeometryBoundsFunction(geometry, boundsFunction); 3250 rtcSetGeometryIntersectFunction(geometry, intersectFunction); 3251 rtcSetGeometryOccludedFunction(geometry, occludedFunction); 3252 3253Please have a look at the `rtcSetGeometryBoundsFunction`, 3254`rtcSetGeometryIntersectFunction`, and `rtcSetGeometryOccludedFunction` 3255functions on the implementation of the callback functions. 3256 3257Primitives of a user geometry are ignored during rendering when their 3258bounds are empty, thus bounds have lower\>upper in at least one 3259dimension. 3260 3261See tutorial [User Geometry] for an example of how to use the 3262user-defined geometries. 3263 3264#### EXIT STATUS {#exit-status} 3265 3266On failure `NULL` is returned and an error code is set that can be 3267queried using `rtcGetDeviceError`. 3268 3269#### SEE ALSO {#see-also} 3270 3271[rtcNewGeometry], [rtcSetGeometryUserPrimitiveCount], 3272[rtcSetGeometryUserData], [rtcSetGeometryBoundsFunction], 3273[rtcSetGeometryIntersectFunction], [rtcSetGeometryOccludedFunction] 3274 3275 3276 3277RTC\_GEOMETRY\_TYPE\_INSTANCE 3278----------------------------- 3279 3280#### NAME {#name} 3281 3282 RTC_GEOMETRY_TYPE_INSTANCE - instance geometry type 3283 3284#### SYNOPSIS {#synopsis} 3285 3286 #include <embree3/rtcore.h> 3287 3288 RTCGeometry geometry = 3289 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE); 3290 3291#### DESCRIPTION {#description} 3292 3293Embree supports instancing of scenes using affine transformations (3×3 3294matrix plus translation). As the instanced scene is stored only a 3295single time, even if instanced to multiple locations, this feature can 3296be used to create very complex scenes with small memory footprint. 3297 3298Embree supports both single-level instancing and multi-level 3299instancing. The maximum instance nesting depth is 3300`RTC_MAX_INSTANCE_LEVEL_COUNT`; it can be configured at compile-time 3301using the constant `EMBREE_MAX_INSTANCE_LEVEL_COUNT`. Users should 3302adapt this constant to their needs: instances nested any deeper are 3303silently ignored in release mode, and cause assertions in debug mode. 3304 3305Instances are created by passing `RTC_GEOMETRY_TYPE_INSTANCE` to the 3306`rtcNewGeometry` function call. The instanced scene can be set using 3307the `rtcSetGeometryInstancedScene` call, and the affine transformation 3308can be set using the `rtcSetGeometryTransform` function. 3309 3310Please note that `rtcCommitScene` on the instanced scene should be 3311called first, followed by `rtcCommitGeometry` on the instance, followed 3312by `rtcCommitScene` for the top-level scene containing the instance. 3313 3314If a ray hits the instance, the `geomID` and `primID` members of the 3315hit are set to the geometry ID and primitive ID of the hit primitive in 3316the instanced scene, and the `instID` member of the hit is set to the 3317geometry ID of the instance in the top-level scene. 3318 3319The instancing scheme can also be implemented using user geometries. To 3320achieve this, the user geometry code should set the `instID` member of 3321the intersection context to the geometry ID of the instance, then trace 3322the transformed ray, and finally set the `instID` field of the 3323intersection context again to -1. The `instID` field is copied 3324automatically by each primitive intersector into the `instID` field of 3325the hit structure when the primitive is hit. See the [User Geometry] 3326tutorial for an example. 3327 3328For multi-segment motion blur, the number of time steps must be first 3329specified using the `rtcSetGeometryTimeStepCount` function. Then a 3330transformation for each time step can be specified using the 3331`rtcSetGeometryTransform` function. 3332 3333See tutorials [Instanced Geometry] and [Multi Level Instancing] for 3334examples of how to use instances. 3335 3336#### EXIT STATUS {#exit-status} 3337 3338On failure `NULL` is returned and an error code is set that can be 3339queried using `rtcGetDeviceError`. 3340 3341#### SEE ALSO {#see-also} 3342 3343[rtcNewGeometry], [rtcSetGeometryInstancedScene], 3344[rtcSetGeometryTransform] 3345 3346 3347 3348RTCCurveFlags 3349------------- 3350 3351#### NAME {#name} 3352 3353 RTCCurveFlags - per segment flags for curve geometry 3354 3355#### SYNOPSIS {#synopsis} 3356 3357 #include <embree3/rtcore.h> 3358 3359enum RTCCurveFlags { RTC\_CURVE\_FLAG\_NEIGHBOR\_LEFT = (1 \<\< 0), 3360RTC\_CURVE\_FLAG\_NEIGHBOR\_RIGHT = (1 \<\< 1) }; 3361 3362#### DESCRIPTION {#description} 3363 3364The RTCCurveFlags type is used for linear curves to determine if the 3365left and/or right neighbor segment exist. Therefore one attaches a 3366buffer of type RTC\_BUFFER\_TYPE\_FLAGS to the curve geometry which 3367stores an individual byte per curve segment. 3368 3369If the RTC\_CURVE\_FLAG\_NEIGHBOR\_LEFT flag in that byte is enabled 3370for a curve segment, then the left segment exists (which starts one 3371vertex before the start vertex of the current curve) and the current 3372segment is rendered to properly attach to that segment. 3373 3374If the RTC\_CURVE\_FLAG\_NEIGHBOR\_RIGHT flag in that byte is enabled 3375for a curve segment, then the right segment exists (which ends one 3376vertex after the end vertex of the current curve) and the current 3377segment is rendered to properly attach to that segment. 3378 3379When not properly specifying left and right flags for linear curves, 3380the rendering at the ending of these curves may not look correct, in 3381particular when round linear curves are viewed from the inside. 3382 3383#### EXIT STATUS {#exit-status} 3384 3385#### SEE ALSO {#see-also} 3386 3387[RTC\_GEOMETRY\_TYPE\_CURVE] 3388 3389 3390 3391rtcRetainGeometry 3392----------------- 3393 3394#### NAME {#name} 3395 3396 rtcRetainGeometry - increments the geometry reference count 3397 3398#### SYNOPSIS {#synopsis} 3399 3400 #include <embree3/rtcore.h> 3401 3402 void rtcRetainGeometry(RTCGeometry geometry); 3403 3404#### DESCRIPTION {#description} 3405 3406Geometry objects are reference counted. The `rtcRetainGeometry` 3407function increments the reference count of the passed geometry object 3408(`geometry` argument). This function together with `rtcReleaseGeometry` 3409allows to use the internal reference counting in a C++ wrapper class to 3410handle the ownership of the object. 3411 3412#### EXIT STATUS {#exit-status} 3413 3414On failure an error code is set that can be queried using 3415`rtcGetDeviceError`. 3416 3417#### SEE ALSO {#see-also} 3418 3419[rtcNewGeometry], [rtcReleaseGeometry] 3420 3421 3422 3423rtcReleaseGeometry 3424------------------ 3425 3426#### NAME {#name} 3427 3428 rtcReleaseGeometry - decrements the geometry reference count 3429 3430#### SYNOPSIS {#synopsis} 3431 3432 #include <embree3/rtcore.h> 3433 3434 void rtcReleaseGeometry(RTCGeometry geometry); 3435 3436#### DESCRIPTION {#description} 3437 3438Geometry objects are reference counted. The `rtcReleaseGeometry` 3439function decrements the reference count of the passed geometry object 3440(`geometry` argument). When the reference count falls to 0, the 3441geometry gets destroyed. 3442 3443#### EXIT STATUS {#exit-status} 3444 3445On failure an error code is set that can be queried using 3446`rtcGetDeviceError`. 3447 3448#### SEE ALSO {#see-also} 3449 3450[rtcNewGeometry], [rtcRetainGeometry] 3451 3452 3453 3454rtcCommitGeometry 3455----------------- 3456 3457#### NAME {#name} 3458 3459 rtcCommitGeometry - commits geometry changes 3460 3461#### SYNOPSIS {#synopsis} 3462 3463 #include <embree3/rtcore.h> 3464 3465 void rtcCommitGeometry(RTCGeometry geometry); 3466 3467#### DESCRIPTION {#description} 3468 3469The `rtcCommitGeometry` function is used to commit all geometry changes 3470performed to a geometry (`geometry` parameter). After a geometry gets 3471modified, this function must be called to properly update the internal 3472state of the geometry to perform interpolations using `rtcInterpolate` 3473or to commit a scene containing the geometry using `rtcCommitScene`. 3474 3475#### EXIT STATUS {#exit-status} 3476 3477On failure an error code is set that can be queried using 3478`rtcGetDeviceError`. 3479 3480#### SEE ALSO {#see-also} 3481 3482[rtcInterpolate], [rtcCommitScene] 3483 3484 3485 3486rtcEnableGeometry 3487----------------- 3488 3489#### NAME {#name} 3490 3491 rtcEnableGeometry - enables the geometry 3492 3493#### SYNOPSIS {#synopsis} 3494 3495 #include <embree3/rtcore.h> 3496 3497 void rtcEnableGeometry(RTCGeometry geometry); 3498 3499#### DESCRIPTION {#description} 3500 3501The `rtcEnableGeometry` function enables the specified geometry 3502(`geometry` argument). Only enabled geometries are rendered. Each 3503geometry is enabled by default at construction time. 3504 3505After enabling a geometry, the scene containing that geometry must be 3506committed using `rtcCommitScene` for the change to have effect. 3507 3508#### EXIT STATUS {#exit-status} 3509 3510On failure an error code is set that can be queried using 3511`rtcGetDeviceError`. 3512 3513#### SEE ALSO {#see-also} 3514 3515[rtcNewGeometry], [rtcDisableGeometry], [rtcCommitScene] 3516 3517 3518 3519rtcDisableGeometry 3520------------------ 3521 3522#### NAME {#name} 3523 3524 rtcDisableGeometry - disables the geometry 3525 3526#### SYNOPSIS {#synopsis} 3527 3528 #include <embree3/rtcore.h> 3529 3530 void rtcDisableGeometry(RTCGeometry geometry); 3531 3532#### DESCRIPTION {#description} 3533 3534The `rtcDisableGeometry` function disables the specified geometry 3535(`geometry` argument). A disabled geometry is not rendered. Each 3536geometry is enabled by default at construction time. 3537 3538After disabling a geometry, the scene containing that geometry must be 3539committed using `rtcCommitScene` for the change to have effect. 3540 3541#### EXIT STATUS {#exit-status} 3542 3543On failure an error code is set that can be queried using 3544`rtcGetDeviceError`. 3545 3546#### SEE ALSO {#see-also} 3547 3548[rtcNewGeometry], [rtcEnableGeometry], [rtcCommitScene] 3549 3550 3551 3552rtcSetGeometryTimeStepCount 3553--------------------------- 3554 3555#### NAME {#name} 3556 3557 rtcSetGeometryTimeStepCount - sets the number of time steps of the 3558 geometry 3559 3560#### SYNOPSIS {#synopsis} 3561 3562 #include <embree3/rtcore.h> 3563 3564 void rtcSetGeometryTimeStepCount( 3565 RTCGeometry geometry, 3566 unsigned int timeStepCount 3567 ); 3568 3569#### DESCRIPTION {#description} 3570 3571The `rtcSetGeometryTimeStepCount` function sets the number of time 3572steps for multi-segment motion blur (`timeStepCount` parameter) of the 3573specified geometry (`geometry` parameter). 3574 3575For triangle meshes (`RTC_GEOMETRY_TYPE_TRIANGLE`), quad meshes 3576(`RTC_GEOMETRY_TYPE_QUAD`), curves (`RTC_GEOMETRY_TYPE_CURVE`), points 3577(`RTC_GEOMETRY_TYPE_POINT`), and subdivision geometries 3578(`RTC_GEOMETRY_TYPE_SUBDIVISION`), the number of time steps directly 3579corresponds to the number of vertex buffer slots available 3580(`RTC_BUFFER_TYPE_VERTEX` buffer type). For these geometries, one 3581vertex buffer per time step must be specified when creating 3582multi-segment motion blur geometries. 3583 3584For instance geometries (`RTC_GEOMETRY_TYPE_INSTANCE`), a 3585transformation must be specified for each time step (see 3586`rtcSetGeometryTransform`). 3587 3588For user geometries, the registered bounding callback function must 3589provide a bounding box per primitive and time step, and the 3590intersection and occlusion callback functions should properly intersect 3591the motion-blurred geometry at the ray time. 3592 3593#### EXIT STATUS {#exit-status} 3594 3595On failure an error code is set that can be queried using 3596`rtcGetDeviceError`. 3597 3598#### SEE ALSO {#see-also} 3599 3600[rtcNewGeometry], [rtcSetGeometryTimeRange] 3601 3602 3603 3604rtcSetGeometryTimeRange 3605----------------------- 3606 3607#### NAME {#name} 3608 3609 rtcSetGeometryTimeRange - sets the time range for a motion blur geometry 3610 3611#### SYNOPSIS {#synopsis} 3612 3613 #include <embree3/rtcore.h> 3614 3615 void rtcSetGeometryTimeRange( 3616 RTCGeometry geometry, 3617 float startTime, 3618 float endTime 3619 ); 3620 3621#### DESCRIPTION {#description} 3622 3623The `rtcSetGeometryTimeRange` function sets a time range which defines 3624the start (and end time) of the first (and last) time step of a motion 3625blur geometry. The time range is defined relative to the camera shutter 3626interval [0,1] but it can be arbitrary. Thus the startTime can be 3627smaller, equal, or larger 0, indicating a geometry whose animation 3628definition start before, at, or after the camera shutter opens. Similar 3629the endTime can be smaller, equal, or larger than 1, indicating a 3630geometry whose animation definition ends after, at, or before the 3631camera shutter closes. The startTime has to be smaller or equal to the 3632endTime. 3633 3634The default time range when this function is not called is the entire 3635camera shutter [0,1]. For best performance at most one time segment 3636of the piece wise linear definition of the motion should fall outside 3637the shutter window to the left and to the right. Thus do not set the 3638startTime or endTime too far outside the [0,1] interval for best 3639performance. 3640 3641This time range feature will also allow geometries to appear and 3642disappear during the camera shutter time if the specified time range is 3643a sub range of [0,1]. 3644 3645Please also have a look at the `rtcSetGeometryTimeStepCount` function 3646to see how to define the time steps for the specified time range. 3647 3648#### EXIT STATUS {#exit-status} 3649 3650On failure an error code is set that can be queried using 3651`rtcGetDeviceError`. 3652 3653#### SEE ALSO {#see-also} 3654 3655[rtcSetGeometryTimeStepCount] 3656 3657 3658 3659rtcSetGeometryVertexAttributeCount 3660---------------------------------- 3661 3662#### NAME {#name} 3663 3664 rtcSetGeometryVertexAttributeCount - sets the number of vertex 3665 attributes of the geometry 3666 3667#### SYNOPSIS {#synopsis} 3668 3669 #include <embree3/rtcore.h> 3670 3671 void rtcSetGeometryVertexAttributeCount( 3672 RTCGeometry geometry, 3673 unsigned int vertexAttributeCount 3674 ); 3675 3676#### DESCRIPTION {#description} 3677 3678The `rtcSetGeometryVertexAttributeCount` function sets the number of 3679slots (`vertexAttributeCount` parameter) for vertex attribute buffers 3680(`RTC_BUFFER_TYPE_VERTEX_ATTRIBUTE`) that can be used for the specified 3681geometry (`geometry` parameter). 3682 3683This function is supported only for triangle meshes 3684(`RTC_GEOMETRY_TYPE_TRIANGLE`), quad meshes (`RTC_GEOMETRY_TYPE_QUAD`), 3685curves (`RTC_GEOMETRY_TYPE_CURVE`), points (`RTC_GEOMETRY_TYPE_POINT`), 3686and subdivision geometries (`RTC_GEOMETRY_TYPE_SUBDIVISION`). 3687 3688#### EXIT STATUS {#exit-status} 3689 3690On failure an error code is set that can be queried using 3691`rtcGetDeviceError`. 3692 3693#### SEE ALSO {#see-also} 3694 3695[rtcNewGeometry], [RTCBufferType] 3696 3697 3698 3699rtcSetGeometryMask 3700------------------ 3701 3702#### NAME {#name} 3703 3704 rtcSetGeometryMask - sets the geometry mask 3705 3706#### SYNOPSIS {#synopsis} 3707 3708 #include <embree3/rtcore.h> 3709 3710 void rtcSetGeometryMask( 3711 RTCGeometry geometry, 3712 unsigned int mask 3713 ); 3714 3715#### DESCRIPTION {#description} 3716 3717The `rtcSetGeometryMask` function sets a 32-bit geometry mask (`mask` 3718argument) for the specified geometry (`geometry` argument). 3719 3720This geometry mask is used together with the ray mask stored inside the 3721`mask` field of the ray. The primitives of the geometry are hit by the 3722ray only if the bitwise `and` operation of the geometry mask with the 3723ray mask is not 0. This feature can be used to disable selected 3724geometries for specifically tagged rays, e.g. to disable shadow casting 3725for certain geometries. 3726 3727Ray masks are disabled in Embree by default at compile time, and can be 3728enabled through the `EMBREE_RAY_MASK` parameter in CMake. One can query 3729whether ray masks are enabled by querying the 3730`RTC_DEVICE_PROPERTY_RAY_MASK_SUPPORTED` device property using 3731`rtcGetDeviceProperty`. 3732 3733#### EXIT STATUS {#exit-status} 3734 3735On failure an error code is set that can be queried using 3736`rtcGetDeviceError`. 3737 3738#### SEE ALSO {#see-also} 3739 3740[RTCRay], [rtcGetDeviceProperty] 3741 3742 3743 3744rtcSetGeometryBuildQuality 3745-------------------------- 3746 3747#### NAME {#name} 3748 3749 rtcSetGeometryBuildQuality - sets the build quality for the geometry 3750 3751#### SYNOPSIS {#synopsis} 3752 3753 #include <embree3/rtcore.h> 3754 3755 void rtcSetGeometryBuildQuality( 3756 RTCGeometry geometry, 3757 enum RTCBuildQuality quality 3758 ); 3759 3760#### DESCRIPTION {#description} 3761 3762The `rtcSetGeometryBuildQuality` function sets the build quality 3763(`quality` argument) for the specified geometry (`geometry` argument). 3764The per-geometry build quality is only a hint and may be ignored. 3765Embree currently uses the per-geometry build quality when the scene 3766build quality is set to `RTC_BUILD_QUALITY_LOW`. In this mode a 3767two-level acceleration structure is build, and geometries build a 3768separate acceleration structure using the geometry build quality. The 3769per-geometry build quality can be one of: 3770 3771- `RTC_BUILD_QUALITY_LOW`: Creates lower quality data structures, 3772 e.g. for dynamic scenes. 3773 3774- `RTC_BUILD_QUALITY_MEDIUM`: Default build quality for most usages. 3775 Gives a good compromise between build and render performance. 3776 3777- `RTC_BUILD_QUALITY_HIGH`: Creates higher quality data structures 3778 for final-frame rendering. Enables a spatial split builder for 3779 certain primitive types. 3780 3781- `RTC_BUILD_QUALITY_REFIT`: Uses a BVH refitting approach when 3782 changing only the vertex buffer. 3783 3784#### EXIT STATUS {#exit-status} 3785 3786On failure an error code is set that can be queried using 3787`rtcGetDeviceError`. 3788 3789#### SEE ALSO {#see-also} 3790 3791[rtcSetSceneBuildQuality] 3792 3793 3794 3795rtcSetGeometryBuffer 3796-------------------- 3797 3798#### NAME {#name} 3799 3800 rtcSetGeometryBuffer - assigns a view of a buffer to the geometry 3801 3802#### SYNOPSIS {#synopsis} 3803 3804 #include <embree3/rtcore.h> 3805 3806 void rtcSetGeometryBuffer( 3807 RTCGeometry geometry, 3808 enum RTCBufferType type, 3809 unsigned int slot, 3810 enum RTCFormat format, 3811 RTCBuffer buffer, 3812 size_t byteOffset, 3813 size_t byteStride, 3814 size_t itemCount 3815 ); 3816 3817#### DESCRIPTION {#description} 3818 3819The `rtcSetGeometryBuffer` function binds a view of a buffer object 3820(`buffer` argument) to a geometry buffer type and slot (`type` and 3821`slot` argument) of the specified geometry (`geometry` argument). 3822 3823One can specify the start of the first buffer element in bytes 3824(`byteOffset` argument), the byte stride between individual buffer 3825elements (`byteStride` argument), the format of the buffer elements 3826(`format` argument), and the number of elements to bind (`itemCount`). 3827 3828The start address (`byteOffset` argument) and stride (`byteStride` 3829argument) must be both aligned to 4 bytes, otherwise the 3830`rtcSetGeometryBuffer` function will fail. 3831 3832After successful completion of this function, the geometry will hold a 3833reference to the buffer object. 3834 3835#### EXIT STATUS {#exit-status} 3836 3837On failure an error code is set that can be queried using 3838`rtcGetDeviceError`. 3839 3840#### SEE ALSO {#see-also} 3841 3842[rtcSetSharedGeometryBuffer], [rtcSetNewGeometryBuffer] 3843 3844 3845 3846rtcSetSharedGeometryBuffer 3847-------------------------- 3848 3849#### NAME {#name} 3850 3851 rtcSetSharedGeometryBuffer - assigns a view of a shared data buffer 3852 to a geometry 3853 3854#### SYNOPSIS {#synopsis} 3855 3856 #include <embree3/rtcore.h> 3857 3858 void rtcSetSharedGeometryBuffer( 3859 RTCGeometry geometry, 3860 enum RTCBufferType type, 3861 unsigned int slot, 3862 enum RTCFormat format, 3863 const void* ptr, 3864 size_t byteOffset, 3865 size_t byteStride, 3866 size_t itemCount 3867 ); 3868 3869#### DESCRIPTION {#description} 3870 3871The `rtcSetSharedGeometryBuffer` function binds a view of a shared 3872user-managed data buffer (`ptr` argument) to a geometry buffer type and 3873slot (`type` and `slot` argument) of the specified geometry (`geometry` 3874argument). 3875 3876One can specify the start of the first buffer element in bytes 3877(`byteOffset` argument), the byte stride between individual buffer 3878elements (`byteStride` argument), the format of the buffer elements 3879(`format` argument), and the number of elements to bind (`itemCount`). 3880 3881The start address (`byteOffset` argument) and stride (`byteStride` 3882argument) must be both aligned to 4 bytes; otherwise the 3883`rtcSetGeometryBuffer` function will fail. 3884 3885When the buffer will be used as a vertex buffer 3886(`RTC_BUFFER_TYPE_VERTEX` and `RTC_BUFFER_TYPE_VERTEX_ATTRIBUTE`), the 3887last buffer element must be readable using 16-byte SSE load 3888instructions, thus padding the last element is required for certain 3889layouts. E.g. a standard `float3` vertex buffer layout should add 3890storage for at least one more float to the end of the buffer. 3891 3892The buffer data must remain valid for as long as the buffer may be 3893used, and the user is responsible for freeing the buffer data when no 3894longer required. 3895 3896Sharing buffers can significantly reduce the memory required by the 3897application, thus we recommend using this feature. When enabling the 3898`RTC_SCENE_FLAG_COMPACT` scene flag, the spatial index structures index 3899into the vertex buffer, resulting in even higher memory savings. 3900 3901#### EXIT STATUS {#exit-status} 3902 3903On failure an error code is set that can be queried using 3904`rtcGetDeviceError`. 3905 3906#### SEE ALSO {#see-also} 3907 3908[rtcSetGeometryBuffer], [rtcSetNewGeometryBuffer] 3909 3910 3911 3912rtcSetNewGeometryBuffer 3913----------------------- 3914 3915#### NAME {#name} 3916 3917 rtcSetNewGeometryBuffer - creates and assigns a new data buffer to 3918 the geometry 3919 3920#### SYNOPSIS {#synopsis} 3921 3922 #include <embree3/rtcore.h> 3923 3924 void* rtcSetNewGeometryBuffer( 3925 RTCGeometry geometry, 3926 enum RTCBufferType type, 3927 unsigned int slot, 3928 enum RTCFormat format, 3929 size_t byteStride, 3930 size_t itemCount 3931 ); 3932 3933#### DESCRIPTION {#description} 3934 3935The `rtcSetNewGeometryBuffer` function creates a new data buffer of 3936specified format (`format` argument), byte stride (`byteStride` 3937argument), and number of items (`itemCount` argument), and assigns it 3938to a geometry buffer slot (`type` and `slot` argument) of the specified 3939geometry (`geometry` argument). The buffer data is managed internally 3940and automatically freed when the geometry is destroyed. 3941 3942The byte stride (`byteStride` argument) must be aligned to 4 bytes; 3943otherwise the `rtcSetNewGeometryBuffer` function will fail. 3944 3945The allocated buffer will be automatically over-allocated slightly when 3946used as a vertex buffer, where a requirement is that each buffer 3947element should be readable using 16-byte SSE load instructions. 3948 3949#### EXIT STATUS {#exit-status} 3950 3951On failure an error code is set that can be queried using 3952`rtcGetDeviceError`. 3953 3954#### SEE ALSO {#see-also} 3955 3956[rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer] 3957 3958 3959 3960RTCFormat 3961--------- 3962 3963#### NAME {#name} 3964 3965 RTCFormat - specifies format of data in buffers 3966 3967#### SYNOPSIS {#synopsis} 3968 3969 #include <embree3/rtcore_ray.h> 3970 3971 enum RTCFormat 3972 { 3973 RTC_FORMAT_UINT, 3974 RTC_FORMAT_UINT2, 3975 RTC_FORMAT_UINT3, 3976 RTC_FORMAT_UINT4, 3977 3978 RTC_FORMAT_FLOAT, 3979 RTC_FORMAT_FLOAT2, 3980 RTC_FORMAT_FLOAT3, 3981 RTC_FORMAT_FLOAT4, 3982 RTC_FORMAT_FLOAT5, 3983 RTC_FORMAT_FLOAT6, 3984 RTC_FORMAT_FLOAT7, 3985 RTC_FORMAT_FLOAT8, 3986 RTC_FORMAT_FLOAT9, 3987 RTC_FORMAT_FLOAT10, 3988 RTC_FORMAT_FLOAT11, 3989 RTC_FORMAT_FLOAT12, 3990 RTC_FORMAT_FLOAT13, 3991 RTC_FORMAT_FLOAT14, 3992 RTC_FORMAT_FLOAT15, 3993 RTC_FORMAT_FLOAT16, 3994 3995 RTC_FORMAT_FLOAT3X4_ROW_MAJOR, 3996 RTC_FORMAT_FLOAT4X4_ROW_MAJOR, 3997 3998 RTC_FORMAT_FLOAT3X4_COLUMN_MAJOR, 3999 RTC_FORMAT_FLOAT4X4_COLUMN_MAJOR, 4000 4001 RTC_FORMAT_GRID, 4002 4003}; 4004 4005#### DESCRIPTION {#description} 4006 4007The `RTFormat` structure defines the data format stored in data buffers 4008provided to Embree using the [rtcSetGeometryBuffer], 4009[rtcSetSharedGeometryBuffer], and [rtcSetNewGeometryBuffer] API 4010calls. 4011 4012The `RTC_FORMAT_UINT/2/3/4` format are used to specify that data 4013buffers store unsigned integers, or unsigned integer vectors of size 40142,3 or 4. This format has typically to get used when specifying index 4015buffers, e.g. `RTC_FORMAT_UINT3` for triangle meshes. 4016 4017The `RTC_FORMAT_FLOAT/2/3/4...` format are used to specify that data 4018buffers store single precision floating point values, or vectors there 4019of (size 2,3,4, etc.). This format is typcally used to specify to 4020format of vertex buffers, e.g. the `RTC_FORMAT_FLOAT3` type for vertex 4021buffers of triangle meshes. 4022 4023The `RTC_FORMAT_FLOAT3X4_ROW_MAJOR` and 4024`RTC_FORMAT_FLOAT3X4_COLUMN_MAJOR` formats, specify a 3x4 floating 4025point matrix layed out either row major or column major. The 4026`RTC_FORMAT_FLOAT4X4_ROW_MAJOR` and `RTC_FORMAT_FLOAT4X4_COLUMN_MAJOR` 4027formats, specify a 4x4 floating point matrix layed out either row major 4028or column major. These matrix formats are used in the 4029[rtcSetGeometryTransform] function in order to set a transformation 4030matrix for geometries. 4031 4032The `RTC_FORMAT_GRID` is a special data format used to specify grid 4033primitives of layout RTCGrid when creating grid geometries (see 4034[RTC\_GEOMETRY\_TYPE\_GRID]). 4035 4036#### EXIT STATUS {#exit-status} 4037 4038#### SEE ALSO {#see-also} 4039 4040[rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer], 4041[rtcSetNewGeometryBuffer], [rtcSetGeometryTransform] 4042 4043 4044 4045RTCBufferType 4046------------- 4047 4048#### NAME {#name} 4049 4050 RTCFormat - specifies format of data in buffers 4051 4052#### SYNOPSIS {#synopsis} 4053 4054 #include <embree3/rtcore_ray.h> 4055 4056 enum RTCBufferType 4057 { 4058 RTC_BUFFER_TYPE_INDEX = 0, 4059 RTC_BUFFER_TYPE_VERTEX = 1, 4060 RTC_BUFFER_TYPE_VERTEX_ATTRIBUTE = 2, 4061 RTC_BUFFER_TYPE_NORMAL = 3, 4062 RTC_BUFFER_TYPE_TANGENT = 4, 4063 RTC_BUFFER_TYPE_NORMAL_DERIVATIVE = 5, 4064 4065 RTC_BUFFER_TYPE_GRID = 8, 4066 4067 RTC_BUFFER_TYPE_FACE = 16, 4068 RTC_BUFFER_TYPE_LEVEL = 17, 4069 RTC_BUFFER_TYPE_EDGE_CREASE_INDEX = 18, 4070 RTC_BUFFER_TYPE_EDGE_CREASE_WEIGHT = 19, 4071 RTC_BUFFER_TYPE_VERTEX_CREASE_INDEX = 20, 4072 RTC_BUFFER_TYPE_VERTEX_CREASE_WEIGHT = 21, 4073 RTC_BUFFER_TYPE_HOLE = 22, 4074 4075 RTC_BUFFER_TYPE_FLAGS = 32 4076 }; 4077 4078#### DESCRIPTION {#description} 4079 4080The `RTBufferType` structure defines slots to assign data buffers to 4081using the [rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer], and 4082[rtcSetNewGeometryBuffer] API calls. 4083 4084For most geometry types the `RTC_BUFFER_TYPE_INDEX` slot is used to 4085assign an index buffer, while the `RTC_BUFFER_TYPE_VERTEX` is used to 4086assign the corresponding vertex buffer. 4087 4088The `RTC_BUFFER_TYPE_VERTEX_ATTRIBUTE` slot can get used to assign 4089arbitrary additional vertex data which can get interpolated using the 4090[rtcInterpolate] API call. 4091 4092The `RTC_BUFFER_TYPE_NORMAL`, `RTC_BUFFER_TYPE_TANGENT`, and 4093`RTC_BUFFER_TYPE_NORMAL_DERIVATIVE` are special buffers required to 4094assign per vertex normals, tangents, and normal derivatives for some 4095curve types. 4096 4097The `RTC_BUFFER_TYPE_GRID` buffer is used to assign the grid primitive 4098buffer for grid geometries (see [RTC\_GEOMETRY\_TYPE\_GRID]). 4099 4100The `RTC_BUFFER_TYPE_FACE`, `RTC_BUFFER_TYPE_LEVEL`, 4101`RTC_BUFFER_TYPE_EDGE_CREASE_INDEX`, 4102`RTC_BUFFER_TYPE_EDGE_CREASE_WEIGHT`, 4103`RTC_BUFFER_TYPE_VERTEX_CREASE_INDEX`, 4104`RTC_BUFFER_TYPE_VERTEX_CREASE_WEIGHT`, and `RTC_BUFFER_TYPE_HOLE` are 4105special buffers required to create subdivision meshes (see 4106[RTC\_GEOMETRY\_TYPE\_SUBDIVISION]). 4107 4108The `RTC_BUFFER_TYPE_FLAGS` can get used to add additional flag per 4109primitive of a geometry, and is currently only used for linear curves. 4110 4111#### EXIT STATUS {#exit-status} 4112 4113#### SEE ALSO {#see-also} 4114 4115[rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer], 4116[rtcSetNewGeometryBuffer] 4117 4118 4119 4120rtcGetGeometryBufferData 4121------------------------ 4122 4123#### NAME {#name} 4124 4125 rtcGetGeometryBufferData - gets pointer to 4126 the first buffer view element 4127 4128#### SYNOPSIS {#synopsis} 4129 4130 #include <embree3/rtcore.h> 4131 4132 void* rtcGetGeometryBufferData( 4133 RTCGeometry geometry, 4134 enum RTCBufferType type, 4135 unsigned int slot 4136 ); 4137 4138#### DESCRIPTION {#description} 4139 4140The `rtcGetGeometryBufferData` function returns a pointer to the first 4141element of the buffer view attached to the specified buffer type and 4142slot (`type` and `slot` argument) of the geometry (`geometry` 4143argument). 4144 4145#### EXIT STATUS {#exit-status} 4146 4147On failure an error code is set that can be queried using 4148`rtcGetDeviceError`. 4149 4150#### SEE ALSO {#see-also} 4151 4152[rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer], 4153[rtcSetNewGeometryBuffer] 4154 4155 4156 4157rtcUpdateGeometryBuffer 4158----------------------- 4159 4160#### NAME {#name} 4161 4162 rtcUpdateGeometryBuffer - marks a buffer view bound to the geometry 4163 as modified 4164 4165#### SYNOPSIS {#synopsis} 4166 4167 #include <embree3/rtcore.h> 4168 4169 void rtcUpdateGeometryBuffer( 4170 RTCGeometry geometry, 4171 enum RTCBufferType type, 4172 unsigned int slot 4173 ); 4174 4175#### DESCRIPTION {#description} 4176 4177The `rtcUpdateGeometryBuffer` function marks the buffer view bound to 4178the specified buffer type and slot (`type` and `slot` argument) of a 4179geometry (`geometry` argument) as modified. 4180 4181If a data buffer is changed by the application, the 4182`rtcUpdateGeometryBuffer` call must be invoked for that buffer. Each 4183buffer view assigned to a buffer slot is initially marked as modified, 4184thus this function needs to be called only when doing buffer 4185modifications after the first `rtcCommitScene`. 4186 4187#### EXIT STATUS {#exit-status} 4188 4189On failure an error code is set that can be queried using 4190`rtcGetDeviceError`. 4191 4192#### SEE ALSO {#see-also} 4193 4194[rtcNewGeometry], [rtcCommitScene] 4195 4196 4197 4198rtcSetGeometryIntersectFilterFunction 4199------------------------------------- 4200 4201#### NAME {#name} 4202 4203 rtcSetGeometryIntersectFilterFunction - sets the intersection filter 4204 for the geometry 4205 4206#### SYNOPSIS {#synopsis} 4207 4208 #include <embree3/rtcore.h> 4209 4210 struct RTCFilterFunctionNArguments 4211 { 4212 int* valid; 4213 void* geometryUserPtr; 4214 const struct RTCIntersectContext* context; 4215 struct RTCRayN* ray; 4216 struct RTCHitN* hit; 4217 unsigned int N; 4218 }; 4219 4220 typedef void (*RTCFilterFunctionN)( 4221 const struct RTCFilterFunctionNArguments* args 4222 ); 4223 4224 void rtcSetGeometryIntersectFilterFunction( 4225 RTCGeometry geometry, 4226 RTCFilterFunctionN filter 4227 ); 4228 4229#### DESCRIPTION {#description} 4230 4231The `rtcSetGeometryIntersectFilterFunction` function registers an 4232intersection filter callback function (`filter` argument) for the 4233specified geometry (`geometry` argument). 4234 4235Only a single callback function can be registered per geometry, and 4236further invocations overwrite the previously set callback function. 4237Passing `NULL` as function pointer disables the registered callback 4238function. 4239 4240The registered intersection filter function is invoked for every hit 4241encountered during the `rtcIntersect`-type ray queries and can accept 4242or reject that hit. The feature can be used to define a silhouette for 4243a primitive and reject hits that are outside the silhouette. E.g. a 4244tree leaf could be modeled with an alpha texture that decides whether 4245hit points lie inside or outside the leaf. 4246 4247If the `RTC_BUILD_QUALITY_HIGH` mode is set, the filter functions may 4248be called multiple times for the same primitive hit. Further, rays 4249hitting exactly the edge might also report two hits for the same 4250surface. For certain use cases, the application may have to work around 4251this limitation by collecting already reported hits (`geomID`/`primID` 4252pairs) and ignoring duplicates. 4253 4254The filter function callback of type `RTCFilterFunctionN` gets passed a 4255number of arguments through the `RTCFilterFunctionNArguments` 4256structure. The `valid` parameter of that structure points to an integer 4257valid mask (0 means invalid and -1 means valid). The `geometryUserPtr` 4258member is a user pointer optionally set per geometry through the 4259`rtcSetGeometryUserData` function. The `context` member points to the 4260intersection context passed to the ray query function. The `ray` 4261parameter points to `N` rays in SOA layout. The `hit` parameter points 4262to `N` hits in SOA layout to test. The `N` parameter is the number of 4263rays and hits in `ray` and `hit`. The hit distance is provided as the 4264`tfar` value of the ray. If the hit geometry is instanced, the `instID` 4265member of the ray is valid, and the ray and the potential hit are in 4266object space. 4267 4268The filter callback function has the task to check for each valid ray 4269whether it wants to accept or reject the corresponding hit. To reject a 4270hit, the filter callback function just has to write `0` to the integer 4271valid mask of the corresponding ray. To accept the hit, it just has to 4272leave the valid mask set to `-1`. The filter function is further 4273allowed to change the hit and decrease the `tfar` value of the ray but 4274it should not modify other ray data nor any inactive components of the 4275ray or hit. 4276 4277When performing ray queries using `rtcIntersect1`, it is guaranteed 4278that the packet size is 1 when the callback is invoked. When performing 4279ray queries using the `rtcIntersect4/8/16` functions, it is not 4280generally guaranteed that the ray packet size (and order of rays inside 4281the packet) passed to the callback matches the initial ray packet. 4282However, under some circumstances these properties are guaranteed, and 4283whether this is the case can be queried using `rtcGetDeviceProperty`. 4284When performing ray queries using the stream API such as 4285`rtcIntersect1M`, `rtcIntersect1Mp`, `rtcIntersectNM`, or 4286`rtcIntersectNp` the order of rays and ray packet size of the callback 4287function might change to either 1, 4, 8, or 16. 4288 4289For many usage scenarios, repacking and re-ordering of rays does not 4290cause difficulties in implementing the callback function. However, 4291algorithms that need to extend the ray with additional data must use 4292the `rayID` component of the ray to identify the original ray to access 4293the per-ray data. 4294 4295The implementation of the filter function can choose to implement a 4296single code path that uses the ray access helper functions `RTCRay_XXX` 4297and hit access helper functions `RTCHit_XXX` to access ray and hit 4298data. Alternatively the code can branch to optimized implementations 4299for specific sizes of `N` and cast the `ray` and `hit` inputs to the 4300proper packet types. 4301 4302#### EXIT STATUS {#exit-status} 4303 4304On failure an error code is set that can be queried using 4305`rtcGetDeviceError`. 4306 4307#### SEE ALSO {#see-also} 4308 4309[rtcSetGeometryOccludedFilterFunction] 4310 4311 4312 4313rtcSetGeometryOccludedFilterFunction 4314------------------------------------ 4315 4316#### NAME {#name} 4317 4318 rtcSetGeometryOccludedFilterFunction - sets the occlusion filter 4319 for the geometry 4320 4321#### SYNOPSIS {#synopsis} 4322 4323 #include <embree3/rtcore.h> 4324 4325 void rtcSetGeometryOccludedFilterFunction( 4326 RTCGeometry geometry, 4327 RTCFilterFunctionN filter 4328 ); 4329 4330#### DESCRIPTION {#description} 4331 4332The `rtcSetGeometryOccludedFilterFunction` function registers an 4333occlusion filter callback function (`filter` argument) for the 4334specified geometry (`geometry` argument). 4335 4336Only a single callback function can be registered per geometry, and 4337further invocations overwrite the previously set callback function. 4338Passing `NULL` as function pointer disables the registered callback 4339function. 4340 4341The registered intersection filter function is invoked for every hit 4342encountered during the `rtcOccluded`-type ray queries and can accept or 4343reject that hit. The feature can be used to define a silhouette for a 4344primitive and reject hits that are outside the silhouette. E.g. a tree 4345leaf could be modeled with an alpha texture that decides whether hit 4346points lie inside or outside the leaf. 4347 4348Please see the description of the 4349`rtcSetGeometryIntersectFilterFunction` for a description of the filter 4350callback function. 4351 4352#### EXIT STATUS {#exit-status} 4353 4354On failure an error code is set that can be queried using 4355`rtcGetDeviceError`. 4356 4357#### SEE ALSO {#see-also} 4358 4359[rtcSetGeometryIntersectFilterFunction] 4360 4361 4362 4363rtcFilterIntersection 4364--------------------- 4365 4366#### NAME {#name} 4367 4368 rtcFilterIntersection - invokes the intersection filter function 4369 4370#### SYNOPSIS {#synopsis} 4371 4372 #include <embree3/rtcore.h> 4373 4374 void rtcFilterIntersection( 4375 const struct RTCIntersectFunctionNArguments* args, 4376 const struct RTCFilterFunctionNArguments* filterArgs 4377 ); 4378 4379#### DESCRIPTION {#description} 4380 4381The `rtcFilterIntersection` function can be called inside an 4382`RTCIntersectFunctionN` callback function to invoke the intersection 4383filter registered to the geometry and stored inside the context. For 4384this an `RTCFilterFunctionNArguments` structure must be created (see 4385`rtcSetGeometryIntersectFilterFunction`) which basically consists of a 4386valid mask, a hit packet to filter, the corresponding ray packet, and 4387the packet size. After the invocation of `rtcFilterIntersection`, only 4388rays that are still valid (valid mask set to -1) should update a hit. 4389 4390#### EXIT STATUS {#exit-status} 4391 4392For performance reasons this function does not do any error checks, 4393thus will not set any error flags on failure. 4394 4395#### SEE ALSO {#see-also} 4396 4397[rtcFilterOcclusion], [rtcSetGeometryIntersectFunction] 4398 4399 4400 4401rtcFilterOcclusion 4402------------------ 4403 4404#### NAME {#name} 4405 4406 rtcFilterOcclusion - invokes the occlusion filter function 4407 4408#### SYNOPSIS {#synopsis} 4409 4410 #include <embree3/rtcore.h> 4411 4412 void rtcFilterOcclusion( 4413 const struct RTCOccludedFunctionNArguments* args, 4414 const struct RTCFilterFunctionNArguments* filterArgs 4415 ); 4416 4417#### DESCRIPTION {#description} 4418 4419The `rtcFilterOcclusion` function can be called inside an 4420`RTCOccludedFunctionN` callback function to invoke the occlusion filter 4421registered to the geometry and stored inside the context. For this an 4422`RTCFilterFunctionNArguments` structure must be created (see 4423`rtcSetGeometryIntersectFilterFunction`) which basically consists of a 4424valid mask, a hit packet to filter, the corresponding ray packet, and 4425the packet size. After the invocation of `rtcFilterOcclusion` only rays 4426that are still valid (valid mask set to -1) should signal an occlusion. 4427 4428#### EXIT STATUS {#exit-status} 4429 4430For performance reasons this function does not do any error checks, 4431thus will not set any error flags on failure. 4432 4433#### SEE ALSO {#see-also} 4434 4435[rtcFilterIntersection], [rtcSetGeometryOccludedFunction] 4436 4437 4438 4439rtcSetGeometryUserData 4440---------------------- 4441 4442#### NAME {#name} 4443 4444 rtcSetGeometryUserData - sets the user-defined data pointer of the 4445 geometry 4446 4447#### SYNOPSIS {#synopsis} 4448 4449 #include <embree3/rtcore.h> 4450 4451 void rtcSetGeometryUserData(RTCGeometry geometry, void* userPtr); 4452 4453#### DESCRIPTION {#description} 4454 4455The `rtcSetGeometryUserData` function sets the user-defined data 4456pointer (`userPtr` argument) for a geometry (`geometry` argument). This 4457user data pointer is intended to be pointing to the application's 4458representation of the geometry, and is passed to various callback 4459functions. The application can use this pointer inside the callback 4460functions to access its geometry representation. 4461 4462The `rtcGetGeometryUserData` function can be used to query an already 4463set user data pointer of a geometry. 4464 4465#### EXIT STATUS {#exit-status} 4466 4467On failure an error code is set that can be queried using 4468`rtcGetDeviceError`. 4469 4470#### SEE ALSO {#see-also} 4471 4472[rtcGetGeometryUserData] 4473 4474 4475 4476rtcGetGeometryUserData 4477---------------------- 4478 4479#### NAME {#name} 4480 4481 rtcGetGeometryUserData - returns the user data pointer 4482 of the geometry 4483 4484#### SYNOPSIS {#synopsis} 4485 4486 #include <embree3/rtcore.h> 4487 4488 void* rtcGetGeometryUserData(RTCGeometry geometry); 4489 4490#### DESCRIPTION {#description} 4491 4492The `rtcGetGeometryUserData` function queries the user data pointer 4493previously set with `rtcSetGeometryUserData`. When 4494`rtcSetGeometryUserData` was not called yet, `NULL` is returned. 4495 4496#### EXIT STATUS {#exit-status} 4497 4498On failure an error code is set that can be queried using 4499`rtcGetDeviceError`. 4500 4501#### SEE ALSO {#see-also} 4502 4503[rtcSetGeometryUserData] 4504 4505 4506 4507rtcSetGeometryUserPrimitiveCount 4508-------------------------------- 4509 4510#### NAME {#name} 4511 4512 rtcSetGeometryUserPrimitiveCount - sets the number of primitives 4513 of a user-defined geometry 4514 4515#### SYNOPSIS {#synopsis} 4516 4517 #include <embree3/rtcore.h> 4518 4519 void rtcSetGeometryUserPrimitiveCount( 4520 RTCGeometry geometry, 4521 unsigned int userPrimitiveCount 4522 ); 4523 4524#### DESCRIPTION {#description} 4525 4526The `rtcSetGeometryUserPrimitiveCount` function sets the number of 4527user-defined primitives (`userPrimitiveCount` parameter) of the 4528specified user-defined geometry (`geometry` parameter). 4529 4530#### EXIT STATUS {#exit-status} 4531 4532On failure an error code is set that can be queried using 4533`rtcGetDeviceError`. 4534 4535#### SEE ALSO {#see-also} 4536 4537[RTC\_GEOMETRY\_TYPE\_USER] 4538 4539 4540 4541rtcSetGeometryBoundsFunction 4542---------------------------- 4543 4544#### NAME {#name} 4545 4546 rtcSetGeometryBoundsFunction - sets a callback to query the 4547 bounding box of user-defined primitives 4548 4549#### SYNOPSIS {#synopsis} 4550 4551 #include <embree3/rtcore.h> 4552 4553 struct RTCBoundsFunctionArguments 4554 { 4555 void* geometryUserPtr; 4556 unsigned int primID; 4557 unsigned int timeStep; 4558 struct RTCBounds* bounds_o; 4559 }; 4560 4561 typedef void (*RTCBoundsFunction)( 4562 const struct RTCBoundsFunctionArguments* args 4563 ); 4564 4565 void rtcSetGeometryBoundsFunction( 4566 RTCGeometry geometry, 4567 RTCBoundsFunction bounds, 4568 void* userPtr 4569 ); 4570 4571#### DESCRIPTION {#description} 4572 4573The `rtcSetGeometryBoundsFunction` function registers a bounding box 4574callback function (`bounds` argument) with payload (`userPtr` argument) 4575for the specified user geometry (`geometry` argument). 4576 4577Only a single callback function can be registered per geometry, and 4578further invocations overwrite the previously set callback function. 4579Passing `NULL` as function pointer disables the registered callback 4580function. 4581 4582The registered bounding box callback function is invoked to calculate 4583axis-aligned bounding boxes of the primitives of the user-defined 4584geometry during spatial acceleration structure construction. The 4585bounding box callback of `RTCBoundsFunction` type is invoked with a 4586pointer to a structure of type `RTCBoundsFunctionArguments` which 4587contains various arguments, such as: the user data of the geometry 4588(`geometryUserPtr` member), the ID of the primitive to calculate the 4589bounds for (`primID` member), the time step at which to calculate the 4590bounds (`timeStep` member), and a memory location to write the 4591calculated bound to (`bounds_o` member). 4592 4593In a typical usage scenario one would store a pointer to the internal 4594representation of the user geometry object using 4595`rtcSetGeometryUserData`. The callback function can then read that 4596pointer from the `geometryUserPtr` field and calculate the proper 4597bounding box for the requested primitive and time, and store that 4598bounding box to the destination structure (`bounds_o` member). 4599 4600#### EXIT STATUS {#exit-status} 4601 4602On failure an error code is set that can be queried using 4603`rtcGetDeviceError`. 4604 4605#### SEE ALSO {#see-also} 4606 4607[RTC\_GEOMETRY\_TYPE\_USER] 4608 4609 4610 4611rtcSetGeometryIntersectFunction 4612------------------------------- 4613 4614#### NAME {#name} 4615 4616 rtcSetGeometryIntersectFunction - sets the callback function to 4617 intersect a user geometry 4618 4619#### SYNOPSIS {#synopsis} 4620 4621 #include <embree3/rtcore.h> 4622 4623 struct RTCIntersectFunctionNArguments 4624 { 4625 int* valid; 4626 void* geometryUserPtr; 4627 unsigned int primID; 4628 struct RTCIntersectContext* context; 4629 struct RTCRayHitN* rayhit; 4630 unsigned int N; 4631 unsigned int geomID; 4632 }; 4633 4634 typedef void (*RTCIntersectFunctionN)( 4635 const struct RTCIntersectFunctionNArguments* args 4636 ); 4637 4638 void rtcSetGeometryIntersectFunction( 4639 RTCGeometry geometry, 4640 RTCIntersectFunctionN intersect 4641 ); 4642 4643#### DESCRIPTION {#description} 4644 4645The `rtcSetGeometryIntersectFunction` function registers a 4646ray/primitive intersection callback function (`intersect` argument) for 4647the specified user geometry (`geometry` argument). 4648 4649Only a single callback function can be registered per geometry and 4650further invocations overwrite the previously set callback function. 4651Passing `NULL` as function pointer disables the registered callback 4652function. 4653 4654The registered callback function is invoked by `rtcIntersect`-type ray 4655queries to calculate the intersection of a ray packet of variable size 4656with one user-defined primitive. The callback function of type 4657`RTCIntersectFunctionN` gets passed a number of arguments through the 4658`RTCIntersectFunctionNArguments` structure. The value `N` specifies the 4659ray packet size, `valid` points to an array of integers that specify 4660whether the corresponding ray is valid (-1) or invalid (0), the 4661`geometryUserPtr` member points to the geometry user data previously 4662set through `rtcSetGeometryUserData`, the `context` member points to 4663the intersection context passed to the ray query, the `rayhit` member 4664points to a ray and hit packet of variable size `N`, and the `geomID` 4665and `primID` member identifies the geometry ID and primitive ID of the 4666primitive to intersect. 4667 4668The `ray` component of the `rayhit` structure contains valid data, in 4669particular the `tfar` value is the current closest hit distance found. 4670All data inside the `hit` component of the `rayhit` structure are 4671undefined and should not be read by the function. 4672 4673The task of the callback function is to intersect each active ray from 4674the ray packet with the specified user primitive. If the user-defined 4675primitive is missed by a ray of the ray packet, the function should 4676return without modifying the ray or hit. If an intersection of the 4677user-defined primitive with the ray was found in the valid range (from 4678`tnear` to `tfar`), it should update the hit distance of the ray 4679(`tfar` member) and the hit (`u`, `v`, `Ng`, `instID`, `geomID`, 4680`primID` members). In particular, the currently intersected instance is 4681stored in the `instID` field of the intersection context, which must be 4682deep copied into the `instID` member of the hit. 4683 4684As a primitive might have multiple intersections with a ray, the 4685intersection filter function needs to be invoked by the user geometry 4686intersection callback for each encountered intersection, if filtering 4687of intersections is desired. This can be achieved through the 4688`rtcFilterIntersection` call. 4689 4690Within the user geometry intersect function, it is safe to trace new 4691rays and create new scenes and geometries. 4692 4693When performing ray queries using `rtcIntersect1`, it is guaranteed 4694that the packet size is 1 when the callback is invoked. When performing 4695ray queries using the `rtcIntersect4/8/16` functions, it is not 4696generally guaranteed that the ray packet size (and order of rays inside 4697the packet) passed to the callback matches the initial ray packet. 4698However, under some circumstances these properties are guaranteed, and 4699whether this is the case can be queried using `rtcGetDeviceProperty`. 4700When performing ray queries using the stream API such as 4701`rtcIntersect1M`, `rtcIntersect1Mp`, `rtcIntersectNM`, or 4702`rtcIntersectNp` the order of rays and ray packet size of the callback 4703function might change to either 1, 4, 8, or 16. 4704 4705For many usage scenarios, repacking and re-ordering of rays does not 4706cause difficulties in implementing the callback function. However, 4707algorithms that need to extend the ray with additional data must use 4708the `rayID` component of the ray to identify the original ray to access 4709the per-ray data. 4710 4711#### EXIT STATUS {#exit-status} 4712 4713On failure an error code is set that can be queried using 4714`rtcGetDeviceError`. 4715 4716#### SEE ALSO {#see-also} 4717 4718[rtcSetGeometryOccludedFunction], [rtcSetGeometryUserData], 4719[rtcFilterIntersection] 4720 4721 4722 4723rtcSetGeometryOccludedFunction 4724------------------------------ 4725 4726#### NAME {#name} 4727 4728 rtcSetGeometryOccludedFunction - sets the callback function to 4729 test a user geometry for occlusion 4730 4731#### SYNOPSIS {#synopsis} 4732 4733 #include <embree3/rtcore.h> 4734 4735 struct RTCOccludedFunctionNArguments 4736 { 4737 int* valid; 4738 void* geometryUserPtr; 4739 unsigned int primID; 4740 struct RTCIntersectContext* context; 4741 struct RTCRayN* ray; 4742 unsigned int N; 4743 unsigned int geomID; 4744 }; 4745 4746 typedef void (*RTCOccludedFunctionN)( 4747 const struct RTCOccludedFunctionNArguments* args 4748 ); 4749 4750 void rtcSetGeometryOccludedFunction( 4751 RTCGeometry geometry, 4752 RTCOccludedFunctionN filter 4753 ); 4754 4755#### DESCRIPTION {#description} 4756 4757The `rtcSetGeometryOccludedFunction` function registers a ray/primitive 4758occlusion callback function (`filter` argument) for the specified user 4759geometry (`geometry` argument). 4760 4761Only a single callback function can be registered per geometry, and 4762further invocations overwrite the previously set callback function. 4763Passing `NULL` as function pointer disables the registered callback 4764function. 4765 4766The registered callback function is invoked by `rtcOccluded`-type ray 4767queries to test whether the rays of a packet of variable size are 4768occluded by a user-defined primitive. The callback function of type 4769`RTCOccludedFunctionN` gets passed a number of arguments through the 4770`RTCOccludedFunctionNArguments` structure. The value `N` specifies the 4771ray packet size, `valid` points to an array of integers which specify 4772whether the corresponding ray is valid (-1) or invalid (0), the 4773`geometryUserPtr` member points to the geometry user data previously 4774set through `rtcSetGeometryUserData`, the `context` member points to 4775the intersection context passed to the ray query, the `ray` member 4776points to a ray packet of variable size `N`, and the `geomID` and 4777`primID` member identifies the geometry ID and primitive ID of the 4778primitive to intersect. 4779 4780The task of the callback function is to intersect each active ray from 4781the ray packet with the specified user primitive. If the user-defined 4782primitive is missed by a ray of the ray packet, the function should 4783return without modifying the ray. If an intersection of the 4784user-defined primitive with the ray was found in the valid range (from 4785`tnear` to `tfar`), it should set the `tfar` member of the ray to 4786`-inf`. 4787 4788As a primitive might have multiple intersections with a ray, the 4789occlusion filter function needs to be invoked by the user geometry 4790occlusion callback for each encountered intersection, if filtering of 4791intersections is desired. This can be achieved through the 4792`rtcFilterOcclusion` call. 4793 4794Within the user geometry occlusion function, it is safe to trace new 4795rays and create new scenes and geometries. 4796 4797When performing ray queries using `rtcOccluded1`, it is guaranteed that 4798the packet size is 1 when the callback is invoked. When performing ray 4799queries using the `rtcOccluded4/8/16` functions, it is not generally 4800guaranteed that the ray packet size (and order of rays inside the 4801packet) passed to the callback matches the initial ray packet. However, 4802under some circumstances these properties are guaranteed, and whether 4803this is the case can be queried using `rtcGetDeviceProperty`. When 4804performing ray queries using the stream API such as `rtcOccluded1M`, 4805`rtcOccluded1Mp`, `rtcOccludedNM`, or `rtcOccludedNp` the order of rays 4806and ray packet size of the callback function might change to either 1, 48074, 8, or 16. 4808 4809For many usage scenarios, repacking and re-ordering of rays does not 4810cause difficulties in implementing the callback function. However, 4811algorithms that need to extend the ray with additional data must use 4812the `rayID` component of the ray to identify the original ray to access 4813the per-ray data. 4814 4815#### EXIT STATUS {#exit-status} 4816 4817On failure an error code is set that can be queried using 4818`rtcGetDeviceError`. 4819 4820#### SEE ALSO {#see-also} 4821 4822[rtcSetGeometryIntersectFunction], [rtcSetGeometryUserData], 4823[rtcFilterOcclusion] 4824 4825 4826 4827rtcSetGeometryPointQueryFunction 4828-------------------------------- 4829 4830#### NAME {#name} 4831 4832 rtcSetGeometryPointQueryFunction - sets the point query callback function 4833 for a geometry 4834 4835#### SYNOPSIS {#synopsis} 4836 4837 #include <embree3/rtcore.h> 4838 4839 struct RTCPointQueryFunctionArguments 4840 { 4841 // the (world space) query object that was passed as an argument of rtcPointQuery. 4842 struct RTCPointQuery* query; 4843 4844 // used for user input/output data. Will not be read or modified internally. 4845 void* userPtr; 4846 4847 // primitive and geometry ID of primitive 4848 unsigned int primID; 4849 unsigned int geomID; 4850 4851 // the context with transformation and instance ID stack 4852 struct RTCPointQueryContext* context; 4853 4854 // scaling factor indicating whether the current instance transformation 4855 // is a similarity transformation. 4856 float similarityScale; 4857 }; 4858 4859 typedef bool (*RTCPointQueryFunction)( 4860 struct RTCPointQueryFunctionArguments* args 4861 ); 4862 4863 void rtcSetGeometryPointQueryFunction( 4864 RTCGeometry geometry, 4865 RTCPointQueryFunction queryFunc 4866 ); 4867 4868#### DESCRIPTION {#description} 4869 4870The `rtcSetGeometryPointQueryFunction` function registers a point query 4871callback function (`queryFunc` argument) for the specified geometry 4872(`geometry` argument). 4873 4874Only a single callback function can be registered per geometry and 4875further invocations overwrite the previously set callback function. 4876Passing `NULL` as function pointer disables the registered callback 4877function. 4878 4879The registered callback function is invoked by [rtcPointQuery] for 4880every primitive of the geometry that intersects the corresponding point 4881query domain. The callback function of type `RTCPointQueryFunction` 4882gets passed a number of arguments through the 4883`RTCPointQueryFunctionArguments` structure. The `query` object is the 4884original point query object passed into [rtcPointQuery], `usrPtr` is 4885an arbitrary pointer to pass input into and store results of the 4886callback function. The `primID`, `geomID` and `context` (see 4887[rtcInitPointQueryContext] for details) can be used to identify the 4888geometry data of the primitive. 4889 4890A `RTCPointQueryFunction` can also be passed directly as an argument to 4891[rtcPointQuery]. In this case the callback is invoked for all 4892primitives in the scene that intersect the query domain. If a callback 4893function is passed as an argument to [rtcPointQuery] and (a 4894potentially different) callback function is set for a geometry with 4895[rtcSetGeometryPointQueryFunction] both callback functions are 4896invoked and the callback function passed to [rtcPointQuery] will be 4897called before the geometry specific callback function. 4898 4899If instancing is used, the parameter `simliarityScale` indicates 4900whether the current instance transform (top element of the stack in 4901`context`) is a similarity transformation or not. Similarity 4902transformations are composed of translation, rotation and uniform 4903scaling and if a matrix M defines a similarity transformation, there is 4904a scaling factor D such that for all x,y: dist(Mx, My) = D \* dist(x, 4905y). In this case the parameter `scalingFactor` is this scaling factor D 4906and otherwise it is 0. A valid similarity scale (`similarityScale` \> 49070) allows to compute distance information in instance space and scale 4908the distances into world space (for example, to update the query 4909radius, see below) by dividing the instance space distance with the 4910similarity scale. If the current instance transform is not a similarity 4911transform (`similarityScale` is 0), the distance computation has to be 4912performed in world space to ensure correctness. In this case the 4913instance to world transformations given with the `context` should be 4914used to transform the primitive data into world space. Otherwise, the 4915query location can be transformed into instance space which can be more 4916efficient. If there is no instance transform, the similarity scale is 49171. 4918 4919The callback function will potentially be called for primitives outside 4920the query domain for two resons: First, the callback is invoked for all 4921primitives inside a BVH leaf node since no geometry data of primitives 4922is determined internally and therefore individual primitives are not 4923culled (only their (aggregated) bounding boxes). Second, in case non 4924similarity transformations are used, the resulting ellipsoidal query 4925domain (in instance space) is approximated by its axis aligned bounding 4926box internally and therefore inner nodes that do not intersect the 4927original domain might intersect the approximative bounding box which 4928results in unneccessary callbacks. In any case, the callbacks are 4929conservative, i.e. if a primitive is inside the query domain a callback 4930will be invoked but the reverse is not neccessarily true. 4931 4932For efficiency, the radius of the `query` object can be decreased (in 4933world space) inside the callback function to improve culling of 4934geometry during BVH traversal. If the query radius was updated, the 4935callback function should return `true` to issue an update of internal 4936traversal information. Increasing the radius or modifying the time or 4937position of the query results in undefined behaviour. 4938 4939Within the callback function, it is safe to call [rtcPointQuery] 4940again, for example when implementing instancing manually. In this case 4941the instance transformation should be pushed onto the stack in 4942`context`. Embree will internally compute the point query information 4943in instance space using the top element of the stack in `context` when 4944[rtcPointQuery] is called. 4945 4946For a reference implementation of a closest point traversal of triangle 4947meshes using instancing and user defined instancing see the tutorial 4948[ClosestPoint]. 4949 4950#### SEE ALSO {#see-also} 4951 4952[rtcPointQuery], [rtcInitPointQueryContext] 4953 4954 4955 4956rtcSetGeometryInstancedScene 4957---------------------------- 4958 4959#### NAME {#name} 4960 4961 rtcSetGeometryInstancedScene - sets the instanced scene of 4962 an instance geometry 4963 4964#### SYNOPSIS {#synopsis} 4965 4966 #include <embree3/rtcore.h> 4967 4968 void rtcSetGeometryInstancedScene( 4969 RTCGeometry geometry, 4970 RTCScene scene 4971 ); 4972 4973#### DESCRIPTION {#description} 4974 4975The `rtcSetGeometryInstancedScene` function sets the instanced scene 4976(`scene` argument) of the specified instance geometry (`geometry` 4977argument). 4978 4979#### EXIT STATUS {#exit-status} 4980 4981On failure an error code is set that can be queried using 4982`rtcGetDeviceError`. 4983 4984#### SEE ALSO {#see-also} 4985 4986[RTC\_GEOMETRY\_TYPE\_INSTANCE], [rtcSetGeometryTransform] 4987 4988 4989 4990rtcSetGeometryTransform 4991----------------------- 4992 4993#### NAME {#name} 4994 4995 rtcSetGeometryTransform - sets the transformation for a particular 4996 time step of an instance geometry 4997 4998#### SYNOPSIS {#synopsis} 4999 5000 #include <embree3/rtcore.h> 5001 5002 void rtcSetGeometryTransform( 5003 RTCGeometry geometry, 5004 unsigned int timeStep, 5005 enum RTCFormat format, 5006 const float* xfm 5007 ); 5008 5009#### DESCRIPTION {#description} 5010 5011The `rtcSetGeometryTransform` function sets the local-to-world affine 5012transformation (`xfm` parameter) of an instance geometry (`geometry` 5013parameter) for a particular time step (`timeStep` parameter). The 5014transformation is specified as a 3×4 matrix (3×3 linear transformation 5015plus translation), for which the following formats (`format` parameter) 5016are supported: 5017 5018- `RTC_FORMAT_FLOAT3X4_ROW_MAJOR`: The 3×4 float matrix is laid out 5019 in row-major form. 5020 5021- `RTC_FORMAT_FLOAT3X4_COLUMN_MAJOR`: The 3×4 float matrix is laid 5022 out in column-major form. 5023 5024- `RTC_FORMAT_FLOAT4X4_COLUMN_MAJOR`: The 3×4 float matrix is laid 5025 out in column-major form as a 4×4 homogeneous matrix with the last 5026 row being equal to (0, 0, 0, 1). 5027 5028#### EXIT STATUS {#exit-status} 5029 5030On failure an error code is set that can be queried using 5031`rtcGetDeviceError`. 5032 5033#### SEE ALSO {#see-also} 5034 5035[RTC\_GEOMETRY\_TYPE\_INSTANCE] 5036 5037 5038 5039rtcSetGeometryTransformQuaternion 5040--------------------------------- 5041 5042#### NAME {#name} 5043 5044 rtcSetGeometryTransformQuaternion - sets the transformation for a particular 5045 time step of an instance geometry as a decomposition of the 5046 transformation matrix using quaternions to represent the rotation. 5047 5048#### SYNOPSIS {#synopsis} 5049 5050 #include <embree3/rtcore.h> 5051 5052 void rtcSetGeometryTransformQuaternion( 5053 RTCGeometry geometry, 5054 unsigned int timeStep, 5055 const struct RTCQuaternionDecomposition* qd 5056 ); 5057 5058#### DESCRIPTION {#description} 5059 5060The `rtcSetGeometryTransformQuaternion` function sets the 5061local-to-world affine transformation (`qd` parameter) of an instance 5062geometry (`geometry` parameter) for a particular time step (`timeStep` 5063parameter). The transformation is specified as a 5064[RTCQuaternionDecomposition], which is a decomposition of an affine 5065transformation that represents the rotational component of an affine 5066transformation as a quaternion. This allows interpolating rotational 5067transformations exactly using spherical linear interpolation (such as a 5068turning wheel). 5069 5070For more information about the decomposition see 5071[RTCQuaternionDecomposition]. The quaternion given in the 5072`RTCQuaternionDecomposition` struct will be normalized internally. 5073 5074For correct results, the transformation matrices for all time steps 5075must be set either using `rtcSetGeometryTransform` or 5076`rtcSetGeometryTransformQuaternion`. Mixing both representations is not 5077allowed. Spherical linear interpolation will be used, iff the 5078transformation matizes are set with 5079`rtcSetGeometryTransformQuaternion`. 5080 5081For an example of this feature see the tutorial [Quaternion Motion 5082Blur]. 5083 5084#### EXIT STATUS {#exit-status} 5085 5086On failure an error code is set that can be queried using 5087`rtcGetDeviceError`. 5088 5089#### SEE ALSO {#see-also} 5090 5091[rtcInitQuaternionDecomposition], [rtcSetGeometryTransform] 5092 5093 5094 5095rtcGetGeometryTransform 5096----------------------- 5097 5098#### NAME {#name} 5099 5100 rtcGetGeometryTransform - returns the interpolated instance 5101 transformation for the specified time 5102 5103#### SYNOPSIS {#synopsis} 5104 5105 #include <embree3/rtcore.h> 5106 5107 void rtcGetGeometryTransform( 5108 RTCGeometry geometry, 5109 float time, 5110 enum RTCFormat format, 5111 void* xfm 5112 ); 5113 5114#### DESCRIPTION {#description} 5115 5116The `rtcGetGeometryTransform` function returns the interpolated local 5117to world transformation (`xfm` parameter) of an instance geometry 5118(`geometry` parameter) for a particular time (`time` parameter in range 5119$[0,1]$) in the specified format (`format` parameter). 5120 5121Possible formats for the returned matrix are: 5122 5123- `RTC_FORMAT_FLOAT3X4_ROW_MAJOR`: The 3×4 float matrix is laid out 5124 in row-major form. 5125 5126- `RTC_FORMAT_FLOAT3X4_COLUMN_MAJOR`: The 3×4 float matrix is laid 5127 out in column-major form. 5128 5129- `RTC_FORMAT_FLOAT4X4_COLUMN_MAJOR`: The 3×4 float matrix is laid 5130 out in column-major form as a 4×4 homogeneous matrix with last row 5131 equal to (0, 0, 0, 1). 5132 5133#### EXIT STATUS {#exit-status} 5134 5135On failure an error code is set that can be queried using 5136`rtcGetDeviceError`. 5137 5138#### SEE ALSO {#see-also} 5139 5140[RTC\_GEOMETRY\_TYPE\_INSTANCE], [rtcSetGeometryTransform] 5141 5142 5143 5144rtcSetGeometryTessellationRate 5145------------------------------ 5146 5147#### NAME {#name} 5148 5149 rtcSetGeometryTessellationRate - sets the tessellation rate of the 5150 geometry 5151 5152#### SYNOPSIS {#synopsis} 5153 5154 #include <embree3/rtcore.h> 5155 5156 void rtcSetGeometryTessellationRate( 5157 RTCGeometry geometry, 5158 float tessellationRate 5159 ); 5160 5161#### DESCRIPTION {#description} 5162 5163The `rtcSetGeometryTessellationRate` function sets the tessellation 5164rate (`tessellationRate` argument) for the specified geometry 5165(`geometry` argument). The tessellation rate can only be set for flat 5166curves and subdivision geometries. For curves, the tessellation rate 5167specifies the number of ray-facing quads per curve segment. For 5168subdivision surfaces, the tessellation rate specifies the number of 5169quads along each edge. 5170 5171#### EXIT STATUS {#exit-status} 5172 5173On failure an error code is set that can be queried using 5174`rtcGetDeviceError`. 5175 5176#### SEE ALSO {#see-also} 5177 5178[RTC\_GEOMETRY\_TYPE\_CURVE], [RTC\_GEOMETRY\_TYPE\_SUBDIVISION] 5179 5180 5181 5182rtcSetGeometryTopologyCount 5183--------------------------- 5184 5185#### NAME {#name} 5186 5187 rtcSetGeometryTopologyCount - sets the number of topologies of 5188 a subdivision geometry 5189 5190#### SYNOPSIS {#synopsis} 5191 5192 #include <embree3/rtcore.h> 5193 5194 void rtcSetGeometryTopologyCount( 5195 RTCGeometry geometry, 5196 unsigned int topologyCount 5197 ); 5198 5199#### DESCRIPTION {#description} 5200 5201The `rtcSetGeometryTopologyCount` function sets the number of 5202topologies (`topologyCount` parameter) for the specified subdivision 5203geometry (`geometry` parameter). The number of topologies of a 5204subdivision geometry must be greater or equal to 1. 5205 5206To use multiple topologies, first the number of topologies must be 5207specified, then the individual topologies can be configured using 5208`rtcSetGeometrySubdivisionMode` and by setting an index buffer 5209(`RTC_BUFFER_TYPE_INDEX`) using the topology ID as the buffer slot. 5210 5211#### EXIT STATUS {#exit-status} 5212 5213On failure an error code is set that can be queried using 5214`rtcGetDeviceError`. 5215 5216#### SEE ALSO {#see-also} 5217 5218[RTC\_GEOMETRY\_TYPE\_SUBDIVISION], [rtcSetGeometrySubdivisionMode] 5219 5220 5221 5222rtcSetGeometrySubdivisionMode 5223----------------------------- 5224 5225#### NAME {#name} 5226 5227 rtcSetGeometrySubdivisionMode - sets the subdivision mode 5228 of a subdivision geometry 5229 5230#### SYNOPSIS {#synopsis} 5231 5232 #include <embree3/rtcore.h> 5233 5234 void rtcSetGeometrySubdivisionMode( 5235 RTCGeometry geometry, 5236 unsigned int topologyID, 5237 enum RTCSubdivisionMode mode 5238 ); 5239 5240#### DESCRIPTION {#description} 5241 5242The `rtcSetGeometrySubdivisionMode` function sets the subdivision mode 5243(`mode` parameter) for the topology (`topologyID` parameter) of the 5244specified subdivision geometry (`geometry` parameter). 5245 5246The subdivision modes can be used to force linear interpolation for 5247certain parts of the subdivision mesh: 5248 5249- `RTC_SUBDIVISION_MODE_NO_BOUNDARY`: Boundary patches are ignored. 5250 This way each rendered patch has a full set of control vertices. 5251 5252- `RTC_SUBDIVISION_MODE_SMOOTH_BOUNDARY`: The sequence of boundary 5253 control points are used to generate a smooth B-spline boundary 5254 curve (default mode). 5255 5256- `RTC_SUBDIVISION_MODE_PIN_CORNERS`: Corner vertices are pinned to 5257 their location during subdivision. 5258 5259- `RTC_SUBDIVISION_MODE_PIN_BOUNDARY`: All vertices at the border are 5260 pinned to their location during subdivision. This way the boundary 5261 is interpolated linearly. This mode is typically used for texturing 5262 to also map texels at the border of the texture to the mesh. 5263 5264- `RTC_SUBDIVISION_MODE_PIN_ALL`: All vertices at the border are 5265 pinned to their location during subdivision. This way all patches 5266 are linearly interpolated. 5267 5268#### EXIT STATUS {#exit-status} 5269 5270On failure an error code is set that can be queried using 5271`rtcGetDeviceError`. 5272 5273#### SEE ALSO {#see-also} 5274 5275[RTC\_GEOMETRY\_TYPE\_SUBDIVISION] 5276 5277 5278 5279rtcSetGeometryVertexAttributeTopology 5280------------------------------------- 5281 5282#### NAME {#name} 5283 5284 rtcSetGeometryVertexAttributeTopology - binds a vertex 5285 attribute to a topology of the geometry 5286 5287#### SYNOPSIS {#synopsis} 5288 5289 #include <embree3/rtcore.h> 5290 5291 void rtcSetGeometryVertexAttributeTopology( 5292 RTCGeometry geometry, 5293 unsigned int vertexAttributeID, 5294 unsigned int topologyID 5295 ); 5296 5297#### DESCRIPTION {#description} 5298 5299The `rtcSetGeometryVertexAttributeTopology` function binds a vertex 5300attribute buffer slot (`vertexAttributeID` argument) to a topology 5301(`topologyID` argument) for the specified subdivision geometry 5302(`geometry` argument). Standard vertex buffers are always bound to the 5303default topology (topology 0) and cannot be bound differently. A vertex 5304attribute buffer always uses the topology it is bound to when used in 5305the `rtcInterpolate` and `rtcInterpolateN` calls. 5306 5307A topology with ID `i` consists of a subdivision mode set through 5308`rtcSetGeometrySubdivisionMode` and the index buffer bound to the index 5309buffer slot `i`. This index buffer can assign indices for each face of 5310the subdivision geometry that are different to the indices of the 5311default topology. These new indices can for example be used to 5312introduce additional borders into the subdivision mesh to map multiple 5313textures onto one subdivision geometry. 5314 5315#### EXIT STATUS {#exit-status} 5316 5317On failure an error code is set that can be queried using 5318`rtcGetDeviceError`. 5319 5320#### SEE ALSO {#see-also} 5321 5322[rtcSetGeometrySubdivisionMode], [rtcInterpolate], 5323[rtcInterpolateN] 5324 5325 5326 5327rtcSetGeometryDisplacementFunction 5328---------------------------------- 5329 5330#### NAME {#name} 5331 5332 rtcSetGeometryDisplacementFunction - sets the displacement function 5333 for a subdivision geometry 5334 5335#### SYNOPSIS {#synopsis} 5336 5337 #include <embree3/rtcore.h> 5338 5339 struct RTCDisplacementFunctionNArguments 5340 { 5341 void* geometryUserPtr; 5342 RTCGeometry geometry; 5343 unsigned int primID; 5344 unsigned int timeStep; 5345 const float* u; 5346 const float* v; 5347 const float* Ng_x; 5348 const float* Ng_y; 5349 const float* Ng_z; 5350 float* P_x; 5351 float* P_y; 5352 float* P_z; 5353 unsigned int N; 5354 }; 5355 5356 typedef void (*RTCDisplacementFunctionN)( 5357 const struct RTCDisplacementFunctionNArguments* args 5358 ); 5359 5360 void rtcSetGeometryDisplacementFunction( 5361 RTCGeometry geometry, 5362 RTCDisplacementFunctionN displacement 5363 ); 5364 5365#### DESCRIPTION {#description} 5366 5367The `rtcSetGeometryDisplacementFunction` function registers a 5368displacement callback function (`displacement` argument) for the 5369specified subdivision geometry (`geometry` argument). 5370 5371Only a single callback function can be registered per geometry, and 5372further invocations overwrite the previously set callback function. 5373Passing `NULL` as function pointer disables the registered callback 5374function. 5375 5376The registered displacement callback function is invoked to displace 5377points on the subdivision geometry during spatial acceleration 5378structure construction, during the `rtcCommitScene` call. 5379 5380The callback function of type `RTCDisplacementFunctionN` is invoked 5381with a number of arguments stored inside the 5382`RTCDisplacementFunctionNArguments` structure. The provided user data 5383pointer of the geometry (`geometryUserPtr` member) can be used to point 5384to the application's representation of the subdivision mesh. A number 5385`N` of points to displace are specified in a structure of array layout. 5386For each point to displace, the local patch UV coordinates (`u` and `v` 5387arrays), the normalized geometry normal (`Ng_x`, `Ng_y`, and `Ng_z` 5388arrays), and the position (`P_x`, `P_y`, and `P_z` arrays) are 5389provided. The task of the displacement function is to use this 5390information and change the position data. 5391 5392The geometry handle (`geometry` member) and primitive ID (`primID` 5393member) of the patch to displace are additionally provided as well as 5394the time step `timeStep`, which can be important if the displacement is 5395time-dependent and motion blur is used. 5396 5397All passed arrays must be aligned to 64 bytes and properly padded to 5398make wide vector processing inside the displacement function easily 5399possible. 5400 5401Also see tutorial [Displacement Geometry] for an example of how to 5402use the displacement mapping functions. 5403 5404#### EXIT STATUS {#exit-status} 5405 5406On failure an error code is set that can be queried using 5407`rtcGetDeviceError`. 5408 5409#### SEE ALSO {#see-also} 5410 5411[RTC\_GEOMETRY\_TYPE\_SUBDIVISION] 5412 5413 5414 5415rtcGetGeometryFirstHalfEdge 5416--------------------------- 5417 5418#### NAME {#name} 5419 5420 rtcGetGeometryFirstHalfEdge - returns the first half edge of a face 5421 5422#### SYNOPSIS {#synopsis} 5423 5424 #include <embree3/rtcore.h> 5425 5426 unsigned int rtcGetGeometryFirstHalfEdge( 5427 RTCGeometry geometry, 5428 unsigned int faceID 5429 ); 5430 5431#### DESCRIPTION {#description} 5432 5433The `rtcGetGeometryFirstHalfEdge` function returns the ID of the first 5434half edge belonging to the specified face (`faceID` argument). For 5435instance in the following example the first half edge of face `f1` is 5436`e4`. 5437 5438![][imgHalfEdges] 5439 5440This function can only be used for subdivision geometries. As all 5441topologies of a subdivision geometry share the same face buffer the 5442function does not depend on the topology ID. 5443 5444Here f0 to f7 are 8 quadrilateral faces with 4 vertices each. The edges 5445e0 to e23 of these faces are shown with their orientation. For each 5446face the ID of the edges corresponds to the slots the face occupies in 5447the index array of the geometry. E.g. as the indices of face f1 start 5448at location 4 of the index array, the first edge is edge e4, the next 5449edge e5, etc. 5450 5451#### EXIT STATUS {#exit-status} 5452 5453On failure an error code is set that can be queried using 5454`rtcGetDeviceError`. 5455 5456#### SEE ALSO {#see-also} 5457 5458[rtcGetGeometryFirstHalfEdge], [rtcGetGeometryFace], 5459[rtcGetGeometryOppositeHalfEdge], [rtcGetGeometryNextHalfEdge], 5460[rtcGetGeometryPreviousHalfEdge] 5461 5462 5463 5464rtcGetGeometryFace 5465------------------ 5466 5467#### NAME {#name} 5468 5469 rtcGetGeometryFace - returns the face of some half edge 5470 5471#### SYNOPSIS {#synopsis} 5472 5473 #include <embree3/rtcore.h> 5474 5475 unsigned int rtcGetGeometryFace( 5476 RTCGeometry geometry, 5477 unsigned int edgeID 5478 ); 5479 5480#### DESCRIPTION {#description} 5481 5482The `rtcGetGeometryFace` function returns the ID of the face the 5483specified half edge (`edgeID` argument) belongs to. For instance in the 5484following example the face `f1` is returned for edges `e4`, `e5`, `e6`, 5485and `e7`. 5486 5487![][imgHalfEdges] 5488 5489This function can only be used for subdivision geometries. As all 5490topologies of a subdivision geometry share the same face buffer the 5491function does not depend on the topology ID. 5492 5493#### EXIT STATUS {#exit-status} 5494 5495On failure an error code is set that can be queried using 5496`rtcGetDeviceError`. 5497 5498#### SEE ALSO {#see-also} 5499 5500[rtcGetGeometryFirstHalfEdge], [rtcGetGeometryFace], 5501[rtcGetGeometryOppositeHalfEdge], [rtcGetGeometryNextHalfEdge], 5502[rtcGetGeometryPreviousHalfEdge] 5503 5504 5505 5506rtcGetGeometryNextHalfEdge 5507-------------------------- 5508 5509#### NAME {#name} 5510 5511 rtcGetGeometryNextHalfEdge - returns the next half edge 5512 5513#### SYNOPSIS {#synopsis} 5514 5515 #include <embree3/rtcore.h> 5516 5517 unsigned int rtcGetGeometryNextHalfEdge( 5518 RTCGeometry geometry, 5519 unsigned int edgeID 5520 ); 5521 5522#### DESCRIPTION {#description} 5523 5524The `rtcGetGeometryNextHalfEdge` function returns the ID of the next 5525half edge of the specified half edge (`edgeID` argument). For instance 5526in the following example the next half edge of `e10` is `e11`. 5527 5528![][imgHalfEdges] 5529 5530This function can only be used for subdivision geometries. As all 5531topologies of a subdivision geometry share the same face buffer the 5532function does not depend on the topology ID. 5533 5534#### EXIT STATUS {#exit-status} 5535 5536On failure an error code is set that can be queried using 5537`rtcGetDeviceError`. 5538 5539#### SEE ALSO {#see-also} 5540 5541[rtcGetGeometryFirstHalfEdge], [rtcGetGeometryFace], 5542[rtcGetGeometryOppositeHalfEdge], [rtcGetGeometryNextHalfEdge], 5543[rtcGetGeometryPreviousHalfEdge] 5544 5545 5546 5547rtcGetGeometryPreviousHalfEdge 5548------------------------------ 5549 5550#### NAME {#name} 5551 5552 rtcGetGeometryPreviousHalfEdge - returns the previous half edge 5553 5554#### SYNOPSIS {#synopsis} 5555 5556 #include <embree3/rtcore.h> 5557 5558 unsigned int rtcGetGeometryPreviousHalfEdge( 5559 RTCGeometry geometry, 5560 unsigned int edgeID 5561 ); 5562 5563#### DESCRIPTION {#description} 5564 5565The `rtcGetGeometryPreviousHalfEdge` function returns the ID of the 5566previous half edge of the specified half edge (`edgeID` argument). For 5567instance in the following example the previous half edge of `e6` is 5568`e5`. 5569 5570![][imgHalfEdges] 5571 5572This function can only be used for subdivision geometries. As all 5573topologies of a subdivision geometry share the same face buffer the 5574function does not depend on the topology ID. 5575 5576#### EXIT STATUS {#exit-status} 5577 5578On failure an error code is set that can be queried using 5579`rtcGetDeviceError`. 5580 5581#### SEE ALSO {#see-also} 5582 5583[rtcGetGeometryFirstHalfEdge], [rtcGetGeometryFace], 5584[rtcGetGeometryOppositeHalfEdge], [rtcGetGeometryNextHalfEdge], 5585[rtcGetGeometryPreviousHalfEdge] 5586 5587 5588 5589rtcGetGeometryOppositeHalfEdge 5590------------------------------ 5591 5592#### NAME {#name} 5593 5594 rtcGetGeometryOppositeHalfEdge - returns the opposite half edge 5595 5596#### SYNOPSIS {#synopsis} 5597 5598 #include <embree3/rtcore.h> 5599 5600 unsigned int rtcGetGeometryOppositeHalfEdge( 5601 RTCGeometry geometry, 5602 unsigned int topologyID, 5603 unsigned int edgeID 5604 ); 5605 5606#### DESCRIPTION {#description} 5607 5608The `rtcGetGeometryOppositeHalfEdge` function returns the ID of the 5609opposite half edge of the specified half edge (`edgeID` argument) in 5610the specified topology (`topologyID` argument). For instance in the 5611following example the opposite half edge of `e6` is `e16`. 5612 5613![][imgHalfEdges] 5614 5615An opposite half edge does not exist if the specified half edge has 5616either no neighboring face, or more than 2 neighboring faces. In these 5617cases the function just returns the same edge `edgeID` again. 5618 5619This function can only be used for subdivision geometries. The function 5620depends on the topology as the topologies of a subdivision geometry 5621have different index buffers assigned. 5622 5623#### EXIT STATUS {#exit-status} 5624 5625On failure an error code is set that can be queried using 5626`rtcGetDeviceError`. 5627 5628#### SEE ALSO {#see-also} 5629 5630[rtcGetGeometryFirstHalfEdge], [rtcGetGeometryFace], 5631[rtcGetGeometryOppositeHalfEdge], [rtcGetGeometryNextHalfEdge], 5632[rtcGetGeometryPreviousHalfEdge] 5633 5634 5635 5636rtcInterpolate 5637-------------- 5638 5639#### NAME {#name} 5640 5641 rtcInterpolate - interpolates vertex attributes 5642 5643#### SYNOPSIS {#synopsis} 5644 5645 #include <embree3/rtcore.h> 5646 5647 struct RTCInterpolateArguments 5648 { 5649 RTCGeometry geometry; 5650 unsigned int primID; 5651 float u; 5652 float v; 5653 enum RTCBufferType bufferType; 5654 unsigned int bufferSlot; 5655 float* P; 5656 float* dPdu; 5657 float* dPdv; 5658 float* ddPdudu; 5659 float* ddPdvdv; 5660 float* ddPdudv; 5661 unsigned int valueCount; 5662 }; 5663 5664 void rtcInterpolate( 5665 const struct RTCInterpolateArguments* args 5666 ); 5667 5668#### DESCRIPTION {#description} 5669 5670The `rtcInterpolate` function smoothly interpolates per-vertex data 5671over the geometry. This interpolation is supported for triangle meshes, 5672quad meshes, curve geometries, and subdivision geometries. Apart from 5673interpolating the vertex attribute itself, it is also possible to get 5674the first and second order derivatives of that value. This 5675interpolation ignores displacements of subdivision surfaces and always 5676interpolates the underlying base surface. 5677 5678The `rtcInterpolate` call gets passed a number of arguments inside a 5679structure of type `RTCInterpolateArguments`. For some geometry 5680(`geometry` parameter) this function smoothly interpolates the 5681per-vertex data stored inside the specified geometry buffer 5682(`bufferType` and `bufferSlot` parameters) to the u/v location (`u` and 5683`v` parameters) of the primitive (`primID` parameter). The number of 5684floating point values to interpolate and store to the destination 5685arrays can be specified using the `valueCount` parameter. As 5686interpolation buffer, one can specify vertex buffers 5687(`RTC_BUFFER_TYPE_VERTEX`) and vertex attribute buffers 5688(`RTC_BUFFER_TYPE_VERTEX_ATTRIBUTE`) as well. 5689 5690The `rtcInterpolate` call stores `valueCount` number of interpolated 5691floating point values to the memory location pointed to by `P`. One can 5692avoid storing the interpolated value by setting `P` to `NULL`. 5693 5694The first order derivative of the interpolation by u and v are stored 5695at the `dPdu` and `dPdv` memory locations. One can avoid storing first 5696order derivatives by setting both `dPdu` and `dPdv` to `NULL`. 5697 5698The second order derivatives are stored at the `ddPdudu`, `ddPdvdv`, 5699and `ddPdudv` memory locations. One can avoid storing second order 5700derivatives by setting these three pointers to `NULL`. 5701 5702To use `rtcInterpolate` for a geometry, all changes to that geometry 5703must be properly committed using `rtcCommitGeometry`. 5704 5705All input buffers and output arrays must be padded to 16 bytes, as the 5706implementation uses 16-byte SSE instructions to read and write into 5707these buffers. 5708 5709See tutorial [Interpolation] for an example of using the 5710`rtcInterpolate` function. 5711 5712#### EXIT STATUS {#exit-status} 5713 5714For performance reasons this function does not do any error checks, 5715thus will not set any error flags on failure. 5716 5717#### SEE ALSO {#see-also} 5718 5719[rtcInterpolateN] 5720 5721 5722 5723rtcInterpolateN 5724--------------- 5725 5726#### NAME {#name} 5727 5728 rtcInterpolateN - performs N interpolations of vertex attribute data 5729 5730#### SYNOPSIS {#synopsis} 5731 5732 #include <embree3/rtcore.h> 5733 5734 struct RTCInterpolateNArguments 5735 { 5736 RTCGeometry geometry; 5737 const void* valid; 5738 const unsigned int* primIDs; 5739 const float* u; 5740 const float* v; 5741 unsigned int N; 5742 enum RTCBufferType bufferType; 5743 unsigned int bufferSlot; 5744 float* P; 5745 float* dPdu; 5746 float* dPdv; 5747 float* ddPdudu; 5748 float* ddPdvdv; 5749 float* ddPdudv; 5750 unsigned int valueCount; 5751 }; 5752 5753 void rtcInterpolateN( 5754 const struct RTCInterpolateNArguments* args 5755 ); 5756 5757#### DESCRIPTION {#description} 5758 5759The `rtcInterpolateN` is similar to `rtcInterpolate`, but performs `N` 5760many interpolations at once. It additionally gets an array of u/v 5761coordinates and a valid mask (`valid` parameter) that specifies which 5762of these coordinates are valid. The valid mask points to `N` integers, 5763and a value of -1 denotes valid and 0 invalid. If the valid pointer is 5764`NULL` all elements are considers valid. The destination arrays are 5765filled in structure of array (SOA) layout. The value `N` must be 5766divisible by 4. 5767 5768To use `rtcInterpolateN` for a geometry, all changes to that geometry 5769must be properly committed using `rtcCommitGeometry`. 5770 5771#### EXIT STATUS {#exit-status} 5772 5773For performance reasons this function does not do any error checks, 5774thus will not set any error flags on failure. 5775 5776#### SEE ALSO {#see-also} 5777 5778[rtcInterpolate] 5779 5780 5781 5782rtcNewBuffer 5783------------ 5784 5785#### NAME {#name} 5786 5787 rtcNewBuffer - creates a new data buffer 5788 5789#### SYNOPSIS {#synopsis} 5790 5791 #include <embree3/rtcore.h> 5792 5793 RTCBuffer rtcNewBuffer( 5794 RTCDevice device, 5795 size_t byteSize 5796 ); 5797 5798#### DESCRIPTION {#description} 5799 5800The `rtcNewBuffer` function creates a new data buffer object of 5801specified size in bytes (`byteSize` argument) that is bound to the 5802specified device (`device` argument). The buffer object is reference 5803counted with an initial reference count of 1. The returned buffer 5804object can be released using the `rtcReleaseBuffer` API call. The 5805specified number of bytes are allocated at buffer construction time and 5806deallocated when the buffer is destroyed. 5807 5808When the buffer will be used as a vertex buffer 5809(`RTC_BUFFER_TYPE_VERTEX` and `RTC_BUFFER_TYPE_VERTEX_ATTRIBUTE`), the 5810last buffer element must be readable using 16-byte SSE load 5811instructions, thus padding the last element is required for certain 5812layouts. E.g. a standard `float3` vertex buffer layout should add 5813storage for at least one more float to the end of the buffer. 5814 5815#### EXIT STATUS {#exit-status} 5816 5817On failure `NULL` is returned and an error code is set that can be 5818queried using `rtcGetDeviceError`. 5819 5820#### SEE ALSO {#see-also} 5821 5822[rtcRetainBuffer], [rtcReleaseBuffer] 5823 5824 5825 5826rtcNewSharedBuffer 5827------------------ 5828 5829#### NAME {#name} 5830 5831 rtcNewSharedBuffer - creates a new shared data buffer 5832 5833#### SYNOPSIS {#synopsis} 5834 5835 #include <embree3/rtcore.h> 5836 5837 RTCBuffer rtcNewSharedBuffer( 5838 RTCDevice device, 5839 void* ptr, 5840 size_t byteSize 5841 ); 5842 5843#### DESCRIPTION {#description} 5844 5845The `rtcNewSharedBuffer` function creates a new shared data buffer 5846object bound to the specified device (`device` argument). The buffer 5847object is reference counted with an initial reference count of 1. The 5848buffer can be released using the `rtcReleaseBuffer` function. 5849 5850At construction time, the pointer to the user-managed buffer data 5851(`ptr` argument) including its size in bytes (`byteSize` argument) is 5852provided to create the buffer. At buffer construction time no buffer 5853data is allocated, but the buffer data provided by the application is 5854used. The buffer data must remain valid for as long as the buffer may 5855be used, and the user is responsible to free the buffer data when no 5856longer required. 5857 5858When the buffer will be used as a vertex buffer 5859(`RTC_BUFFER_TYPE_VERTEX` and `RTC_BUFFER_TYPE_VERTEX_ATTRIBUTE`), the 5860last buffer element must be readable using 16-byte SSE load 5861instructions, thus padding the last element is required for certain 5862layouts. E.g. a standard `float3` vertex buffer layout should add 5863storage for at least one more float to the end of the buffer. 5864 5865The data pointer (`ptr` argument) must be aligned to 4 bytes; otherwise 5866the `rtcNewSharedBuffer` function will fail. 5867 5868#### EXIT STATUS {#exit-status} 5869 5870On failure `NULL` is returned and an error code is set that can be 5871queried using `rtcGetDeviceError`. 5872 5873#### SEE ALSO {#see-also} 5874 5875[rtcRetainBuffer], [rtcReleaseBuffer] 5876 5877 5878 5879rtcRetainBuffer 5880--------------- 5881 5882#### NAME {#name} 5883 5884 rtcRetainBuffer - increments the buffer reference count 5885 5886#### SYNOPSIS {#synopsis} 5887 5888 #include <embree3/rtcore.h> 5889 5890 void rtcRetainBuffer(RTCBuffer buffer); 5891 5892#### DESCRIPTION {#description} 5893 5894Buffer objects are reference counted. The `rtcRetainBuffer` function 5895increments the reference count of the passed buffer object (`buffer` 5896argument). This function together with `rtcReleaseBuffer` allows to use 5897the internal reference counting in a C++ wrapper class to handle the 5898ownership of the object. 5899 5900#### EXIT STATUS {#exit-status} 5901 5902On failure an error code is set that can be queried using 5903`rtcGetDeviceError`. 5904 5905#### SEE ALSO {#see-also} 5906 5907[rtcNewBuffer], [rtcReleaseBuffer] 5908 5909 5910 5911rtcReleaseBuffer 5912---------------- 5913 5914#### NAME {#name} 5915 5916 rtcReleaseBuffer - decrements the buffer reference count 5917 5918#### SYNOPSIS {#synopsis} 5919 5920 #include <embree3/rtcore.h> 5921 5922 void rtcReleaseBuffer(RTCBuffer buffer); 5923 5924#### DESCRIPTION {#description} 5925 5926Buffer objects are reference counted. The `rtcReleaseBuffer` function 5927decrements the reference count of the passed buffer object (`buffer` 5928argument). When the reference count falls to 0, the buffer gets 5929destroyed. 5930 5931#### EXIT STATUS {#exit-status} 5932 5933On failure an error code is set that can be queried using 5934`rtcGetDeviceError`. 5935 5936#### SEE ALSO {#see-also} 5937 5938[rtcNewBuffer], [rtcRetainBuffer] 5939 5940 5941 5942rtcGetBufferData 5943---------------- 5944 5945#### NAME {#name} 5946 5947 rtcGetBufferData - gets a pointer to the buffer data 5948 5949#### SYNOPSIS {#synopsis} 5950 5951 #include <embree3/rtcore.h> 5952 5953 void* rtcGetBufferData(RTCBuffer buffer); 5954 5955#### DESCRIPTION {#description} 5956 5957The `rtcGetBufferData` function returns a pointer to the buffer data of 5958the specified buffer object (`buffer` argument). 5959 5960#### EXIT STATUS {#exit-status} 5961 5962On failure an error code is set that can be queried using 5963`rtcGetDeviceError`. 5964 5965#### SEE ALSO {#see-also} 5966 5967[rtcNewBuffer] 5968 5969 5970 5971RTCRay 5972------ 5973 5974#### NAME {#name} 5975 5976 RTCRay - single ray structure 5977 5978#### SYNOPSIS {#synopsis} 5979 5980 #include <embree3/rtcore_ray.h> 5981 5982 struct RTC_ALIGN(16) RTCRay 5983 { 5984 float org_x; // x coordinate of ray origin 5985 float org_y; // y coordinate of ray origin 5986 float org_z; // z coordinate of ray origin 5987 float tnear; // start of ray segment 5988 5989 float dir_x; // x coordinate of ray direction 5990 float dir_y; // y coordinate of ray direction 5991 float dir_z; // z coordinate of ray direction 5992 float time; // time of this ray for motion blur 5993 5994 float tfar; // end of ray segment (set to hit distance) 5995 unsigned int mask; // ray mask 5996 unsigned int id; // ray ID 5997 unsigned int flags; // ray flags 5998 }; 5999 6000#### DESCRIPTION {#description} 6001 6002The `RTCRay` structure defines the ray layout for a single ray. The ray 6003contains the origin (`org_x`, `org_y`, `org_z` members), direction 6004vector (`dir_x`, `dir_y`, `dir_z` members), and ray segment (`tnear` 6005and `tfar` members). The ray direction does not have to be normalized, 6006and only the parameter range specified by the `tnear`/`tfar` interval 6007is considered valid. 6008 6009The ray segment must be in the range $[0, \infty]$, thus ranges that 6010start behind the ray origin are not allowed, but ranges can reach to 6011infinity. For rays inside a ray stream, `tfar` \< `tnear` identifies an 6012inactive ray. 6013 6014The ray further contains a motion blur time in the range $[0, 1]$ 6015(`time` member), a ray mask (`mask` member), a ray ID (`id` member), 6016and ray flags (`flags` member). The ray mask can be used to mask out 6017some geometries for some rays (see `rtcSetGeometryMask` for more 6018details). The ray ID can be used to identify a ray inside a callback 6019function, even if the order of rays inside a ray packet or stream has 6020changed. The ray flags are reserved. 6021 6022The `embree3/rtcore_ray.h` header additionally defines the same ray 6023structure in structure of array (SOA) layout for API functions 6024accepting ray packets of size 4 (`RTCRay4` type), size 8 (`RTCRay8` 6025type), and size 16 (`RTCRay16` type). The header additionally defines 6026an `RTCRayNt` template for ray packets of an arbitrary compile-time 6027size. 6028 6029#### EXIT STATUS {#exit-status} 6030 6031#### SEE ALSO {#see-also} 6032 6033[RTCHit] 6034 6035 6036 6037RTCHit 6038------ 6039 6040#### NAME {#name} 6041 6042 RTCHit - single hit structure 6043 6044#### SYNOPSIS {#synopsis} 6045 6046 #include <embree3/rtcore.h> 6047 6048 struct RTCHit 6049 { 6050 float Ng_x; // x coordinate of geometry normal 6051 float Ng_y; // y coordinate of geometry normal 6052 float Ng_z; // z coordinate of geometry normal 6053 6054 float u; // barycentric u coordinate of hit 6055 float v; // barycentric v coordinate of hit 6056 6057 unsigned int primID; // geometry ID 6058 unsigned int geomID; // primitive ID 6059 unsigned int instID[RTC_MAX_INSTANCE_LEVEL_COUNT]; // instance ID 6060 }; 6061 6062#### DESCRIPTION {#description} 6063 6064The `RTCHit` type defines the type of a ray/primitive intersection 6065result. The hit contains the unnormalized geometric normal in object 6066space at the hit location (`Ng_x`, `Ng_y`, `Ng_z` members), the 6067barycentric u/v coordinates of the hit (`u` and `v` members), as well 6068as the primitive ID (`primID` member), geometry ID (`geomID` member), 6069and instance ID stack (`instID` member) of the hit. The parametric 6070intersection distance is not stored inside the hit, but stored inside 6071the `tfar` member of the ray. 6072 6073The `embree3/rtcore_ray.h` header additionally defines the same hit 6074structure in structure of array (SOA) layout for hit packets of size 4 6075(`RTCHit4` type), size 8 (`RTCHit8` type), and size 16 (`RTCHit16` 6076type). The header additionally defines an `RTCHitNt` template for hit 6077packets of an arbitrary compile-time size. 6078 6079#### EXIT STATUS {#exit-status} 6080 6081#### SEE ALSO {#see-also} 6082 6083[RTCRay], [Multi-Level Instancing] 6084 6085 6086 6087RTCRayHit 6088--------- 6089 6090#### NAME {#name} 6091 6092 RTCRayHit - combined single ray/hit structure 6093 6094#### SYNOPSIS {#synopsis} 6095 6096 #include <embree3/rtcore_ray.h> 6097 6098 struct RTCORE_ALIGN(16) RTCRayHit 6099 { 6100 struct RTCRay ray; 6101 struct RTCHit hit; 6102 }; 6103 6104#### DESCRIPTION {#description} 6105 6106The `RTCRayHit` structure is used as input for the `rtcIntersect`-type 6107functions and stores the ray to intersect and some hit fields that hold 6108the intersection result afterwards. 6109 6110The `embree3/rtcore_ray.h` header additionally defines the same ray/hit 6111structure in structure of array (SOA) layout for API functions 6112accepting ray packets of size 4 (`RTCRayHit4` type), size 8 6113(`RTCRayHit8` type), and size 16 (`RTCRayHit16` type). The header 6114additionally defines an `RTCRayHitNt` template to generate ray/hit 6115packets of an arbitrary compile-time size. 6116 6117#### EXIT STATUS {#exit-status} 6118 6119#### SEE ALSO {#see-also} 6120 6121[RTCRay], [RTCHit] 6122 6123 6124 6125RTCRayN 6126------- 6127 6128#### NAME {#name} 6129 6130 RTCRayN - ray packet of runtime size 6131 6132#### SYNOPSIS {#synopsis} 6133 6134 #include <embree3/rtcore_ray.h> 6135 6136 struct RTCRayN; 6137 6138 float& RTCRayN_org_x(RTCRayN* ray, unsigned int N, unsigned int i); 6139 float& RTCRayN_org_y(RTCRayN* ray, unsigned int N, unsigned int i); 6140 float& RTCRayN_org_z(RTCRayN* ray, unsigned int N, unsigned int i); 6141 float& RTCRayN_tnear(RTCRayN* ray, unsigned int N, unsigned int i); 6142 6143 float& RTCRayN_dir_x(RTCRayN* ray, unsigned int N, unsigned int i); 6144 float& RTCRayN_dir_y(RTCRayN* ray, unsigned int N, unsigned int i); 6145 float& RTCRayN_dir_z(RTCRayN* ray, unsigned int N, unsigned int i); 6146 float& RTCRayN_time (RTCRayN* ray, unsigned int N, unsigned int i); 6147 6148 float& RTCRayN_tfar (RTCRayN* ray, unsigned int N, unsigned int i); 6149 unsigned int& RTCRayN_mask (RTCRayN* ray, unsigned int N, unsigned int i); 6150 unsigned int& RTCRayN_id (RTCRayN* ray, unsigned int N, unsigned int i); 6151 unsigned int& RTCRayN_flags(RTCRayN* ray, unsigned int N, unsigned int i); 6152 6153#### DESCRIPTION {#description} 6154 6155When the ray packet size is not known at compile time (e.g. when Embree 6156returns a ray packet in the `RTCFilterFuncN` callback function), Embree 6157uses the `RTCRayN` type for ray packets. These ray packets can only 6158have sizes of 1, 4, 8, or 16. No other packet size will be used. 6159 6160You can either implement different special code paths for each of these 6161possible packet sizes and cast the ray to the appropriate ray packet 6162type, or implement one general code path that uses the `RTCRayN_XXX` 6163helper functions to access the ray packet components. 6164 6165These helper functions get a pointer to the ray packet (`ray` 6166argument), the packet size (`N` argument), and returns a reference to a 6167component (e.g. x-component of origin) of the the i-th ray of the 6168packet (`i` argument). 6169 6170#### EXIT STATUS {#exit-status} 6171 6172#### SEE ALSO {#see-also} 6173 6174[RTCHitN] 6175 6176 6177 6178RTCHitN 6179------- 6180 6181#### NAME {#name} 6182 6183 RTCHitN - hit packet of runtime size 6184 6185#### SYNOPSIS {#synopsis} 6186 6187 #include <embree3/rtcore.h> 6188 6189 struct HitN; 6190 6191 float& RTCHitN_Ng_x(RTCHitN* hit, unsigned int N, unsigned int i); 6192 float& RTCHitN_Ng_y(RTCHitN* hit, unsigned int N, unsigned int i); 6193 float& RTCHitN_Ng_z(RTCHitN* hit, unsigned int N, unsigned int i); 6194 6195 float& RTCHitN_u(RTCHitN* hit, unsigned int N, unsigned int i); 6196 float& RTCHitN_v(RTCHitN* hit, unsigned int N, unsigned int i); 6197 6198 unsigned& RTCHitN_primID(RTCHitN* hit, unsigned int N, unsigned int i); 6199 unsigned& RTCHitN_geomID(RTCHitN* hit, unsigned int N, unsigned int i); 6200 unsigned& RTCHitN_instID(RTCHitN* hit, unsigned int N, unsigned int i, unsigned int level); 6201 6202#### DESCRIPTION {#description} 6203 6204When the hit packet size is not known at compile time (e.g. when Embree 6205returns a hit packet in the `RTCFilterFuncN` callback function), Embree 6206uses the `RTCHitN` type for hit packets. These hit packets can only 6207have sizes of 1, 4, 8, or 16. No other packet size will be used. 6208 6209You can either implement different special code paths for each of these 6210possible packet sizes and cast the hit to the appropriate hit packet 6211type, or implement one general code path that uses the `RTCHitN_XXX` 6212helper functions to access hit packet components. 6213 6214These helper functions get a pointer to the hit packet (`hit` 6215argument), the packet size (`N` argument), and returns a reference to a 6216component (e.g. x component of `Ng`) of the the i-th hit of the packet 6217(`i` argument). 6218 6219#### EXIT STATUS {#exit-status} 6220 6221#### SEE ALSO {#see-also} 6222 6223[RTCRayN] 6224 6225 6226 6227RTCRayHitN 6228---------- 6229 6230#### NAME {#name} 6231 6232 RTCRayHitN - combined ray/hit packet of runtime size 6233 6234#### SYNOPSIS {#synopsis} 6235 6236 #include <embree3/rtcore_ray.h> 6237 6238 struct RTCRayHitN; 6239 6240 struct RTCRayN* RTCRayHitN_RayN(struct RTCRayHitN* rayhit, unsigned int N); 6241 struct RTCHitN* RTCRayHitN_HitN(struct RTCRayHitN* rayhit, unsigned int N); 6242 6243#### DESCRIPTION {#description} 6244 6245When the packet size of a ray/hit structure is not known at compile 6246time (e.g. when Embree returns a ray/hit packet in the 6247`RTCIntersectFunctionN` callback function), Embree uses the 6248`RTCRayHitN` type for ray packets. These ray/hit packets can only have 6249sizes of 1, 4, 8, or 16. No other packet size will be used. 6250 6251You can either implement different special code paths for each of these 6252possible packet sizes and cast the ray/hit to the appropriate ray/hit 6253packet type, or extract the `RTCRayN` and `RTCHitN` components using 6254the `rtcGetRayN` and `rtcGetHitN` helper functions and use the 6255`RTCRayN_XXX` and `RTCHitN_XXX` functions to access the ray and hit 6256parts of the structure. 6257 6258#### EXIT STATUS {#exit-status} 6259 6260#### SEE ALSO {#see-also} 6261 6262[RTCHitN] 6263 6264 6265 6266rtcInitIntersectContext 6267----------------------- 6268 6269#### NAME {#name} 6270 6271 rtcInitIntersectContext - initializes the intersection context 6272 6273#### SYNOPSIS {#synopsis} 6274 6275 #include <embree3/rtcore.h> 6276 6277 enum RTCIntersectContextFlags 6278 { 6279 RTC_INTERSECT_CONTEXT_FLAG_NONE, 6280 RTC_INTERSECT_CONTEXT_FLAG_INCOHERENT, 6281 RTC_INTERSECT_CONTEXT_FLAG_COHERENT, 6282 }; 6283 6284 struct RTCIntersectContext 6285 { 6286 enum RTCIntersectContextFlags flags; 6287 RTCFilterFunctionN filter; 6288 6289 #if RTC_MAX_INSTANCE_LEVEL_COUNT > 1 6290 unsigned int instStackSize; 6291 #endif 6292 6293 unsigned int instID[RTC_MAX_INSTANCE_LEVEL_COUNT]; 6294 6295 #if RTC_MIN_WIDTH 6296 float minWidthDistanceFactor; 6297 #endif 6298 }; 6299 6300 void rtcInitIntersectContext( 6301 struct RTCIntersectContext* context 6302 ); 6303 6304#### DESCRIPTION {#description} 6305 6306A per ray-query intersection context (`RTCIntersectContext` type) is 6307supported that can be used to configure intersection flags (`flags` 6308member), specify a filter callback function (`filter` member), specify 6309the chain of IDs of the current instance (`instID` and `instStackSize` 6310members), and to attach arbitrary data to the query (e.g. per ray 6311data). 6312 6313The `rtcInitIntersectContext` function initializes the context to 6314default values and should be called to initialize every intersection 6315context. This function gets inlined, which minimizes overhead and 6316allows for compiler optimizations. 6317 6318The intersection context flag can be used to tune the behavior of the 6319traversal algorithm. Using the `RTC_INTERSECT_CONTEXT_FLAG_INCOHERENT` 6320flags uses an optimized traversal algorithm for incoherent rays 6321(default), while `RTC_INTERSECT_CONTEXT_FLAG_COHERENT` uses an 6322optimized traversal algorithm for coherent rays (e.g. primary camera 6323rays). 6324 6325Best primary ray performance can be obtained by using the ray stream 6326API and setting the intersect context flag to 6327`RTC_INTERSECT_CONTEXT_FLAG_COHERENT`. For secondary rays, it is 6328typically better to use the `RTC_INTERSECT_CONTEXT_FLAG_INCOHERENT` 6329flag, unless the rays are known to be very coherent too (e.g. for 6330primary transparency rays). 6331 6332A filter function can be specified inside the context. This filter 6333function is invoked as a second filter stage after the per-geometry 6334intersect or occluded filter function is invoked. Only rays that passed 6335the first filter stage are valid in this second filter stage. Having 6336such a per ray-query filter function can be useful to implement 6337modifications of the behavior of the query, such as collecting all hits 6338or accumulating transparencies. The support for the context filter 6339function must be enabled for a scene by using the 6340`RTC_SCENE_FLAG_CONTEXT_FILTER_FUNCTION` scene flag. In case of 6341instancing this feature has to get enabled also for each instantiated 6342scene. 6343 6344The minWidthDistanceFactor value controls the target size of the curve 6345radii when the min-width feature is enabled. Please see the 6346[rtcSetGeometryMaxRadiusScale] function for more details on the 6347min-width feature. 6348 6349It is guaranteed that the pointer to the intersection context passed to 6350a ray query is directly passed to the registered callback functions. 6351This way it is possible to attach arbitrary data to the end of the 6352intersection context, such as a per-ray payload. 6353 6354Please note that the ray pointer is not guaranteed to be passed to the 6355callback functions, thus reading additional data from the ray pointer 6356passed to callbacks is not possible. 6357 6358#### EXIT STATUS {#exit-status} 6359 6360No error code is set by this function. 6361 6362#### SEE ALSO {#see-also} 6363 6364[rtcIntersect1], [rtcOccluded1] 6365 6366 6367 6368rtcIntersect1 6369------------- 6370 6371#### NAME {#name} 6372 6373 rtcIntersect1 - finds the closest hit for a single ray 6374 6375#### SYNOPSIS {#synopsis} 6376 6377 #include <embree3/rtcore.h> 6378 6379 void rtcIntersect1( 6380 RTCScene scene, 6381 struct RTCIntersectContext* context, 6382 struct RTCRayHit* rayhit 6383 ); 6384 6385#### DESCRIPTION {#description} 6386 6387The `rtcIntersect1` function finds the closest hit of a single ray with 6388the scene (`scene` argument). The provided ray/hit structure (`rayhit` 6389argument) contains the ray to intersect and some hit output fields that 6390are filled when a hit is found. 6391 6392The user has to initialize the ray origin (`org` ray member), ray 6393direction (`dir` ray member), ray segment (`tnear`, `tfar` ray 6394members), and set the ray flags to `0` (`flags` ray member). If the 6395scene contains motion blur geometries, also the ray time (`time` ray 6396member) must be initialized to a value in the range $[0, 1]$. If ray 6397masks are enabled at compile time, the ray mask (`mask` ray member) 6398must be initialized as well. The ray segment has to be in the range 6399$[0, \infty]$, thus ranges that start behind the ray origin are not 6400valid, but ranges can reach to infinity. See Section [RTCRay] for the 6401ray layout description. 6402 6403The geometry ID (`geomID` hit member) of the hit data must be 6404initialized to `RTC_INVALID_GEOMETRY_ID` (-1). 6405 6406Further, an intersection context for the ray query function must be 6407created and initialized (see `rtcInitIntersectContext`). 6408 6409When no intersection is found, the ray/hit data is not updated. When an 6410intersection is found, the hit distance is written into the `tfar` 6411member of the ray and all hit data is set, such as unnormalized 6412geometry normal in object space (`Ng` hit member), local hit 6413coordinates (`u`, `v` hit member), instance ID stack (`instID` hit 6414member), geometry ID (`geomID` hit member), and primitive ID (`primID` 6415hit member). See Section [RTCHit] for the hit layout description. 6416 6417If the instance ID stack has a prefix of values not equal to 6418`RTC_INVALID_GEOMETRY_ID`, the instance ID on each level corresponds to 6419the geometry ID of the hit instance of the higher-level scene, the 6420geometry ID corresponds to the hit geometry inside the hit instanced 6421scene, and the primitive ID corresponds to the n-th primitive of that 6422geometry. 6423 6424If level 0 of the instance ID stack is equal to 6425`RTC_INVALID_GEOMETRY_ID`, the geometry ID corresponds to the hit 6426geometry inside the top-level scene, and the primitive ID corresponds 6427to the n-th primitive of that geometry. 6428 6429The implementation makes no guarantees that primitives whose hit 6430distance is exactly at (or very close to) `tnear` or `tfar` are hit or 6431missed. If you want to exclude intersections at `tnear` just pass a 6432slightly enlarged `tnear`, and if you want to include intersections at 6433`tfar` pass a slightly enlarged `tfar`. 6434 6435The intersection context (`context` argument) can specify flags to 6436optimize traversal and a filter callback function to be invoked for 6437every intersection. Further, the pointer to the intersection context is 6438propagated to callback functions invoked during traversal and can thus 6439be used to extend the ray with additional data. See Section 6440`RTCIntersectContext` for more information. 6441 6442The ray pointer passed to callback functions is not guaranteed to be 6443identical to the original ray provided. To extend the ray with 6444additional data to be accessed in callback functions, use the 6445intersection context. 6446 6447The ray/hit structure must be aligned to 16 bytes. 6448 6449#### EXIT STATUS {#exit-status} 6450 6451For performance reasons this function does not do any error checks, 6452thus will not set any error flags on failure. 6453 6454#### SEE ALSO {#see-also} 6455 6456[rtcOccluded1], [RTCRayHit], [RTCRay], [RTCHit] 6457 6458 6459 6460rtcOccluded1 6461------------ 6462 6463#### NAME {#name} 6464 6465 rtcOccluded1 - finds any hit for a single ray 6466 6467#### SYNOPSIS {#synopsis} 6468 6469 #include <embree3/rtcore.h> 6470 6471 void rtcOccluded1( 6472 RTCScene scene, 6473 struct RTCIntersectContext* context, 6474 struct RTCRay* ray 6475 ); 6476 6477#### DESCRIPTION {#description} 6478 6479The `rtcOccluded1` function checks for a single ray (`ray` argument) 6480whether there is any hit with the scene (`scene` argument). 6481 6482The user must initialize the ray origin (`org` ray member), ray 6483direction (`dir` ray member), ray segment (`tnear`, `tfar` ray 6484members), and must set the ray flags to `0` (`flags` ray member). If 6485the scene contains motion blur geometries, also the ray time (`time` 6486ray member) must be initialized to a value in the range $[0, 1]$. If 6487ray masks are enabled at compile time, the ray mask (`mask` ray member) 6488must be initialized as well. The ray segment must be in the range 6489$[0, \infty]$, thus ranges that start behind the ray origin are not 6490valid, but ranges can reach to infinity. See Section [RTCRay] for the 6491ray layout description. 6492 6493When no intersection is found, the ray data is not updated. In case a 6494hit was found, the `tfar` component of the ray is set to `-inf`. 6495 6496The implementation makes no guarantees that primitives whose hit 6497distance is exactly at (or very close to) `tnear` or `tfar` are hit or 6498missed. If you want to exclude intersections at `tnear` just pass a 6499slightly enlarged `tnear`, and if you want to include intersections at 6500`tfar` pass a slightly enlarged `tfar`. 6501 6502The intersection context (`context` argument) can specify flags to 6503optimize traversal and a filter callback function to be invoked for 6504every intersection. Further, the pointer to the intersection context is 6505propagated to callback functions invoked during traversal and can thus 6506be used to extend the ray with additional data. See Section 6507`RTCIntersectContext` for more information. 6508 6509The ray pointer passed to callback functions is not guaranteed to be 6510identical to the original ray provided. To extend the ray with 6511additional data to be accessed in callback functions, use the 6512intersection context. 6513 6514The ray must be aligned to 16 bytes. 6515 6516#### EXIT STATUS {#exit-status} 6517 6518For performance reasons this function does not do any error checks, 6519thus will not set any error flags on failure. 6520 6521#### SEE ALSO {#see-also} 6522 6523[rtcOccluded1], [RTCRay] 6524 6525 6526 6527rtcIntersect4/8/16 6528------------------ 6529 6530#### NAME {#name} 6531 6532 rtcIntersect4/8/16 - finds the closest hits for a ray packet 6533 6534#### SYNOPSIS {#synopsis} 6535 6536 #include <embree3/rtcore.h> 6537 6538 void rtcIntersect4( 6539 const int* valid, 6540 RTCScene scene, 6541 struct RTCIntersectContext* context, 6542 struct RTCRayHit4* rayhit 6543 ); 6544 6545 void rtcIntersect8( 6546 const int* valid, 6547 RTCScene scene, 6548 struct RTCIntersectContext* context, 6549 struct RTCRayHit8* rayhit 6550 ); 6551 6552 void rtcIntersect16( 6553 const int* valid, 6554 RTCScene scene, 6555 struct RTCIntersectContext* context, 6556 struct RTCRayHit16* rayhit 6557 ); 6558 6559#### DESCRIPTION {#description} 6560 6561The `rtcIntersect4/8/16` functions finds the closest hits for a ray 6562packet of size 4, 8, or 16 (`rayhit` argument) with the scene (`scene` 6563argument). The ray/hit input contains a ray packet and hit packet. See 6564Section [rtcIntersect1] for a description of how to set up and trace 6565rays. 6566 6567A ray valid mask must be provided (`valid` argument) which stores one 656832-bit integer (`-1` means valid and `0` invalid) per ray in the 6569packet. Only active rays are processed, and hit data of inactive rays 6570is not changed. 6571 6572The intersection context (`context` argument) can specify flags to 6573optimize traversal and a filter callback function to be invoked for 6574every intersection. Further, the pointer to the intersection context is 6575propagated to callback functions invoked during traversal and can thus 6576be used to extend the ray with additional data. See Section 6577`RTCIntersectContext` for more information. 6578 6579The ray pointer passed to callback functions is not guaranteed to be 6580identical to the original ray provided. To extend the ray with 6581additional data to be accessed in callback functions, use the 6582intersection context. 6583 6584The implementation of these functions is guaranteed to invoke callback 6585functions always with the same ray packet size and ordering of rays as 6586specified initially. 6587 6588For `rtcIntersect4` the ray packet must be aligned to 16 bytes, for 6589`rtcIntersect8` the alignment must be 32 bytes, and for 6590`rtcIntersect16` the alignment must be 64 bytes. 6591 6592The `rtcIntersect4`, `rtcIntersect8` and `rtcIntersect16` functions may 6593change the ray packet size and ray order when calling back into 6594intersect filter functions or user geometry callbacks. Under some 6595conditions the application can assume packets to stay intakt, which can 6596determined by querying the `RTC_DEVICE_PROPERTY_NATIVE_RAY4_SUPPORTED`, 6597`RTC_DEVICE_PROPERTY_NATIVE_RAY8_SUPPORTED`, 6598`RTC_DEVICE_PROPERTY_NATIVE_RAY16_SUPPORTED` properties through the 6599`rtcGetDeviceProperty` function. See [rtcGetDeviceProperty] for more 6600information. 6601 6602#### EXIT STATUS {#exit-status} 6603 6604For performance reasons this function does not do any error checks, 6605thus will not set any error flags on failure. 6606 6607#### SEE ALSO {#see-also} 6608 6609[rtcOccluded4/8/16] 6610 6611 6612 6613rtcOccluded4/8/16 6614----------------- 6615 6616#### NAME {#name} 6617 6618 rtcOccluded4/8/16 - finds any hits for a ray packet 6619 6620#### SYNOPSIS {#synopsis} 6621 6622 #include <embree3/rtcore.h> 6623 6624 void rtcOccluded4( 6625 const int* valid, 6626 RTCScene scene, 6627 struct RTCIntersectContext* context, 6628 struct RTCRay4* ray 6629 ); 6630 6631 void rtcOccluded8( 6632 const int* valid, 6633 RTCScene scene, 6634 struct RTCIntersectContext* context, 6635 struct RTCRay8* ray 6636 ); 6637 6638 void rtcOccluded16( 6639 const int* valid, 6640 RTCScene scene, 6641 struct RTCIntersectContext* context, 6642 struct RTCRay16* ray 6643 ); 6644 6645#### DESCRIPTION {#description} 6646 6647The `rtcOccluded4/8/16` functions checks for each active ray of the ray 6648packet of size 4, 8, or 16 (`ray` argument) whether there is any hit 6649with the scene (`scene` argument). See Section [rtcOccluded1] for a 6650description of how to set up and trace occlusion rays. 6651 6652A ray valid mask must be provided (`valid` argument) which stores one 665332-bit integer (`-1` means valid and `0` invalid) per ray in the 6654packet. Only active rays are processed, and hit data of inactive rays 6655is not changed. 6656 6657The intersection context (`context` argument) can specify flags to 6658optimize traversal and a filter callback function to be invoked for 6659every intersection. Further, the pointer to the intersection context is 6660propagated to callback functions invoked during traversal and can thus 6661be used to extend the ray with additional data. See Section 6662`RTCIntersectContext` for more information. 6663 6664The ray pointer passed to callback functions is not guaranteed to be 6665identical to the original ray provided. To extend the ray with 6666additional data to be accessed in callback functions, use the 6667intersection context. 6668 6669The implementation of these functions is guaranteed to invoke callback 6670functions always with the same ray packet size and ordering of rays as 6671specified initially. 6672 6673For `rtcOccluded4` the ray packet must be aligned to 16 bytes, for 6674`rtcOccluded8` the alignment must be 32 bytes, and for `rtcOccluded16` 6675the alignment must be 64 bytes. 6676 6677The `rtcOccluded4`, `rtcOccluded8` and `rtcOccluded16` functions may 6678change the ray packet size and ray order when calling back into 6679intersect filter functions or user geometry callbacks. Under some 6680conditions the application can assume packets to stay intakt, which can 6681determined by querying the `RTC_DEVICE_PROPERTY_NATIVE_RAY4_SUPPORTED`, 6682`RTC_DEVICE_PROPERTY_NATIVE_RAY8_SUPPORTED`, 6683`RTC_DEVICE_PROPERTY_NATIVE_RAY16_SUPPORTED` properties through the 6684`rtcGetDeviceProperty` function. See [rtcGetDeviceProperty] for more 6685information. 6686 6687#### EXIT STATUS {#exit-status} 6688 6689For performance reasons this function does not do any error checks, 6690thus will not set any error flags on failure. 6691 6692#### SEE ALSO {#see-also} 6693 6694[rtcOccluded4/8/16] 6695 6696 6697 6698rtcIntersect1M 6699-------------- 6700 6701#### NAME {#name} 6702 6703 rtcIntersect1M - finds the closest hits for a stream of M single 6704 rays 6705 6706#### SYNOPSIS {#synopsis} 6707 6708 #include <embree3/rtcore.h> 6709 6710 void rtcIntersect1M( 6711 RTCScene scene, 6712 struct RTCIntersectContext* context, 6713 struct RTCRayHit* rayhit, 6714 unsigned int M, 6715 size_t byteStride 6716 ); 6717 6718#### DESCRIPTION {#description} 6719 6720The `rtcIntersect1M` function finds the closest hits for a stream of 6721`M` single rays (`rayhit` argument) with the scene (`scene` argument). 6722The `rayhit` argument points to an array of ray and hit data with 6723specified byte stride (`byteStride` argument) between the ray/hit 6724structures. See Section [rtcIntersect1] for a description of how to 6725set up and trace rays. 6726 6727The intersection context (`context` argument) can specify flags to 6728optimize traversal and a filter callback function to be invoked for 6729every intersection. Further, the pointer to the intersection context is 6730propagated to callback functions invoked during traversal and can thus 6731be used to extend the ray with additional data. See Section 6732`RTCIntersectContext` for more information. 6733 6734The implementation of the stream ray query functions may re-order rays 6735arbitrarily and re-pack rays into ray packets of different size. For 6736this reason, callback functions may be invoked with an arbitrary packet 6737size (of size 1, 4, 8, or 16) and different ordering as specified 6738initially. For this reason, one may have to use the `rayID` component 6739of the ray to identify the original ray, e.g. to access a per-ray 6740payload. 6741 6742A ray in a ray stream is considered inactive if its `tnear` value is 6743larger than its `tfar` value. 6744 6745The stream size `M` can be an arbitrary positive integer including 0. 6746Each ray must be aligned to 16 bytes. 6747 6748#### EXIT STATUS {#exit-status} 6749 6750For performance reasons this function does not do any error checks, 6751thus will not set any error flags on failure. 6752 6753#### SEE ALSO {#see-also} 6754 6755[rtcOccluded1M] 6756 6757 6758 6759rtcOccluded1M 6760------------- 6761 6762#### NAME {#name} 6763 6764 rtcOccluded1M - finds any hits for a stream of M single rays 6765 6766#### SYNOPSIS {#synopsis} 6767 6768 #include <embree3/rtcore.h> 6769 6770 void rtcOccluded1M( 6771 RTCScene scene, 6772 struct RTCIntersectContext* context, 6773 struct RTCRay* ray, 6774 unsigned int M, 6775 size_t byteStride 6776 ); 6777 6778#### DESCRIPTION {#description} 6779 6780The `rtcOccluded1M` function checks whether there are any hits for a 6781stream of `M` single rays (`ray` argument) with the scene (`scene` 6782argument). The `ray` argument points to an array of rays with specified 6783byte stride (`byteStride` argument) between the rays. See Section 6784[rtcOccluded1] for a description of how to set up and trace occlusion 6785rays. 6786 6787The intersection context (`context` argument) can specify flags to 6788optimize traversal and a filter callback function to be invoked for 6789every intersection. Further, the pointer to the intersection context is 6790propagated to callback functions invoked during traversal and can thus 6791be used to extend the ray with additional data. See Section 6792`RTCIntersectContext` for more information. 6793 6794The implementation of the stream ray query functions may re-order rays 6795arbitrarily and re-pack rays into ray packets of different size. For 6796this reason, callback functions may be invoked with an arbitrary packet 6797size (of size 1, 4, 8, or 16) and different ordering as specified 6798initially. For this reason, one may have to use the `rayID` component 6799of the ray to identify the original ray, e.g. to access a per-ray 6800payload. 6801 6802A ray in a ray stream is considered inactive if its `tnear` value is 6803larger than its `tfar` value. 6804 6805The stream size `M` can be an arbitrary positive integer including 0. 6806Each ray must be aligned to 16 bytes. 6807 6808#### EXIT STATUS {#exit-status} 6809 6810For performance reasons this function does not do any error checks, 6811thus will not set any error flags on failure. 6812 6813#### SEE ALSO {#see-also} 6814 6815[rtcIntersect1M] 6816 6817 6818 6819rtcIntersect1Mp 6820--------------- 6821 6822#### NAME {#name} 6823 6824 rtcIntersect1Mp - finds the closest hits for a stream of M pointers 6825 to single rays 6826 6827#### SYNOPSIS {#synopsis} 6828 6829 #include <embree3/rtcore.h> 6830 6831 void rtcIntersect1Mp( 6832 RTCScene scene, 6833 struct RTCIntersectContext* context, 6834 struct RTCRayHit** rayhit, 6835 unsigned int M 6836 ); 6837 6838#### DESCRIPTION {#description} 6839 6840The `rtcIntersect1Mp` function finds the closest hits for a stream of 6841`M` single rays (`rayhit` argument) with the scene (`scene` argument). 6842The `rayhit` argument points to an array of pointers to the individual 6843ray/hit structures. See Section [rtcIntersect1] for a description of 6844how to set up and trace a ray. 6845 6846The intersection context (`context` argument) can specify flags to 6847optimize traversal and a filter callback function to be invoked for 6848every intersection. Further, the pointer to the intersection context is 6849propagated to callback functions invoked during traversal and can thus 6850be used to extend the ray with additional data. See Section 6851`RTCIntersectContext` for more information. 6852 6853The implementation of the stream ray query functions may re-order rays 6854arbitrarily and re-pack rays into ray packets of different size. For 6855this reason, callback functions may be invoked with an arbitrary packet 6856size (of size 1, 4, 8, or 16) and different ordering as specified 6857initially. For this reason, one may have to use the `rayID` component 6858of the ray to identify the original ray, e.g. to access a per-ray 6859payload. 6860 6861A ray in a ray stream is considered inactive if its `tnear` value is 6862larger than its `tfar` value. 6863 6864The stream size `M` can be an arbitrary positive integer including 0. 6865Each ray must be aligned to 16 bytes. 6866 6867#### EXIT STATUS {#exit-status} 6868 6869For performance reasons this function does not do any error checks, 6870thus will not set any error flags on failure. 6871 6872#### SEE ALSO {#see-also} 6873 6874[rtcOccluded1Mp] 6875 6876 6877 6878rtcOccluded1Mp 6879-------------- 6880 6881#### NAME {#name} 6882 6883 rtcOccluded1Mp - find any hits for a stream of M pointers to 6884 single rays 6885 6886#### SYNOPSIS {#synopsis} 6887 6888 #include <embree3/rtcore.h> 6889 6890 void rtcOccluded1M( 6891 RTCScene scene, 6892 struct RTCIntersectContext* context, 6893 struct RTCRay** ray, 6894 unsigned int M 6895 ); 6896 6897#### DESCRIPTION {#description} 6898 6899The `rtcOccluded1Mp` function checks whether there are any hits for a 6900stream of `M` single rays (`ray` argument) with the scene (`scene` 6901argument). The `ray` argument points to an array of pointers to rays. 6902Section [rtcOccluded1] for a description of how to set up and trace a 6903occlusion rays. 6904 6905The intersection context (`context` argument) can specify flags to 6906optimize traversal and a filter callback function to be invoked for 6907every intersection. Further, the pointer to the intersection context is 6908propagated to callback functions invoked during traversal and can thus 6909be used to extend the ray with additional data. See Section 6910`RTCIntersectContext` for more information. 6911 6912The implementation of the stream ray query functions may re-order rays 6913arbitrarily and re-pack rays into ray packets of different size. For 6914this reason, callback functions may be invoked with an arbitrary packet 6915size (of size 1, 4, 8, or 16) and different ordering as specified 6916initially. For this reason, one may have to use the `rayID` component 6917of the ray to identify the original ray, e.g. to access a per-ray 6918payload. 6919 6920A ray in a ray stream is considered inactive if its `tnear` value is 6921larger than its `tfar` value. 6922 6923The stream size `M` can be an arbitrary positive integer including 0. 6924Each ray must be aligned to 16 bytes. 6925 6926#### EXIT STATUS {#exit-status} 6927 6928For performance reasons this function does not do any error checks, 6929thus will not set any error flags on failure. 6930 6931#### SEE ALSO {#see-also} 6932 6933[rtcIntersect1Mp] 6934 6935 6936 6937rtcIntersectNM 6938-------------- 6939 6940#### NAME {#name} 6941 6942 rtcIntersectNM - finds the closest hits for a stream of M 6943 ray packets of size N 6944 6945#### SYNOPSIS {#synopsis} 6946 6947 #include <embree3/rtcore.h> 6948 6949 void rtcIntersectNM( 6950 RTCScene scene, 6951 struct RTCIntersectContext* context, 6952 struct RTCRayHitN* rayhit, 6953 unsigned int N, 6954 unsigned int M, 6955 size_t byteStride 6956 ); 6957 6958#### DESCRIPTION {#description} 6959 6960The `rtcIntersectNM` function finds the closest hits for a stream of 6961`M` ray packets (`rayhit` argument) of size `N` with the scene (`scene` 6962argument). The `rays` argument points to an array of ray and hit 6963packets with specified byte stride (`byteStride` argument) between the 6964ray/hit packets. See Section [rtcIntersect1] for a description of how 6965to set up and trace rays. 6966 6967The intersection context (`context` argument) can specify flags to 6968optimize traversal and a filter callback function to be invoked for 6969every intersection. Further, the pointer to the intersection context is 6970propagated to callback functions invoked during traversal and can thus 6971be used to extend the ray with additional data. See Section 6972`RTCIntersectContext` for more information. 6973 6974The implementation of the stream ray query functions may re-order rays 6975arbitrarily and re-pack rays into ray packets of different size. For 6976this reason, callback functions may be invoked with an arbitrary packet 6977size (of size 1, 4, 8, or 16) and different ordering as specified 6978initially. For this reason, one may have to use the `rayID` component 6979of the ray to identify the original ray, e.g. to access a per-ray 6980payload. 6981 6982A ray in a ray stream is considered inactive if its `tnear` value is 6983larger than its `tfar` value. 6984 6985The packet size `N` must be larger than 0, and the stream size `M` can 6986be an arbitrary positive integer including 0. Each ray must be aligned 6987to 16 bytes. 6988 6989#### EXIT STATUS {#exit-status} 6990 6991For performance reasons this function does not do any error checks, 6992thus will not set any error flags on failure. 6993 6994#### SEE ALSO {#see-also} 6995 6996[rtcOccludedNM] 6997 6998 6999 7000rtcOccludedNM 7001------------- 7002 7003#### NAME {#name} 7004 7005 rtcOccludedNM - finds any hits for a stream of M ray packets of 7006 size N 7007 7008#### SYNOPSIS {#synopsis} 7009 7010 #include <embree3/rtcore.h> 7011 7012 void rtcOccludedNM( 7013 RTCScene scene, 7014 struct RTCIntersectContext* context, 7015 struct RTCRayN* ray, 7016 unsigned int N, 7017 unsigned int M, 7018 size_t byteStride 7019 ); 7020 7021#### DESCRIPTION {#description} 7022 7023The `rtcOccludedNM` function checks whether there are any hits for a 7024stream of `M` ray packets (`ray` argument) of size `N` with the scene 7025(`scene` argument). The `ray` argument points to an array of ray 7026packets with specified byte stride (`byteStride` argument) between the 7027ray packets. See Section [rtcOccluded1] for a description of how to 7028set up and trace occlusion rays. 7029 7030The intersection context (`context` argument) can specify flags to 7031optimize traversal and a filter callback function to be invoked for 7032every intersection. Further, the pointer to the intersection context is 7033propagated to callback functions invoked during traversal and can thus 7034be used to extend the ray with additional data. See Section 7035`RTCIntersectContext` for more information. 7036 7037The implementation of the stream ray query functions may re-order rays 7038arbitrarily and re-pack rays into ray packets of different size. For 7039this reason, callback functions may be invoked with an arbitrary packet 7040size (of size 1, 4, 8, or 16) and different ordering as specified 7041initially. For this reason, one may have to use the `rayID` component 7042of the ray to identify the original ray, e.g. to access a per-ray 7043payload. 7044 7045A ray in a ray stream is considered inactive if its `tnear` value is 7046larger than its `tfar` value. 7047 7048The packet size `N` must be larger than 0, and the stream size `M` can 7049be an arbitrary positive integer including 0. Each ray must be aligned 7050to 16 bytes. 7051 7052#### EXIT STATUS {#exit-status} 7053 7054For performance reasons this function does not do any error checks, 7055thus will not set any error flags on failure. 7056 7057#### SEE ALSO {#see-also} 7058 7059[rtcIntersectNM] 7060 7061 7062 7063rtcIntersectNp 7064-------------- 7065 7066#### NAME {#name} 7067 7068 rtcIntersectNp - finds the closest hits for a SOA ray stream of 7069 size N 7070 7071#### SYNOPSIS {#synopsis} 7072 7073 #include <embree3/rtcore.h> 7074 7075 void rtcIntersectNp( 7076 RTCScene scene, 7077 struct RTCIntersectContext* context, 7078 struct RTCRayHitNp* rayhit, 7079 unsigned int N 7080 ); 7081 7082#### DESCRIPTION {#description} 7083 7084The `rtcIntersectNp` function finds the closest hits for a SOA ray 7085stream (`rays` argument) of size `N` (basically a large ray packet) 7086with the scene (`scene` argument). The `rayhit` argument points to two 7087structures of pointers with one pointer for each ray and hit component. 7088Each of these pointers points to an array with the ray or hit component 7089data for each ray or hit. This way the individual components of the SOA 7090ray stream do not need to be stored sequentially in memory, which makes 7091it possible to have large varying size ray packets in SOA layout. See 7092Section [rtcIntersect1] for a description of how to set up and trace 7093rays. 7094 7095The intersection context (`context` argument) can specify flags to 7096optimize traversal and a filter callback function to be invoked for 7097every intersection. Further, the pointer to the intersection context is 7098propagated to callback functions invoked during traversal and can thus 7099be used to extend the ray with additional data. See Section 7100`RTCIntersectContext` for more information. 7101 7102The implementation of the stream ray query functions may re-order rays 7103arbitrarily and re-pack rays into ray packets of different size. For 7104this reason, callback functions may be invoked with an arbitrary packet 7105size (of size 1, 4, 8, or 16) and different ordering as specified 7106initially. For this reason, one may have to use the `rayID` component 7107of the ray to identify the original ray, e.g. to access a per-ray 7108payload. 7109 7110A ray in a ray stream is considered inactive if its `tnear` value is 7111larger than its `tfar` value. 7112 7113The stream size `N` can be an arbitrary positive integer including 0. 7114Each ray component array must be aligned to 16 bytes. 7115 7116#### EXIT STATUS {#exit-status} 7117 7118For performance reasons this function does not do any error checks, 7119thus will not set any error flags on failure. 7120 7121#### SEE ALSO {#see-also} 7122 7123[rtcOccludedNp] 7124 7125 7126 7127rtcOccludedNp 7128------------- 7129 7130#### NAME {#name} 7131 7132 rtcOccludedNp - finds any hits for a SOA ray stream of size N 7133 7134#### SYNOPSIS {#synopsis} 7135 7136 #include <embree3/rtcore.h> 7137 7138 void rtcOccludedNp( 7139 RTCScene scene, 7140 struct RTCIntersectContext* context, 7141 struct RTCRayNp* ray, 7142 unsigned int N 7143 ); 7144 7145#### DESCRIPTION {#description} 7146 7147The `rtcOccludedNp` function checks whether there are any hits for a 7148SOA ray stream (`ray` argument) of size `N` (basically a large ray 7149packet) with the scene (`scene` argument). The `ray` argument points to 7150a structure of pointers with one pointer for each ray component. Each 7151of these pointers points to an array with the ray component data for 7152each ray. This way the individual components of the SOA ray stream do 7153not need to be stored sequentially in memory, which makes it possible 7154to have large varying size ray packets in SOA layout. See Section 7155[rtcOccluded1] for a description of how to set up and trace occlusion 7156rays. 7157 7158The intersection context (`context` argument) can specify flags to 7159optimize traversal and a filter callback function to be invoked for 7160every intersection. Further, the pointer to the intersection context is 7161propagated to callback functions invoked during traversal and can thus 7162be used to extend the ray with additional data. See Section 7163`RTCIntersectContext` for more information. 7164 7165The implementation of the stream ray query functions may re-order rays 7166arbitrarily and re-pack rays into ray packets of different size. For 7167this reason, callback functions may be invoked with an arbitrary packet 7168size (of size 1, 4, 8, or 16) and different ordering as specified 7169initially. For this reason, one may have to use the `rayID` component 7170of the ray to identify the original ray, e.g. to access a per-ray 7171payload. 7172 7173A ray in a ray stream is considered inactive if its `tnear` value is 7174larger than its `tfar` value. 7175 7176The stream size `N` can be an arbitrary positive integer including 0. 7177Each ray component array must be aligned to 16 bytes. 7178 7179#### EXIT STATUS {#exit-status} 7180 7181For performance reasons this function does not do any error checks, 7182thus will not set any error flags on failure. 7183 7184#### SEE ALSO {#see-also} 7185 7186[rtcIntersectNp] 7187 7188 7189 7190rtcInitPointQueryContext 7191------------------------ 7192 7193#### NAME {#name} 7194 7195 rtcInitPointQueryContext - initializes the context information (e.g. 7196 stack of (multilevel-)instance transformations) for point queries 7197 7198#### SYNOPSIS {#synopsis} 7199 7200 #include <embree3/rtcore.h> 7201 7202 struct RTC_ALIGN(16) RTCPointQueryContext 7203 { 7204 // accumulated 4x4 column major matrices from world to instance space. 7205 float world2inst[RTC_MAX_INSTANCE_LEVEL_COUNT][16]; 7206 7207 // accumulated 4x4 column major matrices from instance to world space. 7208 float inst2world[RTC_MAX_INSTANCE_LEVEL_COUNT][16]; 7209 7210 // instance ids. 7211 unsigned int instID[RTC_MAX_INSTANCE_LEVEL_COUNT]; 7212 7213 // number of instances currently on the stack. 7214 unsigned int instStackSize; 7215 }; 7216 7217 void rtcInitPointQueryContext( 7218 struct RTCPointQueryContext* context 7219 ); 7220 7221#### DESCRIPTION {#description} 7222 7223A stack (`RTCPointQueryContext` type) which stores the IDs and instance 7224transformations during a BVH traversal for a point query. The 7225transformations are assumed to be affine transformations (3×3 matrix 7226plus translation) and therefore the last column is ignored (see 7227[RTC\_GEOMETRY\_TYPE\_INSTANCE] for details). 7228 7229The `rtcInitPointContext` function initializes the context to default 7230values and should be called for initialization. 7231 7232The context will be passed as an argument to the point query callback 7233function (see [rtcSetGeometryPointQueryFunction]) and should be used 7234to pass instance information down the instancing chain for user defined 7235instancing (see tutorial [ClosestPoint] for a reference 7236implementation of point queries with user defined instancing). 7237 7238The context is an necessary argument to [rtcPointQuery] and Embree 7239internally uses the topmost instance tranformation of the stack to 7240transform the point query into instance space. 7241 7242#### EXIT STATUS {#exit-status} 7243 7244No error code is set by this function. 7245 7246#### SEE ALSO {#see-also} 7247 7248[rtcPointQuery], [rtcSetGeometryPointQueryFunction] 7249 7250 7251 7252rtcPointQuery 7253------------- 7254 7255#### NAME {#name} 7256 7257 rtcPointQuery - traverses the BVH with a point query object 7258 7259#### SYNOPSIS {#synopsis} 7260 7261 #include <embree3/rtcore.h> 7262 7263 struct RTC_ALIGN(16) RTCPointQuery 7264 { 7265 // location of the query 7266 float x; 7267 float y; 7268 float z; 7269 7270 // radius and time of the query 7271 float radius; 7272 float time; 7273 }; 7274 7275 void rtcPointQuery( 7276 RTCScene scene, 7277 struct RTCPointQuery* query, 7278 struct RTCPointQueryContext* context, 7279 struct RTCPointQueryFunction* queryFunc, 7280 void* userPtr 7281 ); 7282 7283#### DESCRIPTION {#description} 7284 7285The `rtcPointQuery` function traverses the BVH using a `RTCPointQuery` 7286object (`query` argument) and calls a user defined callback function 7287(e.g `queryFunc` argument) for each primitive of the scene (`scene` 7288argument) that intersects the query domain. 7289 7290The user has to initialize the query location (`x`, `y` and `z` member) 7291and query radius in the range $[0, \infty]$. If the scene contains 7292motion blur geometries, also the query time (`time` member) must be 7293initialized to a value in the range $[0, 1]$. 7294 7295Further, a `RTCPointQueryContext` (`context` argument) must be created 7296and initialized. It contains ID and transformation information of the 7297instancing hierarchy if (multilevel-)instancing is used. See 7298[rtcInitPointQueryContext] for further information. 7299 7300For every primitive that intersects the query domain, the callback 7301function (`queryFunc` argument) is called, in which distance 7302computations to the primitive can be implemented. The user will be 7303provided with the primID and geomID of the according primitive, 7304however, the geometry information (e.g. triangle index and vertex data) 7305has to be determined manually. The `userPtr` argument can be used to 7306input geometry data of the scene or output results of the point query 7307(e.g. closest point currently found on surface geometry (see tutorial 7308[ClosestPoint])). 7309 7310The parameter `queryFunc` is optional and can be NULL, in which case 7311the callback function is not invoked. However, a callback function can 7312still get attached to a specific `RTCGeometry` object using 7313[rtcSetGeometryPointQueryFunction]. If a callback function is 7314attached to a geometry and (a potentially different) callback function 7315is passed as an argument to `rtcPointQuery`, both functions are called 7316for the primitives of the according geometries. 7317 7318The query radius can be decreased inside the callback function, which 7319allows to efficiently cull parts of the scene during BVH traversal. 7320Increasing the query radius and modifying time or location of the query 7321will result in undefined behaviour. 7322 7323The callback function will be called for all primitives in a leaf node 7324of the BVH even if the primitive is outside the query domain, since 7325Embree does not gather geometry information of primitives internally. 7326 7327Point queries can be used with (multilevel)-instancing. However, care 7328has to be taken when the instance transformation contains anisotropic 7329scaling or sheering. In these cases distance computations have to be 7330performed in world space to ensure correctness and the ellipsoidal 7331query domain (in instance space) will be approximated with its axis 7332aligned bounding box interally. Therefore, the callback function might 7333be invoked even for primitives in inner BVH nodes that do not intersect 7334the query domain. See [rtcSetGeometryPointQueryFunction] for details. 7335 7336The point query structure must be aligned to 16 bytes. 7337 7338#### SUPPORTED PRIMITIVES 7339 7340Currenly, all primitive types are supported by the point query API 7341except of points (see [RTC\_GEOMETRY\_TYPE\_POINT]), curves (see 7342[RTC\_GEOMETRY\_TYPE\_CURVE]) and sudivision surfaces (see 7343[RTC\_GEOMETRY\_SUBDIVISION]). 7344 7345#### EXIT STATUS {#exit-status} 7346 7347For performance reasons this function does not do any error checks, 7348thus will not set any error flags on failure. 7349 7350#### SEE ALSO {#see-also} 7351 7352[rtcSetGeometryPointQueryFunction], [rtcInitPointQueryContext] 7353 7354 7355 7356rtcCollide 7357---------- 7358 7359#### NAME {#name} 7360 7361 rtcCollide - intersects one BVH with another 7362 7363#### SYNOPSIS {#synopsis} 7364 7365 #include <embree3/rtcore.h> 7366 7367 struct RTCCollision { 7368 unsigned int geomID0, primID0; 7369 unsigned int geomID1, primID1; 7370 }; 7371 7372 typedef void (*RTCCollideFunc) ( 7373 void* userPtr, 7374 RTCCollision* collisions, 7375 size_t num_collisions); 7376 7377 void rtcCollide ( 7378 RTCScene hscene0, 7379 RTCScene hscene1, 7380 RTCCollideFunc callback, 7381 void* userPtr 7382 ); 7383 7384#### DESCRIPTION {#description} 7385 7386The `rtcCollide` function intersects the BVH of `hscene0` with the BVH 7387of scene `hscene1` and calls a user defined callback function (e.g 7388`callback` argument) for each pair of intersecting primitives between 7389the two scenes. A user defined data pointer (`userPtr` argument) can 7390also be passed in. 7391 7392For every pair of primitives that may intersect each other, the 7393callback function (`callback` argument) is called. The user will be 7394provided with the primID's and geomID's of multiple potentially 7395intersecting primitive pairs. Currently, only scene entirely composed 7396of user geometries are supported, thus the user is expected to 7397implement a primitive/primitive intersection to filter out false 7398positives in the callback function. The `userPtr` argument can be used 7399to input geometry data of the scene or output results of the 7400intersection query. 7401 7402#### SUPPORTED PRIMITIVES {#supported-primitives} 7403 7404Currently, the only supported type is the user geometry type (see 7405[RTC\_GEOMETRY\_TYPE\_USER]). 7406 7407#### EXIT STATUS {#exit-status} 7408 7409On failure an error code is set that can be queried using 7410`rtcGetDeviceError`. 7411 7412#### SEE ALSO {#see-also} 7413 7414 7415 7416rtcNewBVH 7417--------- 7418 7419#### NAME {#name} 7420 7421 rtcNewBVH - creates a new BVH object 7422 7423#### SYNOPSIS {#synopsis} 7424 7425 #include <embree3/rtcore.h> 7426 7427 RTCBVH rtcNewBVH(RTCDevice device); 7428 7429#### DESCRIPTION {#description} 7430 7431This function creates a new BVH object and returns a handle to this 7432BVH. The BVH object is reference counted with an initial reference 7433count of 1. The handle can be released using the `rtcReleaseBVH` API 7434call. 7435 7436The BVH object can be used to build a BVH in a user-specified format 7437over user-specified primitives. See the documentation of the 7438`rtcBuildBVH` call for more details. 7439 7440#### EXIT STATUS {#exit-status} 7441 7442On failure an error code is set that can be queried using 7443`rtcGetDeviceError`. 7444 7445#### SEE ALSO {#see-also} 7446 7447[rtcRetainBVH], [rtcReleaseBVH], [rtcBuildBVH] 7448 7449 7450 7451rtcRetainBVH 7452------------ 7453 7454#### NAME {#name} 7455 7456 rtcRetainBVH - increments the BVH reference count 7457 7458#### SYNOPSIS {#synopsis} 7459 7460 #include <embree3/rtcore.h> 7461 7462 void rtcRetainBVH(RTCBVH bvh); 7463 7464#### DESCRIPTION {#description} 7465 7466BVH objects are reference counted. The `rtcRetainBVH` function 7467increments the reference count of the passed BVH object (`bvh` 7468argument). This function together with `rtcReleaseBVH` allows to use 7469the internal reference counting in a C++ wrapper class to handle the 7470ownership of the object. 7471 7472#### EXIT STATUS {#exit-status} 7473 7474On failure an error code is set that can be queried using 7475`rtcGetDeviceError`. 7476 7477#### SEE ALSO {#see-also} 7478 7479[rtcNewBVH], [rtcReleaseBVH] 7480 7481 7482 7483rtcReleaseBVH 7484------------- 7485 7486#### NAME {#name} 7487 7488 rtcReleaseBVH - decrements the BVH reference count 7489 7490#### SYNOPSIS {#synopsis} 7491 7492 #include <embree3/rtcore.h> 7493 7494 void rtcReleaseBVH(RTCBVH bvh); 7495 7496#### DESCRIPTION {#description} 7497 7498BVH objects are reference counted. The `rtcReleaseBVH` function 7499decrements the reference count of the passed BVH object (`bvh` 7500argument). When the reference count falls to 0, the BVH gets destroyed. 7501 7502#### EXIT STATUS {#exit-status} 7503 7504On failure an error code is set that can be queried using 7505`rtcGetDeviceError`. 7506 7507#### SEE ALSO {#see-also} 7508 7509[rtcNewBVH], [rtcRetainBVH] 7510 7511 7512 7513rtcBuildBVH 7514----------- 7515 7516#### NAME {#name} 7517 7518 rtcBuildBVH - builds a BVH 7519 7520#### SYNOPSIS {#synopsis} 7521 7522 #include <embree3/rtcore.h> 7523 7524 struct RTC_ALIGN(32) RTCBuildPrimitive 7525 { 7526 float lower_x, lower_y, lower_z; 7527 unsigned int geomID; 7528 float upper_x, upper_y, upper_z; 7529 unsigned int primID; 7530 }; 7531 7532 typedef void* (*RTCCreateNodeFunction) ( 7533 RTCThreadLocalAllocator allocator, 7534 unsigned int childCount, 7535 void* userPtr 7536 ); 7537 7538 typedef void (*RTCSetNodeChildrenFunction) ( 7539 void* nodePtr, 7540 void** children, 7541 unsigned int childCount, 7542 void* userPtr 7543 ); 7544 7545 typedef void (*RTCSetNodeBoundsFunction) ( 7546 void* nodePtr, 7547 const struct RTCBounds** bounds, 7548 unsigned int childCount, 7549 void* userPtr 7550 ); 7551 7552 typedef void* (*RTCCreateLeafFunction) ( 7553 RTCThreadLocalAllocator allocator, 7554 const struct RTCBuildPrimitive* primitives, 7555 size_t primitiveCount, 7556 void* userPtr 7557 ); 7558 7559 typedef void (*RTCSplitPrimitiveFunction) ( 7560 const struct RTCBuildPrimitive* primitive, 7561 unsigned int dimension, 7562 float position, 7563 struct RTCBounds* leftBounds, 7564 struct RTCBounds* rightBounds, 7565 void* userPtr 7566 ); 7567 7568 typedef bool (*RTCProgressMonitorFunction)( 7569 void* userPtr, double n 7570 ); 7571 7572 enum RTCBuildFlags 7573 { 7574 RTC_BUILD_FLAG_NONE, 7575 RTC_BUILD_FLAG_DYNAMIC 7576 }; 7577 7578 struct RTCBuildArguments 7579 { 7580 size_t byteSize; 7581 7582 enum RTCBuildQuality buildQuality; 7583 enum RTCBuildFlags buildFlags; 7584 unsigned int maxBranchingFactor; 7585 unsigned int maxDepth; 7586 unsigned int sahBlockSize; 7587 unsigned int minLeafSize; 7588 unsigned int maxLeafSize; 7589 float traversalCost; 7590 float intersectionCost; 7591 7592 RTCBVH bvh; 7593 struct RTCBuildPrimitive* primitives; 7594 size_t primitiveCount; 7595 size_t primitiveArrayCapacity; 7596 7597 RTCCreateNodeFunction createNode; 7598 RTCSetNodeChildrenFunction setNodeChildren; 7599 RTCSetNodeBoundsFunction setNodeBounds; 7600 RTCCreateLeafFunction createLeaf; 7601 RTCSplitPrimitiveFunction splitPrimitive; 7602 RTCProgressMonitorFunction buildProgress; 7603 void* userPtr; 7604 }; 7605 7606 struct RTCBuildArguments rtcDefaultBuildArguments(); 7607 7608 void* rtcBuildBVH( 7609 const struct RTCBuildArguments* args 7610 ); 7611 7612#### DESCRIPTION {#description} 7613 7614The `rtcBuildBVH` function can be used to build a BVH in a user-defined 7615format over arbitrary primitives. All arguments to the function are 7616provided through the `RTCBuildArguments` structure. The first member of 7617that structure must be set to the size of the structure in bytes 7618(`bytesSize` member) which allows future extensions of the structure. 7619It is recommended to initialize the build arguments structure using the 7620`rtcDefaultBuildArguments` function. 7621 7622The `rtcBuildBVH` function gets passed the BVH to build (`bvh` member), 7623the array of primitives (`primitives` member), the capacity of that 7624array (`primitiveArrayCapacity` member), the number of primitives 7625stored inside the array (`primitiveCount` member), callback function 7626pointers, and a user-defined pointer (`userPtr` member) that is passed 7627to all callback functions when invoked. The `primitives` array can be 7628freed by the application after the BVH is built. All callback functions 7629are typically called from multiple threads, thus their implementation 7630must be thread-safe. 7631 7632Four callback functions must be registered, which are invoked during 7633build to create BVH nodes (`createNode` member), to set the pointers to 7634all children (`setNodeChildren` member), to set the bounding boxes of 7635all children (`setNodeBounds` member), and to create a leaf node 7636(`createLeaf` member). 7637 7638The function pointer to the primitive split function (`splitPrimitive` 7639member) may be `NULL`, however, then no spatial splitting in high 7640quality mode is possible. The function pointer used to report the build 7641progress (`buildProgress` member) is optional and may also be `NULL`. 7642 7643Further, some build settings are passed to configure the BVH build. 7644Using the build quality settings (`buildQuality` member), one can 7645select between a faster, low quality build which is good for dynamic 7646scenes, and a standard quality build for static scenes. One can also 7647specify the desired maximum branching factor of the BVH 7648(`maxBranchingFactor` member), the maximum depth the BVH should have 7649(`maxDepth` member), the block size for the SAH heuristic 7650(`sahBlockSize` member), the minimum and maximum leaf size 7651(`minLeafSize` and `maxLeafSize` member), and the estimated costs of 7652one traversal step and one primitive intersection (`traversalCost` and 7653`intersectionCost` members). When enabling the `RTC_BUILD_FLAG_DYNAMIC` 7654build flags (`buildFlags` member), re-build performance for dynamic 7655scenes is improved at the cost of higher memory requirements. 7656 7657To spatially split primitives in high quality mode, the builder needs 7658extra space at the end of the build primitive array to store splitted 7659primitives. The total capacity of the build primitive array is passed 7660using the `primitiveArrayCapacity` member, and should be about twice 7661the number of primitives when using spatial splits. 7662 7663The `RTCCreateNodeFunc` and `RTCCreateLeafFunc` callbacks are passed a 7664thread local allocator object that should be used for fast allocation 7665of nodes using the `rtcThreadLocalAlloc` function. We strongly 7666recommend using this allocation mechanism, as alternative approaches 7667like standard `malloc` can be over 10× slower. The allocator object 7668passed to the create callbacks may be used only inside the current 7669thread. Memory allocated using `rtcThreadLocalAlloc` is automatically 7670freed when the `RTCBVH` object is deleted. If you use your own memory 7671allocation scheme you have to free the memory yourself when the 7672`RTCBVH` object is no longer used. 7673 7674The `RTCCreateNodeFunc` callback additionally gets the number of 7675children for this node in the range from 2 to `maxBranchingFactor` 7676(`childCount` argument). 7677 7678The `RTCSetNodeChildFunc` callback function gets a pointer to the node 7679as input (`nodePtr` argument), an array of pointers to the children 7680(`childPtrs` argument), and the size of this array (`childCount` 7681argument). 7682 7683The `RTCSetNodeBoundsFunc` callback function gets a pointer to the node 7684as input (`nodePtr` argument), an array of pointers to the bounding 7685boxes of the children (`bounds` argument), and the size of this array 7686(`childCount` argument). 7687 7688The `RTCCreateLeafFunc` callback additionally gets an array of 7689primitives as input (`primitives` argument), and the size of this array 7690(`primitiveCount` argument). The callback should read the `geomID` and 7691`primID` members from the passed primitives to construct the leaf. 7692 7693The `RTCSplitPrimitiveFunc` callback is invoked in high quality mode to 7694split a primitive (`primitive` argument) at the specified position 7695(`position` argument) and dimension (`dimension` argument). The 7696callback should return bounds of the clipped left and right parts of 7697the primitive (`leftBounds` and `rightBounds` arguments). 7698 7699The `RTCProgressMonitorFunction` callback function is called with the 7700estimated completion rate `n` in the range $[0,1]$. Returning `true` 7701from the callback lets the build continue; returning `false` cancels 7702the build. 7703 7704#### EXIT STATUS {#exit-status} 7705 7706On failure an error code is set that can be queried using 7707`rtcGetDeviceError`. 7708 7709#### SEE ALSO {#see-also} 7710 7711[rtcNewBVH] 7712 7713 7714 7715RTCQuaternionDecomposition 7716-------------------------- 7717 7718#### NAME {#name} 7719 7720 RTCQuaternionDecomposition - structure that represents a quaternion 7721 decomposition of an affine transformation 7722 7723#### SYNOPSIS {#synopsis} 7724 7725 struct RTCQuaternionDecomposition 7726 { 7727 float scale_x, scale_y, scale_z; 7728 float skew_xy, skew_xz, skew_yz; 7729 float shift_x, shift_y, shift_z; 7730 float quaternion_r, quaternion_i, quaternion_j, quaternion_k; 7731 float translation_x, translation_y, translation_z; 7732 }; 7733 7734#### DESCRIPTION {#description} 7735 7736The struct `RTCQuaternionDecomposition` represents an affine 7737transformation decomposed into three parts. An upper triangular 7738scaling/skew/shift matrix 7739 7740$$ 7741S = \left( \begin{array}{cccc} 7742scale_x & skew_{xy} & skew_{xz} & shift_x \ 77430 & scale_y & skew_{yz} & shift_y \ 77440 & 0 & scale_z & shift_z \ 77450 & 0 & 0 & 1 \ 7746\end{array} \right), 7747$$ 7748 7749a translation matrix 7750 7751$$ 7752T = \left( \begin{array}{cccc} 77531 & 0 & 0 & translation_x \ 77540 & 1 & 0 & translation_y \ 77550 & 0 & 1 & translation_z \ 77560 & 0 & 0 & 1 \ 7757\end{array} \right), 7758$$ 7759 7760and a rotation matrix $R$, represented as a quaternion 7761 7762$quaternion_r + quaternion_i \mathbf{i} + quaternion_j \mathbf{i} + quaternion_k \mathbf{k}$ 7763 7764where $\mathbf{i}$, $\mathbf{j}$ $\mathbf{k}$ are the imaginary 7765quaternion units. The passed quaternion will be normalized internally. 7766 7767The affine transformation matrix corresponding to a 7768`RTCQuaternionDecomposition` is $TRS$ and a point 7769$p = (p_x, p_y, p_z, 1)^T$ will be transformed as 7770$$p' = T R S p.$$ 7771 7772The functions `rtcInitQuaternionDecomposition`, 7773`rtcQuaternionDecompositionSetQuaternion`, 7774`rtcQuaternionDecompositionSetScale`, 7775`rtcQuaternionDecompositionSetSkew`, 7776`rtcQuaternionDecompositionSetShift`, and 7777`rtcQuaternionDecompositionSetTranslation` allow to set the fields of 7778the structure more conveniently. 7779 7780#### EXIT STATUS {#exit-status} 7781 7782No error code is set by this function. 7783 7784#### SEE ALSO {#see-also} 7785 7786[rtcSetGeometryTransformQuaternion], 7787[rtcInitQuaternionDecomposition] 7788 7789 7790 7791rtcInitQuaternionDecomposition 7792------------------------------ 7793 7794#### NAME {#name} 7795 7796 rtcInitQuaternionDecomposition - initializes quaternion decomposition 7797 7798#### SYNOPSIS {#synopsis} 7799 7800 void rtcInitQuaternionDecomposition( 7801 struct RTCQuaternionDecomposition* qd 7802 ); 7803 7804#### DESCRIPTION {#description} 7805 7806The `rtcInitQuaternionDecomposition` function initializes a 7807`RTCQuaternionDecomposition` structure to represent an identity 7808transformation. 7809 7810#### EXIT STATUS {#exit-status} 7811 7812No error code is set by this function. 7813 7814#### SEE ALSO {#see-also} 7815 7816[rtcSetGeometryTransformQuaternion], [RTCQuaternionDecomposition] 7817 7818 7819 7820Performance Recommendations 7821=========================== 7822 7823MXCSR control and status register 7824--------------------------------- 7825 7826It is strongly recommended to have the `Flush to Zero` and 7827`Denormals are Zero` mode of the MXCSR control and status register 7828enabled for each thread before calling the `rtcIntersect`-type and 7829`rtcOccluded`-type functions. Otherwise, under some circumstances 7830special handling of denormalized floating point numbers can 7831significantly reduce application and Embree performance. When using 7832Embree together with the Intel® Threading Building Blocks, it is 7833sufficient to execute the following code at the beginning of the 7834application main thread (before the creation of the 7835`tbb::task_scheduler_init` object): 7836 7837 #include <xmmintrin.h> 7838 #include <pmmintrin.h> 7839 ... 7840 _MM_SET_FLUSH_ZERO_MODE(_MM_FLUSH_ZERO_ON); 7841 _MM_SET_DENORMALS_ZERO_MODE(_MM_DENORMALS_ZERO_ON); 7842 7843If using a different tasking system, make sure each rendering thread 7844has the proper mode set. 7845 7846Thread Creation and Affinity Settings 7847------------------------------------- 7848 7849Tasking systems like TBB create worker threads on demand, which will 7850add a runtime overhead for the very first `rtcCommitScene` call. In 7851case you want to benchmark the scene build time, you should start the 7852threads at application startup. You can let Embree start TBB threads by 7853passing `start_threads=1` to the `cfg` parameter of `rtcNewDevice`. 7854 7855On machines with a high thread count (e.g. dual-socket Xeon or Xeon Phi 7856machines), affinitizing TBB worker threads increases build and 7857rendering performance. You can let Embree affinitize TBB worker threads 7858by passing `set_affinity=1` to the `cfg` parameter of `rtcNewDevice`. 7859By default, threads are not affinitized by Embree with the exception of 7860Xeon Phi Processors where they are affinitized by default. 7861 7862All Embree tutorials automatically start and affinitize TBB worker 7863threads by passing `start_threads=1,set_affinity=1` to `rtcNewDevice`. 7864 7865Fast Coherent Rays 7866------------------ 7867 7868For getting the highest performance for highly coherent rays, e.g. 7869primary or hard shadow rays, it is recommended to use packets or 7870streams of single rays/packets with setting the 7871`RTC_INTERSECT_CONTEXT_FLAG_COHERENT` flag in the `RTCIntersectContext` 7872passed to the `rtcIntersect`/`rtcOccluded` calls. The total number of 7873rays in a coherent stream of ray packets should be around 64, e.g. 8 7874times 8-wide packets, or 4 times 16-wide packets. The rays inside each 7875packet should be grouped as coherent as possible. 7876 7877Huge Page Support 7878----------------- 7879 7880It is recommended to use huge pages under Linux to increase rendering 7881performance. Embree supports 2MB huge pages under Windows, Linux, and 7882macOS. Under Linux huge page support is enabled by default, and under 7883Windows and macOS disabled by default. Huge page support can be enabled 7884in Embree by passing `hugepages=1` to `rtcNewDevice` or disabled by 7885passing `hugepages=0` to `rtcNewDevice`. 7886 7887We recommend using 2MB huge pages with Embree under Linux as this 7888improves ray tracing performance by about 5-10%. Under Windows using 7889huge pages requires the application to run in elevated mode which is a 7890security issue, thus likely not an option for most use cases. Under 7891macOS huge pages are rarely available as memory tends to get quickly 7892fragmented, thus we do not recommend using huge pages on macOS. 7893 7894### Huge Pages under Linux 7895 7896Linux supports transparent huge pages and explicit huge pages. To 7897enable transparent huge page support under Linux, execute the following 7898as root: 7899 7900 echo always > /sys/kernel/mm/transparent_hugepage/enabled 7901 7902When transparent huge pages are enabled, the kernel tries to merge 4KB 7903pages to 2MB pages when possible as a background job. Many Linux 7904distributions have transparent huge pages enabled by default. See the 7905following webpage for more information on [transparent huge pages under 7906Linux](https://www.kernel.org/doc/Documentation/vm/transhuge.txt). In 7907this mode each application, including your rendering application based 7908on Embree, will automatically tend to use huge pages. 7909 7910Using transparent huge pages, the transitioning from 4KB to 2MB pages 7911might take some time. For that reason Embree also supports allocating 79122MB pages directly when a huge page pool is configured. Such a pool can 7913be configured by writing some number of huge pages to allocate to 7914`/proc/sys/vm/nr_overcommit_hugepages` as root user. E.g. to configure 79152GB of address space for huge page allocation, execute the following as 7916root: 7917 7918 echo 1000 > /proc/sys/vm/nr_overcommit_hugepages 7919 7920See the following webpage for more information on [huge pages under 7921Linux](https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt). 7922 7923### Huge Pages under Windows 7924 7925To use huge pages under Windows, the current user must have the "Lock 7926pages in memory" (SeLockMemoryPrivilege) assigned. This can be 7927configured through the "Local Security Policy" application, by adding a 7928user to "Local Policies" -\> "User Rights Assignment" -\> "Lock pages 7929in memory". You have to log out and in again for this change to take 7930effect. 7931 7932Further, your application must be executed as an elevated process ("Run 7933as administrator") and the "SeLockMemoryPrivilege" must be explicitly 7934enabled by your application. Example code on how to enable this 7935privilege can be found in the "common/sys/alloc.cpp" file of Embree. 7936Alternatively, Embree will try to enable this privilege when passing 7937`enable_selockmemoryprivilege=1` to `rtcNewDevice`. Further, huge pages 7938should be enabled in Embree by passing `hugepages=1` to `rtcNewDevice`. 7939 7940When the system has been running for a while, physical memory gets 7941fragmented, which can slow down the allocation of huge pages 7942significantly under Windows. 7943 7944### Huge Pages under macOS 7945 7946To use huge pages under macOS you have to pass `hugepages=1` to 7947`rtcNewDevice` to enable that feature in Embree. 7948 7949When the system has been running for a while, physical memory gets 7950quickly fragmented, and causes huge page allocations to fail. For this 7951reason, huge pages are not very useful under macOS in practice. 7952 7953Avoid store-to-load forwarding issues with single rays 7954------------------------------------------------------ 7955 7956We recommend to use a single SSE store to set up the `org` and `tnear` 7957components, and a single SSE store to set up the `dir` and `time` 7958components of a single ray (`RTCRay` type). Storing these values using 7959scalar stores causes a store-to-load forwarding penalty because Embree 7960is reading these components using SSE loads later on. 7961 7962 7963 7964Embree Tutorials 7965================ 7966 7967Embree comes with a set of tutorials aimed at helping users understand 7968how Embree can be used and extended. There is a very basic minimal 7969that can be compiled as both C and C++, which should get new users started quickly. 7970All other tutorials exist in an ISPC and C++ version to demonstrate 7971the two versions of the API. Look for files 7972named `tutorialname_device.ispc` for the ISPC implementation of the 7973tutorial, and files named `tutorialname_device.cpp` for the single ray C++ 7974version of the tutorial. To start the C++ version use the `tutorialname` 7975executables, to start the ISPC version use the `tutorialname_ispc` 7976executables. All tutorials can print available command line options 7977using the `--help` command line parameter. 7978 7979For all tutorials except minimal, you can select an initial camera using 7980the `--vp` (camera position), `--vi` (camera look-at point), `--vu` 7981(camera up vector), and `--fov` (vertical field of view) command line 7982parameters: 7983 7984 ./triangle_geometry --vp 10 10 10 --vi 0 0 0 7985 7986You can select the initial window size using the `--size` command line 7987parameter, or start the tutorials in full screen using the `--fullscreen` 7988parameter: 7989 7990 ./triangle_geometry --size 1024 1024 7991 ./triangle_geometry --fullscreen 7992 7993The initialization string for the Embree device (`rtcNewDevice` call) 7994can be passed to the ray tracing core through the `--rtcore` command 7995line parameter, e.g.: 7996 7997 ./triangle_geometry --rtcore verbose=2,threads=1 7998 7999The navigation in the interactive display mode follows the camera orbit 8000model, where the camera revolves around the current center of interest. 8001With the left mouse button you can rotate around the center of interest 8002(the point initially set with `--vi`). Holding Control pressed while 8003clicking the left mouse button rotates the camera around its location. 8004You can also use the arrow keys for navigation. 8005 8006You can use the following keys: 8007 8008F1 8009: Default shading 8010 8011F2 8012: Gray EyeLight shading 8013 8014F3 8015: Traces occlusion rays only. 8016 8017F4 8018: UV Coordinate visualization 8019 8020F5 8021: Geometry normal visualization 8022 8023F6 8024: Geometry ID visualization 8025 8026F7 8027: Geometry ID and Primitive ID visualization 8028 8029F8 8030: Simple shading with 16 rays per pixel for benchmarking. 8031 8032F9 8033: Switches to render cost visualization. Pressing again reduces 8034 brightness. 8035 8036F10 8037: Switches to render cost visualization. Pressing again increases 8038 brightness. 8039 8040f 8041: Enters or leaves full screen mode. 8042 8043c 8044: Prints camera parameters. 8045 8046ESC 8047: Exits the tutorial. 8048 8049q 8050: Exits the tutorial. 8051 8052Minimal 8053------- 8054 8055This tutorial is designed to get new users started with Embree. 8056It can be compiled as both C and C++. It demonstrates how to initialize 8057a device and scene, and how to intersect rays with the scene. 8058There is no image output to keep the tutorial as simple as possible. 8059 8060[Source Code](https://github.com/embree/embree/blob/master/tutorials/minimal/minimal.cpp) 8061 8062Triangle Geometry 8063----------------- 8064 8065[![][imgTriangleGeometry]](https://github.com/embree/embree/blob/master/tutorials/triangle_geometry/triangle_geometry_device.cpp) 8066 8067This tutorial demonstrates the creation of a static cube and ground 8068plane using triangle meshes. It also demonstrates the use of the 8069`rtcIntersect1` and `rtcOccluded1` functions to render primary visibility 8070and hard shadows. The cube sides are colored based on the ID of the hit 8071primitive. 8072 8073[Source Code](https://github.com/embree/embree/blob/master/tutorials/triangle_geometry/triangle_geometry_device.cpp) 8074 8075Dynamic Scene 8076------------- 8077 8078[![][imgDynamicScene]](https://github.com/embree/embree/blob/master/tutorials/dynamic_scene/dynamic_scene_device.cpp) 8079 8080This tutorial demonstrates the creation of a dynamic scene, consisting 8081of several deforming spheres. Half of the spheres use the 8082`RTC_BUILD_QUALITY_REFIT` geometry build quality, which allows Embree 8083to use a refitting strategy for these spheres, the other half uses the 8084`RTC_BUILD_QUALITY_LOW` geometry build quality, causing a high 8085performance rebuild of their spatial data structure each frame. The 8086spheres are colored based on the ID of the hit sphere geometry. 8087 8088[Source Code](https://github.com/embree/embree/blob/master/tutorials/dynamic_scene/dynamic_scene_device.cpp) 8089 8090Multi Scene Geometry 8091------------- 8092 8093[![][imgDynamicScene]](https://github.com/embree/embree/blob/master/tutorials/multiscene_geometry/multiscene_geometry_device.cpp) 8094 8095This tutorial demonstrates the creation of multiple scenes sharing the 8096same geometry objects. Here, three scenes are built. One with all 8097the dynamic spheres of the Dynamic Scene test and two others each with 8098half. The ground plane is shared by all three scenes. The space bar 8099is used to cycle the scene chosen for rendering. 8100 8101[Source Code](https://github.com/embree/embree/blob/master/tutorials/multiscene_geometry/multiscene_geometry_device.cpp) 8102 8103User Geometry 8104------------- 8105 8106[![][imgUserGeometry]](https://github.com/embree/embree/blob/master/tutorials/user_geometry/user_geometry_device.cpp) 8107 8108This tutorial shows the use of user-defined geometry, to re-implement 8109instancing, and to add analytic spheres. A two-level scene is created, 8110with a triangle mesh as ground plane, and several user geometries that 8111instance other scenes with a small number of spheres of different kinds. 8112The spheres are colored using the instance ID and geometry ID of the hit 8113sphere, to demonstrate how the same geometry instanced in different 8114ways can be distinguished. 8115 8116[Source Code](https://github.com/embree/embree/blob/master/tutorials/user_geometry/user_geometry_device.cpp) 8117 8118Viewer 8119------ 8120 8121[![][imgViewer]](https://github.com/embree/embree/blob/master/tutorials/viewer/viewer_device.cpp) 8122 8123This tutorial demonstrates a simple OBJ viewer that traces primary 8124visibility rays only. A scene consisting of multiple meshes is created, 8125each mesh sharing the index and vertex buffer with the application. 8126It also demonstrates how to support additional per-vertex data, such as 8127shading normals. 8128 8129You need to specify an OBJ file at the command line for this tutorial to 8130work: 8131 8132 ./viewer -i model.obj 8133 8134[Source Code](https://github.com/embree/embree/blob/master/tutorials/viewer/viewer_device.cpp) 8135 8136Stream Viewer 8137------------- 8138 8139[![][imgViewerStream]](https://github.com/embree/embree/blob/master/tutorials/viewer_stream/viewer_stream_device.cpp) 8140 8141This tutorial is a simple OBJ viewer that demonstrates the use of ray 8142streams. You need to specify an OBJ file at the command line for this 8143tutorial to work: 8144 8145 ./viewer_stream -i model.obj 8146 8147[Source Code](https://github.com/embree/embree/blob/master/tutorials/viewer_stream/viewer_stream_device.cpp) 8148 8149Intersection Filter 8150------------------- 8151 8152[![][imgIntersectionFilter]](https://github.com/embree/embree/blob/master/tutorials/intersection_filter/intersection_filter_device.cpp) 8153 8154This tutorial demonstrates the use of filter callback functions to 8155efficiently implement transparent objects. The filter function used for 8156primary rays lets the ray pass through the geometry if it is entirely 8157transparent. Otherwise, the shading loop handles the transparency 8158properly, by potentially shooting secondary rays. The filter function 8159used for shadow rays accumulates the transparency of all surfaces along 8160the ray, and terminates traversal if an opaque occluder is hit. 8161 8162[Source Code](https://github.com/embree/embree/blob/master/tutorials/intersection_filter/intersection_filter_device.cpp) 8163 8164Instanced Geometry 8165------------------ 8166 8167[![][imgInstancedGeometry]](https://github.com/embree/embree/blob/master/tutorials/instanced_geometry/instanced_geometry_device.cpp) 8168 8169This tutorial demonstrates the in-build instancing feature of Embree, by 8170instancing a number of other scenes built from triangulated spheres. The 8171spheres are again colored using the instance ID and geometry ID of the 8172hit sphere, to demonstrate how the same geometry instanced in different 8173ways can be distinguished. 8174 8175[Source Code](https://github.com/embree/embree/blob/master/tutorials/instanced_geometry/instanced_geometry_device.cpp) 8176 8177Multi Level Instancing 8178---------------------- 8179 8180[![][imgMultiLevelInstancing]](https://github.com/embree/embree/blob/master/tutorials/multi_instanced_geometry/multi_instanced_geometry_device.cpp) 8181 8182This tutorial demonstrates multi-level instancing, i.e., nesting instances 8183into instances. To enable the tutorial, set the compile-time variable 8184`EMBREE_MAX_INSTANCE_LEVEL_COUNT` to a value other than the default 1. 8185This variable is available in the code as `RTC_MAX_INSTANCE_LEVEL_COUNT`. 8186 8187The renderer uses a basic path tracing approach, and the 8188image will progressively refine over time. 8189There are two levels of instances in this scene: multiple instances of 8190the same tree nest instances of a twig. 8191Intersections on up to `RTC_MAX_INSTANCE_LEVEL_COUNT` nested levels of 8192instances work out of the box. Users may obtain the *instance ID stack* for 8193a given hitpoint from the `instID` member. 8194During shading, the instance ID stack is used to accumulate 8195normal transformation matrices for each hit. The tutorial visualizes 8196transformed normals as colors. 8197 8198[Source Code](https://github.com/embree/embree/blob/master/tutorials/multi_instanced_geometry/multi_instanced_geometry_device.cpp) 8199 8200Path Tracer 8201----------- 8202 8203[![][imgPathtracer]](https://github.com/embree/embree/blob/master/tutorials/pathtracer/pathtracer_device.cpp) 8204 8205This tutorial is a simple path tracer, based on the viewer tutorial. 8206 8207You need to specify an OBJ file and light source at the command line for 8208this tutorial to work: 8209 8210 ./pathtracer -i model.obj --ambientlight 1 1 1 8211 8212As example models we provide the "Austrian Imperial Crown" model by 8213[Martin Lubich](http://www.loramel.net) and the "Asian Dragon" model from the 8214[Stanford 3D Scanning Repository](http://graphics.stanford.edu/data/3Dscanrep/). 8215 8216[crown.zip](https://github.com/embree/models/releases/download/release/crown.zip) 8217 8218[asian_dragon.zip](https://github.com/embree/models/releases/download/release/asian_dragon.zip) 8219 8220To render these models execute the following: 8221 8222 ./pathtracer -c crown/crown.ecs 8223 ./pathtracer -c asian_dragon/asian_dragon.ecs 8224 8225[Source Code](https://github.com/embree/embree/blob/master/tutorials/pathtracer/pathtracer_device.cpp) 8226 8227Hair 8228---- 8229 8230[![][imgHairGeometry]](https://github.com/embree/embree/blob/master/tutorials/hair_geometry/hair_geometry_device.cpp) 8231 8232This tutorial demonstrates the use of the hair geometry to render a 8233hairball. 8234 8235[Source Code](https://github.com/embree/embree/blob/master/tutorials/hair_geometry/hair_geometry_device.cpp) 8236 8237Curve Geometry 8238-------------- 8239 8240[![][imgCurveGeometry]](https://github.com/embree/embree/blob/master/tutorials/curve_geometry/curve_geometry_device.cpp) 8241 8242This tutorial demonstrates the use of the Linear Basis, B-Spline, and Catmull-Rom curve geometries. 8243 8244[Source Code](https://github.com/embree/embree/blob/master/tutorials/curve_geometry/curve_geometry_device.cpp) 8245 8246Subdivision Geometry 8247-------------------- 8248 8249[![][imgSubdivisionGeometry]](https://github.com/embree/embree/blob/master/tutorials/subdivision_geometry/subdivision_geometry_device.cpp) 8250 8251This tutorial demonstrates the use of Catmull-Clark subdivision 8252surfaces. 8253 8254[Source Code](https://github.com/embree/embree/blob/master/tutorials/subdivision_geometry/subdivision_geometry_device.cpp) 8255 8256Displacement Geometry 8257--------------------- 8258 8259[![][imgDisplacementGeometry]](https://github.com/embree/embree/blob/master/tutorials/displacement_geometry/displacement_geometry_device.cpp) 8260 8261This tutorial demonstrates the use of Catmull-Clark subdivision 8262surfaces with procedural displacement mapping using a constant edge 8263tessellation level. 8264 8265[Source Code](https://github.com/embree/embree/blob/master/tutorials/displacement_geometry/displacement_geometry_device.cpp) 8266 8267Grid Geometry 8268--------------------- 8269 8270[![][imgGridGeometry]](https://github.com/embree/embree/tree/master/tutorials/grid_geometry) 8271 8272This tutorial demonstrates the use of the memory efficient grid 8273primitive to handle highly tessellated and displaced geometry. 8274 8275[Source Code](https://github.com/embree/embree/tree/master/tutorials/grid_geometry) 8276 8277Point Geometry 8278--------------------- 8279 8280[![][imgPointGeometry]](https://github.com/embree/embree/blob/master/tutorials/point_geometry/point_geometry_device.cpp) 8281 8282This tutorial demonstrates the use of the three representations 8283of point geometry. 8284 8285[Source Code](https://github.com/embree/embree/blob/master/tutorials/point_geometry/point_geometry_device.cpp) 8286 8287Motion Blur Geometry 8288-------------------- 8289 8290[![][imgMotionBlurGeometry]](https://github.com/embree/embree/blob/master/tutorials/motion_blur_geometry/motion_blur_geometry_device.cpp) 8291 8292This tutorial demonstrates rendering of motion blur using the 8293multi-segment motion blur feature. Shown is motion blur of a triangle mesh, 8294quad mesh, subdivision surface, line segments, hair geometry, Bézier 8295curves, instantiated triangle mesh where the instance moves, 8296instantiated quad mesh where the instance and the quads move, and user 8297geometry. 8298 8299The number of time steps used can be configured using the `--time-steps 8300<int>` and `--time-steps2 <int>` command line parameters, and the 8301geometry can be rendered at a specific time using the the `--time 8302<float>` command line parameter. 8303 8304[Source Code](https://github.com/embree/embree/blob/master/tutorials/motion_blur_geometry/motion_blur_geometry_device.cpp) 8305 8306Quaternion Motion Blur 8307---------------------- 8308 8309[![][imgQuaternionMotionBlur]](https://github.com/embree/embree/blob/master/tutorials/quaternion_motion_blur/quaternion_motion_blur_device.cpp) 8310 8311This tutorial demonstrates rendering of motion blur using quaternion 8312interpolation. Shown is motion blur using spherical linear interpolation of 8313the rotational component of the instance transformation on the left and 8314simple linear interpolation of the instance transformation on the right. The 8315number of time steps can be modified as well. 8316 8317[Source Code](https://github.com/embree/embree/blob/master/tutorials/quaternion_motion_blur/quaternion_motion_blur_device.cpp) 8318 8319Interpolation 8320------------- 8321 8322[![][imgInterpolation]](https://github.com/embree/embree/blob/master/tutorials/interpolation/interpolation_device.cpp) 8323 8324This tutorial demonstrates interpolation of user-defined per-vertex data. 8325 8326[Source Code](https://github.com/embree/embree/blob/master/tutorials/interpolation/interpolation_device.cpp) 8327 8328Closest Point 8329---------------------- 8330 8331[![][imgClosestPoint]](https://github.com/embree/embree/blob/master/tutorials/closest_point/closest_point_device.cpp) 8332 8333This tutorial demonstrates a use-case of the point query API. The scene 8334consists of a simple collection of objects that are instanced and for several 8335point in the scene (red points) the closest point on the surfaces of the 8336scene are computed (white points). The closest point functionality is 8337implemented for Embree internal and for user-defined instancing. The tutorial 8338also illustrates how to handle instance transformations that are not 8339similarity transforms. 8340 8341[Source Code](https://github.com/embree/embree/blob/master/tutorials/closest_point/closest_point_device.cpp) 8342 8343Voronoi 8344---------------------- 8345 8346[![][imgVoronoi]](https://github.com/embree/embree/blob/master/tutorials/voronoi/voronoi_device.cpp) 8347 8348This tutorial demonstrates how to implement nearest neighbour lookups using 8349the point query API. Several colored points are located on a plane and the 8350corresponding voroni regions are illustrated. 8351 8352[Source Code](https://github.com/embree/embree/blob/master/tutorials/voronoi/voronoi_device.cpp) 8353 8354Collision Detection 8355---------------------- 8356 8357[![][imgCollision]](https://github.com/embree/embree/blob/master/tutorials/collide/collide_device.cpp) 8358 8359This tutorial demonstrates how to implement collision detection using 8360the collide API. A simple cloth solver is setup to collide with a sphere. 8361 8362The cloth can be reset with the `space` bar. The sim stepped once with `n` 8363and continuous simulation started and paused with `p`. 8364 8365[Source Code](https://github.com/embree/embree/blob/master/tutorials/collide/collide_device.cpp) 8366 8367BVH Builder 8368----------- 8369 8370This tutorial demonstrates how to use the templated hierarchy builders 8371of Embree to build a bounding volume hierarchy with a user-defined 8372memory layout using a high-quality SAH builder using spatial splits, a 8373standard SAH builder, and a very fast Morton builder. 8374 8375[Source Code](https://github.com/embree/embree/blob/master/tutorials/bvh_builder/bvh_builder_device.cpp) 8376 8377BVH Access 8378----------- 8379 8380This tutorial demonstrates how to access the internal triangle 8381acceleration structure build by Embree. Please be aware that the 8382internal Embree data structures might change between Embree updates. 8383 8384[Source Code](https://github.com/embree/embree/blob/master/tutorials/bvh_access/bvh_access.cpp) 8385 8386Find Embree 8387----------- 8388 8389This tutorial demonstrates how to use the `FIND_PACKAGE` CMake feature 8390to use an installed Embree. Under Linux and macOS the tutorial finds 8391the Embree installation automatically, under Windows the `embree_DIR` 8392CMake variable must be set to the following folder of the Embree 8393installation: `C:\Program Files\Intel\Embree3`. 8394 8395[Source Code](https://github.com/embree/embree/blob/master/tutorials/find_embree/CMakeLists.txt) 8396 8397Next Hit 8398----------- 8399 8400This tutorial demonstrates how to robustly enumerate all hits along 8401the ray using multiple ray queries and an intersection filter 8402function. To improve performance, the tutorial also supports 8403collecting the next N hits in a single ray query. 8404 8405[Source Code](https://github.com/embree/embree/blob/master/tutorials/next_hit/next_hit_device.cpp) 8406 8407 8408 8409[Embree API]: #embree-api 8410[Embree Tutorials]: #embree-tutorials 8411[Ray Layout]: #ray-layout 8412[Extending the Ray Structure]: #extending-the-ray-structure 8413[Embree Example Renderer]: https://embree.github.io/renderer.html 8414[Triangle Geometry]: #triangle-geometry 8415[Stream Viewer]: #stream-viewer 8416[User Geometry]: #user-geometry 8417[Instanced Geometry]: #instanced-geometry 8418[Multi Level Instancing]: #multi-level-instancing 8419[Intersection Filter]: #intersection-filter 8420[Hair]: #hair 8421[Curves]: #bézier-curves 8422[Subdivision Geometry]: #subdivision-geometry 8423[Displacement Geometry]: #displacement-geometry 8424[Quaternion Motion Blur]: #quaternion-motion-blur 8425[BVH Builder]: #bvh-builder 8426[Interpolation]: #interpolation 8427[Closest Point]: #closest-point 8428[Voronoi]: #voronoi 8429[imgHalfEdges]: https://embree.github.io/images/half_edges.png 8430[imgTriangleUV]: https://embree.github.io/images/triangle_uv.png 8431[imgQuadUV]: https://embree.github.io/images/quad_uv.png 8432[imgTriangleGeometry]: https://embree.github.io/images/triangle_geometry.jpg 8433[imgDynamicScene]: https://embree.github.io/images/dynamic_scene.jpg 8434[imgUserGeometry]: https://embree.github.io/images/user_geometry.jpg 8435[imgViewer]: https://embree.github.io/images/viewer.jpg 8436[imgViewerStream]: https://embree.github.io/images/viewer_stream.jpg 8437[imgInstancedGeometry]: https://embree.github.io/images/instanced_geometry.jpg 8438[imgMultiLevelInstancing]: https://embree.github.io/images/multi_level_instancing.jpg 8439[imgIntersectionFilter]: https://embree.github.io/images/intersection_filter.jpg 8440[imgPathtracer]: https://embree.github.io/images/pathtracer.jpg 8441[imgHairGeometry]: https://embree.github.io/images/hair_geometry.jpg 8442[imgCurveGeometry]: https://embree.github.io/images/curve_geometry.jpg 8443[imgSubdivisionGeometry]: https://embree.github.io/images/subdivision_geometry.jpg 8444[imgDisplacementGeometry]: https://embree.github.io/images/displacement_geometry.jpg 8445[imgGridGeometry]: https://embree.github.io/images/grid_geometry.jpg 8446[imgPointGeometry]: https://embree.github.io/images/point_geometry.jpg 8447[imgMotionBlurGeometry]: https://embree.github.io/images/motion_blur_geometry.jpg 8448[imgQuaternionMotionBlur]: https://embree.github.io/images/quaternion_motion_blur.jpg 8449[imgInterpolation]: https://embree.github.io/images/interpolation.jpg 8450[imgClosestPoint]: https://embree.github.io/images/closest_point.jpg 8451[imgVoronoi]: https://embree.github.io/images/voronoi.jpg 8452[imgCollision]: https://embree.github.io/images/collide.jpg 8453