update rtcSet(New|Shared)GeometryBuffer(|HostDevice) documentation

doc/src/api-ref.md

@@ -269,11 +269,21 @@
 ```
 \pagebreak
 
+## rtcSetSharedGeometryBufferHostDevice
+``` {include=src/api/rtcSetSharedGeometryBufferHostDevice.md}
+```
+\pagebreak
+
 ## rtcSetNewGeometryBuffer
 ``` {include=src/api/rtcSetNewGeometryBuffer.md}
 ```
 \pagebreak
 
+## rtcSetNewGeometryBufferHostDevice
+``` {include=src/api/rtcSetNewGeometryBufferHostDevice.md}
+```
+\pagebreak
+
 ## RTCFormat
 ``` {include=src/api/RTCFormat.md}
 ```
@@ -289,6 +299,11 @@
 ```
 \pagebreak
 
+## rtcGetGeometryBufferDataDevice
+``` {include=src/api/rtcGetGeometryBufferDataDevice.md}
+```
+\pagebreak
+
 ## rtcUpdateGeometryBuffer
 ``` {include=src/api/rtcUpdateGeometryBuffer.md}
 ```

doc/src/api/rtcCommitBuffer.md

@@ -1,4 +1,4 @@
-% rtcCommitSBuffer(3) | Embree Ray Tracing Kernels 4
+% rtcCommitBuffer(3) | Embree Ray Tracing Kernels 4
 
 #### NAME
 

doc/src/api/rtcGetGeometryBufferData.md

@@ -22,11 +22,16 @@ element of the buffer view attached to the specified buffer type and
 slot (`type` and `slot` argument) of the geometry (`geometry`
 argument).
 
+If the device associated with `geometry` is a SYCL device,
+the returned pointer only accessible on the host. The function
+`rtcGetGeometryBufferDataDevice` can be used to get a pointer
+accessible on the SYCL device.
 #### EXIT STATUS
 
 On failure an error code is set that can be queried using
 `rtcGetDeviceError`.
 
 #### SEE ALSO
 
-[rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer], [rtcSetNewGeometryBuffer]
+[rtcGetGeometryBufferDataDevice], [rtcSetGeometryBuffer],
+[rtcSetSharedGeometryBuffer], [rtcSetNewGeometryBuffer]

doc/src/api/rtcGetGeometryBufferDataDevice.md

@@ -0,0 +1,36 @@
+% rtcGetGeometryBufferDataDevice(3) | Embree Ray Tracing Kernels 4
+
+#### NAME
+
+    rtcGetGeometryBufferDataDevice - gets pointer to
+      the first buffer view element on the device.
+
+#### SYNOPSIS
+
+    #include <embree4/rtcore.h>
+
+    void* rtcGetGeometryBufferDataDevice(
+      RTCGeometry geometry,
+      enum RTCBufferType type,
+      unsigned int slot
+    );
+
+#### DESCRIPTION
+
+The `rtcGetGeometryBufferDataDevice` function returns a pointer to the first
+element of the buffer view attached to the specified buffer type and
+slot (`type` and `slot` argument) of the geometry (`geometry`
+argument) on the device.
+
+If the device associated with `geometry` is no SYCL device, or if Embree
+is executed on a system with host unified memory (e.g., on an iGPU),
+the returned pointer is the same as the one returned by `rtcGetGeometryBufferData`.
+
+#### EXIT STATUS
+
+On failure an error code is set that can be queried using
+`rtcGetDeviceError`.
+
+#### SEE ALSO
+
+[rtcGetGeometryBufferData], [rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer], [rtcSetNewGeometryBuffer]

doc/src/api/rtcSetNewGeometryBufferHostDevice.md

@@ -0,0 +1,62 @@
+% rtcSetNewGeometryBufferHostDevice(3) | Embree Ray Tracing Kernels 4
+
+#### NAME
+
+    rtcSetNewGeometryBufferHostDevice - creates and assigns a new host/device
+      data buffer pair to the geometry
+
+#### SYNOPSIS
+
+    #include <embree4/rtcore.h>
+
+    void rtcSetNewGeometryBufferHostDevice(
+      RTCGeometry geometry,
+      enum RTCBufferType type,
+      unsigned int slot,
+      enum RTCFormat format,
+      size_t byteStride,
+      size_t itemCount,
+      void** ptr,
+      void** dptr
+    );
+
+#### DESCRIPTION
+
+The `rtcSetNewGeometryBufferHostDevice` function creates a new host/device data buffer pair of
+specified format (`format` argument), byte stride (`byteStride`
+argument), and number of items (`itemCount` argument), and assigns it
+to a geometry buffer slot (`type` and `slot` argument) of the
+specified geometry (`geometry` argument). The buffer data is managed
+internally and automatically freed when the geometry is destroyed.
+
+The byte stride (`byteStride` argument) must be aligned to 4 bytes;
+otherwise the `rtcSetNewGeometryBuffer` function will fail.
+
+The allocated buffer will be automatically over-allocated slightly
+when used as a vertex buffer, where a requirement is that each buffer
+element should be readable using 16-byte SSE load instructions.
+
+If `ptr` is not null, it will be used to return the address of the
+host data buffer. If `dptr` is not null, it will be used to return
+the address of the device data buffer. Either `ptr` or `dptr` or both
+can be null. In this case `rtcGetGeometryBufferData` and
+`rtcGetGeometryBufferDataDevice` can be used to get the addresses of the
+host and device data buffers.
+
+The application is responsible of keeping the host and device memory
+in sync. The host memory has to be updated before calls of
+`rtcCommitScene` involving the associated geometry.
+
+If Embree has no SYCL support or the associated Embree device is no
+SYCL device the `dptr` argument will return the same address as `ptr` if on null.
+In this case the function `rtcSetNewGeometryBufferHostDevice` will behave like
+`rtcSetSharedGeometryBuffer`.
+
+#### EXIT STATUS
+
+On failure an error code is set that can be queried using
+`rtcGetDeviceError`.
+
+#### SEE ALSO
+[rtcSetNewGeometryBuffer], [rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer],
+[rtcGetGeometryBufferData], [rtcGetGeometryBufferDataDevice]

