TIL_HuskDevice.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        TIL_HuskDevice.h (TIL Library, C++)
 *
 * COMMENTS:
 */

#ifndef __TIL_HuskDevice__
#define __TIL_HuskDevice__

#include "TIL_API.h"
#include <UT/UT_Array.h>
#include <UT/UT_Rect.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_Vector2.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_NonCopyable.h>

class PXL_Raster;
class IMG_FileParms;
class IMG_Stat;
class UT_Options;

extern "C"
{
    /// The DSO should call @c TIL_HuskDevice::setDefaultFactory() to override
    /// the default husk display device.
    SYS_VISIBILITY_EXPORT extern void installHuskDisplay();
}

class TIL_API TIL_HuskDevice
{
public:
    using TIL_HuskDevicePtr = UT_UniquePtr<TIL_HuskDevice>;

    struct TIL_API Factory
    {
        Factory() = default;
        virtual ~Factory();
        UT_NON_COPYABLE(Factory);

        virtual TIL_HuskDevicePtr        create() const = 0;
    };

    /// Register the default factory
    static void setDefaultFactory(UT_UniquePtr<Factory> factory);

    /// Return the default device (may be a @c nullptr)
    static TIL_HuskDevicePtr    createDefault();

    TIL_HuskDevice() = default;
    virtual ~TIL_HuskDevice();
    UT_NON_COPYABLE(TIL_HuskDevice);

    /// If supported, return the current pixel location where the user has
    /// clicked the mouse.  husk can pass this through to the render delegate.
    ///
    /// Returns @c false if not supported or if the position passed in is the
    /// same as the last click.
    virtual bool        getMousePosition(UT_Vector2i &pos) const;

    /// Open a new device:
    /// - @c stat contains the AOVs for the image (and contains metadata)
    /// - @c parms contains additional file parameters
    /// - @c creation_options contains creation options (like the frame range,
    ///      and mplay specific settings).
    /// - @c update_options is a list of optional parameters containing stats
    ///      like `percentDone` or `renderStage`.
    /// - @c display_scale is a scale to apply to the display of the rasters.
    ///      The scale will always be greater than 0 and less than or equal to 1.
    /// - @c first_frame is set to true when this is the first frame of a
    ///      sequence (even if the sequence is on frame long).
    virtual bool        create(const IMG_Stat &stat,
                                const IMG_FileParms &parms,
                                const UT_Options &creation_options,
                                const UT_Options &update_options,
                                float display_scale,
                                bool first_frame) = 0;

    /// Update the display with the current rasters
    /// - @c stat contains the AOVs for the image (and contains metadata)
    /// - @c parms contains additional file parameters
    /// - @c update_options is a list of optional parameters containing dynamic
    ///      stats like `percentDone` or `renderStage`.
    /// - @c rasters is the full list of rasters provided by the render delegate
    /// - @c save_rasters is an array of rasters which should be saved
    /// - @c active_buckets is a list of the active bucket regions that the
    ///      renderer provides to husk.
    ///
    /// Note that the @c rasters array may be larger than the number of AOVs
    /// defined in the @c IMG_Stat passed in the @c create call.  The @c
    /// save_rasters array will have an entry for each AOV defined in the @c
    /// IMG_Stat.  For example: @code
    ///  for (int i = 0, n = save_rasters.size(); i < n; ++i) {
    ///      PXL_Raster &rp = rasters[save_rasters[i]];
    ///      saveRaster(stat.getPlane(i), rp);
    ///  }
    /// @endcode
    virtual void        update(const UT_Array<PXL_Raster> &rasters,
                                const UT_Array<int> &save_rasters,
                                const IMG_Stat &stat,
                                const IMG_FileParms &parms,
                                const UT_Options &update_options,
                                const UT_Array<UT_DimRect> &active_buckets) = 0;
};

#endif