TIL_RasterFilter.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_MiscHelper.h (TIL Library, C++)
 *
 * COMMENTS:    A generic interface to provide filters for rasters with
 *              multiple raster planes.  Examples of this might include
 *              denoisers which read from multiple input planes and write to
 *              multiple output planes.
 *
 */

#ifndef TIL_MiscHelper_H
#define TIL_MiscHelper_H

#include "TIL_API.h"
#include "TIL_Defines.h"

#include <UT/UT_NonCopyable.h>
#include <UT/UT_Options.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_UniquePtr.h>
#include <SYS/SYS_Visibility.h>

class PXL_Raster;
class UT_Options;

/// Apply arbitrary filters to PXL_Raster image(s).
///
/// The DSO must implement "newRasterFilter" function which should create new
/// filters by calling TIL_RasterFilter::registerFactory().  Image filters will
/// be searched for in $HOUDINI_DSO_PATH/img_filter.
///
/// When the filter is instantiated, the caller will initialize the filter
/// calling @c setOptions.  This is only called one time, though the filter may
/// be invoked multiple times.
///
/// Prior to invoking the filter, the @c reset() method will be called.  This
/// lets the filter reset any information that changes from run to run.
///
/// The caller will then set up any optional read-only auxilliary rasters the
/// filter may need for processing.  That is, the caller will call @c
/// setAuxPlane zero or more times.
///
/// After the filter is reset and auxilliary planes are added, the @c apply()
/// method will finally be called.  This should modify the raster passed in to
/// create the resulting image.  It's possible the apply() method may be called
/// multiple times before reset() is called again.
class TIL_API TIL_RasterFilter
{
public:
    using TIL_RasterFilterPtr = UT_UniquePtr<TIL_RasterFilter>;

    /// The factory to define a filter
    struct TIL_API Factory
    {
        Factory() = default;
        virtual ~Factory();
        UT_NON_COPYABLE(Factory)
        virtual const UT_StringHolder   &name() const = 0;
        virtual const UT_StringHolder   &label() const = 0;
        virtual TIL_RasterFilterPtr      newFilter() const = 0;
    };

    /// @{
    /// Constructor/Destructor
    TIL_RasterFilter() {};
    virtual ~TIL_RasterFilter() {};
    /// @}

    UT_NON_COPYABLE(TIL_RasterFilter)

    /// @{
    /// Get tokens that are used to store auxilliary planes
    static const UT_StringHolder        &albedoToken();
    static const UT_StringHolder        &normalToken();
    static const UT_StringHolder        &mvectorToken();
    static const UT_StringHolder        &prevfrToken();
    /// @}

    /// Register a new factory.  Set HOUDINI_DSO_ERROR=1 to get information on
    /// why the filter might not be installed.
    static void         registerFactory(UT_UniquePtr<Factory> factory);

    /// Remove a factory from the list
    static void         removeFactory(const UT_StringRef &name);

    /// Get a list of all the filters
    static void         getFilters(UT_Array<const Factory *> &filters);

    // Allocate a filter of a given name
    static TIL_RasterFilterPtr  allocFilter(const UT_StringRef &name);

    /// For debugging
    virtual const char          *className() const = 0;

    /// Initiaze the filter with user specified options.  This method is only
    /// called once.  If the filter isn't valid, the @c myErrorString member
    /// should be set to a meaningful error and the function should return
    /// false.
    ///
    /// Aside from setting any specific options, this is also the time you
    /// should build myAuxPlaneNames.  This lets the caller know which extra
    /// AOVs you can read from.  Not all of them may exist, but this lets the
    /// caller know which planes you can look at.
    virtual bool        setOptions(const UT_Options &options) { return true; }

    /// Set up an auxilliary plane.  This is a raster which isn't actually
    /// modified, but is used in the filtering (for example a mask).  The
    /// caller looks at the @c myAuxPlaneNames list to see which rasters you
    /// might require.  If they are available, they will be stashed in this
    /// array.
    void                setAuxPlane(const UT_StringHolder &planename,
                                     const PXL_Raster *raster)
                        {
                            myAuxPlanes[planename] = raster;
                        }

    /// Returns false if fail
    virtual bool        apply(PXL_Raster *raster) = 0;

    /// Reset and get ready for a new filter.  If you subclass this method,
    /// please make sure to call the base class method.
    virtual void        reset()
                        {
                            myAuxPlanes.clear();
                        }

    /// Get the list of aux plane names
    const UT_StringArray        &getAuxPlaneNames() const
                                    { return myAuxPlaneNames; }

    /// Get stored error msg in case apply() fails.  Sub-classes can set @c
    /// myErrorString to something meaningful for the caller.
    const UT_StringHolder   &getErrorString() const
                                    { return myErrorString; }

    /// If the filter can run in a few milliseconds, you can try returning
    /// true.
    virtual bool        isInteractive() const { return false; }

protected:
    UT_StringArray                       myAuxPlaneNames;
    UT_StringMap<const PXL_Raster *>     myAuxPlanes;
    UT_StringHolder                      myErrorString;
};

using TIL_RasterFilterPtr = TIL_RasterFilter::TIL_RasterFilterPtr;

extern "C" {
    /// DSO function called.  This function can register one or more filters.
    /// Only filters which are supported should be registered.
    SYS_VISIBILITY_EXPORT extern void     newRasterFilter();
}

#endif