Update documentation

Author: johguenther

CHANGELOG.md

@@ -3,24 +3,72 @@ Version History
 
 ### Changes in v3.0.0:
 
+-   Beta support for Intel Xe GPUs (Intel Arc™ GPUs a Intel Data Center
+    GPU Flex and Max Series), exploiting ray tracing hardware support.
+    Implementation is based on the [SYCL](https://www.khronos.org/sycl/)
+    cross-platform programming language implemented by [Intel oneAPI
+    Data Parallel C++
+    (DPC++)](https://www.intel.com/content/www/us/en/developer/tools/oneapi/data-parallel-c-plus-plus.html).  
+    Note that the following features are not implemented yet or are not
+    working correctly on the new `gpu` device:
+    -   Multiple volumes in the scene
+    -   Clipping
+    -   Motion blur
+    -   Subdivision surfaces
+    -   Progress reporting via `ospGetProgress` or canceling the frame via `ospCancel`
+    -   Picking via `ospPick`
+    -   Adaptive accumulation via `OSP_FB_VARIANCE` and `varianceThreshold`
+    -   Framebuffer channels `OSP_FB_ID_*` (id buffers)
+    -   Experimental support for shared device-only data, works only for
+        `structuredRegular` volume
+    -   Further known issues
+        -   Some delay on start-up or when changing the scene, because
+            kernel code is JIT compiled and specialized. JIT compilation
+            can be cached by setting environment variable
+            `SYCL_CACHE_PERSISTENT=1`, then consecutive starts or
+            rendering the same scene configuration is without delay
+        -   For some combination of compiler, GPU driver and scene the
+            rendered images might show artifacts (e.g., vertical lines
+            or small blocks)
+        -   Multidevice does not support `OSPImageOperation`s for
+            denoising or tone mapping
 -   Add implicit indexing for `mesh` geometry
+-   Add support for transferring ownership of temporary buffers:
+    `ospNewSharedData` accepts an optional deleter callback
+-   Optimizations for MPI module, supported by new integrated
+    performance tracing framework
+-   Optimize `scivis` gradient shading
+-   Main thread does not set FTZ/DAZ anymore for denormals handling
+-   Compute intersection epsilon for Mesh to avoid rendering artifacts
+    due to self-intersection
+-   Fix energy conservation of Pricipled material under certain
+    parameter combinations
+-   Fix `denoiser` to not wipe the alpha channel
+-   Fix crash in HDRI light
+-   Fix link order for Debug build on Windows
 -   The new minimum versions of dependencies:
-       - Embree v4.3.0
-       - Open VKL v2.0.0
-       - Open Image Denoise v2.1.0
-       - ISPC v1.21.1
-       - rkcommon v1.12.0
+    -    Embree v4.3.0
+    -    Open VKL v2.0.0
+    -    Open Image Denoise v2.1.0
+    -    ISPC v1.21.1
+    -    rkcommon v1.12.0
 -   Breaking API changes
     -   Renamed `OSP_TEXTURE_FILTER_BILINEAR` to
         `OSP_TEXTURE_FILTER_LINEAR ` and
         `OSP_VOLUME_FILTER_TRI[LINEAR|CUBIC]` to
         `OSP_VOLUME_FILTER_[LINEAR|CUBIC]`
-    -   Most enums have storage type uint32 now
+    -   Most enums now use storage type `uint32`
     -   `gridSpacing` of spherical regular volume defaults to full
         sphere
     -   Remove deprecated parameters and API calls
--   Add support for transferring ownership of temporary buffers:
-    `ospNewSharedData` accepts an optional deleter callback
+        -   error callback signatures without user pointer
+        -   first argument of `ospNewMaterial`
+        -   module name `ispc`; use `cpu`
+        -   `volume` texture and `isosurface` geometry: `volumetricModel`; use `OSPVolume volume`
+        -   Transfer function `vec2f valueRange`; use `box1f value`
+        -   `hdri` and `sun-sky` lights: `intensityQuantity` `OSP_INTENSITY_QUANTITY_RADIANCE`
+        -   `spot` light with `intensityDistribution`: `intensityQuantity` other than `OSP_INTENSITY_QUANTITY_SCALE`
+
 
 
 ### Changes in v2.12.0:

README.md

@@ -40,7 +40,7 @@ CMake is easy:
 -   You should now have `libospray.[so,dylib]` as well as a set of
     [example applications].
 
-#### Entitlements on Mac OS\ X
+### Entitlements on Mac OS\ X
 
 Mac OS\ X requires notarization of applications as a security mechanism,
 and [entitlements must be
@@ -62,9 +62,8 @@ way to configure OSPRay and to create the Visual Studio solution files:
     does not exist yet CMake will create it).
 
 -   Click "Configure" and select as generator the Visual Studio version
-    you have (OSPRay needs Visual Studio 15 2017 or newer), for Win64
-    (32\ bit builds are not supported by OSPRay), e.g., "Visual Studio 15
-    2017 Win64".
+    you have; OSPRay needs "Visual Studio 15 2017 Win64" or newer, 32\
+    bit builds are not supported, e.g., "Visual Studio 17 2022".
 
 -   If the configuration fails because some dependencies could not be
     found then follow the instructions given in the error message,
@@ -85,7 +84,7 @@ console. In the Visual Studio command prompt type:
     cd path\to\ospray
     mkdir build
     cd build
-    cmake -G "Visual Studio 15 2017 Win64" [-D VARIABLE=value] ..
+    cmake -G "Visual Studio 17 2022" [-D VARIABLE=value] ..
     cmake --build . --config Release
 
 Use `-D` to set variables for CMake, e.g., the path to Embree with "`-D
@@ -105,7 +104,7 @@ Finding an OSPRay Install with CMake
 Client applications using OSPRay can find it with CMake's
 `find_package()` command. For example,
 
-    find_package(ospray 2.0.0 REQUIRED)
+    find_package(ospray 3.0.0 REQUIRED)
 
 finds OSPRay via OSPRay's configuration file `osprayConfig.cmake`^[This
 file is usually in

doc/api.md

@@ -14,25 +14,48 @@ need
 
 We recommend the latest version of both TBB and Embree libraries.
 
+GPU Runtime Requirements
+------------------------
+
+To run OSPRay on Intel GPUs you will need to first have drivers
+installed on your system.
+
+### GPU drivers on Linux
+
+Install the latest GPGPU drivers for your Intel GPU from:
+https://dgpu-docs.intel.com/. Follow the driver installation
+instructions for your graphics card.
+
+### GPU drivers on Windows
+
+Install the latest GPGPU drivers for your Intel GPU from:
+https://www.intel.com/content/www/us/en/download/785597/intel-arc-iris-xe-graphics-windows.html.
+Follow the driver installation instructions for your graphics card.
+
+
 Packages
 --------
 
 Packages for x86_64 are provided, OSPRay can be built for ARM64/NEON
 using the superbuild (see [Building and Finding OSPRay](#building-and-finding-ospray)).
 
-For Linux we provide OSPRay precompiled for 64\ bit as a TGZ archive.  
-[ospray-<OSPRAY_VERSION>.x86_64.linux.tar.gz](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.x86_64.linux.tar.gz)
+For Linux we provide OSPRay precompiled for 64\ bit as a TGZ archive.
+The "sycl" variant includes the GPU module.  
+[ospray-<OSPRAY_VERSION>.x86_64.linux.tar.gz](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.x86_64.linux.tar.gz)  
+[ospray-<OSPRAY_VERSION>.sycl.x86_64.linux.tar.gz](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.sycl.x86_64.linux.tar.gz)
 
 For Mac OS\ X we provide OSPRay as a ZIP archive:  
 [ospray-<OSPRAY_VERSION>.x86_64.macosx.zip](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.x86_64.macosx.zip)
 
 For Windows we provide OSPRay binaries precompiled for 64\ bit as an MSI
-installer as well as a ZIP archive:  
+installer as well as a ZIP archive. The "sycl" variant includes the GPU module.  
 [ospray-<OSPRAY_VERSION>.x86_64.windows.msi](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.x86_64.windows.msi)  
-[ospray-<OSPRAY_VERSION>.x86_64.windows.zip](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.x86_64.windows.zip)
+[ospray-<OSPRAY_VERSION>.sycl.x86_64.windows.msi](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.sycl.x86_64.windows.msi)  
+[ospray-<OSPRAY_VERSION>.x86_64.windows.zip](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.x86_64.windows.zip)  
+[ospray-<OSPRAY_VERSION>.sycl.x86_64.windows.zip](https://github.com/ospray/OSPRay/releases/download/v<OSPRAY_VERSION>/ospray-<OSPRAY_VERSION>.sycl.x86_64.windows.zip)
 
 The source code of the latest OSPRay version can be downloaded here:  
 [ospray-<OSPRAY_VERSION>.zip](https://github.com/ospray/OSPRay/archive/v<OSPRAY_VERSION>.zip)  
 [ospray-<OSPRAY_VERSION>.tar.gz](https://github.com/ospray/OSPRay/archive/v<OSPRAY_VERSION>.tar.gz)
 
-You can also access [old OSPRay releases](https://github.com/ospray/OSPRay/releases).
+You can also access [previous OSPRay releases](https://github.com/ospray/OSPRay/releases).

doc/compilation.md

@@ -1,6 +1,6 @@
 
 [Embree]: https://www.embree.org/
-[Intel Embree]: https://www.embree.org/
+[Open VKL]: https://www.openvkl.org/
 [Open Image Denoise]: https://openimagedenoise.github.io/
 [OSPRayReadme]: https://www.ospray.org/OSPRay_readme.pdf "OSPRay Documentation"
 [doc/ospray2_porting_guide.md]: https://www.ospray.org/ospray2_porting_guide.html

doc/getting_ospray.md

@@ -1,40 +1,48 @@
 OSPRay Overview
 ===============
 
-Intel OSPRay is an **o**pen source, **s**calable, and **p**ortable **ray**
-tracing engine for high-performance, high-fidelity visualization on
-Intel Architecture CPUs. OSPRay is part of the [Intel oneAPI Rendering
+Intel® OSPRay is an **o**pen source, **s**calable, and **p**ortable
+**ray** tracing engine for high-performance, high-fidelity visualization
+on Intel Architecture CPUs, Intel Xe GPUs, and ARM64 CPUs. OSPRay is part
+of the [Intel oneAPI Rendering
 Toolkit](https://software.intel.com/en-us/rendering-framework) and is
 released under the permissive [Apache 2.0
 license](http://www.apache.org/licenses/LICENSE-2.0).
 
 The purpose of OSPRay is to provide an open, powerful, and easy-to-use
 rendering library that allows one to easily build applications that use
 ray tracing based rendering for interactive applications (including both
-surface- and volume-based visualizations). OSPRay is completely
-CPU-based, and runs on anything from laptops, to workstations, to
-compute nodes in HPC systems.
-
-OSPRay internally builds on top of [Intel Embree] and [Intel ISPC
-(Implicit SPMD Program Compiler)](https://ispc.github.io/), and fully
-exploits modern instruction sets like Intel SSE4, AVX, AVX2, AVX-512 and NEON
-to achieve high rendering performance, thus a CPU with support for at
-least SSE4.1 is required to run OSPRay on x86_64 architectures.
-A CPU with support for NEON is required to run OSPRay on ARM64 architectures.
+surface- and volume-based visualizations). OSPRay runs on anything from
+laptops, to workstations, to compute nodes in HPC systems.
+
+OSPRay internally builds on top of Intel [Embree], Intel [Open VKL], and
+Intel [Open Image Denoise]. The CPU implementation is based on
+Intel [ISPC (Implicit SPMD Program Compiler)](https://ispc.github.io/)
+and fully exploits modern instruction sets like Intel SSE4, AVX, AVX2,
+AVX-512 and NEON to achieve high rendering performance. Hence, a CPU
+with support for at least SSE4.1 is required to run OSPRay on x86_64
+architectures, or a CPU with support for NEON is required to run OSPRay
+on ARM64 architectures.
+
+OSPRay's GPU implementation (beta status) is based on the
+[SYCL](https://www.khronos.org/sycl/) cross-platform programming
+language implemented by [Intel oneAPI Data Parallel C++
+(DPC++)](https://www.intel.com/content/www/us/en/developer/tools/oneapi/data-parallel-c-plus-plus.html)
+and currently supports Intel Arc™ GPUs on Linux and Windows, and Intel
+Data Center GPU Flex and Max Series on Linux, exploiting ray tracing
+hardware support.
 
 
 OSPRay Support and Contact
 --------------------------
 
 OSPRay is under active development, and though we do our best to
 guarantee stable release versions a certain number of bugs,
-as-yet-missing features, inconsistencies, or any other issues are
-still possible. Should you find any such issues please report
-them immediately via [OSPRay's GitHub Issue
-Tracker](https://github.com/ospray/OSPRay/issues) (or, if you should
-happen to have a fix for it,you can also send us a pull request); for
-missing features please contact us via email at
-<[email protected]>.
+as-yet-missing features, inconsistencies, or any other issues are still
+possible. For any such requests or findings please use [OSPRay's GitHub
+Issue Tracker](https://github.com/ospray/OSPRay/issues) (or, if you
+should happen to have a fix for it, you can also send us a pull
+request).
 
 To receive release announcements simply ["Watch" the OSPRay
 repository](https://github.com/ospray/OSPRay) on GitHub.

doc/links.md

@@ -40,9 +40,9 @@ before you can build OSPRay you need the following prerequisites:
 -   OSPRay also heavily uses Intel [Embree], installing version 4.3.0
     or newer is required. If Embree is not found by CMake its location
     can be hinted with the variable `embree_DIR`.
--   OSPRay support volume rendering (enabled by default via
-    `OSPRAY_ENABLE_VOLUMES`), which heavily uses Intel [Open
-    VKL](https://www.openvkl.org/), version 2.0.0 or newer is required.
+-   OSPRay supports volume rendering (enabled by default via
+    `OSPRAY_ENABLE_VOLUMES`), which heavily uses Intel [Open VKL],
+    version 2.0.0 or newer is required.
     If Open VKL is not found by CMake its location can be hinted with
     the variable `openvkl_DIR`, or disable `OSPRAY_ENABLE_VOLUMES`.
 -   OSPRay also provides an optional module implementing the `denoiser`
@@ -83,3 +83,22 @@ Under Windows please directly use the appropriate installers for
 [ISPC](https://ispc.github.io/downloads.html) (for your Visual Studio
 version) and [Embree](https://github.com/embree/embree/releases/).
 
+### Additional Prerequisites for GPU Build {-}
+
+To build OSPRay's GPU module you need
+
+-   a SYCL compiler, either the open source [oneAPI DPC++ Compiler
+    2023-09-22](https://github.com/intel/llvm/releases/tag/nightly-2023-09-22)
+    or the latest [Intel oneAPI DPC++/C++
+    Compiler](https://www.intel.com/content/www/us/en/developer/articles/tool/oneapi-standalone-components.html#dpcpp-cpp)
+-   a recent [CMake](http://www.cmake.org), version 3.25.3 or higher
+-   the [oneAPI Level Zero Loader
+    v1.12.0](https://github.com/oneapi-src/level-zero/releases/tag/v1.12.0)
+    development packages
+    -   On Linux Ubuntu 22.04 there are prebuilt packages available for
+        this: `level-zero-devel` and `level-zero`
+    -   Other Linux distributions require building these packages from source
+    -   On Windows, you can use the single package
+        `level-zero_<version>_win-sdk`; note you will need to set the
+        environment variable `LEVEL_ZERO_ROOT` to the location of the
+        SDK

doc/overview.md

@@ -82,44 +82,6 @@ OSPRay `world` and objects common in all scenes (for example lighting
 and ground plane), which can be conveniently overridden in the derived
 builders.
 
-Given below are different scenes listed with their string identifiers:
-
-boxes
-: A simple scene with `box` geometry type.
-
-cornell_box
-: A scene depicting a classic cornell box with `quad` mesh geometry type
-for rendering two cubes and a `quad` light type.
-
-curves
-: A simple scene with `curve` geometry type and options to change
-`curveBasis`. For details on different basis' please check documentation
-of [curves].
-
-gravity_spheres_volume
-: A scene with `structuredRegular` type of [volume].
-
-gravity_spheres_isosurface
-: A scene depicting iso-surface rendering of `gravity_spheres_volume`
-using geometry type `isosurface`.
-
-perlin_noise_volumes
-: An example scene with `structuredRegular` volume type depicting perlin
-noise.
-
-random_spheres
-: A simple scene depicting `sphere` geometry type.
-
-streamlines
-: A scene showcasing streamlines geometry derived from `curve` geometry
-type.
-
-subdivision_cube
-: A scene with a cube of `subdivision` geometry type to showcase
-subdivision surfaces.
-
-unstructured_volume
-: A simple scene with a volume of `unstructured` volume type.
 
 ### Renderer
 
@@ -136,22 +98,6 @@ to change `turbidity` and `sunDirection`.
 ![Rendering an evening sky with the `renderSunSky` option.][imgRenderSunSky]
 
 
-MPI Distributed Tutorials
-=========================
-
-The MPI Distributed tutorials demonstrate various ways that distributed
-applications using MPI can leverage OSPRay's distributed rendering
-capabilities to render distributed, replicated, and partially replicated
-data across the processes. The tutorials will be built as part of OSPRay
-when running cmake with
-
-    cmake \
-      -DOSPRAY_ENABLE_APPS=ON \
-      -DOSPRAY_ENABLE_APPS_TUTORIALS=ON \
-      -DOSPRAY_MODULE_MPI=ON \
-      -DOSPRAY_MPI_BUILD_TUTORIALS=ON \
-      <other args>
-
 ospMPIDistribTutorial
 ---------------------
 

doc/prerequisites.md

@@ -14,10 +14,10 @@ cmake [<OSPRAY_SOURCE_DIR>/scripts/superbuild]
 cmake --build .
 ```
 
-On Windows make sure to select the non-default 64bit generator, e.g.
+On Windows make sure to select a 64bit generator, e.g.
 
 ```sh
-cmake -G "Visual Studio 15 2017 Win64" [<OSPRAY_SOURCE_DIR>/scripts/superbuild]
+cmake -G "Visual Studio 17 2022" [<OSPRAY_SOURCE_DIR>/scripts/superbuild]
 ```
 
 The resulting `install` directory (or the one set with
@@ -52,6 +52,10 @@ BUILD_OSPRAY_MODULE_MPI
 :   set to ON to build OSPRay’s MPI module for data-replicated and
     distributed parallel rendering on multiple nodes.
 
+BUILD_GPU_SUPPORT
+:   enables beta GPU support, fetching the SYCL variants of the
+    dependencies and builds `OSPRAY_MODULE_GPU`
+
 BUILD_TBB_FROM_SOURCE
 :   set to ON to build TBB from source (required for ARM support). The
     default setting is OFF.