update documentation for RTCBuffer

doc/src/api-ref.md

@@ -460,17 +460,26 @@
 ```
 \pagebreak
 
-
 ## rtcNewBuffer
 ``` {include=src/api/rtcNewBuffer.md}
 ```
 \pagebreak
 
+## rtcNewBufferHostDevice
+``` {include=src/api/rtcNewBufferHostDevice.md}
+```
+\pagebreak
+
 ## rtcNewSharedBuffer
 ``` {include=src/api/rtcNewSharedBuffer.md}
 ```
 \pagebreak
 
+## rtcNewSharedBufferHostDevice
+``` {include=src/api/rtcNewSharedBufferHostDevice.md}
+```
+\pagebreak
+
 ## rtcRetainBuffer
 ``` {include=src/api/rtcRetainBuffer.md}
 ```
@@ -486,6 +495,21 @@
 ```
 \pagebreak
 
+## rtcGetBufferDataDevice
+``` {include=src/api/rtcGetBufferDataDevice.md}
+```
+\pagebreak
+
+## rtcCommitBuffer
+``` {include=src/api/rtcCommitBuffer.md}
+```
+\pagebreak
+
+## rtcCommitBufferWithQueue
+``` {include=src/api/rtcCommitBufferWithQueue.md}
+```
+\pagebreak
+
 ## RTCRay
 ``` {include=src/api/RTCRay.md}
 ```

doc/src/api/rtcCommitBuffer.md

@@ -0,0 +1,31 @@
+% rtcCommitSBuffer(3) | Embree Ray Tracing Kernels 4
+
+#### NAME
+
+    rtcCommitBuffer - commits buffer content from host to device
+
+#### SYNOPSIS
+
+    #include <embree4/rtcore.h>
+
+    void rtcCommitBuffer(RTCBuffer buffer);
+
+#### DESCRIPTION
+
+If the buffer was created using `rtcNewBufferHostDevice` the 
+`rtcCommitBuffer` function commits changes of the host buffer data 
+to the device. If the buffer was created with a non SYCL Embree device 
+or the SYCL device has host unified memory, this call has no effect.
+
+The call to `rtcCommitBuffer` will internally use a temporary SYCL 
+queue and wait for the memory copy to finish. The function 
+`rtcCommitBufferWithQueue` can be used to asyncronously copy the 
+data to the device.
+#### EXIT STATUS
+
+On failure an error code is set that can be queried using
+`rtcGetDeviceError`.
+
+#### SEE ALSO
+
+[rtcCommitBufferWithQueue] [rtcNewBufferHostDevice]

doc/src/api/rtcCommitBufferWithQueue.md

@@ -0,0 +1,39 @@
+% rtcCommitBufferWithQueue(3) | Embree Ray Tracing Kernels 4
+
+#### NAME
+
+    rtcCommitBufferWithQueue - commits buffer content from host to device using a given SYCL queue
+
+#### SYNOPSIS
+
+    #include <embree4/rtcore.h>
+
+    void rtcCommitBufferWithQueue(RTCBuffer buffer,
+        sycl::queue queue, sycl::event* event);
+
+#### DESCRIPTION
+
+If the buffer was created using `rtcNewBufferHostDevice` the 
+`rtcCommitBufferWithQueue` function commits changes of the host buffer data 
+to the device. If the buffer was created with a non SYCL Embree device 
+or the SYCL device has host unified memory, this call has no effect.
+
+The call to `rtcCommitBufferWithQueue` will use the given SYCL queue
+to copy the memory asynchronously. If the SYCL event argument `event`
+is a valid pointer, Embree will use this pointer to return a copy of 
+the SYCL event associated to the memory copy. The parameter `event` 
+is optional and will be ignored if it is a null pointer.
+
+The user is responsible for synchronization using the SYCL queue or 
+the optional SYCL event.
+
+This function is only avaiable on Embree versions with enabled SYCL support.
+
+#### EXIT STATUS
+
+On failure an error code is set that can be queried using
+`rtcGetDeviceError`.
+
+#### SEE ALSO
+
+[rtcCommitBuffer] [rtcNewBufferHostDevice]

doc/src/api/rtcForwardOccluded1.md

@@ -16,7 +16,7 @@
       unsigned int instID
     );
 
