diff --git a/doc/src/api-ref.md b/doc/src/api-ref.md index 7600211be7..58057929a5 100644 --- a/doc/src/api-ref.md +++ b/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} ``` diff --git a/doc/src/api/rtcCommitBuffer.md b/doc/src/api/rtcCommitBuffer.md new file mode 100644 index 0000000000..5cb8c1fc76 --- /dev/null +++ b/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 + + 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] diff --git a/doc/src/api/rtcCommitBufferWithQueue.md b/doc/src/api/rtcCommitBufferWithQueue.md new file mode 100644 index 0000000000..fa81daa2e2 --- /dev/null +++ b/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 + + 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] diff --git a/doc/src/api/rtcForwardOccluded1.md b/doc/src/api/rtcForwardOccluded1.md index a46d102870..ee3cc24ca8 100644 --- a/doc/src/api/rtcForwardOccluded1.md +++ b/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, diff --git a/doc/src/api/rtcGetBufferData.md b/doc/src/api/rtcGetBufferData.md index ea30735748..d9d429f0a0 100644 --- a/doc/src/api/rtcGetBufferData.md +++ b/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] diff --git a/doc/src/api/rtcGetBufferDataDevice.md b/doc/src/api/rtcGetBufferDataDevice.md new file mode 100644 index 0000000000..dbb7c5f5d3 --- /dev/null +++ b/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 + + 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] diff --git a/doc/src/api/rtcNewBuffer.md b/doc/src/api/rtcNewBuffer.md index 1927ad2cd8..5a4701402d 100644 --- a/doc/src/api/rtcNewBuffer.md +++ b/doc/src/api/rtcNewBuffer.md @@ -26,6 +26,13 @@ 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 @@ -33,4 +40,4 @@ queried using `rtcGetDeviceError`. #### SEE ALSO -[rtcRetainBuffer], [rtcReleaseBuffer] +[rtcNewBufferHostDevice], [rtcRetainBuffer], [rtcReleaseBuffer] diff --git a/doc/src/api/rtcNewBufferHostDevice.md b/doc/src/api/rtcNewBufferHostDevice.md new file mode 100644 index 0000000000..02e64d9b1b --- /dev/null +++ b/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 + + 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] diff --git a/doc/src/api/rtcNewSharedBuffer.md b/doc/src/api/rtcNewSharedBuffer.md index 728ead1c90..48720f51c2 100644 --- a/doc/src/api/rtcNewSharedBuffer.md +++ b/doc/src/api/rtcNewSharedBuffer.md @@ -42,4 +42,4 @@ queried using `rtcGetDeviceError`. #### SEE ALSO -[rtcRetainBuffer], [rtcReleaseBuffer] +[rtcNewSharedBufferHostDevice], [rtcRetainBuffer], [rtcReleaseBuffer] diff --git a/doc/src/api/rtcNewSharedBufferHostDevice.md b/doc/src/api/rtcNewSharedBufferHostDevice.md new file mode 100644 index 0000000000..7a87a82001 --- /dev/null +++ b/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 + + 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]