doc/src/api/rtcSetSharedGeometryBuffer.md

@@ -43,6 +43,11 @@ The buffer data must remain valid for as long as the buffer may be
 used, and the user is responsible for freeing the buffer data when no
 longer required.
 
+If using a SYCL Embree device, `ptr` must be allocated using SYCL USM shared
+memory to be accessible on the device. Alternatively the function
+`rtcSetSharedGeometryBufferHostDevice` can be used to pass an explicitly
+managed host/device buffer pair.
+
 Sharing buffers can significantly reduce the memory required by the
 application, thus we recommend using this feature. When enabling the
 `RTC_SCENE_FLAG_COMPACT` scene flag, the spatial index structures index
@@ -55,4 +60,4 @@ On failure an error code is set that can be queried using
 
 #### SEE ALSO
 
-[rtcSetGeometryBuffer], [rtcSetNewGeometryBuffer]
+[rtcSetSharedGeometryBufferHostDevice], [rtcSetGeometryBuffer], [rtcSetNewGeometryBuffer]

doc/src/api/rtcSetSharedGeometryBufferHostDevice.md

@@ -0,0 +1,70 @@
+% rtcSetSharedGeometryBufferHostDevice(3) | Embree Ray Tracing Kernels 4
+
+#### NAME
+
+    rtcSetSharedGeometryBufferHostDevice - assigns views of shared data buffers
+      to a geometry using explicit host and device memory
+
+#### SYNOPSIS
+
+    #include <embree4/rtcore.h>
+
+    void rtcSetSharedGeometryBuffer(
+      RTCGeometry geometry,
+      enum RTCBufferType type,
+      unsigned int slot,
+      enum RTCFormat format,
+      const void* ptr,
+      const void* dptr,
+      size_t byteOffset,
+      size_t byteStride,
+      size_t itemCount
+    );
+
+#### DESCRIPTION
+
+The `rtcSetSharedGeometryBufferHostDevice` function binds views of a
+shared user-managed data buffers to a geometry buffer
+type and slot (`type` and `slot` argument) of the specified geometry
+(`geometry` argument). The user-managed data buffers are passed using the
+`ptr` argument for the host side allocated memory and the `dptr` parameter
+for the memory allocated on the device.
+
+One can specify the start of the first buffer element in bytes
+(`byteOffset` argument), the byte stride between individual buffer
+elements (`byteStride` argument), the format of the buffer elements
+(`format` argument), and the number of elements to bind (`itemCount`).
+
+The start address (`byteOffset` argument) and stride (`byteStride`
+argument) must be both aligned to 4 bytes; otherwise the
+`rtcSetSharedGeometryBufferHostDevice` function will fail.
+
+``` {include=src/api/inc/buffer_padding.md}
+```
+
+The buffer data must remain valid for as long as the buffer may be
+used, and the user is responsible for freeing the buffer data when no
+longer required.
+
+The application is responsible of keeping the host and device memory
+in sync. The host memory has to be updated before calls of
+`rtcCommitScene` involving the associated geometry.
+
+If Embree has no SYCL support or the associated Embree device is no
+SYCL device the `dptr` argument must be a null pointer. In this case
+the function `rtcSetSharedGeometryBufferHostDevice` will behave like
+`rtcSetSharedGeometryBuffer`.
+
+Sharing buffers can significantly reduce the memory required by the
+application, thus we recommend using this feature. When enabling the
+`RTC_SCENE_FLAG_COMPACT` scene flag, the spatial index structures index
+into the vertex buffer, resulting in even higher memory savings.
+
+#### EXIT STATUS
+
+On failure an error code is set that can be queried using
+`rtcGetDeviceError`.
+
+#### SEE ALSO
+
+[rtcSetSharedGeometryBuffer], [rtcSetGeometryBuffer], [rtcSetNewGeometryBuffer]