BRAY_ImageFilter.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:        BRAY_ImageFilter.h (RAY Library, C++)
 *
 * COMMENTS:
 */

#ifndef __BRAY_ImageFilter__
#define __BRAY_ImageFilter__

#include "BRAY_API.h"
#include "BRAY_FilterBase.h"
#include "BRAY_PixelOracle.h"
#include "BRAY_Interface.h"

class UT_Options;
class BRAY_Raster;
class BRAY_FilterInit;

extern "C" {
    SYS_VISIBILITY_EXPORT extern void newBRAYImageFilter(void *);
}

/// Image filter plugins are run after pixel filtering, but before the rasters
/// are written to the display device.
class BRAY_API BRAY_ImageFilter
    : public BRAY_FilterBase
{
public:
    class BRAY_API Factory
    {
    public:
        virtual ~Factory();

        /// Create an instance of the BRAY_ImageFilter
        virtual UT_UniquePtr<BRAY_ImageFilter> instance(const UT_Options *o) const = 0;
    };
    using FactoryPtr = UT_UniquePtr<Factory>;

    /// @{
    /// Access to factory
    static void listFactories(UT_StringArray &result);

    static void registerPlugin(const UT_StringHolder &name, FactoryPtr factory);

    static UT_UniquePtr<BRAY_ImageFilter> instancePlugin(
                                const UT_StringRef &style,
                                const UT_Options *options=nullptr);
    static void releasePlugin(UT_UniquePtr<BRAY_ImageFilter> p);
    static void freePluginCache();
    /// @}

    // c-tor
    BRAY_ImageFilter(const UT_Options *o)
        : BRAY_FilterBase(o)
    {
    }

    // d-tor
    ~BRAY_ImageFilter() override;

    /// @{
    /// Methods to be implemented from base class
    using BRAY_FilterBase::className;
    using BRAY_FilterBase::getAOVs;
    using BRAY_FilterBase::errorMessage;
    /// @}

    /// Return whether the filter can be run interactively (for intermediate
    /// IPR updates for example).  If this method returns false, when rendering
    /// interactively, the filter will only be run when the rendering has
    /// completed.  If the method returns true, the filter may be run 100s or
    /// 1000s of times during an interactive render.
    ///
    /// When rendering non-interactively, image filters are run at the end of
    /// the render.
    virtual bool        isInteractive() const = 0;

    /// If the filter does not need to read or write to neighbouring pixels,
    /// then allow it to run per-bucket. When this is true, processBucket() is
    /// invoked instead of processImage(), and it is invoked each time a bucket
    /// is finished (by its own worker thread).
    virtual bool        isPerBucket() const { return false; }

    /// Process the rasters.  The plugin should write to the @c write rasters
    /// passed in, using the @c read rasters as source data.  The order of the
    /// rasters in the arrays matches the order in @c writePlanes() and @c
    /// readPlanes().  So, it follows the size of the arrays should match the
    /// size of the @c writePlanes() and @c readPlanes.
    ///
    /// This order is immutable after initialization is called.
    virtual bool         processImage(const UT_Array<BRAY_Raster *> &write,
                                const UT_Array<const BRAY_Raster *> &read) = 0;

    /// Process the rasters (per-bucket version).
    /// Note that per-bucket image filters are processed before whole-image
    /// filters.
    virtual bool         processBucket(const UT_Array<BRAY_Raster *> &write,
                                const UT_Array<const BRAY_Raster *> &read,
                                const UT_DimRect &bucket)
                         { return false; }

    /// An image filter can, optionally, provide a pixel oracle to help steer
    /// rendering.  The filter should provide an option to the user to disable
    /// creation of this oracle.  It should also be able to run without the
    /// oracle.  The default method returns a nullptr.
    ///
    /// This method is called after @c initialize() is called on the image
    /// filter.
    virtual BRAY_PixelOraclePtr pixelOracle()
                        { return BRAY_PixelOraclePtr(); }

    /// Updates the image filter for the given options.
    /// If supported an image filter can update itself by calling 
    /// update method with new parameters. This avoids the need to 
    /// recreate the filter everytime an option changes.
    /// 
    /// Returns true on success or false if fails to update.
    virtual bool                update(const UT_Options& options) 
                        { return false; };

protected:
    /// If the filter needs an additional AOV, you can call this method during
    /// getAOVs().  The function returns the index of the new AOV (or -1 on
    /// failure).  If there are errors, the messages will be printed out to
    /// UT_ErrorLog.
    ///
    /// If options are required, they can be initialized by planeProperties()
    /// Passing in an empty OptionSet is legal.
    int                 addAOV(BRAY_FilterInit &init,
                                const UT_StringHolder &name,
                                const UT_StringHolder &var,
                                int tuple_size,
                                const BRAY::OptionSet &options);

    /// Create an option set before adding creating an extra AOV
    BRAY::OptionSet     planeProperties(BRAY_FilterInit &init) const;
};

using BRAY_ImageFilterPtr = UT_UniquePtr<BRAY_ImageFilter>;

#endif