Asynchronous GPU upload manager. More...
#include <GPUUploadManager.h>
Public Member Functions | |
| virtual void DILIGENT_CALL_TYPE | RenderThreadUpdate (IDeviceContext *pContext)=0 |
| virtual bool DILIGENT_CALL_TYPE | ScheduleBufferUpdate (const ScheduleBufferUpdateInfo &UpdateInfo)=0 |
| virtual bool DILIGENT_CALL_TYPE | ScheduleTextureUpdate (const ScheduleTextureUpdateInfo &UpdateInfo)=0 |
| virtual void DILIGENT_CALL_TYPE | GetStats (GPUUploadManagerStats &Stats)=0 |
| virtual void DILIGENT_CALL_TYPE | Stop (IDeviceContext *pContext)=0 |
| Public Member Functions inherited from Diligent.IObject | |
| virtual void DILIGENT_CALL_TYPE | QueryInterface (const INTERFACE_ID &IID, IObject **ppInterface)=0 |
| Queries the specific interface. | |
| template<typename DerivedType, typename = typename std::enable_if<std::is_base_of<IObject, DerivedType>::value>::type> | |
| void | QueryInterface (const INTERFACE_ID &IID, DerivedType **ppInterface) |
| virtual ReferenceCounterValueType DILIGENT_CALL_TYPE | AddRef ()=0 |
| Increments the number of strong references by 1. | |
| virtual ReferenceCounterValueType DILIGENT_CALL_TYPE | Release ()=0 |
| virtual IReferenceCounters *DILIGENT_CALL_TYPE | GetReferenceCounters () const =0 |
Detailed Description
Asynchronous GPU upload manager.
Member Function Documentation
◆ GetStats()
|
pure virtual |
Retrieves GPU upload manager statistics.
The method must not be called concurrently with RenderThreadUpdate(), GetStats(), or ScheduleBufferUpdate()/ScheduleTextureUpdate() calls that provide a non-null device context. It may be called concurrently with worker-thread ScheduleBufferUpdate()/ScheduleTextureUpdate() calls that use a null device context.
Pointers returned in the Stats structure are valid only until the next call to GetStats() and must not be used after that.
◆ RenderThreadUpdate()
|
pure virtual |
Executes pending render-thread operations.
The method can be called in parallel with ScheduleBufferUpdate() and ScheduleTextureUpdate() from worker threads, but only one thread is allowed to call RenderThreadUpdate() at a time. RenderThreadUpdate() must not be called concurrently with Stop(), and the device context used by the manager must not be used concurrently by other threads. pContext must not be null. If no context was provided at creation, the first context passed to RenderThreadUpdate() becomes the manager context. Otherwise, it must be the same as the manager context.
The method must be called periodically to process pending updates. If the method is not called, ScheduleBufferUpdate() or ScheduleTextureUpdate() may block indefinitely when there are no free pages available for new updates.
◆ ScheduleBufferUpdate()
|
pure virtual |
Schedules an asynchronous buffer update operation.
- Parameters
-
[in] UpdateInfo - Structure describing the buffer update operation. See ScheduleBufferUpdateInfo for details.
- Returns
- true if the update was successfully accepted by the manager, false if it was rejected due to invalid parameters, a stopped manager, or an internal scheduling failure. If false is returned, any abandoned-scheduling callback is invoked before the method returns.
The method is thread-safe for worker-thread calls that use a null pContext. These calls can be made from multiple threads simultaneously with other worker-thread ScheduleBufferUpdate() calls and RenderThreadUpdate(). Calls that provide a non-null pContext use the device context and must be externally serialized with RenderThreadUpdate(), Stop(), GetStats(), and other use of the same context. The caller must keep the upload manager alive for the entire duration of this call. Worker threads should hold their own strong reference to the manager if the manager may be stopped or released concurrently. Calls admitted before Stop() may complete; calls admitted after Stop() are ignored and return false. Calls must not race with manager destruction.
Accepted updates are not ordered by submission time. Updates may be submitted to different internal streams or different pages and can be executed or reported through callbacks in a different order than ScheduleBufferUpdate() calls were made. If the final contents depend on the order of overlapping destination ranges, schedule the later update only after the earlier update's callback has reported that it was enqueued, or submit one update with the final data.
If the method is called from a worker thread, the pContext parameter must be null, and the render thread must periodically call RenderThreadUpdate() to process pending buffer updates. If RenderThreadUpdate() is not called, the method may block indefinitely when there are no free pages available for new updates.
If the method is called from the render thread, the pContext parameter must be a pointer to the manager context. If no manager context has been set yet, pContext becomes the manager context. If the method is called from the render thread with null pContext, it may never return.
◆ ScheduleTextureUpdate()
|
pure virtual |
Schedules an asynchronous texture update operation.
- Parameters
-
[in] UpdateInfo - Structure describing the texture update operation. See ScheduleTextureUpdateInfo for details.
- Returns
- true if the update was successfully accepted by the manager, false if it was rejected due to invalid parameters, a stopped manager, or an internal scheduling failure. If false is returned, any abandoned-scheduling callback is invoked before the method returns.
The method is thread-safe for worker-thread calls that use a null pContext. These calls can be made from multiple threads simultaneously with other worker-thread ScheduleTextureUpdate() calls and RenderThreadUpdate(). Calls that provide a non-null pContext use the device context and must be externally serialized with RenderThreadUpdate(), Stop(), GetStats(), and other use of the same context. The caller must keep the upload manager alive for the entire duration of this call. Worker threads should hold their own strong reference to the manager if the manager may be stopped or released concurrently. Calls admitted before Stop() may complete; calls admitted after Stop() are ignored and return false. Calls must not race with manager destruction.
Accepted updates are not ordered by submission time. Updates may be submitted to different internal streams or different pages and can be executed or reported through callbacks in a different order than ScheduleTextureUpdate() calls were made. If the final contents depend on the order of overlapping destination regions, schedule the later update only after the earlier update's callback has reported that it was enqueued, or submit one update with the final data.
If the method is called from a worker thread, the pContext parameter must be null, and the render thread must periodically call RenderThreadUpdate() to process pending texture updates. If RenderThreadUpdate() is not called, the method may block indefinitely when there are no free pages available for new updates.
If the method is called from the render thread, the pContext parameter must be a pointer to the manager context. If no manager context has been set yet, pContext becomes the manager context. If the method is called from the render thread with null pContext, it may never return.
◆ Stop()
|
pure virtual |
Permanently stops the upload manager.
- Parameters
-
[in] pContext - Device context used to release staging resources. Must not be null.
The method wakes any threads blocked in ScheduleBufferUpdate() or ScheduleTextureUpdate(). After this call, the manager must not be used for new upload scheduling, render-thread updates, or statistics queries; only releasing outstanding references is allowed. Worker-thread calls that are already blocked in ScheduleBufferUpdate() or ScheduleTextureUpdate() are cancelled and invoke their callbacks with null handles as the calls return. Accepted updates that have not yet been submitted by RenderThreadUpdate() are abandoned and will invoke their callbacks with null handles during manager teardown. RenderThreadUpdate() and GetStats() calls after Stop() are misuse.
Stop() waits for admitted scheduling calls to return and releases staging resources using pContext. If the manager context has not been set yet, pContext becomes the manager context. Otherwise, pContext must be the same as the manager context. The context must not be used concurrently while Stop() is executing. Internal stream/page objects remain alive until the manager is destroyed.
Stop() is a render-thread/context-owning call. The first Stop() call must be made from the render thread and must not race with RenderThreadUpdate(), GetStats(), another Stop() call, or ScheduleBufferUpdate()/ScheduleTextureUpdate() calls that provide a non-null device context. After Stop() has completed, subsequent Stop() calls are no-ops and return immediately.
The method may be called while worker threads are inside ScheduleBufferUpdate() or ScheduleTextureUpdate(). The manager must remain alive until these calls have returned. The first Stop() call must not be made while other render-thread/context-owning upload-manager calls are running.
If Stop() is not called explicitly, the manager destructor performs the same internal stop sequence using the stored manager context from whichever thread releases the last reference. If no context has ever been provided to the manager, destructor cleanup proceeds without a context; in this case no staging resources have been mapped through the manager.
