|
HdRenderThread is a utility that specific render delegates can choose to use depending on their needs. More...
#include <renderThread.h>
Public Member Functions | |
API for thread management | |
HD_API void | SetRenderCallback (std::function< void()> renderCallback) |
Set the rendering callback for the render thread to use. | |
HD_API void | SetShutdownCallback (std::function< void()> shutdownCallback) |
Set the shutdown callback for the render thread to use. | |
HD_API void | StartThread () |
Start the rendering background thread. | |
HD_API void | StopThread () |
Stop the rendering background thread. | |
HD_API bool | IsThreadRunning () |
Check whether the background thread is running (i.e. | |
API for hydra threads | |
HD_API void | StartRender () |
Ask the render thread to start rendering. | |
HD_API void | StopRender () |
Ask the render thread to stop rendering, and block until the render thread is idle. | |
HD_API bool | IsRendering () |
Query whether the render thread is currently rendering. | |
HD_API void | PauseRender () |
Ask the render thread to pause rendering. | |
HD_API void | ResumeRender () |
Ask the render thread to resume rendering. | |
HD_API bool | IsStopRequested () |
Query whether hydra has asked to interrupt the current frame since the last time StartRender() was called. | |
HD_API bool | IsPauseRequested () |
Query whether hydra has asked to pause rendering. | |
HD_API bool | IsPauseDirty () |
Query whether the pause/resume state has changed since the last time we called IsPauseDirty. | |
API for both hydra and render threads | |
HD_API std::unique_lock< std::mutex > | LockFramebuffer () |
Return a scoped lock on the render delegate's framebuffer. | |
HdRenderThread is a utility that specific render delegates can choose to use depending on their needs.
It provides a system for rendering in a background thread, and synchronizing between hydra (either in the main thread, or the sync threadpool) and the rendering thread.
The render thread is implemented in terms of a state machine, and hydra requests to the render thread are implemented in terms of transitions on that state machine.
States:
Transitions:
Having a locked and shared framebuffer is important if you want to avoid tearing, or if the rendering API disallows multithreaded access to buffers (for example, if your framebuffers are on a GPU). It might be unnecessary for some renderers.
Stopping the render only when you're about to make a scene edit means that long-running renders aren't interrupted if the scene is static. Hiding the renderer's scene data handle behind AcquireSceneForEdit helps callers use the synchronization mechanisms correctly.
The render is restarted at the last possible second, in the render pass, after we know scene edits are done.
The render callback should use IsStopRequested() as a cancellation mechanism.
Definition at line 129 of file renderThread.h.
HD_API bool IsPauseDirty | ( | ) |
Query whether the pause/resume state has changed since the last time we called IsPauseDirty.
HD_API bool IsPauseRequested | ( | ) |
Query whether hydra has asked to pause rendering.
This will continue to return true until a request has been made for rendering to resume. Remember to check for a stop request while paused.
HD_API bool IsRendering | ( | ) |
Query whether the render thread is currently rendering.
This is set by StartRender() and reset after the render callback exits, or reset by StopRender() if the render callback never runs. This does not block, and is fully threadsafe.
HD_API bool IsStopRequested | ( | ) |
Query whether hydra has asked to interrupt the current frame since the last time StartRender() was called.
The render callback can check this to determine whether to cancel rendering.
HD_API bool IsThreadRunning | ( | ) |
Check whether the background thread is running (i.e.
StartThread was called successfully, but StopThread has not been).
HD_API std::unique_lock< std::mutex > LockFramebuffer | ( | ) |
Return a scoped lock on the render delegate's framebuffer.
Hydra and the render thread can use this to synchronize blits between render-thread owned resources, and application-owned resources.
HD_API void PauseRender | ( | ) |
Ask the render thread to pause rendering.
The speed at which the renderer actually enters the pause state depends on the delegate.
HD_API void ResumeRender | ( | ) |
Ask the render thread to resume rendering.
Pause and Resume calls do not need to be paired. The last call (to Pause or Resume) decides the current state.
HD_API void SetRenderCallback | ( | std::function< void()> | renderCallback | ) |
Set the rendering callback for the render thread to use.
HD_API void SetShutdownCallback | ( | std::function< void()> | shutdownCallback | ) |
Set the shutdown callback for the render thread to use.
This will be called once, right before the render thread exits, regardless of whether the render callback has been called. This can be used to clean up thread-specific rendering resources.
HD_API void StartRender | ( | ) |
Ask the render thread to start rendering.
This call is a no-op if the render thread is already rendering. Otherwise, it may block briefly. This is threadsafe against the render thread, but it shouldn't be called at the same time as StopRender(), and it shouldn't be called from multiple hydra threads at once.
HD_API void StartThread | ( | ) |
Start the rendering background thread.
Note: it's an error to call this function when the render thread is already running, but it's acceptable to stop the render thread and then start it again.
HD_API void StopRender | ( | ) |
Ask the render thread to stop rendering, and block until the render thread is idle.
This is fully threadsafe, and can be called from multiple hydra threads at once.
HD_API void StopThread | ( | ) |
Stop the rendering background thread.
This function will ask the render thread to transition to StateTerminated, and then join on the thread, so it will block. After this function returns, the rendering state machine will be back in its initial state, and the render thread can be started again.