renderThread.h

//
// Copyright 2018 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache License.
//
#ifndef PXR_IMAGING_HD_RENDER_THREAD_H
#define PXR_IMAGING_HD_RENDER_THREAD_H

#include "pxr/pxr.h"
#include "pxr/imaging/hd/api.h"

#include <atomic>
#include <condition_variable>
#include <functional>
#include <mutex>
#include <thread>

PXR_NAMESPACE_OPEN_SCOPE


class HdRenderThread {
public:

    HD_API
    HdRenderThread();

    HD_API
    ~HdRenderThread();


    HD_API
    void SetRenderCallback(std::function<void()> renderCallback);

    HD_API
    void SetShutdownCallback(std::function<void()> shutdownCallback);

    HD_API
    void StartThread();

    HD_API
    void StopThread();

    HD_API
    bool IsThreadRunning();



    HD_API
    void StartRender();

    HD_API
    void StopRender();

    HD_API
    bool IsRendering();

    HD_API
    void PauseRender();

    HD_API
    void ResumeRender();



    HD_API
    bool IsStopRequested();

    HD_API
    bool IsPauseRequested();

    HD_API
    bool IsPauseDirty();



    HD_API
    std::unique_lock<std::mutex> LockFramebuffer();


private:
    // _RenderLoop implements the render thread's state machine; see
    // \ref HdRenderThread_StateMachine for details.  It runs in a background
    // thread and manages synchronization with hydra.  To implement rendering,
    // it calls out to the render callback provided via SetRenderCallback.
    void _RenderLoop();

    // _renderCallback is the render-delegate-provided function responsible for
    // actually rendering.  It's called from _RenderLoop.
    std::function<void()> _renderCallback;

    // _shutdownCallback is the render-delegate-provided function responsible
    // for cleaning up thread-specific resources.  It's called once, right
    // before _RenderLoop exits.
    std::function<void()> _shutdownCallback;

    // A placeholder initial value for _renderCallback.
    static void _DefaultRenderCallback();

    // A placeholder initial value for _shutdownCallback.
    static void _DefaultShutdownCallback();

    // The state enumeration of the render thread state machine; see
    // \ref HdRenderThread_StateMachine for details.
    enum State {
        // Initial constructed state. Render thread is not running.
        StateInitial,
        // Render thread is running and ready for scene edits. No rendering
        // is taking place.
        StateIdle,
        // Render thread is running and rendering; no scene edits are allowed.
        StateRendering,
        // Render thread is shutting down.
        StateTerminated,
    };

    // _requestedState is set by hydra to direct the render thread's state
    // machine; see \ref HdRenderThread_StateMachine for details.
    // _requestedState is protected by a mutex/condition variable combination.
    // The render thread holds _requestedStateMutex while rendering; the
    // frequency with which it can give it up is the interruption frequency.
    //
    // StartRender() and StopRender() lock and write to _requestedState.
    // _RenderLoop() locks and reads _requestedState.
    State _requestedState;
    std::mutex _requestedStateMutex;
    std::condition_variable _requestedStateCV;

    // _enableRender provides an out-of-band way for hydra to cancel a
    // render while the render thread is still holding _requestedStateMutex.
    //
    // StartRender() and StopRender() will write true/false to _enableRender.
    // IsStopRequested() will read from _enableRender.
    std::atomic_flag _enableRender;
    // _stopRequested keeps track of whether _enableRender has gone low since
    // the last time the render callback was called (since _enableRender is
    // reset on read).
    bool _stopRequested;

    // _pauseRender provides a properly locked boolean flag that holds the
    // current pause state of the thread. Toggled by calling PauseRender and
    // ResumeRender, tested by IsPauseRequested.
    std::atomic<bool> _pauseRender;

    // _pauseDirty provides a properly locked boolean flag that holds the
    // current dirtyness of the pause state of the thread. Toggled by
    // calling PauseRender and ResumeRender, tested by IsPauseDirty.
    std::atomic<bool> _pauseDirty;

    // _rendering records whether the render thread is currently inside the
    // render callback, or planning to be inside the render callback.
    // It is managed by StartRender(), StopRender(), and _RenderLoop().
    // IsRendering() will read from _rendering.
    std::atomic<bool> _rendering;

    // _renderThread is the background render thread; it runs _RenderLoop().
    std::thread _renderThread;

    // _frameBufferMutex protects access to the render delegate's framebuffer,
    // and provides an optional synchronization point for blits between the
    // render thread's resources and the application's resources.
    std::mutex _frameBufferMutex;
};


PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_IMAGING_HD_RENDER_THREAD_H