From ca626dec13e333754647a12ed2aa7ccc6f55300f Mon Sep 17 00:00:00 2001 From: Florian Reibold Date: Tue, 10 Dec 2024 11:33:01 +0100 Subject: [PATCH] update rtcSet(New|Shared)GeometryBuffer(|HostDevice) documentation --- doc/src/api-ref.md | 15 ++++ doc/src/api/rtcCommitBuffer.md | 2 +- doc/src/api/rtcGetGeometryBufferData.md | 7 +- doc/src/api/rtcGetGeometryBufferDataDevice.md | 36 ++++++++++ .../api/rtcSetNewGeometryBufferHostDevice.md | 62 ++++++++++++++++ doc/src/api/rtcSetSharedGeometryBuffer.md | 7 +- .../rtcSetSharedGeometryBufferHostDevice.md | 70 +++++++++++++++++++ 7 files changed, 196 insertions(+), 3 deletions(-) create mode 100644 doc/src/api/rtcGetGeometryBufferDataDevice.md create mode 100644 doc/src/api/rtcSetNewGeometryBufferHostDevice.md create mode 100644 doc/src/api/rtcSetSharedGeometryBufferHostDevice.md diff --git a/doc/src/api-ref.md b/doc/src/api-ref.md index 58057929a5..f7a66507ec 100644 --- a/doc/src/api-ref.md +++ b/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} ``` diff --git a/doc/src/api/rtcCommitBuffer.md b/doc/src/api/rtcCommitBuffer.md index 5cb8c1fc76..529ba44403 100644 --- a/doc/src/api/rtcCommitBuffer.md +++ b/doc/src/api/rtcCommitBuffer.md @@ -1,4 +1,4 @@ -% rtcCommitSBuffer(3) | Embree Ray Tracing Kernels 4 +% rtcCommitBuffer(3) | Embree Ray Tracing Kernels 4 #### NAME diff --git a/doc/src/api/rtcGetGeometryBufferData.md b/doc/src/api/rtcGetGeometryBufferData.md index 85188c8cc1..e13ce634eb 100644 --- a/doc/src/api/rtcGetGeometryBufferData.md +++ b/doc/src/api/rtcGetGeometryBufferData.md @@ -22,6 +22,10 @@ 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 @@ -29,4 +33,5 @@ On failure an error code is set that can be queried using #### SEE ALSO -[rtcSetGeometryBuffer], [rtcSetSharedGeometryBuffer], [rtcSetNewGeometryBuffer] +[rtcGetGeometryBufferDataDevice], [rtcSetGeometryBuffer], +[rtcSetSharedGeometryBuffer], [rtcSetNewGeometryBuffer] diff --git a/doc/src/api/rtcGetGeometryBufferDataDevice.md b/doc/src/api/rtcGetGeometryBufferDataDevice.md new file mode 100644 index 0000000000..a51b21e4dd --- /dev/null +++ b/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 + + 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] diff --git a/doc/src/api/rtcSetNewGeometryBufferHostDevice.md b/doc/src/api/rtcSetNewGeometryBufferHostDevice.md new file mode 100644 index 0000000000..e0120324f3 --- /dev/null +++ b/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 + + 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] diff --git a/doc/src/api/rtcSetSharedGeometryBuffer.md b/doc/src/api/rtcSetSharedGeometryBuffer.md index f04cc241d2..50f617ff78 100644 --- a/doc/src/api/rtcSetSharedGeometryBuffer.md +++ b/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] diff --git a/doc/src/api/rtcSetSharedGeometryBufferHostDevice.md b/doc/src/api/rtcSetSharedGeometryBufferHostDevice.md new file mode 100644 index 0000000000..381cbfb0cd --- /dev/null +++ b/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 + + 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]