{"id":15039310,"url":"https://github.com/renderkit/embree","last_synced_at":"2025-05-13T15:11:22.431Z","repository":{"id":5734031,"uuid":"6946079","full_name":"RenderKit/embree","owner":"RenderKit","description":"Embree ray tracing kernels repository.","archived":false,"fork":false,"pushed_at":"2025-04-14T13:06:35.000Z","size":270487,"stargazers_count":2484,"open_issues_count":81,"forks_count":398,"subscribers_count":125,"default_branch":"master","last_synced_at":"2025-04-23T21:44:09.355Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RenderKit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-11-30T21:33:29.000Z","updated_at":"2025-04-23T19:49:50.000Z","dependencies_parsed_at":"2023-02-15T19:30:43.106Z","dependency_job_id":"a7466b4c-71c3-478c-9be1-b1c6d16d1ff7","html_url":"https://github.com/RenderKit/embree","commit_stats":{"total_commits":15019,"total_committers":65,"mean_commits":"231.06153846153848","dds":"0.31100605899194356","last_synced_commit":"02192dc3f91ea86bd96a8352c91bfda833c509ae"},"previous_names":["renderkit/embree","embree/embree"],"tags_count":140,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RenderKit%2Fembree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RenderKit%2Fembree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RenderKit%2Fembree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RenderKit%2Fembree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RenderKit","download_url":"https://codeload.github.com/RenderKit/embree/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253969259,"owners_count":21992263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T20:42:23.573Z","updated_at":"2025-05-13T15:11:17.410Z","avatar_url":"https://github.com/RenderKit.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"% Embree: High Performance Ray Tracing Kernels 4.4.0\n% Intel Corporation\n\nIntel® Embree Overview\n======================\n\nIntel® Embree is a high-performance ray tracing library developed at\nIntel, which is released as open source under the [Apache 2.0\nlicense](http://www.apache.org/licenses/LICENSE-2.0). Intel® Embree\nsupports x86 CPUs under Linux, macOS, and Windows; ARM CPUs on Linux\nand macOS; as well as Intel® GPUs under Linux and Windows.\n\nIntel® Embree targets graphics application developers to improve the\nperformance of photo-realistic rendering applications. Embree is\noptimized towards production rendering, by putting focus on incoherent\nray performance, high quality acceleration structure construction, a\nrich feature set, accurate primitive intersection, and low memory\nconsumption.\n\nEmbree's feature set includes various primitive types such as\ntriangles (as well quad and grids for lower memory consumption);\nCatmull-Clark subdivision surfaces; various types of curve primitives,\nsuch as flat curves (for distant views), round curves (for closeup\nviews), and normal oriented curves, all supported with different basis\nfunctions (linear, Bézier, B-spline, Hermite, and Catmull Rom);\npoint-like primitives, such as ray oriented discs, normal oriented\ndiscs, and spheres; user defined geometries with a procedural\nintersection function; multi-level instancing; filter callbacks\ninvoked for any hit encountered; motion blur including multi-segment\nmotion blur, deformation blur, and quaternion motion blur; and ray\nmasking.\n\nIntel® Embree contains ray tracing kernels optimized for the latest\nx86 processors with support for SSE, AVX, AVX2, and AVX-512\ninstructions, and uses runtime code selection to choose between these\nkernels. Intel® Embree contains algorithms optimized for incoherent\nworkloads (e.g.  Monte Carlo ray tracing algorithms) and coherent\nworkloads (e.g. primary visibility and hard shadow rays) as well as\nsupports for dynamic scenes by implementing high-performance two-level\nspatial index structure construction algorithms.\n\nIntel® Embree supports applications written with the Intel® Implicit\nSPMD Program Compiler (Intel® ISPC, \u003chttps://ispc.github.io/\u003e) by\nproviding an ISPC interface to the core ray tracing\nalgorithms. This makes it possible to write a renderer that\nautomatically vectorizes and leverages SSE, AVX, AVX2, and AVX-512\ninstructions.\n\nIntel® Embree supports Intel GPUs through the\n[SYCL](https://www.khronos.org/sycl/) open standard programming\nlanguage. SYCL allows to write C++ code that can be run on various\ndevices, such as CPUs and GPUs. Using Intel® Embree application\ndevelopers can write a single source renderer that executes\nefficiently on CPUs and GPUs. Maintaining just one code base\nthis way can significantly improve productivity and eliminate\ninconsistencies between a CPU and GPU version of the renderer. Embree\nsupports GPUs based on the Xe HPG and Xe HPC microarchitecture,\nwhich support hardware accelerated ray tracing do deliver excellent\nlevels of ray tracing performance.\n\nSupported Platforms\n-------------------\n\nEmbree supports Windows (32-bit and 64-bit), Linux (64-bit), and macOS\n(64-bit). Under Windows, Linux and macOS x86 based CPUs are supported,\nwhile ARM CPUs are currently only supported under Linux and macOS (e.g. \nApple M1). ARM support for Windows experimental.\n\nEmbree supports Intel GPUs based on the Xe HPG microarchitecture\n(Intel® Arc™ GPU) under Linux and Windows and Xe HPC microarchitecture\n(Intel® Data Center GPU Flex Series and Intel® Data Center GPU Max\nSeries) under Linux.\n\nThe code compiles with the Intel® Compiler, Intel® oneAPI DPC++\nCompiler, GCC, Clang, and the Microsoft Compiler. To use Embree on the\nGPU the Intel® oneAPI DPC++ Compiler must be used. Please see section\n[Compiling Embree] for details on tested compiler versions.\n\nEmbree requires at least an x86 CPU with support for\nSSE2 or an Apple M1 CPU.\n\nEmbree Support and Contact\n--------------------------\n\nIf you encounter bugs please report them via [Embree's GitHub Issue\nTracker](https://github.com/embree/embree/issues).\n\nFor questions and feature requests please write us at\n\u003cembree_support@intel.com\u003e.\n\nTo receive notifications of updates and new features of Embree please\nsubscribe to the [Embree mailing\nlist](https://groups.google.com/d/forum/embree/).\n\nInstallation of Embree\n======================\n\n\nWindows Installation\n--------------------\n\nA pre-built version of Embree for Windows is provided as a ZIP archive\n[embree-4.4.0.x64.windows.zip](https://github.com/embree/embree/releases/download/v4.4.0/embree-4.4.0.x64.windows.zip). After\nunpacking this ZIP file, you should set the path to the `lib` folder\nmanually to your `PATH` environment variable for applications to find\nEmbree.\n\n\nLinux Installation\n------------------\n\nA pre-built version of Embree for Linux is provided as a `tar.gz` archive:\n[embree-4.4.0.x86_64.linux.tar.gz](https://github.com/embree/embree/releases/download/v4.4.0/embree-4.4.0.x86_64.linux.tar.gz). Unpack\nthis file using `tar` and source the provided `embree-vars.sh` (if you\nare using the bash shell) or `embree-vars.csh` (if you are using the C\nshell) to set up the environment properly:\n\n    tar xzf embree-4.4.0.x86_64.linux.tar.gz\n    source embree-4.4.0.x86_64.linux/embree-vars.sh\n\nWe recommend adding a relative `RPATH` to your application that points\nto the location where Embree (and TBB) can be found, e.g. `$ORIGIN/../lib`.\n\n\nmacOS Installation\n------------------\n\nThe macOS version of Embree is also delivered as a ZIP file:\n[embree-4.4.0.x86_64.macosx.zip](https://github.com/embree/embree/releases/download/v4.4.0/embree-4.4.0.x86_64.macosx.zip). Unpack\nthis file using `tar` and source the provided `embree-vars.sh` (if you\nare using the bash shell) or `embree-vars.csh` (if you are using the C\nshell) to set up the environment properly:\n\n    unzip embree-4.4.0.x64.macosx.zip    source embree-4.4.0.x64.macosx/embree-vars.sh\n\nIf you want to ship Embree with your application, please use the Embree\nlibrary of the provided ZIP file. The library name of that Embree\nlibrary is of the form `@rpath/libembree.4.dylib`\n(and similar also for the included TBB library). This ensures that you\ncan add a relative `RPATH` to your application that points to the location\nwhere Embree (and TBB) can be found, e.g. `@loader_path/../lib`.\n\n\nBuilding Embree Applications\n----------------------------\n\nThe most convenient way to build an Embree application is through\nCMake. Just let CMake find your unpacked Embree package using the\n`FIND_PACKAGE` function inside your `CMakeLists.txt` file:\n\n     FIND_PACKAGE(embree 4 REQUIRED)\n\nFor CMake to properly find Embree you need to set the `embree_DIR` variable to\nthe folder containing the `embree_config.cmake` file. You might also have to\nset the `TBB_DIR` variable to the path containing `TBB-config.cmake` of a local\nTBB install, in case you do not have TBB installed globally on your system,\ne.g:\n\n    cmake -D embree_DIR=path_to_embree_package/lib/cmake/embree-4.4.0/ \\\n          -D TBB_DIR=path_to_tbb_package/lib/cmake/tbb/ \\\n          ..\n\nThe `FIND_PACKAGE` function will create an `embree` target that\nyou can add to your target link libraries:\n\n    TARGET_LINK_LIBRARIES(application embree)\n\nFor a full example on how to build an Embree application please have a\nlook at the `minimal` tutorial provided in the `src` folder of the\nEmbree package and also the contained `README.txt` file.\n\n\nBuilding Embree SYCL Applications\n----------------------------------\n\nBuilding Embree SYCL applications is also best done using\nCMake. Please first get some compatible SYCL compiler and setup the\nenvironment as decribed in sections [Linux SYCL Compilation] and\n[Windows SYCL Compilation].\n\nAlso perform the setup steps from the previous [Building Embree\nApplications] section.\n\nPlease also have a look at the [Minimal] tutorial that is provided\nwith the Embree release, for an example how to build a simple SYCL\napplication using CMake and Embree.\n\nTo properly compile your SYCL application you have to add additional\nSYCL compile flags for each C++ file that contains SYCL device side\ncode or kernels as described next.\n\n\n### JIT Compilation\n\nWe recommend using just in time compilation (JIT compilation) together\nwith [SYCL JIT caching] to compile Embree SYCL applications. For JIT\ncompilation add these options to the compilation phase of all C++\nfiles that contain SYCL code:\n\n    -fsycl -Xclang -fsycl-allow-func-ptr -fsycl-targets=spir64\n\nThese options enable SYCL two phase compilation (`-fsycl` option),\nenable function pointer support (`-Xclang -fsycl-allow-func-ptr`\noption), and just in time (JIT) compilation only\n(`-fsycl-targets=spir64` option).\n\nThe following link options have to get added to the linking stage of\nyour application when using just in time compilation:\n\n    -fsycl -fsycl-targets=spir64\n\nFor a full example on how to build an Embree SYCL application please\nhave a look at the SYCL version of the `minimal` tutorial provided in\nthe `src` folder of the Embree package and also the contained\n`README.txt` file.\n\nPlease have a look at the [Compiling Embree] section on how to create\nan Embree package from sources if required.\n\n\n### AOT Compilation\n\nAhead of time compilation (AOT compilation) allows to speed up first\napplication start up time as device binaries are precompiled. We do\nnot recommend using AOT compilation as it does not allow the usage of\nspecialization constants to reduce code complexity.\n\nFor ahead of time compilation add these compile options to the\ncompilation phase of all C++ files that contain SYCL code:\n\n    -fsycl -Xclang -fsycl-allow-func-ptr -fsycl-targets=spir64_gen\n\nThese options enable SYCL two phase compilation (`-fsycl` option),\nenable function pointer support (`-Xclang -fsycl-allow-func-ptr`\noption), and ahead of time (AOT) compilation\n(`-fsycl-targets=spir64_gen` option).\n\nThe following link options have to get added to the linking stage of\nyour application when compiling ahead of time for Xe HPG devices:\n\n    -fsycl -fsycl-targets=spir64_gen\n    -Xsycl-target-backend=spir64_gen \"-device XE_HPG_CORE\"\n\nThis in particular configures the devices for AOT compilation to\n`XE_HPG_CORE`.\n\nTo get a list of all device supported by AOT compilation look at the\nhelp of the device option in ocloc tool:\n\n    ocloc compile --help\n\n\nBuilding Embree Tests\n---------------------\n\nEmbree is released with a bundle of tests in an optional testing package.\nTo run these tests extract the testing package in the same folder as your embree installation.\ne.g.:\n    \n    tar -xzf embree-4.4.0-testing.zip -C /path/to/installed/embree\n\nThe tests are extracted into a new folder inside you embree installation and can be run with:\n\n    cd /path/to/installed/embree/testing\n    cmake -B build\n    cmake --build build target=tests\n\n\nCompiling Embree\n================\n\nWe recommend using the prebuild Embree packages from\n[https://github.com/embree/embree/releases](https://github.com/embree/embree/releases). If\nyou need to compile Embree yourself you need to use CMake as described\nin the following.\n\nDo not enable fast-math optimizations in your compiler as this mode is\nnot supported by Embree.\n\nLinux and macOS\n---------------\n\nTo compile Embree you need a modern C++ compiler that supports\nC++11. Embree is tested with the following compilers:\n\nLinux\n\n  - Intel® oneAPI DPC++/C++ Compiler 2024.0.2\n  - oneAPI DPC++/C++ Compiler 2023-10-26\n  - Clang 5.0.0\n  - Clang 4.0.0\n  - GCC 10.0.1 (Fedora 32) AVX512 support\n  - GCC  8.3.1 (Fedora 29) AVX512 support\n  - Intel® Implicit SPMD Program Compiler 1.22.0\n\nmacOS x86_64\n\n  - Apple Clang 15\n\nmacOS Arm64\n\n  - Apple Clang 14\n\nEmbree supports using the Intel® Threading Building Blocks (TBB) as the\ntasking system. For performance and flexibility reasons we recommend\nusing Embree with the Intel® Threading Building Blocks (TBB) and best\nalso use TBB inside your application. Optionally you can disable TBB\nin Embree through the `EMBREE_TASKING_SYSTEM` CMake variable.\n\nEmbree supports the Intel® Implicit SPMD Program Compiler (Intel® ISPC), which allows\nstraightforward parallelization of an entire renderer. If you\nwant to use Intel® ISPC then you can enable `EMBREE_ISPC_SUPPORT` in\nCMake. Download and install the Intel® ISPC binaries from\n[ispc.github.io](https://ispc.github.io/downloads.html). After\ninstallation, put the path to `ispc` permanently into your `PATH` environment\nvariable or you set the `EMBREE_ISPC_EXECUTABLE` variable to point at the ISPC\nexecutable during CMake configuration.\n\nYou additionally have to install CMake 3.1.0 or higher and the developer\nversion of [GLFW](https://www.glfw.org/) version 3.\n\nUnder macOS, all these dependencies can be installed\nusing [MacPorts](http://www.macports.org/):\n\n    sudo port install cmake tbb glfw-devel\n\nDepending on your Linux distribution you can install these dependencies\nusing `yum` or `apt-get`.  Some of these packages might already be\ninstalled or might have slightly different names.\n\nType the following to install the dependencies using `yum`:\n\n    sudo yum install cmake\n    sudo yum install tbb-devel\n    sudo yum install glfw-devel\n\nType the following to install the dependencies using `apt-get`:\n\n    sudo apt-get install cmake-curses-gui\n    sudo apt-get install libtbb-dev\n    sudo apt-get install libglfw3-dev\n\nFinally, you can compile Embree using CMake. Create a build directory\ninside the Embree root directory and execute `ccmake ..` inside this\nbuild directory.\n\n    mkdir build\n    cd build\n    ccmake ..\n\nPer default, CMake will use the compilers specified with the `CC` and\n`CXX` environment variables. Should you want to use a different\ncompiler, run `cmake` first and set the `CMAKE_CXX_COMPILER` and\n`CMAKE_C_COMPILER` variables to the desired compiler. For example, to\nuse the Clang compiler instead of the default GCC on most Linux machines\n(`g++` and `gcc`), execute\n\n    cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang ..\n\nRunning `ccmake` will open a dialog where you can perform various\nconfigurations as described below in [CMake Configuration]. After having\nconfigured Embree, press `c` (for configure) and `g` (for generate) to\ngenerate a Makefile and leave the configuration. The code can be\ncompiled by executing make.\n\n    make -j 8\n\nThe executables will be generated inside the build folder. We recommend\ninstalling the Embree library and header files on your\nsystem. Therefore set the `CMAKE_INSTALL_PREFIX` to `/usr` in cmake\nand type:\n\n    sudo make install\n\nIf you keep the default `CMAKE_INSTALL_PREFIX` of `/usr/local` then\nyou have to make sure the path `/usr/local/lib` is in your\n`LD_LIBRARY_PATH`.\n\nYou can also uninstall Embree again by executing:\n\n    sudo make uninstall\n\nYou can also create an Embree package using the following command:\n\n    make package\n\nPlease see the [Building Embree Applications] section on how to build\nyour application with such an Embree package.\n\nLinux SYCL Compilation\n-----------------------\n\nThere are two options to compile Embree with SYCL support:\nThe open source [\"oneAPI DPC++ Compiler\"](https://github.com/intel/llvm/) or\nthe [\"Intel(R) oneAPI DPC++/C++ Compiler\"](https://www.intel.com/content/www/us/en/developer/articles/tool/oneapi-standalone-components.html#dpcpp-cpp).\nOther SYCL compilers are not supported.\n\nThe \"oneAPI DPC++ Compiler\" is more up-to-date than the \"Intel(R) oneAPI\nDPC++/C++ Compiler\" but less stable. The current tested version of the \"oneAPI\nDPC++ compiler is\n\n  - [oneAPI DPC++ Compiler 2023-10-26](https://github.com/intel/llvm/releases/tag/nightly-2023-10-26)\n  \nThe compiler can be downloaded and simply extracted. The oneAPI DPC++ compiler\ncan be set up executing the following commands in a Linux (bash) shell:\n\n    export SYCL_BUNDLE_ROOT=path_to_dpcpp_compiler\n    export PATH=$SYCL_BUNDLE_ROOT/bin:$PATH\n    export CPATH=$SYCL_BUNDLE_ROOT/include:$CPATH\n    export LIBRARY_PATH=$SYCL_BUNDLE_ROOT/lib:$LIBRARY_PATH\n    export LD_LIBRARY_PATH=$SYCL_BUNDLE_ROOT/lib:$LD_LIBRARY_PATH\n    export LD_LIBRARY_PATH=$SYCL_BUNDLE_ROOT/linux/lib/x64:$LD_LIBRARY_PATH\n\nwhere the `path_to_dpcpp_compiler` should point to the unpacked oneAPI DPC++\ncompiler. This will put `clang++` and `clang` from the oneAPI DPC++ Compiler\ninto your path.\n\nPlease also install all Linux packages described in the previous\nsection.\n\nNow, you can configure Embree using CMake by executing the following command\nin the Embree root directory:\n\n    cmake -B build \\\n          -DCMAKE_CXX_COMPILER=clang++ \\\n          -DCMAKE_C_COMPILER=clang \\\n          -DEMBREE_SYCL_SUPPORT=ON\n\nThis will create a directory `build` to use as the CMake build directory,\nconfigure the usage of the oneAPI DPC++ Compiler, and turn on SYCL support\nthrough `EMBREE_SYCL_SUPPORT=ON`.\n\nAlternatively, you can download and run the installer of the\n\n - [Intel(R) oneAPI DPC++/C++ Compiler](https://www.intel.com/content/www/us/en/developer/articles/tool/oneapi-standalone-components.html#dpcpp-cpp).\n\nAfter installation, you can set up the compiler by sourcing the\n`vars.sh` script in the `env` directory of the compiler install directory, for example,\n\n    source /opt/intel/oneAPI/compiler/latest/env/vars.sh\n\nThis script will put the `icpx` and `icx` compiler executables from the\nIntel(R) oneAPI DPC++/C++ Compiler in your path.\n\nNow, you can configure Embree using CMake by executing the following command\nin the Embree root directory:\n\n    cmake -B build \\\n          -DCMAKE_CXX_COMPILER=icpx \\\n          -DCMAKE_C_COMPILER=icx \\\n          -DEMBREE_SYCL_SUPPORT=ON\n\nMore information about setting up the Intel(R) oneAPI DPC++/C++ compiler can be\nfound in the [Development Reference Guide](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-dpcpp-cpp-compiler-dev-guide-and-reference/top/compiler-setup.html). Please note, that the Intel(R) oneAPI DPC++/C++ compiler\nrequires [at least CMake version 3.20.5 on Linux](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-dpcpp-cpp-compiler-dev-guide-and-reference/top/compiler-setup/use-the-command-line/use-cmake-with-the-compiler.html).\n\nIndependent of the DPC++ compiler choice, you can now build Embree using\n\n    cmake --build build -j 8\n\nThe executables will be generated inside the build folder. The\nexecutable names of the SYCL versions of the tutorials end with\n`_sycl`.\n\n\n### Linux Graphics Driver Installation\n\nTo run the SYCL code you need to install the latest GPGPU drivers for\nyour Intel Xe HPG/HPC GPUs from here\n[https://dgpu-docs.intel.com/](https://dgpu-docs.intel.com/). Follow\nthe driver installation instructions for your graphics card and\noperating system.\n\nAfter installing the drivers you have to install an additional package\nmanually using\n\n    sudo apt install intel-level-zero-gpu-raytracing\n\n\nWindows\n-------\n\nEmbree is tested using the following compilers under Windows:\n\n  - Intel® oneAPI DPC++/C++ Compiler 2024.0.2\n  - oneAPI DPC++/C++ Compiler 2023-10-26\n  - Visual Studio 2022\n  - Visual Studio 2019\n  - Visual Studio 2017\n  - Intel® Implicit SPMD Program Compiler 1.22.0\n\nTo compile Embree for AVX-512 you have to use the Intel® Compiler.\n\nEmbree supports using the Intel® Threading Building Blocks (TBB) as the\ntasking system. For performance and flexibility reasons we recommend\nusing use Embree with the Intel® Threading Building Blocks (TBB) and best\nalso use TBB inside your application. Optionally you can disable TBB\nin Embree through the `EMBREE_TASKING_SYSTEM` CMake variable.\n\nEmbree will either find the Intel® Threading Building Blocks (TBB)\ninstallation that comes with the Intel® Compiler, or you can install the\nbinary distribution of TBB directly from\n[https://github.com/oneapi-src/oneTBB/releases](https://github.com/oneapi-src/oneTBB/releases)\ninto a folder named `tbb` into your Embree root directory. You also have\nto make sure that the libraries `tbb.dll` and `tbb_malloc.dll` can be\nfound when executing your Embree applications, e.g. by putting the path\nto these libraries into your `PATH` environment variable.\n\nEmbree supports the Intel® Implicit SPMD Program Compiler (Intel® ISPC), which\nallows straightforward parallelization of an entire renderer. When installing\nIntel® ISPC, make sure to download an Intel® ISPC version from\n[ispc.github.io](https://ispc.github.io/downloads.html) that is compatible with\nyour Visual Studio version. After installation, put the path to `ispc.exe`\npermanently into your `PATH` environment variable or you need to correctly set\nthe `EMBREE_ISPC_EXECUTABLE` variable during CMake configuration to point to\nthe ISPC executable. If you want to use Intel® ISPC, you have to enable\n`EMBREE_ISPC_SUPPORT` in CMake.\n\nYou additionally have to install [CMake](http://www.cmake.org/download/)\n(version 3.1 or higher). Note that you need a native Windows CMake\ninstallation because CMake under Cygwin cannot generate solution files\nfor Visual Studio.\n\n### Using the IDE\n\nRun `cmake-gui`, browse to the Embree sources, set the build directory\nand click Configure. Now you can select the Generator, e.g. \"Visual\nStudio 12 2013\" for a 32-bit build or \"Visual Studio 12 2013 Win64\"\nfor a 64-bit build.\n\nTo use a different compiler than the Microsoft Visual C++ compiler, you\nadditionally need to specify the proper compiler toolset through the\noption \"Optional toolset to use (-T parameter)\". E.g. to use Clang for\ncompilation set the toolset to \"LLVM_v142\".\n\nDo not change the toolset manually in a solution file (neither through\nthe project properties dialog nor through the \"Use Intel Compiler\"\nproject context menu), because then some compiler-specific command line\noptions cannot be set by CMake.\n\nMost configuration parameters described in the [CMake Configuration]\ncan be set under Windows as well. Finally, click \"Generate\" to create\nthe Visual Studio solution files. \n\nThe following CMake options are only available under Windows:\n\n+ `CMAKE_CONFIGURATION_TYPE`:  List of generated\n  configurations. The default value is Debug;Release;RelWithDebInfo.\n\n+  `USE_STATIC_RUNTIME`: Use the static version of the C/C++ runtime\n  library. This option is turned OFF by default.\n\nUse the generated Visual Studio solution file `embree4.sln` to compile\nthe project.\n\nWe recommend enabling syntax highlighting for the `.ispc` source and\n`.isph` header files. To do so open Visual Studio, go to Tools ⇒\nOptions ⇒ Text Editor ⇒ File Extension and add the `isph` and `ispc`\nextensions for the \"Microsoft Visual C++\" editor.\n\n### Using the Command Line\n\nEmbree can also be configured and built without the IDE using the Visual\nStudio command prompt:\n\n    cd path\\to\\embree\n    mkdir build\n    cd build\n    cmake -G \"Visual Studio 16 2019\" ..\n    cmake --build . --config Release\n\nYou can also build only some projects with the `--target` switch.\nAdditional parameters after \"`--`\" will be passed to `msbuild`. For\nexample, to build the Embree library in parallel use\n\n    cmake --build . --config Release --target embree -- /m\n\n### Building Embree - Using vcpkg\n\nYou can download and install Embree using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:\n\n    git clone https://github.com/Microsoft/vcpkg.git\n    cd vcpkg\n    ./bootstrap-vcpkg.sh\n    ./vcpkg integrate install\n    ./vcpkg install embree3\n\nThe Embree port in vcpkg is kept up to date by Microsoft team members\nand community contributors. If the version is out of date, please\n[create an issue or pull request](https://github.com/Microsoft/vcpkg)\non the vcpkg repository.\n\n\nWindows SYCL Compilation\n-------------------------\n\nThere are two options to compile Embree with SYCL support:\nThe open source [\"oneAPI DPC++ Compiler\"](https://github.com/intel/llvm/) or\nthe [\"Intel(R) oneAPI DPC++/C++ Compiler\"](https://www.intel.com/content/www/us/en/developer/articles/tool/oneapi-standalone-components.html#dpcpp-cpp).\nOther SYCL compilers are not supported. You will also need an installed version\nof Visual Studio that supports the C++17 standard, e.g. Visual Studio 2019.\n\nThe \"oneAPI DPC++ Compiler\" is more up-to-date than the \"Intel(R) oneAPI\nDPC++/C++ Compiler\" but less stable. The current tested version of the oneAPI\nDPC++ compiler is\n\n  - [oneAPI DPC++ Compiler 2023-10-26](https://github.com/intel/llvm/releases/tag/nightly-2023-10-26)\n\nDownload and unpack the archive and open the \"x64 Native Tools Command Prompt\"\nof Visual Studio and execute the following lines to properly configure the\nenvironment to use the oneAPI DPC++ compiler:\n\n    set \"DPCPP_DIR=path_to_dpcpp_compiler\"\n    set \"PATH=%DPCPP_DIR%\\bin;%PATH%\"\n    set \"PATH=%DPCPP_DIR%\\lib;%PATH%\"\n    set \"CPATH=%DPCPP_DIR%\\include;%CPATH%\"\n    set \"INCLUDE=%DPCPP_DIR%\\include;%INCLUDE%\"\n    set \"LIB=%DPCPP_DIR%\\lib;%LIB%\"\n\nThe `path_to_dpcpp_compiler` should point to the unpacked oneAPI DPC++\ncompiler.\n\nNow, you can configure Embree using CMake by executing the following command\nin the Embree root directory:\n\n    cmake -B build\n          -G Ninja\n          -D CMAKE_BUILD_TYPE=Release\n          -D CMAKE_CXX_COMPILER=clang++\n          -D CMAKE_C_COMPILER=clang\n          -D EMBREE_SYCL_SUPPORT=ON\n          -D TBB_ROOT=path_to_tbb\\lib\\cmake\\tbb\n\nThis will create a directory `build` to use as the CMake build directory, and\nconfigure a release build that uses `clang++` and `clang` from the oneAPI DPC++\ncompiler.\n\nThe [Ninja](https://ninja-build.org/) generator is currently the easiest way to\nuse the oneAPI DPC++ compiler.\n\nWe also enable SYCL support in Embree using the `EMBREE_SYCL_SUPPORT` CMake\noption.\n\nAlternatively, you can download and run the installer of the\n\n - [Intel(R) oneAPI DPC++/C++ Compiler](https://www.intel.com/content/www/us/en/developer/articles/tool/oneapi-standalone-components.html#dpcpp-cpp).\n\nAfter installation, you can either open a regular `Command Prompt` and execute\nthe `vars.bat` script in the `env` directory of the compiler install directory,\nfor example\n\n    C:\\Program Files (x86)\\Intel\\oneAPI\\compiler\\latest\\env\\vars.bat\n\nor simply open the installed \"Intel oneAPI command prompt for Intel 64 for Visual Studio\".\n\nBoth ways will put the `icx` compiler executable from the\nIntel(R) oneAPI DPC++/C++ compiler in your path.\n\nNow, you can configure Embree using CMake by executing the following command\nin the Embree root directory:\n\n    cmake -B build\n          -G Ninja\n          -D CMAKE_BUILD_TYPE=Release\n          -D CMAKE_CXX_COMPILER=icx\n          -D CMAKE_C_COMPILER=icx\n          -D EMBREE_SYCL_SUPPORT=ON\n          -D TBB_ROOT=path_to_tbb\\lib\\cmake\\tbb\n\nMore information about setting up the Intel(R) oneAPI DPC++/C++ compiler can be\nfound in the [Development Reference Guide](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-dpcpp-cpp-compiler-dev-guide-and-reference/top/compiler-setup.html). Please note, that the Intel(R) oneAPI DPC++/C++ compiler\nrequires [at least CMake version 3.23 on Windows](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-dpcpp-cpp-compiler-dev-guide-and-reference/top/compiler-setup/use-the-command-line/use-cmake-with-the-compiler.html).\n\nIndependent of the DPC++ compiler choice, you can now build Embree using\n\n    cmake --build build\n\nIf you have problems with Ninja re-running CMake in an infinite loop,\nthen first remove the \"Re-run CMake if any of its inputs changed.\"\nsection from the `build.ninja` file and run the above command again.\n\nYou can also create an Embree package using the following command:\n\n    cmake --build build --target package\n\nPlease see the [Building Embree SYCL Applications] section on how to build\nyour application with such an Embree package.\n\n\n### Windows Graphics Driver Installation\n\nIn order to run the SYCL tutorials on HPG hardware, you first need to\ninstall the graphics drivers for your graphics card from\n[https://www.intel.com](https://www.intel.com). Please make sure to\nhave installed version 31.0.101.4644 or newer.\n\n\nCMake Configuration\n-------------------\n\nThe default CMake configuration in the configuration dialog should be\nappropriate for most usages. The following list describes all\nparameters that can be configured in CMake:\n\n+ `CMAKE_BUILD_TYPE`: Can be used to switch between Debug mode\n  (Debug), Release mode (Release) (default), and Release mode with\n  enabled assertions and debug symbols (RelWithDebInfo).\n\n+ `EMBREE_STACK_PROTECTOR`: Enables protection of return address\n  from buffer overwrites. This option is OFF by default.\n\n+ `EMBREE_ISPC_SUPPORT`: Enables Intel® ISPC support of Embree. This option\n  is OFF by default.\n\n+ `EMBREE_SYCL_SUPPORT`: Enables GPU support using SYCL. When this\n  option is enabled you have to use some DPC++ compiler. Please see\n  the sections [Linux SYCL Compilation] and [Windows SYCL Compilation]\n  on supported DPC++ compilers. This option is OFF by default.\n\n+ `EMBREE_SYCL_AOT_DEVICES`: Selects a list of GPU devices for\n  ahead-of-time (AOT) compilation of device code. Possible values are\n  either, \"none\" which enables only just in time (JIT) compilation, or\n  a list of the Embree-supported Xe GPUs for AOT compilation:\n\n  * XE_HPG_CORE : Xe HPG devices\n  * XE_HPC_CORE : Xe HPC devices\n\n  One can also specify multiple devices separated by comma to\n  compile ahead of time for multiple devices,\n  e.g. \"XE_HPG_CORE,XE_HP_CORE\". When enabling AOT compilation for one\n  or multiple devices, JIT compilation will always additionally be\n  enabled in case the code is executed on a device no code is\n  precompiled for.\n\n  Execute \"ocloc compile --help\" for more details of possible devices\n  to pass. Embree is only supported on Xe HPG/HPC and newer devices.\n\n  Per default, this option is set to \"none\" to enable JIT\n  compilation. We recommend using JIT compilation as this enables the\n  use of specialization constants to reduce code complexity.\n\n+ `EMBREE_STATIC_LIB`: Builds Embree as a static library (OFF by\n  default). Further multiple static libraries are generated for the\n  different ISAs selected (e.g. `embree4.a`, `embree4_sse42.a`,\n  `embree4_avx.a`, `embree4_avx2.a`, `embree4_avx512.a`). You have\n  to link these libraries in exactly this order of increasing ISA.\n\n+ `EMBREE_API_NAMESPACE`: Specifies a namespace name to put all Embree\n  API symbols inside. By default, no namespace is used and plain C symbols\n  are exported.\n\n+ `EMBREE_LIBRARY_NAME`: Specifies the name of the Embree library file\n  created. By default, the name embree4 is used.\n\n+ `EMBREE_IGNORE_CMAKE_CXX_FLAGS`: When enabled, Embree ignores\n  default CMAKE_CXX_FLAGS. This option is turned ON by default.\n\n+ `EMBREE_TUTORIALS`: Enables build of Embree tutorials (default ON).\n\n+ `EMBREE_BACKFACE_CULLING`: Enables backface culling, i.e. only\n  surfaces facing a ray can be hit. This option is turned OFF by\n  default.\n\n+ `EMBREE_BACKFACE_CULLING_CURVES`: Enables backface culling for curves,\n  i.e. only surfaces facing a ray can be hit. This option is turned OFF\n  by default.\n\n+ `EMBREE_BACKFACE_CULLING_SPHERES`: Enables backface culling for spheres,\n  i.e. only surfaces facing a ray can be hit. This option is turned OFF\n  by default.\n\n+ `EMBREE_COMPACT_POLYS`: Enables compact tris/quads, i.e. only\n  geomIDs and primIDs are stored inside the leaf nodes.  \n\n+ `EMBREE_FILTER_FUNCTION`: Enables the intersection filter function\n  feature (ON by default).\n\n+ `EMBREE_RAY_MASK`: Enables the ray masking feature (OFF by default).\n\n+ `EMBREE_RAY_PACKETS`: Enables ray packet traversal kernels. This\n  feature is turned ON by default. When turned on packet traversal is\n  used internally and packets passed to rtcIntersect4/8/16 are kept\n  intact in callbacks (when the ISA of appropriate width is enabled).\n\n+ `EMBREE_IGNORE_INVALID_RAYS`: Makes code robust against the risk of\n  full-tree traversals caused by invalid rays (e.g. rays containing\n  INF/NaN as origins). This option is turned OFF by default.\n\n+ `EMBREE_TASKING_SYSTEM`: Chooses between Intel® Threading TBB\n  Building Blocks (TBB), Parallel Patterns Library (PPL) (Windows\n  only), or an internal tasking system (INTERNAL). By default, TBB is\n  used.\n\n+ `EMBREE_TBB_ROOT`: If Intel® Threading Building Blocks (TBB)\n  is used as a tasking system, search the library in this directory\n  tree.\n\n+ `EMBREE_TBB_COMPONENT`: The component/library name of Intel® Threading \n  Building Blocks (TBB). Embree searches for this library name (default: tbb)\n  when TBB is used as the tasking system.\n\n+ `EMBREE_TBB_POSTFIX`: If Intel® Threading Building Blocks (TBB)\n  is used as a tasking system, link to tbb\u003cEMBREE_TBB_POSTFIX\u003e.(so,dll,lib).\n  Defaults to the empty string.\n\n+ `EMBREE_TBB_DEBUG_ROOT`: If Intel® Threading Building Blocks (TBB)\n  is used as a tasking system, search the library in this directory\n  tree in Debug mode. Defaults to `EMBREE_TBB_ROOT`.\n\n+ `EMBREE_TBB_DEBUG_POSTFIX`: If Intel® Threading Building Blocks (TBB)\n  is used as a tasking system, link to tbb\u003cEMBREE_TBB_DEBUG_POSTFIX\u003e.(so,dll,lib)\n  in Debug mode. Defaults to \"_debug\".\n\n+ `EMBREE_MAX_ISA`: Select highest supported ISA (SSE2, SSE4.2, AVX,\n  AVX2, AVX512, or NONE). When set to NONE the\n  EMBREE_ISA_* variables can be used to enable ISAs individually. By\n  default, the option is set to AVX2.\n\n+ `EMBREE_ISA_SSE2`: Enables SSE2 when EMBREE_MAX_ISA is set to\n  NONE. By default, this option is turned OFF.\n\n+ `EMBREE_ISA_SSE42`: Enables SSE4.2 when EMBREE_MAX_ISA is set to\n  NONE. By default, this option is turned OFF.\n\n+ `EMBREE_ISA_AVX`: Enables AVX when EMBREE_MAX_ISA is set to NONE. By\n  default, this option is turned OFF.\n\n+ `EMBREE_ISA_AVX2`: Enables AVX2 when EMBREE_MAX_ISA is set to\n  NONE. By default, this option is turned OFF.\n\n+ `EMBREE_ISA_AVX512`: Enables AVX-512 for Skylake when\n  EMBREE_MAX_ISA is set to NONE. By default, this option is turned OFF.\n\n+ `EMBREE_GEOMETRY_TRIANGLE`: Enables support for triangle geometries\n  (ON by default).\n\n+ `EMBREE_GEOMETRY_QUAD`: Enables support for quad geometries (ON by\n  default).\n\n+ `EMBREE_GEOMETRY_CURVE`: Enables support for curve geometries (ON by\n  default).\n\n+ `EMBREE_GEOMETRY_SUBDIVISION`: Enables support for subdivision\n  geometries (ON by default).\n\n+ `EMBREE_GEOMETRY_INSTANCE`: Enables support for instances (ON by\n  default).\n\n+ `EMBREE_GEOMETRY_INSTANCE_ARRAY`: Enables support for instance arrays (ON by\n  default).\n\n+ `EMBREE_GEOMETRY_USER`: Enables support for user-defined geometries\n  (ON by default).\n\n+ `EMBREE_GEOMETRY_POINT`: Enables support for point geometries\n  (ON by default).\n\n+ `EMBREE_CURVE_SELF_INTERSECTION_AVOIDANCE_FACTOR`: Specifies a\n  factor that controls the self-intersection avoidance feature for flat\n  curves. Flat curve intersections which are closer than\n  curve_radius*`EMBREE_CURVE_SELF_INTERSECTION_AVOIDANCE_FACTOR` to\n  the ray origin are ignored. A value of 0.0f disables self-intersection\n  avoidance while 2.0f is the default value.\n\n+ `EMBREE_DISC_POINT_SELF_INTERSECTION_AVOIDANCE`: Enables self-intersection\n  avoidance for RTC_GEOMETRY_TYPE_DISC_POINT geometry type (ON by default).\n  When enabled intersections are skipped if the ray origin lies inside the\n  sphere defined by the point primitive.\n\n+ `EMBREE_MIN_WIDTH`: Enabled the min-width feature, which allows\n  increasing the radius of curves and points to match some amount of\n  pixels. See [rtcSetGeometryMaxRadiusScale] for more details.\n\n+ `EMBREE_MAX_INSTANCE_LEVEL_COUNT`: Specifies the maximum number of nested\n  instance levels. Should be greater than 0; the default value is 1.\n  Instances nested any deeper than this value will silently disappear in\n  release mode, and cause assertions in debug mode.\n\n\n\n\n# Embree API\n\nThe Embree API is a low-level C99 ray tracing API which can be used to\nbuild spatial index structures for 3D scenes and perform ray queries of\ndifferent types.\n\nThe API can get used on the CPU using standard C, C++, and ISPC code\nand Intel GPUs by using SYCL code.\n\nThe Intel® Implicit SPMD Program Compiler (Intel® ISPC) version of the\nAPI, is almost identical to the standard C99 version, but contains\nadditional functions that operate on ray packets with a size of the\nnative SIMD width used by Intel® ISPC.\n\nThe SYCL version of the API is also mostly identical to the C99 version\nof the API, with some exceptions listed in section [Embree SYCL API].\n\nFor simplicity this document refers to the C99 version of the API\nfunctions. For changes when upgrading from the Embree 3 to the current\nEmbree 4 API see Section [Upgrading from Embree 3 to Embree 4].\n\nAll API calls carry the prefix `rtc` (or `RTC` for types) which stands\nfor **r**ay **t**racing **c**ore. The API supports scenes consisting of\ndifferent geometry types such as triangle meshes, quad meshes (triangle\npairs), grid meshes, flat curves, round curves, oriented curves,\nsubdivision meshes, instances, and user-defined geometries. See Section\n[Scene Object](#scene-object) for more information.\n\nFinding the closest hit of a ray segment with the scene\n(`rtcIntersect`-type functions), and determining whether any hit\nbetween a ray segment and the scene exists (`rtcOccluded`-type\nfunctions) are both supported. The API supports queries for single rays\nand ray packets. See Section [Ray Queries](#ray-queries) for more\ninformation.\n\nThe API is designed in an object-oriented manner, e.g. it contains\ndevice objects (`RTCDevice` type), scene objects (`RTCScene` type),\ngeometry objects (`RTCGeometry` type), buffer objects (`RTCBuffer`\ntype), and BVH objects (`RTCBVH` type). All objects are reference\ncounted, and handles can be released by calling the appropriate release\nfunction (e.g. `rtcReleaseDevice`) or retained by incrementing the\nreference count (e.g. `rtcRetainDevice`). In general, API calls that\naccess the same object are not thread-safe, unless specified otherwise.\nHowever, attaching geometries to the same scene and performing ray\nqueries in a scene is thread-safe.\n\nStarting with Embree 4.4 intersection and occlusion queries on a SYCL\ndevice require the use of the `rtcTraversableIntersect`-type functions\nor the `rtcTraversableOccluded`-type function respectively. These\nfunctions take a traversable object (`RTCTraversable` type) which\ncorresponds to a `RTCScene`. Traversable objects are not reference\ncounted and therefore they do not have to be released like the other\nhandles. Traversable objects grant read-only access to a scene object\non a SYCL device and are valid as long as the corresponding scene\nobject is valid.\n\n## Device Object\n\nEmbree supports a device concept, which allows different components of\nthe application to use the Embree API without interfering with each\nother. An application typically first creates a device using the\n[rtcNewDevice] function (or [rtcNewSYCLDevice] when using SYCL for\nthe GPU). This device can then be used to construct further objects,\nsuch as scenes and geometries. Before the application exits, it should\nrelease all devices by invoking [rtcReleaseDevice]. An application\ntypically creates only a single device. If required differently, it\nshould only use a small number of devices at any given time.\n\nEach user thread has its own error flag per device. If an error occurs\nwhen invoking an API function, this flag is set to an error code (if it\nisn't already set by a previous error). See Section\n[rtcGetDeviceError] for information on how to read the error code and\nSection [rtcSetDeviceErrorFunction] on how to register a callback\nthat is invoked for each error encountered. It is recommended to always\nset a error callback function, to detect all errors.\n\n## Scene Object\n\nA scene is a container for a set of geometries, and contains a spatial\nacceleration structure which can be used to perform different types of\nray queries.\n\nA scene is created using the `rtcNewScene` function call, and released\nusing the `rtcReleaseScene` function call. To populate a scene with\ngeometries use the `rtcAttachGeometry` call, and to detach them use the\n`rtcDetachGeometry` call. Once all scene geometries are attached, an\n`rtcCommitScene` call (or `rtcJoinCommitScene` call) will finish the\nscene description and trigger building of internal data structures.\nAfter the scene got committed, it is safe to perform ray queries (see\nSection [Ray Queries](#ray-queries)) or to query the scene bounding box\n(see [rtcGetSceneBounds] and [rtcGetSceneLinearBounds]).\n\nIf scene geometries get modified or attached or detached, the\n`rtcCommitScene` call must be invoked before performing any further ray\nqueries for the scene; otherwise the effect of the ray query is\nundefined. The modification of a geometry, committing the scene, and\ntracing of rays must always happen sequentially, and never at the same\ntime. Any API call that sets a property of the scene or geometries\ncontained in the scene count as scene modification, e.g. including\nsetting of intersection filter functions.\n\nWhen using SYCL, calls to `rtcCommitScene` trigger memory transfers\nfrom the host (CPU) to the device (GPU). Calling `rtcCommitScene` will\nbe blocking and return only after the memory transfers are completed.\nEmbree also provides the function `rtcCommitSceneWithQueue` which takes\na SYCL queue as argument to which the memory transfer operations are\nsubmitted. Calling `rtcCommitSceneWithQueue` will trigger the memory\ntransfers asynchronously and the application is responsible for\nsychronizing command on the queue properly to ensure the scene data is\navailable on a SYCL device when a SYCL kernels performs intersection\nqueries that rely on the scene data.\n\nScene flags can be used to configure a scene to use less memory\n(`RTC_SCENE_FLAG_COMPACT`), use more robust traversal algorithms\n(`RTC_SCENE_FLAG_ROBUST`), and to optimize for dynamic content. See\nSection [rtcSetSceneFlags] for more details.\n\nA build quality can be specified for a scene to balance between\nacceleration structure build performance and ray query performance. See\nSection [rtcSetSceneBuildQuality] for more details on build quality.\n\n## Traversable Object\n\nStarting with Embree 4.4 scene objects (`RTCScene` types) are not valid\nhandles on SYCL devices anymore and therefore can not be used for\nEmbree API calls in a SYCL kernel. Instead, Embree API calls on a SYCL\nkernel have a variation which use traversable objects (`RTCTraversable`\ntype).\n\nTraversable objects grant read-only access to a scene object on a SYCL\ndevice and are valid as long as the corresponding scene object is\nvalid. They can be queried from a scene object using the\n`rtcGetSceneTraversable` function and used in\n`rtcTraversableIntersect`-type functions or the\n`rtcTraversableOccluded`-type function. They can also be used in CPU\ncode and Embree provides other API calls such as the\n`rtcTraversablePointQuery` (which are not currently implemented for\nSYCL) to help write portable code compatible with CPU and SYCL device\nexecution.\n\n## Geometry Object\n\nA new geometry is created using the `rtcNewGeometry` function.\nDepending on the geometry type, different buffers must be bound (e.g.\nusing `rtcSetSharedGeometryBuffer`) to set up the geometry data. In\nmost cases, binding of a vertex and index buffer is required. The\nnumber of primitives and vertices of that geometry is typically\ninferred from the size of these bound buffers.\n\nChanges to the geometry always must be committed using the\n`rtcCommitGeometry` call before using the geometry. After committing, a\ngeometry is not included in any scene. A geometry can be added to a\nscene by using the `rtcAttachGeometry` function (to automatically\nassign a geometry ID) or using the `rtcAttachGeometryById` function (to\nspecify the geometry ID manually). A geometry can get attached to\nmultiple scenes.\n\nAll geometry types support multi-segment motion blur with an arbitrary\nnumber of equidistant time steps (in the range of 2 to 129) inside a\nuser specified time range. Each geometry can have a different number of\ntime steps and a different time range. The motion blur geometry is\ndefined by linearly interpolating the geometries of neighboring time\nsteps. To construct a motion blur geometry, first the number of time\nsteps of the geometry must be specified using the\n`rtcSetGeometryTimeStepCount` function, and then a vertex buffer for\neach time step must be bound, e.g. using the\n`rtcSetSharedGeometryBuffer` function. Optionally, a time range\ndefining the start (and end time) of the first (and last) time step can\nbe set using the `rtcSetGeometryTimeRange` function. This feature will\nalso allow geometries to appear and disappear during the camera shutter\ntime if the time range is a sub range of [0,1].\n\n## Ray Queries\n\nThe API supports finding the closest hit of a ray segment with the\nscene (`rtcIntersect`-type functions), and determining whether any hit\nbetween a ray segment and the scene exists (`rtcOccluded`-type\nfunctions).\n\nSupported are single ray queries (`rtcIntersect1` and `rtcOccluded1`)\nas well as ray packet queries for ray packets of size 4\n(`rtcIntersect4` and `rtcOccluded4`), ray packets of size 8\n(`rtcIntersect8` and `rtcOccluded8`), and ray packets of size 16\n(`rtcIntersect16` and `rtcOccluded16`).\n\nSee Sections [rtcIntersect1] and [rtcOccluded1] for a detailed\ndescription of how to set up and trace a ray.\n\nSee tutorial [Triangle Geometry] for a complete example of how to\ntrace single rays and ray packets.\n\nOn SYCL devices the API functions `rtcTraversableIntersect` and\n`rtcTraversableOccluded` have to be used.\n\n## Point Queries\n\nThe API supports traversal of the BVH using a point query object that\nspecifies a location and a query radius. For all primitives\nintersecting the according domain, a user defined callback function is\ncalled which allows queries such as finding the closest point on the\nsurface geometries of the scene (see Tutorial [Closest Point]) or\nnearest neighbour queries (see Tutorial [Voronoi]).\n\nPoint Queries can currently not be used on SYCL devices.\n\nSee Section [rtcPointQuery] for a detailed description of how to set\nup point queries.\n\n## Collision Detection\n\nThe Embree API also supports collision detection queries between two\nscenes consisting only of user geometries. Embree only performs\nbroadphase collision detection, the narrow phase detection can be\nperformed through a callback function.\n\nCollision detection can currently not be used on SYCL devices.\n\nSee Section [rtcCollide] for a detailed description of how to set up\ncollision detection.\n\nSeen tutorial [Collision Detection](#collision-detection) for a\ncomplete example of collision detection being used on a simple cloth\nsolver.\n\n## Filter Functions\n\nThe API supports filter functions that are invoked for each\nintersection found during the `rtcIntersect`-type or `rtcOccluded`-type\ncalls.\n\nThe filter functions can be set per-geometry using the\n`rtcSetGeometryIntersectFilterFunction` and\n`rtcSetGeometryOccludedFilterFunction` calls. The former ones are\ncalled geometry intersection filter functions, the latter ones geometry\nocclusion filter functions. These filter functions are designed to be\nused to ignore intersections outside of a user-defined silhouette of a\nprimitive, e.g. to model tree leaves using transparency textures.\n\nThe filter function can also get passed as arguments directly to the\ntraversal functions, see section [rtcInitIntersectArguments] and\n[rtcInitOccludedArguments] for more details. These argument filter\nfunctions are designed to change the semantics of the ray query,\ne.g. to accumulate opacity for transparent shadows, count the number of\nsurfaces along a ray, collect all hits along a ray, etc. The argument\nfilter function must be enabled to be used for a scene using the\n`RTC_SCENE_FLAG_FILTER_FUNCTION_IN_ARGUMENTS` scene flag. The callback\nis only invoked for geometries that enable the callback using the\n`rtcSetGeometryEnableFilterFunctionFromArguments` call, or enabled for\nall geometries when the `RTC_RAY_QUERY_FLAG_INVOKE_ARGUMENT_FILTER` ray\nquery flag is set.\n\n## BVH Build API\n\nThe internal algorithms to build a BVH are exposed through the `RTCBVH`\nobject and `rtcBuildBVH` call. This call makes it possible to build a\nBVH in a user-specified format over user-specified primitives. See the\ndocumentation of the `rtcBuildBVH` call for more details.\n\n# Embree SYCL API\n\nEmbree supports ray tracing on Intel GPUs by using the SYCL programming\nlanguage. SYCL is a Khronos standardized C++ based language for single\nsource heterogenous programming for acceleration offload, see the [SYCL\nwebpage](https://www.khronos.org/sycl/) for details.\n\nThe Embree SYCL API is designed for photorealistic rendering use cases,\nwhere scene setup is performed on the host, and rendering on the\ndevice. The Embree SYCL API is very similar to the standard Embree C99\nAPI, and supports most of its features, such as all triangle-type\ngeometries, all curve types and basis functions, point geometry types,\nuser geometries, filter callbacks, multi-level instancing, and motion\nblur.\n\nTo enable SYCL support you have to include the `sycl.hpp` file before\nthe Embree API headers:\n\n    #include \u003csycl/sycl.hpp\u003e\n    #include \u003cembree4/rtcore.h\u003e\n\nNext you need to initializes an Embree SYCL device using the\n`rtcNewSYCLDevice` API function by providing a SYCL context.\n\nEmbree provides the `rtcIsSYCLDeviceSupported` API function to check if\nsome SYCL device is supported by Embree. You can also use the\n`rtcSYCLDeviceSelector` to conveniently select the first SYCL device\nthat is supported by Embree, e.g.:\n\n    sycl::device device(rtcSYCLDeviceSelector);\n    sycl::queue queue(device, exception_handler);\n    sycl::context context(device);\n    RTCDevice device = rtcNewSYCLDevice(context,\"\");\n\nScenes created with an Embree SYCL device can only get used to trace\nrays using SYCL on the GPU, it is not possible to trace rays on the CPU\nwith such a device. To render on the CPU and GPU in parallel, the user\nhas to create a second Embree device and create a second scene to be\nused on the CPU.\n\nStarting with Embree 4.4 scene objects (`RTCScene` types) are not valid\nhandles on SYCL devices anymore and therefore can not be used for\nEmbree API calls in a SYCL kernel. Instead, Embree API calls on a SYCL\nkernel have a variation which use traversable objects (`RTCTraversable`\ntype). To get a traversable object for a scene object the application\ncan call `rtcGetSceneTraversable`.\n\nFiles containing SYCL code, have to get compiled with the Intel® oneAPI\nDPC++ compiler. Please see section [Linux SYCL Compilation] and\n[Windows SYCL Compilation] for supported compilers. The DPC++\ncompiler performs a two-phase compilation, where host code is compiled\nin a first phase, and device code compiled in a second compilation\nphase.\n\nStandard Embree API functions for scene construction can get used on\nthe host but not the device.\n\nBefore version 4.4, Embree made heavy use of unified shared memory\n(USM) shared memory which simplifies memory management with SYCL\ndevices by letting the SYCL runtime transfer data from host to device\nimplicitly. However, some applications require more control over when\nand how data is migrated from CPU to GPU. Embree 4.4 allows to use\nexplicit host and device memory allocations. See for example\n`rtcSetNewGeometryBufferHostDevice`,\n`rtcSetSharedGeometryBufferHostDevice`, `rtcNewBufferHostDevice`, and\n`rtcNewSharedBufferHostDevice`. It is still possible to share data\nbuffers with Embree using SYCL USM shared memory by using the API calls\nwithout the `HostDevice` suffix.\n\nThe easiest way to share data buffers with Embree (e.g. for vertex of\nindex buffers) is to allocate the data as USM shared memory, using the\n`sycl::malloc` or `sycl::aligned_alloc` calls with\n`sycl::usm::alloc::shared` property, or the sycl::aligned_alloc_shared\ncall, e.g:\n\n    void* ptr = sycl::aligned_alloc(16, bytes, queue, sycl::usm::alloc::shared);\n\nThese shared allocations have to be valid during rendering, as Embree\nmay access contained data when tracing rays.\n\nDevice side rendering can get invoked by submitting a SYCL\n`parallel_for` to the SYCL queue:\n\n    const sycl::specialization_id\u003cRTCFeatureFlags\u003e feature_mask;\n\n    RTCFeatureFlags required_features = RTC_FEATURE_FLAG_TRIANGLE;\n\n    RTCTraversable traversable = rtcGetSceneTraversable(scene);\n\n    queue.submit([=](sycl::handler\u0026 cgh)\n    {\n      cgh.set_specialization_constant\u003cfeature_mask\u003e(required_features);\n      \n      cgh.parallel_for(sycl::range\u003c1\u003e(1),[=](sycl::id\u003c1\u003e item, sycl::kernel_handler kh)\n      {\n        RTCIntersectArguments args;\n        rtcInitIntersectArguments(\u0026args);\n\n        const RTCFeatureFlags features = kh.get_specialization_constant\u003cfeature_mask\u003e();\n        args.feature_mask = features;\n\n        struct RTCRayHit rayhit;\n        rayhit.ray.org_x = ox;\n        rayhit.ray.org_y = oy;\n        rayhit.ray.org_z = oz;\n        rayhit.ray.dir_x = dx;\n        rayhit.ray.dir_y = dy;\n        rayhit.ray.dir_z = dz;\n        rayhit.ray.tnear = 0;\n        rayhit.ray.tfar = std::numeric_limits\u003cfloat\u003e::infinity();\n        rayhit.ray.mask = -1;\n        rayhit.ray.flags = 0;\n        rayhit.hit.geomID = RTC_INVALID_GEOMETRY_ID;\n        rayhit.hit.instID[0] = RTC_INVALID_GEOMETRY_ID;\n\n        rtcTraversableIntersect1(traversable, \u0026rayhit, \u0026args);\n\n        result-\u003egeomID = rayhit.hit.geomID;\n        result-\u003eprimID = rayhit.hit.primID;\n        result-\u003etfar = rayhit.ray.tfar;\n      });\n    });\n    queue.wait_and_throw();\n\nThis example passes a feature mask using a specialization constant to\nthe `rtcTraversableIntersect1` function, which is recommended for GPU\nrendering. For best performance, this feature mask should get used to\nenable only features required by the application to render the scene,\ne.g. just triangles in this example.\n\nInside the SYCL `parallel_for` loop you can use rendering related\nfunctions, such as the `rtcTraversableIntersect1` and\n`rtcTraversableOccluded1` functions to trace rays,\n`rtcTraversableForwardIntersect1/Ex` and\n`rtcTraversableForwardOccluded1/Ex` to continue object traversal from\ninside a user geometry callback, and\n`rtcGetGeometryUserDataFromTraversable` to get the user data pointer of\nsome geometry.\n\nHave a look at the [Minimal] tutorial for a minimal SYCL example and\nthe [Host Device Memory] tutorial shows four different ways in which\ndata buffers can be created by or shared with Embree using explicit\nhost/device data buffers.\n\n## SYCL JIT caching\n\nCompile times for just in time compilation (JIT compilation) can be\nlarge. To resolve this issue we recommend enabling persistent JIT\ncompilation caching inside your application, by setting the\n`SYCL_CACHE_PERSISTENT` environment variable to `1`, and the\n`SYCL_CACHE_DIR` environment variable to some proper directory where\nthe JIT cache should get stored. These environment variables have to\nget set before the SYCL device is created, e.g:\n\n    setenv(\"SYCL_CACHE_PERSISTENT\",\"1\",1);\n    setenv(\"SYCL_CACHE_DIR\",\"cache_dir\",1);\n\n    sycl::device device(rtcSYCLDeviceSelector);\n    ...\n\n## SYCL Memory Pooling\n\nMemory Pooling is a mechanism where small USM memory allocations are\npacked into larger allocation blocks. This mode is required when your\napplication performs many small USM allocations, as otherwise only a\nsmall fraction of GPU memory is usable and data transfer performance\nwill be low.\n\nMemory pooling is supported for USM allocations that are read-only by\nthe device. The following example allocated device read-only memory\nwith memory pooling support:\n\n    sycl::aligned_alloc_shared(align, bytes, queue,\n      sycl::ext::oneapi::property::usm::device_read_only());\n\n## Embree SYCL Limitations\n\nEmbree only supports Xe HPC and HPG GPUs as SYCL devices, thus in\nparticular the CPU and other GPUs cannot get used as a SYCL device. To\nrender on the CPU just use the standard C99 API without relying on\nSYCL.\n\nThe SYCL language spec puts some restrictions to device functions, such\nas disallowing: global variable access, malloc, invocation of virtual\nfunctions, function pointers, runtime type information, exceptions,\nrecursion, etc. See Section\n`5.4. Language Restrictions for device functions` of the [SYCL\nspecification](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:language.restrictions.kernels)\nfor more details.\n\nUsing Intel's oneAPI DPC++ compiler invoking an indirectly called\nfunction is allowed, but we do not recommend this for performance\nreasons.\n\nSome features are not supported by the Embree SYCL API thus cannot get\nused on the GPU:\n\n-   Since Embree 4.4, all the ray query functions that take an\n    `RTCScene` object as argument cannot get used in SYCL device side\n    code. Instead, the API functions taking a `RTCTraversable` object\n    (e.g. `rtcTraversableIntersect1`) have to be used.\n\n-   The packet tracing functions `rtcTraversableIntersect4/8/16` and\n    `rtcTraversableOccluded4/8/16` are not supported in SYCL device\n    side code. Using these functions makes no sense for SYCL, as the\n    programming model is implicitly executed in SIMT mode on the GPU\n    anyway.\n\n-   Filter and user geometry callbacks stored inside the geometry\n    objects are not supported on SYCL. Please use the alternative\n    approach of passing the function pointer through the\n    `RTCIntersectArguments` (or `RTCOccludedArguments`) structures to\n    the tracing function, which enables inlining on the GPU.\n\n-   The `rtcInterpolate` function cannot get used on the the device.\n    For most primitive types the vertex data interpolation is anyway a\n    trivial operation, and an API call just introduces overheads. On\n    the CPU that overhead is acceptable, but on the GPU it is not. The\n    `rtcInterpolate` function does not know the geometry type it is\n    interpolating over, thus its implementation on the GPU would\n    contain a large switch statement for all potential geometry types.\n\n-   Tracing rays using `rtcTraversableIntersect1` and\n    `rtcTraversableOccluded1` functions from user geometry callbacks is\n    not supported in SYCL. Please use the tail recursive\n    `rtcTraversableForwardIntersect1` and\n    `rtcTraversableForwardOccluded1` calls instead.\n\n-   Subdivision surfaces are not supported for Embree SYCL devices.\n\n-   Collision detection (`rtcCollide` API call) is not supported in\n    SYCL device side code.\n\n-   Point queries (`rtcPointQuery` API call) are not supported in SYCL\n    device side code.\n\n## Embree SYCL Known Issues\n\n-   Compilation with build configuration \"debug\" is currently not\n    feasible because compilation times are very long.\n\n# Upgrading from Embree 3 to Embree 4\n\nThis section summarizes API changes between Embree 3 and Embree4. Most\nof these changes are motivated by GPU performance and having a\nconsistent API that works properly for the CPU and GPU.\n\n-   The API include folder got renamed from embree3 to embree4, to be\n    able to install Embree 3 and Embree 4 side by side, without having\n    conflicts in API folder.\n\n-   The `RTCIntersectContext` is renamed to `RTCRayQueryContext` and\n    the `RTCIntersectContextFlags` got renamed to `RTCRayQueryFlags`.\n\n-   There are some changes to the `rtcIntersect` and `rtcOccluded`\n    functions. Most members of the old intersect context have been\n    moved to some optional `RTCIntersectArguments` (and\n    `RTCOccludedArguments`) structures, which also contains a pointer\n    to the new ray query context. The argument structs fulfill the task\n    of providing additional advanced arguments to the traversal\n    functions. The ray query context can get used to pass additional\n    data to callbacks, and to maintain an instID stack in case\n    instancing is done manually inside user geometry callbacks. The\n    arguments struct is not available inside callbacks. This change was\n    in particular necessary for SYCL to allow inlining of function\n    pointers provided to the traversal functions, and to reduce the\n    amount of state passed to callbacks, which both improves GPU\n    performance. Most applications can just drop passing the ray query\n    context to port to Embree 4.\n\n-   The `rtcFilterIntersection` and `rtcFilterOcclusion` API calls that\n    invoke both, the geometry and argument version of the filter\n    callback, from a user geometry callback are no longer supported.\n    Instead applications should use the\n    `rtcInvokeIntersectFilterFromGeometry` and\n    `rtcInvokeOccludedFilterFromGeometry` API calls that invoke just\n    the geometry version of the filter function, and invoke the\n    argument filter function manually if required.\n\n-   The filter function passed as arguments to `rtcIntersect` and\n    `rtcOccluded` functions is only invoked for some geometry if\n    enabled through `rtcSetGeometryEnableFilterFunctionFromArguments`\n    for that geometry. Alternatively, argument filter functions can get\n    enabled for all geometries using the\n    `RTC_RAY_QUERY_FLAG_INVOKE_ARGUMENT_FILTER` ray query flag.\n\n-   User geometry callbacks get a valid vector as input to identify\n    valid and invalid rays. In Embree 3 the user geometry callback just\n    had to update the ray hit members when an intersection was found\n    and perform no operation otherwise. In Embree 4 the callback\n    additionally has to return valid=-1 when a hit was found, and\n    valid=0 when no hit was found. This allows Embree to properly pass\n    the new hit distance to the ray tracing hardware only in the case a\n    hit was found.\n\n-   Further ray masking is enabled by default now as required by most\n    applications and the default ray mask for geometries got changed\n    from 0xFFFFFFFF to 0x1.\n\n-   The stream tracing functions `rtcIntersect1M`, `rtcIntersect1Mp`,\n    `rtcIntersectNM`, `rtcIntersectNp`, `rtcOccluded1M`,\n    `rtcOccluded1Mp`, `rtcOccludedNM`, and `rtcOccludedNp` got removed\n    as they were rarely used and did not provide relevant performance\n    benefits. As alternative the application can just iterate over\n    `rtcIntersect1` and potentially `rtcIntersect4/8/16` to get similar\n    performance.\n\nTo use Embree through SYCL on the CPU and GPU additional changes are\nrequired:\n\n-   Embree 3 allows to use `rtcIntersect` recursively from a user\n    geometry or intersection filter callback to continue a ray inside\n    an instantiated object. In Embree 4 using `rtcIntersect`\n    recursively is disallowed on the GPU but still supported on the\n    CPU. To properly continue a ray inside an instantiated object use\n    the new `rtc(Traversable)ForwardIntersect1` and\n    `rtc(Traversable)ForwardOccluded1` functions.\n\n-   The geometry object and scene object of Embree 4 are a host side\n    only objects, thus accessing it during rendering from the GPU is\n    not allowed. Thus all API functions that take an RTCGeometry object\n    or RTCScene object as argument cannot get used during rendering. In\n    particular the `rtcGetGeometryUserData(RTCGeometry)` call cannot\n    get used, but there is an alternative function\n    `rtcGetGeometryUserDataFromTraversable(RTCTraversable traversable,uint geomID)`\n    that should get used instead. To perform ray queries on the GPU\n    (e.g. `rtcTraversableIntersect1`) the application has to get a\n    `RTCTraversable` object first (using `rtcGetSceneTraversable`) and\n    pass it to the SYCL kernel.\n\n-   The user geometry callback and filter callback functions should get\n    passed through the intersection and occlusion argument structures\n    to the `rtcTraversableIntersect1` and `rtcTraversableOccluded1`\n    functions directly to allow inlining. The experimental geometry\n    version of the callbacks is disabled in SYCL and should not get\n    used.\n\n-   The feature flags should get used in SYCL to minimal GPU code for\n    optimal performance.\n\n-   The `rtcInterpolate` function cannot get used on the device, and\n    vertex data interpolation should get implemented by the\n    application.\n\n-   Indirectly called functions must be declared with\n    `RTC_SYCL_INDIRECTLY_CALLABLE` when used as filter or user geometry\n    callbacks.\n\n```{=tex}\n\n```\n# Embree API Reference\n\n## rtcNewDevice\n\n#### NAME\n\n    rtcNewDevice - creates a new device\n\n#### SYNOPSIS\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    RTCDevice rtcNewDevice(const char* config);\n\n#### DESCRIPTION\n\nThis function creates a new device to be used for CPU ray tracing and\nreturns a handle to this device. The device object is reference counted\nwith an initial reference count of 1. The handle can be released using\nthe `rtcReleaseDevice` API call.\n\nThe device object acts as a class factory for all other object types.\nAll objects created from the device (like scenes, geometries, etc.)\nhold a reference to the device, thus the device will not be destroyed\nunless these objects are destroyed first.\n\nObjects are only compatible if they belong to the same device, e.g it\nis not allowed to create a geometry in one device and attach it to a\nscene created with a different device.\n\nA configuration string (`config` argument) can be passed to the device\nconstruction. This configuration string can be `NULL` to use the\ndefault configuration.\n\nThe following configuration is supported:\n\n-   `threads=[int]`: Specifies a number of build threads to use. A\n    value of 0 enables all detected hardware threads. By default all\n    hardware threads are used.\n\n-   `user_threads=[int]`: Sets the number of user threads that can be\n    used to join and participate in a scene commit using\n    `rtcJoinCommitScene`. The tasking system will only use\n    threads-user_threads many worker threads, thus if the app wants to\n    solely use its threads to commit scenes, just set threads equal to\n    user_threads. This option only has effect with the Intel(R)\n    Threading Building Blocks (TBB) tasking system.\n\n-   `set_affinity=[0/1]`: When enabled, build threads are affinitized\n    to hardware threads. This option is disabled by default on standard\n    CPUs, and enabled by default on Xeon Phi Processors.\n\n-   `start_threads=[0/1]`: When enabled, the build threads are started\n    upfront. This can be useful for benchmarking to exclude thread\n    creation time. This option is disabled by default.\n\n-   `isa=[sse2,sse4.2,avx,avx2,avx512]`: Use specified ISA. By default\n    the ISA is selected automatically.\n\n-   `max_isa=[sse2,sse4.2,avx,avx2,avx512]`: Configures the automated\n    ISA selection to use maximally the specified ISA.\n\n-   `hugepages=[0/1]`: Enables or disables usage of huge pages. Under\n    Linux huge pages are used by default but under Windows and macOS\n    they are disabled by default.\n\n-   `enable_selockmemoryprivilege=[0/1]`: When set to 1, this enables\n    the `SeLockMemoryPrivilege` privilege with is required to use huge\n    pages on Windows. This option has an effect only under Windows and\n    is ignored on other platforms. See Section [Huge Page Support]\n    for more details.\n\n-   `verbose=[0,1,2,3]`: Sets the verbosity of the output. When set to\n    0, no output is printed by Embree, when set to a higher level more\n    output is printed. By default Embree does not print anything on the\n    console.\n\n-   `frequency_level=[simd128,simd256,simd512]`: Specifies the\n    frequency level the application want to run on, which can be\n    either:\n\n    a)  simd128 to run at highest frequency\n    b)  simd256 to run at AVX2-heavy frequency level\n    c)  simd512 to run at heavy AVX512 frequency level. When some\n        frequency level is specified, Embree will avoid doing\n        optimizations that may reduce the frequency level below the\n        level specified. E.g. if your app does not use AVX instructions\n        setting \"frequency_level=simd128\" will cause some CPUs to run\n        at highest frequency, which may result in higher application\n        performance if you do much shading. If you application heavily\n        uses AVX code, you should best set the frequency level to\n        simd256. Per default Embree tries to avoid reducing the\n        frequency of the CPU by setting the simd256 level only when the\n        CPU has no significant down clocking.\n\nDifferent configuration options should be separated by commas, e.g.:\n\n    rtcNewDevice(\"threads=1,isa=avx\");\n\n#### EXIT STATUS\n\nOn success returns a handle of the created device. On failure returns\n`NULL` as device and sets a per-thread error code that can be queried\nusing `rtcGetDeviceError(NULL)`.\n\n#### SEE ALSO\n\n[rtcRetainDevice], [rtcReleaseDevice], [rtcNewSYCLDevice]\n\n```{=tex}\n\n```\n## rtcNewSYCLDevice\n\n#### NAME {#name}\n\n    rtcNewSYCLDevice - creates a new device to be used with SYCL\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    RTCDevice rtcNewSYCLDevice(sycl::context context, const char* config);\n\n#### DESCRIPTION {#description}\n\nThis function creates a new device to be used with SYCL for GPU\nrendering and returns a handle to this device. The device object is\nreference counted with an initial reference count of 1. The handle can\nget released using the `rtcReleaseDevice` API call.\n\nThe passed SYCL context (`context` argument) is used to allocate GPU\ndata, thus only devices contained inside this context can be used for\nrendering. By default the GPU data is allocated on the first GPU device\nof the context, but this behavior can get changed with the\n[rtcSetDeviceSYCLDevice] function.\n\nThe device object acts as a class factory for all other object types.\nAll objects created from the device (like scenes, geometries, etc.)\nhold a reference to the device, thus the device will not be destroyed\nunless these objects are destroyed first.\n\nObjects are only compatible if they belong to the same device, e.g it\nis not allowed to create a geometry in one device and attach it to a\nscene created with a different device.\n\nFor an overview of configurations that can get passed (`config`\nargument) please see the [rtcNewDevice] function description.\n\n#### EXIT STATUS {#exit-status}\n\nOn success returns a handle of the created device. On failure returns\n`NULL` as device and sets a per-thread error code that can be queried\nusing `rtcGetDeviceError(NULL)`.\n\n#### SEE ALSO {#see-also}\n\n[rtcRetainDevice], [rtcReleaseDevice], [rtcNewDevice]\n\n```{=tex}\n\n```\n## rtcIsSYCLDeviceSupported\n\n#### NAME {#name}\n\n    rtcIsSYCLDeviceSupported - checks if some SYCL device is supported by Embree\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    bool rtcIsSYCLDeviceSupported(const sycl::device sycl_device);\n\n#### DESCRIPTION {#description}\n\nThis function can be used to check if some SYCL device (`sycl_device`\nargument) is supported by Embree.\n\n#### EXIT STATUS {#exit-status}\n\nThe function returns true if the SYCL device is supported by Embree and\nfalse otherwise. On failure an error code is set that can get queried\nusing `rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcSYCLDeviceSelector]\n\n```{=tex}\n\n```\n## rtcSYCLDeviceSelector\n\n#### NAME {#name}\n\n    rtcSYCLDeviceSelector - SYCL device selector function to select\n      devices supported by Embree\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    int rtcSYCLDeviceSelector(const sycl::device sycl_device);\n\n#### DESCRIPTION {#description}\n\nThis function checks if the passed SYCL device (`sycl_device`\narguments) is supported by Embree or not. This function can be used\ndirectly to select some supported SYCL device by using it as SYCL\ndevice selector function. For instance, the following code sequence\nselects an Embree supported SYCL device and creates an Embree device\nfrom it:\n\n    sycl::device sycl_device(rtcSYCLDeviceSelector);\n    sycl::queue sycl_queue(sycl_device);\n    sycl::context(sycl_device);\n    RTCDevice device = rtcNewSYCLDevice(sycl_context,nullptr);\n\n#### EXIT STATUS {#exit-status}\n\nThe function returns -1 if the SYCL device is supported by Embree and 1\notherwise. On failure an error code is set that can get queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcIsSYCLDeviceSupported]\n\n```{=tex}\n\n```\n## rtcSetDeviceSYCLDevice\n\n#### NAME {#name}\n\n    rtcSetDeviceSYCLDevice - sets the SYCL device to be used for memory allocations\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    void rtcSetDeviceSYCLDevice(RTCDevice device, const sycl::device sycl_device);\n\n#### DESCRIPTION {#description}\n\nThis function sets the SYCL device (`sycl_device` argument) to be used\nto allocate GPU memory when using the specified Embree device (`device`\nargument). This SYCL device must be one of the SYCL devices contained\ninside the SYCL context used to create the Embree device.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can get queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcNewSYCLDevice]\n\n```{=tex}\n\n```\n## rtcRetainDevice\n\n#### NAME {#name}\n\n    rtcRetainDevice - increments the device reference count\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    void rtcRetainDevice(RTCDevice device);\n\n#### DESCRIPTION {#description}\n\nDevice objects are reference counted. The `rtcRetainDevice` function\nincrements the reference count of the passed device object (`device`\nargument). This function together with `rtcReleaseDevice` allows to use\nthe internal reference counting in a C++ wrapper class to manage the\nownership of the object.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcNewDevice], [rtcReleaseDevice]\n\n```{=tex}\n\n```\n## rtcReleaseDevice\n\n#### NAME {#name}\n\n    rtcReleaseDevice - decrements the device reference count\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    void rtcReleaseDevice(RTCDevice device);\n\n#### DESCRIPTION {#description}\n\nDevice objects are reference counted. The `rtcReleaseDevice` function\ndecrements the reference count of the passed device object (`device`\nargument). When the reference count falls to 0, the device gets\ndestroyed.\n\nAll objects created from the device (like scenes, geometries, etc.)\nhold a reference to the device, thus the device will not get destroyed\nunless these objects are destroyed first.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcNewDevice], [rtcRetainDevice]\n\n```{=tex}\n\n```\n## rtcGetDeviceProperty\n\n#### NAME {#name}\n\n    rtcGetDeviceProperty - queries properties of the device\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    ssize_t rtcGetDeviceProperty(\n      RTCDevice device,\n      enum RTCDeviceProperty prop\n    );\n\n#### DESCRIPTION {#description}\n\nThe `rtcGetDeviceProperty` function can be used to query properties\n(`prop` argument) of a device object (`device` argument). The returned\nproperty is an integer of type `ssize_t`.\n\nPossible properties to query are:\n\n-   `RTC_DEVICE_PROPERTY_VERSION`: Queries the combined version number\n    (MAJOR.MINOR.PATCH) with two decimal digits per component. E.g. for\n    Embree 2.8.3 the integer 208003 is returned.\n\n-   `RTC_DEVICE_PROPERTY_VERSION_MAJOR`: Queries the major version\n    number of Embree.\n\n-   `RTC_DEVICE_PROPERTY_VERSION_MINOR`: Queries the minor version\n    number of Embree.\n\n-   `RTC_DEVICE_PROPERTY_VERSION_PATCH`: Queries the patch version\n    number of Embree.\n\n-   `RTC_DEVICE_PROPERTY_NATIVE_RAY4_SUPPORTED`: Queries whether the\n    `rtcIntersect4` and `rtcOccluded4` functions preserve packet size\n    and ray order when invoking callback functions. This is only the\n    case if Embree is compiled with `EMBREE_RAY_PACKETS` and `SSE2` (or\n    `SSE4.2`) enabled, and if the machine it is running on supports\n    `SSE2` (or `SSE4.2`).\n\n-   `RTC_DEVICE_PROPERTY_NATIVE_RAY8_SUPPORTED`: Queries whether the\n    `rtcIntersect8` and `rtcOccluded8` functions preserve packet size\n    and ray order when invoking callback functions. This is only the\n    case if Embree is compiled with `EMBREE_RAY_PACKETS` and `AVX` (or\n    `AVX2`) enabled, and if the machine it is running on supports `AVX`\n    (or `AVX2`).\n\n-   `RTC_DEVICE_PROPERTY_NATIVE_RAY16_SUPPORTED`: Queries whether the\n    `rtcIntersect16` and `rtcOccluded16` functions preserve packet size\n    and ray order when invoking callback functions. This is only the\n    case if Embree is compiled with `EMBREE_RAY_PACKETS` and `AVX512`\n    enabled, and if the machine it is running on supports `AVX512`.\n\n-   `RTC_DEVICE_PROPERTY_RAY_MASK_SUPPORTED`: Queries whether ray masks\n    are supported. This is only the case if Embree is compiled with\n    `EMBREE_RAY_MASK` enabled.\n\n-   `RTC_DEVICE_PROPERTY_BACKFACE_CULLING_ENABLED`: Queries whether\n    back face culling is enabled. This is only the case if Embree is\n    compiled with `EMBREE_BACKFACE_CULLING` enabled.\n\n-   `RTC_DEVICE_PROPERTY_BACKFACE_CULLING_CURVES_ENABLED`: Queries\n    whether back face culling for curves is enabled. This is only the\n    case if Embree is compiled with `EMBREE_BACKFACE_CULLING_CURVES`\n    enabled.\n\n-   `RTC_DEVICE_PROPERTY_BACKFACE_CULLING_SPHERES_ENABLED`: Queries\n    whether back face culling for spheres is enabled. This is only the\n    case if Embree is compiled with `EMBREE_BACKFACE_CULLING_SPHERES`\n    enabled.\n\n-   `RTC_DEVICE_PROPERTY_COMPACT_POLYS_ENABLED`: Queries whether\n    compact polys is enabled. This is only the case if Embree is\n    compiled with `EMBREE_COMPACT_POLYS` enabled.\n\n-   `RTC_DEVICE_PROPERTY_FILTER_FUNCTION_SUPPORTED`: Queries whether\n    filter functions are supported, which is the case if Embree is\n    compiled with `EMBREE_FILTER_FUNCTION` enabled.\n\n-   `RTC_DEVICE_PROPERTY_IGNORE_INVALID_RAYS_ENABLED`: Queries whether\n    invalid rays are ignored, which is the case if Embree is compiled\n    with `EMBREE_IGNORE_INVALID_RAYS` enabled.\n\n-   `RTC_DEVICE_PROPERTY_TRIANGLE_GEOMETRY_SUPPORTED`: Queries whether\n    triangles are supported, which is the case if Embree is compiled\n    with `EMBREE_GEOMETRY_TRIANGLE` enabled.\n\n-   `RTC_DEVICE_PROPERTY_QUAD_GEOMETRY_SUPPORTED`: Queries whether\n    quads are supported, which is the case if Embree is compiled with\n    `EMBREE_GEOMETRY_QUAD` enabled.\n\n-   `RTC_DEVICE_PROPERTY_SUBDIVISION_GEOMETRY_SUPPORTED`: Queries\n    whether subdivision meshes are supported, which is the case if\n    Embree is compiled with `EMBREE_GEOMETRY_SUBDIVISION` enabled.\n\n-   `RTC_DEVICE_PROPERTY_CURVE_GEOMETRY_SUPPORTED`: Queries whether\n    curves are supported, which is the case if Embree is compiled with\n    `EMBREE_GEOMETRY_CURVE` enabled.\n\n-   `RTC_DEVICE_PROPERTY_POINT_GEOMETRY_SUPPORTED`: Queries whether\n    points are supported, which is the case if Embree is compiled with\n    `EMBREE_GEOMETRY_POINT` enabled.\n\n-   `RTC_DEVICE_PROPERTY_USER_GEOMETRY_SUPPORTED`: Queries whether user\n    geometries are supported, which is the case if Embree is compiled\n    with `EMBREE_GEOMETRY_USER` enabled.\n\n-   `RTC_DEVICE_PROPERTY_TASKING_SYSTEM`: Queries the tasking system\n    Embree is compiled with. Possible return values are:\n\n    0.  internal tasking system\n    1.  Intel Threading Building Blocks (TBB)\n    2.  Parallel Patterns Library (PPL)\n\n-   `RTC_DEVICE_PROPERTY_JOIN_COMMIT_SUPPORTED`: Queries whether\n    `rtcJoinCommitScene` is supported. This is not the case when Embree\n    is compiled with PPL or older versions of TBB.\n\n-   `RTC_DEVICE_PROPERTY_PARALLEL_COMMIT_SUPPORTED`: Queries whether\n    `rtcCommitScene` can get invoked from multiple TBB worker threads\n    concurrently. This feature is only supported starting with TBB 2019\n    Update 9.\n\n#### EXIT STATUS {#exit-status}\n\nOn success returns the value of the queried property. For properties\nreturning a boolean value, the return value 0 denotes `false` and 1\ndenotes `true`.\n\nOn failure zero is returned and an error code is set that can be\nqueried using `rtcGetDeviceError`.\n\n```{=tex}\n\n```\n## rtcGetDeviceError\n\n#### NAME {#name}\n\n    rtcGetDeviceError - returns the error code of the device\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    RTCError rtcGetDeviceError(RTCDevice device);\n\n#### DESCRIPTION {#description}\n\nEach thread has its own error code per device. If an error occurs when\ncalling an API function, this error code is set to the occurred error\nif it stores no previous error. The `rtcGetDeviceError` function reads\nand returns the currently stored error and clears the error code. This\nassures that the returned error code is always the first error occurred\nsince the last invocation of `rtcGetDeviceError`.\n\nPossible error codes returned by `rtcGetDeviceError` are:\n\n-   `RTC_ERROR_NONE`: No error occurred.\n\n-   `RTC_ERROR_UNKNOWN`: An unknown error has occurred.\n\n-   `RTC_ERROR_INVALID_ARGUMENT`: An invalid argument was specified.\n\n-   `RTC_ERROR_INVALID_OPERATION`: The operation is not allowed for the\n    specified object.\n\n-   `RTC_ERROR_OUT_OF_MEMORY`: There is not enough memory left to\n    complete the operation.\n\n-   `RTC_ERROR_UNSUPPORTED_CPU`: The CPU is not supported as it does\n    not support the lowest ISA Embree is compiled for.\n\n-   `RTC_ERROR_CANCELLED`: The operation got canceled by a memory\n    monitor callback or progress monitor callback function.\n\n-   `RTC_ERROR_LEVEL_ZERO_RAYTRACING_SUPPORT_MISSING`: This error can\n    occur when creating an Embree device with SYCL support using\n    `rtcNewSYCLDevice` fails. This error probably means that the GPU\n    driver is to old or not installed properly. Install a new GPU\n    driver and on Linux make sure that the package\n    `intel-level-zero-gpu-raytracing` is installed. For general driver\n    installation information for Linux refer to\n    \u003chttps://dgpu-docs.intel.com\u003e.\n\nWhen the device construction fails, `rtcNewDevice` returns `NULL` as\ndevice. To detect the error code of a such a failed device\nconstruction, pass `NULL` as device to the `rtcGetDeviceError`\nfunction. For all other invocations of `rtcGetDeviceError`, a proper\ndevice pointer must be specified.\n\nThe API function `rtcGetDeviceLastErrorMessage` can be used to get more\ndetails about the last `RTCError` a `RTCDevice` encountered.\n\nFor convenient reporting of a `RTCError`, the API function\n`rtcGetErrorString` can be used, which returns a string representation\nof a given `RTCError`.\n\n#### EXIT STATUS {#exit-status}\n\nReturns the error code for the device.\n\n#### SEE ALSO {#see-also}\n\n[rtcSetDeviceErrorFunction], [rtcGetDeviceLastErrorMessage],\n[rtcGetErrorString]\n\n```{=tex}\n\n```\n## rtcGetDeviceLastErrorMessage\n\n#### NAME {#name}\n\n    rtcGetDeviceLastErrorMessage - returns a message corresponding\n      to the last error code\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    const char* rtcGetDeviceLastErrorMessage(RTCDevice device);\n\n#### DESCRIPTION {#description}\n\nThis function can be used to get a message corresponding to the last\nerror code (returned by `rtcGetDeviceError`) which often provides\ndetails about the error that happened. The message is the same as the\nmessage that will written to console when verbosity is \\\u003e 0 or which is\npassed as the `str` argument of the `RTCErrorFunction` (see\n[rtcSetDeviceErrorFunction]). However, when device construction fails\nthis is the only way to get additional information about the error. In\nthis case, `rtcNewDevice` returns `NULL` as device. To query the error\nmessage for such a failed device construction, pass `NULL` as device to\nthe `rtcGetDeviceLastErrorMessage` function. For all other invocations\nof `rtcGetDeviceLastErrorMessage`, a proper device pointer must be\nspecified.\n\n#### EXIT STATUS {#exit-status}\n\nReturns a message corresponding to the last error code.\n\n#### SEE ALSO {#see-also}\n\n[rtcGetDeviceError], [rtcSetDeviceErrorFunction]\n\n```{=tex}\n\n```\n## rtcGetErrorString\n\n#### NAME {#name}\n\n    rtcGetErrorString - returns a string representation\n      of a given RTCError\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    const char* rtcGetErrorString(RTCError code);\n\n#### DESCRIPTION {#description}\n\nReturns a string representation for a `RTCError` error code. For\nexample, for the `RTCError` RTC_ERROR_UNKNOWN this function will return\nthe string \"Unknown Error\". This is purely a convenience function for\nprinting error information on the user side.\n\nThe returned strings should not be used for comparing different\n`RTCError` error codes or make other decisions based on the type of\nerror that occurred. For such things only the `RTCError` enum values\nshould be used.\n\n#### EXIT STATUS {#exit-status}\n\nReturns a string representation of a given `RTCError` error code.\n\n#### SEE ALSO {#see-also}\n\n[rtcGetDeviceError]\n\n```{=tex}\n\n```\n## rtcSetDeviceErrorFunction\n\n#### NAME {#name}\n\n    rtcSetDeviceErrorFunction - sets an error callback function for the device\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    typedef void (*RTCErrorFunction)(\n      void* userPtr,\n      RTCError code,\n      const char* str\n    );\n\n    void rtcSetDeviceErrorFunction(\n      RTCDevice device,\n      RTCErrorFunction error,\n      void* userPtr\n    );\n\n#### DESCRIPTION {#description}\n\nUsing the `rtcSetDeviceErrorFunction` call, it is possible to set a\ncallback function (`error` argument) with payload (`userPtr` argument),\nwhich is called whenever an error occurs for the specified device\n(`device` argument).\n\nOnly a single callback function can be registered per device, and\nfurther invocations overwrite the previously set callback function.\nPassing `NULL` as function pointer disables the registered callback\nfunction.\n\nWhen the registered callback function is invoked, it gets passed the\nuser-defined payload (`userPtr` argument as specified at registration\ntime), the error code (`code` argument) of the occurred error, as well\nas a string (`str` argument) that further describes the error.\n\nThe error code is also set if an error callback function is registered.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcGetDeviceError]\n\n```{=tex}\n\n```\n## rtcSetDeviceMemoryMonitorFunction\n\n#### NAME {#name}\n\n    rtcSetDeviceMemoryMonitorFunction - registers a callback function\n      to track memory consumption\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    typedef bool (*RTCMemoryMonitorFunction)(\n      void* userPtr,\n      ssize_t bytes,\n      bool post\n    );\n\n    void rtcSetDeviceMemoryMonitorFunction(\n      RTCDevice device,\n      RTCMemoryMonitorFunction memoryMonitor,\n      void* userPtr\n    );\n\n#### DESCRIPTION {#description}\n\nUsing the `rtcSetDeviceMemoryMonitorFunction` call, it is possible to\nregister a callback function (`memoryMonitor` argument) with payload\n(`userPtr` argument) for a device (`device` argument), which is called\nwhenever internal memory is allocated or deallocated by objects of that\ndevice. Using this memory monitor callback mechanism, the application\ncan track the memory consumption of an Embree device, and optionally\nterminate API calls that consume too much memory.\n\nOnly a single callback function can be registered per device, and\nfurther invocations overwrite the previously set callback function.\nPassing `NULL` as function pointer disables the registered callback\nfunction.\n\nOnce registered, the Embree device will invoke the memory monitor\ncallback function before or after it allocates or frees important\nmemory blocks. The callback function gets passed the payload as\nspecified at registration time (`userPtr` argument), the number of\nbytes allocated or deallocated (`bytes` argument), and whether the\ncallback is invoked after the allocation or deallocation took place\n(`post` argument). The callback function might get called from multiple\nthreads concurrently.\n\nThe application can track the current memory usage of the Embree device\nby atomically accumulating the `bytes` input parameter provided to the\ncallback function. This parameter will be \\\u003e0 for allocations and \\\u003c0\nfor deallocations.\n\nEmbree will continue its operation normally when returning `true` from\nthe callback function. If `false` is returned, Embree will cancel the\ncurrent operation with the `RTC_ERROR_OUT_OF_MEMORY` error code.\nIssuing multiple cancel requests from different threads is allowed.\nCanceling will only happen when the callback was called for allocations\n(bytes \\\u003e 0), otherwise the cancel request will be ignored.\n\nIf a callback to cancel was invoked before the allocation happens\n(`post == false`), then the `bytes` parameter should not be\naccumulated, as the allocation will never happen. If the callback to\ncancel was invoked after the allocation happened (`post == true`), then\nthe `bytes` parameter should be accumulated, as the allocation properly\nhappened and a deallocation will later free that data block.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcNewDevice]\n\n```{=tex}\n\n```\n## rtcNewScene\n\n#### NAME {#name}\n\n    rtcNewScene - creates a new scene\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    RTCScene rtcNewScene(RTCDevice device);\n\n#### DESCRIPTION {#description}\n\nThis function creates a new scene bound to the specified device\n(`device` argument), and returns a handle to this scene. The scene\nobject is reference counted with an initial reference count of 1. The\nscene handle can be released using the `rtcReleaseScene` API call.\n\n#### EXIT STATUS {#exit-status}\n\nOn success a scene handle is returned. On failure `NULL` is returned\nand an error code is set that can be queried using `rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcRetainScene], [rtcReleaseScene]\n\n```{=tex}\n\n```\n## rtcGetSceneDevice\n\n#### NAME {#name}\n\n    rtcGetSceneDevice - returns the device the scene got created in\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    RTCDevice rtcGetSceneDevice(RTCScene scene);\n\n#### DESCRIPTION {#description}\n\nThis function returns the device object the scene got created in. The\nreturned handle own one additional reference to the device object, thus\nyou should need to call `rtcReleaseDevice` when the returned handle is\nno longer required.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcReleaseDevice]\n\n```{=tex}\n\n```\n## rtcRetainScene\n\n#### NAME {#name}\n\n    rtcRetainScene - increments the scene reference count\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    void rtcRetainScene(RTCScene scene);\n\n#### DESCRIPTION {#description}\n\nScene objects are reference counted. The `rtcRetainScene` function\nincrements the reference count of the passed scene object (`scene`\nargument). This function together with `rtcReleaseScene` allows to use\nthe internal reference counting in a C++ wrapper class to handle the\nownership of the object.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcNewScene], [rtcReleaseScene]\n\n```{=tex}\n\n```\n## rtcReleaseScene\n\n#### NAME {#name}\n\n    rtcReleaseScene - decrements the scene reference count\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    void rtcReleaseScene(RTCScene scene);\n\n#### DESCRIPTION {#description}\n\nScene objects are reference counted. The `rtcReleaseScene` function\ndecrements the reference count of the passed scene object (`scene`\nargument). When the reference count falls to 0, the scene gets\ndestroyed.\n\nThe scene holds a reference to all attached geometries, thus if the\nscene gets destroyed, all geometries get detached and their reference\ncount decremented.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcNewScene], [rtcRetainScene]\n\n```{=tex}\n\n```\n## rtcAttachGeometry\n\n#### NAME {#name}\n\n    rtcAttachGeometry - attaches a geometry to the scene\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    unsigned int rtcAttachGeometry(\n      RTCScene scene,\n      RTCGeometry geometry\n    );\n\n#### DESCRIPTION {#description}\n\nThe `rtcAttachGeometry` function attaches a geometry (`geometry`\nargument) to a scene (`scene` argument) and assigns a geometry ID to\nthat geometry. All geometries attached to a scene are defined to be\nincluded inside the scene. A geometry can get attached to multiple\nscenes. The geometry ID is unique for the scene, and is used to\nidentify the geometry when hit by a ray during ray queries.\n\nThis function is thread-safe, thus multiple threads can attach\ngeometries to a scene in parallel.\n\nThe geometry IDs are assigned sequentially, starting from 0, as long as\nno geometry got detached. If geometries got detached, the\nimplementation will reuse IDs in an implementation dependent way.\nConsequently sequential assignment is no longer guaranteed, but a\ncompact range of IDs.\n\nThese rules allow the application to manage a dynamic array to\nefficiently map from geometry IDs to its own geometry representation.\nAlternatively, the application can also use per-geometry user data to\nmap to its geometry representation. See `rtcSetGeometryUserData` and\n`rtcGetGeometryUserData` for more information.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcSetGeometryUserData], [rtcGetGeometryUserData]\n\n```{=tex}\n\n```\n## rtcAttachGeometryByID\n\n#### NAME {#name}\n\n    rtcAttachGeometryByID - attaches a geometry to the scene\n      using a specified geometry ID\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    void rtcAttachGeometryByID(\n      RTCScene scene,\n      RTCGeometry geometry,\n      unsigned int geomID\n    );\n\n#### DESCRIPTION {#description}\n\nThe `rtcAttachGeometryByID` function attaches a geometry (`geometry`\nargument) to a scene (`scene` argument) and assigns a user provided\ngeometry ID (`geomID` argument) to that geometry. All geometries\nattached to a scene are defined to be included inside the scene. A\ngeometry can get attached to multiple scenes. The passed user-defined\ngeometry ID is used to identify the geometry when hit by a ray during\nray queries. Using this function, it is possible to share the same IDs\nto refer to geometries inside the application and Embree.\n\nThis function is thread-safe, thus multiple threads can attach\ngeometries to a scene in parallel.\n\nThe user-provided geometry ID must be unused in the scene, otherwise\nthe creation of the geometry will fail. Further, the user-provided\ngeometry IDs should be compact, as Embree internally creates a vector\nwhich size is equal to the largest geometry ID used. Creating very\nlarge geometry IDs for small scenes would thus cause a memory\nconsumption and performance overhead.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcAttachGeometry]\n\n```{=tex}\n\n```\n## rtcDetachGeometry\n\n#### NAME {#name}\n\n    rtcDetachGeometry - detaches a geometry from the scene\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    void rtcDetachGeometry(RTCScene scene, unsigned int geomID);\n\n#### DESCRIPTION {#description}\n\nThis function detaches a geometry identified by its geometry ID\n(`geomID` argument) from a scene (`scene` argument). When detached, the\ngeometry is no longer contained in the scene.\n\nThis function is thread-safe, thus multiple threads can detach\ngeometries from a scene at the same time.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure an error code is set that can be queried using\n`rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcAttachGeometry], [rtcAttachGeometryByID]\n\n```{=tex}\n\n```\n## rtcGetGeometry\n\n#### NAME {#name}\n\n    rtcGetGeometry - returns the geometry bound to\n      the specified geometry ID\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    RTCGeometry rtcGetGeometry(RTCScene scene, unsigned int geomID);\n\n#### DESCRIPTION {#description}\n\nThe `rtcGetGeometry` function returns the geometry that is bound to the\nspecified geometry ID (`geomID` argument) for the specified scene\n(`scene` argument). This function just looks up the handle and does\n*not* increment the reference count. If you want to get ownership of\nthe handle, you need to additionally call `rtcRetainGeometry`.\n\nThis function is not thread safe and thus can be used during rendering.\nHowever, it is generally recommended to store the geometry handle\ninside the application's geometry representation and look up the\ngeometry handle from that representation directly.\n\nIf you need a thread safe version of this function please use\n[rtcGetGeometryThreadSafe].\n\n#### EXIT STATUS {#exit-status}\n\nOn failure `NULL` is returned and an error code is set that can be\nqueried using `rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcAttachGeometry], [rtcAttachGeometryByID],\n[rtcGetGeometryThreadSafe]\n\n```{=tex}\n\n```\n## rtcGetGeometryThreadSafe\n\n#### NAME {#name}\n\n    rtcGetGeometryThreadSafe - returns the geometry bound to\n      the specified geometry ID\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    RTCGeometry rtcGetGeometryThreadSafe(RTCScene scene, unsigned int geomID);\n\n#### DESCRIPTION {#description}\n\nThe `rtcGetGeometryThreadSafe` function returns the geometry that is\nbound to the specified geometry ID (`geomID` argument) for the\nspecified scene (`scene` argument). This function just looks up the\nhandle and does *not* increment the reference count. If you want to get\nownership of the handle, you need to additionally call\n`rtcRetainGeometry`.\n\nThis function is thread safe and should NOT get used during rendering.\nIf you need a fast non-thread safe version during rendering please use\nthe [rtcGetGeometry] function.\n\n#### EXIT STATUS {#exit-status}\n\nOn failure `NULL` is returned and an error code is set that can be\nqueried using `rtcGetDeviceError`.\n\n#### SEE ALSO {#see-also}\n\n[rtcAttachGeometry], [rtcAttachGeometryByID], [rtcGetGeometry]\n\n```{=tex}\n\n```\n## rtcCommitScene\n\n#### NAME {#name}\n\n    rtcCommitScene - commits scene changes\n\n#### SYNOPSIS {#synopsis}\n\n    #include \u003cembree4/rtcore.h\u003e\n\n    void rtcCommitScene(RTCScene scene);\n\n#### DESCRIPTION {#description}\n\nThe `rtcCommitScene` function commits all changes for the specified\nscene (`scene` argument). This internally triggers building of a\nspatial acceleration structure for the scene using all available worker\nthreads. Ray queries can be performed only after committing all scene\nchanges.\n\nIf the application uses TBB 2019 Update 9 or later for parallelization\nof rendering, lazy scene construction during rendering is supported by\n`rtcCommitScene`. Therefore `rtcCommitScene` can get called from\nmultiple TBB worker threads concurrently for the same scene. The\n`rtcCommitScene` function will then internally isolate the scene\nconstruction using a tbb::isolated_task_group. The alternative approach\nof using `rtcJoinCommitScene` which uses an tbb:task_arena internally,\nis not recommended due to it's high runtime overhead.\n\nIf scene geometries get modified or attached or detached, the\n`rtcCommitScene` call must be invoked before performing any further ray\nqueries for the scene; otherwise the effect of the ray query is\nundefined. The modification of a geometry, committing the scene, and\ntracing of rays must always happen sequentially, and never at the same\ntime. Any API call that sets a property of the scene or geometries\ncontained in the scene count as scene modification, e.g. including\nsetting of intersection filter functions.\n\nThe kind of acceleration structure built can be influenced using scene\nflags (see `rtcSetSceneFlags`), and the quality can be specified using\nthe `rtcSetSceneBuildQuality` function.\n\nEmbree silently ignores primitives during spatial acceleration\nstructure construction that would cause numerical issues,\ne.g. primitives containing NaNs, INFs, or values greater than 1.844E18f\n(as no reasonable calculations can be performed with such values\nwithout causing overflows).\n\nIn case the RTCDevice associated with the `scene` is a SYCL device,\n`rtcCommitScene` will internally create a temporary SYCL queue to issue\nmemory transfers from host to device memory. In this case, the call to\n`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenderkit%2Fembree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frenderkit%2Fembree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenderkit%2Fembree/lists"}