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

#ifndef __BRAY_PixelFilter__
#define __BRAY_PixelFilter__

#include "BRAY_API.h"
#include "BRAY_SampleFilter.h"
#include "BRAY_Interface.h"
#include "BRAY_Raster.h"
#include <UT/UT_UniquePtr.h>
#include <UT/UT_IntArray.h>

class UT_Options;
class BRAY_PixelState;
class BRAY_FilterInit;

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

/// Pixel filters take raw samples as generated by the renderer and can adjust
/// the sample data values prior to sending it to pixel filtering.  A pixel
/// filter might average all the samples for a given pixel, or it might just
/// select a single sample for the pixel value.
class BRAY_API BRAY_PixelFilter
{
public:
    class BRAY_API Factory
    {
    public:
        virtual ~Factory();

        /// Create an instance of the BRAY_PixelFilter
        virtual UT_UniquePtr<BRAY_PixelFilter> instance(const UT_Options *o) const = 0;

        /// Test if the filter is deprecated
        virtual bool    isDeprecated() const { return false; }
    };
    using FactoryPtr = UT_UniquePtr<Factory>;

    /// @{
    /// Access to factory
    static void listFactories(UT_StringArray &result,
                        bool include_deprecated=false);

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

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

    // c-tor
    BRAY_PixelFilter(const UT_Options *options);

    // d-tor
    virtual ~BRAY_PixelFilter();

    /// Class name for the pixel filter
    virtual const char  *className() const = 0;

    /// Sample data passed to the pixel filter is the same as the data
    /// processed by sample filters.
    using SampleData = BRAY_SampleFilter::SampleData;

    /// Process the sample data.  Each AOV plane of the @c data will point to a
    /// contiguous array of sample data which contains at least @c npixels of
    /// data.  The filter should be applied to each pixel in the sample data.
    ///
    /// The @c sample_locations are stored as: @code
    ///   v[0] := pixel_x location
    ///   v[1] := pixel_y location
    ///   v[2] := jitter_x location (0 to 1 in pixel)
    ///   v[3] := jitter_y location (0 to 1 in pixel)
    /// @endcode
    ///
    /// Note that with Filtered Importance Sampling, the jitter values may be
    /// outside the given pixel.
    ///
    /// The @c BRAY_PixelState object is an opaque object that should be passed
    /// to @c writePixel()
    ///
    /// The typical filtering code looks like: @code
    /// for (size_t sample = 0; sample < nsamples; ++sample)
    /// {
    ///     // Optionally only write data if the sample hit an object
    ///     // if (sampleHitOrMiss(pstate)) {}
    ///     writePixel(pstate, data, sample_locations, i);
    /// }
    /// @endcode
    virtual void         filter(BRAY_PixelState &pstate,
                                const SampleData &data,
                                const UT_Vector4 *sample_locations,
                                size_t nsamples) = 0;

    /// The checkpoint function is called to save the state of the pixel filter
    /// to a checkpoint file.
    virtual bool        checkpoint(UT_JSONWriter &w) const = 0;

    /// @c loadCheckpoint is called to restore the state of the pixel filter.
    /// In theory, all the settings for the pixel filter should match.  Only
    /// per-pixel data should be different.
    virtual bool        loadCheckpoint(UT_JSONParser &p);

    /// Test whether the sample hit or missed intersecting an object
    bool        sampleHitOrMiss(const BRAY_PixelState &ps, int sidx) const;

    /// Write sample data to a pixel.  The @c weight is the filter weight for
    /// the given sample.  The sample data is passed directly from the
    /// BRAY_SampleFilters.
    void        writePixel(BRAY_PixelState &ps,
                            const SampleData &data,
                            const UT_Vector4 *sample_locations,
                            int sidx);

    /// Overwrite the color in the pixel with the given sample data.  This
    /// doesn't filter data, but writes the data directly to the AOVs,
    /// overwriting the data that was there previously.
    void        overwritePixel(BRAY_PixelState &ps,
                            const SampleData &data,
                            const UT_Vector4 *sample_locations,
                            int sidx);

    /// Add to existing data without any filtering.
    void        accumulatePixel(BRAY_PixelState &ps,
                            const SampleData &data,
                            const UT_Vector4 *sample_locations,
                            int sidx);

    /// Test to see if data has been written to a given sample
    bool        hasWrittenPixel(const BRAY_PixelState &ps,
                            const UT_Vector4 *sample_locations,
                            int sidx) const;

    /// Return the AOVs that this pixel filter is applied to.  This may not be
    /// a subset of all the AOVs.  The filter should only write to these planes
    /// and no others.
    const UT_IntArray   &aovs() const { return myAOVs; }

    /// @{
    /// @private This method is used to create the weight buffer.
    void                 initializeWeight(BRAY_FilterInit &init,
                                int xres, int yres,
                                const UT_StringArray &aovnames);
    void                 setAOVs(const UT_IntArray &aovs) { myAOVs = aovs; }
    SYS_HashType         optionsHash() const { return myOptionsHash; }
    /// @}

    /// By default(0) one pixel filter instance can be applied to any number of
    /// AOVs. Some filters (e.g. minmax under "min" or "max" mode) shouldn't be
    /// shared between multiple AOVs, in which case this may return 1.
    virtual int          aovLimit() const { return 0; }

    /// @{
    /// Save and restore state
    bool        saveState(UT_JSONWriter &w) const;
    bool        loadState(UT_JSONParser &p);
    /// @}

protected:
    /// This method can be used to perform any setup required prior to
    /// filtering.  This method may be called when re-rendering.  That is, this
    /// method may be called on an existing object.
    ///
    /// The AOV names passed in will be in the same order as the sample data
    /// passed in.
    virtual void        setResolution(BRAY_FilterInit &init,
                                    int xres, int yres,
                                    const UT_StringArray &aovnames);

    /// If the filter needs an additional AOV, you can call this method during
    /// setResolution().  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.
    ///
    /// Data from this AOV will be available in the SampleData at the returned
    /// index.
    ///
    /// 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;

private:
    UT_IntArray                 myAOVs;
    UT_UniquePtr<BRAY_Raster>   myWriteCount;
    SYS_HashType                myOptionsHash;
};

using BRAY_PixelFilterPtr = UT_UniquePtr<BRAY_PixelFilter>;

#endif