-    void rtcForwardOccluded1(
+    void rtcForwardOccluded1Ex(
       const struct RTCOccludedFunctionNArguments* args,
       RTCScene scene,
       struct RTCRay* ray,

doc/src/api/rtcGetBufferData.md

@@ -13,7 +13,10 @@
 #### DESCRIPTION
 
 The `rtcGetBufferData` function returns a pointer to the buffer data
-of the specified buffer object (`buffer` argument).
+of the specified buffer object (`buffer` argument). If the buffer
+was created using `rtcNewBufferHostDevice` and the SYCL device has no
+host unified memory, this pointer is only valid on the host. To get
+a device pointer in this case, use `rtcGetBufferDataDevice`.
 
 #### EXIT STATUS
 
@@ -22,4 +25,4 @@ On failure an error code is set that can be queried using
 
 #### SEE ALSO
 
-[rtcNewBuffer]
+[rtcGetBufferDataDevice], [rtcNewBuffer], [rtcNewBufferHostDevice]

doc/src/api/rtcGetBufferDataDevice.md

@@ -0,0 +1,28 @@
+% rtcGetBufferData(3) | Embree Ray Tracing Kernels 4
+
+#### NAME
+
+    rtcGetBufferDataDevice - gets a device pointer to the buffer data
+
+#### SYNOPSIS
+
+    #include <embree4/rtcore.h>
+
+    void* rtcGetBufferDataDevice(RTCBuffer buffer);
+
+#### DESCRIPTION
+
+The `rtcGetBufferDataDevice` function returns a pointer to the buffer data
+of the specified buffer object (`buffer` argument) which can be used for
+accessing the data on the device. If Embree has no SYCL support or the SYCL 
+device has host unified memory, the pointer is equal to the pointer returend 
+by `rtcGetBufferData`.
+
+#### EXIT STATUS
+
+On failure an error code is set that can be queried using
+`rtcGetDeviceError`.
+
+#### SEE ALSO
+
+[rtcGetBufferData], [rtcNewBuffer]

doc/src/api/rtcNewBuffer.md

@@ -26,11 +26,18 @@ and deallocated when the buffer is destroyed.
 ``` {include=src/api/inc/buffer_padding.md}
 ```
 
+If the `device` is a Embree SYCL device, the buffer will be allocated
+using SYCL USM shared memory, i.e. the buffer can be accessed on the host
+and device (GPU) and the SYCL runtime will handle buffer transfers automatically.
+
+For precise control over when memory is copied from host to device, 
+a buffer can also be created using `rtcNewBufferHostDevice`.
+
 #### EXIT STATUS
 
 On failure `NULL` is returned and an error code is set that can be
 queried using `rtcGetDeviceError`.
 
 #### SEE ALSO
 
-[rtcRetainBuffer], [rtcReleaseBuffer]
+[rtcNewBufferHostDevice], [rtcRetainBuffer], [rtcReleaseBuffer]

doc/src/api/rtcNewBufferHostDevice.md

@@ -0,0 +1,43 @@
+% rtcNewBuffer(3) | Embree Ray Tracing Kernels 4
+
+#### NAME
+
+    rtcNewBufferHostDevice - creates a new data buffer with 
+      explicitly managed host and device memory allocations
+
+#### SYNOPSIS
+
+    #include <embree4/rtcore.h>
+
+    RTCBuffer rtcNewBufferHostDevice(
+      RTCDevice device,
+      size_t byteSize
+    );
+
+#### DESCRIPTION
+
+The `rtcNewBufferHostDevice` function creates a new data buffer object of
+specified size in bytes (`byteSize` argument) that is bound to the
+specified device (`device` argument). The buffer object is reference
+counted with an initial reference count of 1. The returned buffer
+object can be released using the `rtcReleaseBuffer` API call. If Embree has SYCL
+support enabled and the SYCL device has no host unifed memory (e.g, a discrete GPU), 
+the buffer allocates memory on the host and device explicitly.
+After the buffer is modified on the host `rtcCommitBuffer` can be used to synchronize
+host and device memory by copying the buffer content from the host to device. If the Embree
+version has no SYCL support or the SYCL device has host unified memory, the buffer will behave 
+the same as a buffer created using `rtcNewBuffer`. The
+specified number of bytes are allocated at buffer construction time
+and deallocated when the buffer is destroyed.
+
+``` {include=src/api/inc/buffer_padding.md}
+```
+
+#### EXIT STATUS
+
+On failure `NULL` is returned and an error code is set that can be
+queried using `rtcGetDeviceError`.
+
+#### SEE ALSO
+
+[rtcCommitBuffer], [rtcNewBuffer], [rtcRetainBuffer], [rtcReleaseBuffer]

doc/src/api/rtcNewSharedBuffer.md

@@ -42,4 +42,4 @@ queried using `rtcGetDeviceError`.
 
 #### SEE ALSO
 
-[rtcRetainBuffer], [rtcReleaseBuffer]
+[rtcNewSharedBufferHostDevice], [rtcRetainBuffer], [rtcReleaseBuffer]

doc/src/api/rtcNewSharedBufferHostDevice.md

@@ -0,0 +1,50 @@
+% rtcNewSharedBufferHostDevice(3) | Embree Ray Tracing Kernels 4
+
+#### NAME
+
+    rtcNewSharedBufferHostDevice - creates a new shared data buffer
+      with a managed copy of the buffer in device memory
+
+#### SYNOPSIS
+
+    #include <embree4/rtcore.h>
+
+    RTCBuffer rtcNewSharedBufferHostDevice(
+      RTCDevice device,
+      void* ptr,
+      size_t byteSize
+    );
+
+#### DESCRIPTION
+
+The `rtcNewSharedBufferHostDevice` function creates a new shared data buffer
+object bound to the specified device (`device` argument). The buffer
+object is reference counted with an initial reference count of 1. The
+buffer can be released using the `rtcReleaseBuffer` function.
+
+At construction time, the pointer to the user-managed buffer data
+(`ptr` argument) including its size in bytes (`byteSize` argument) is
+provided to create the buffer. At buffer construction time no buffer
+data is allocated on the host, but the buffer data provided by the application is
+used. A equal sized memory allocation is created on the device. 
+The buffer data must remain valid for as long as the buffer may
+be used, and the user is responsible to free the buffer data when no
+longer required.
+
+``` {include=src/api/inc/buffer_padding.md}
+```
+
+The data pointer (`ptr` argument) must be aligned to 4 bytes; otherwise
+the `rtcNewSharedBuffer` function will fail.
+
+The function `rtcCommitBuffer` can be used to synchronize the buffer 
+content with the device.
+
+#### EXIT STATUS
+
+On failure `NULL` is returned and an error code is set that can be
+queried using `rtcGetDeviceError`.
+
+#### SEE ALSO
+
+[rtcNewSharedBuffer], [rtcCommitBuffer], [rtcRetainBuffer], [rtcReleaseBuffer]