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

#ifndef __BRAY_PixelOracle__
#define __BRAY_PixelOracle__

#include "BRAY_API.h"
#include "BRAY_Interface.h"
#include "BRAY_SampleFilter.h"
#include <SYS/SYS_Hash.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_Rect.h>

class BRAY_PixelState;
class BRAY_FilterInit;
class UT_Options;
class UT_StringArray;

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

/// A Pixel Oracle is responsible for detemining which pixels should be sampled
/// within a tile.
class BRAY_API BRAY_PixelOracle
{
public:
    class BRAY_API Factory
    {
    public:
        virtual ~Factory();
        virtual UT_UniquePtr<BRAY_PixelOracle>
                        instance(const UT_Options *args) const = 0;
    };
    using FactoryPtr = UT_UniquePtr<Factory>;

    /// @{
    /// Factory access
    static void listFactories(UT_StringArray &result);
    static void registerPlugin(const UT_StringHolder &name, FactoryPtr factory);
    static UT_UniquePtr<BRAY_PixelOracle> instancePlugin(
                                const UT_StringRef &style,
                                const UT_Options *options);
    static void releasePlugin(UT_UniquePtr<BRAY_PixelOracle> p);
    static void freePluginCache();
    /// @}

    BRAY_PixelOracle(const UT_Options *args);
    virtual ~BRAY_PixelOracle();

    /// Class name of the oracle
    virtual const char  *className() const = 0;

    /// Fill out the pixels which need to be sampled, returning the number of
    /// pixels filled out.  The @c pixels buffer is guaranteed to have at least
    /// rect.width()*rect.height() entries.  The function should return the
    /// number of samples filled out.  Each pixel should be inside the bounding
    /// rectangle.
    ///
    /// The oracle is free to return a smaller number of rays.  It's also
    /// possible to send multiple rays for a single pixel.
    ///
    /// The default method will send one ray per pixel and is somewhat similar
    /// to @code
    /// for (int y = rect.y(), ye = rect.y2e(); y < ye; ++y)
    ///     for (int x = rect.x(), xe = rect.x2e(); x < xe; ++x, ++pixels)
    ///         *pixels = UT_Vector2i(x, y);
    /// return rect.width()*rect.height();
    /// @endcode
    ///
    virtual size_t      fillPixels(BRAY_PixelState &pstate,
                                    const UT_DimRect &rect,
                                    UT_Vector2i *pixels);

    /// Method used to initialize the oracle.  This will be called prior to
    /// each render (oracles should clear any buffers on subsequent renders).
    ///
    /// Note that sample filters are @b not cleared between subsequent renders,
    /// so if the oracle creates a sample filter, it should be persistent
    /// between runs.
    virtual bool        initializeOracle(BRAY_FilterInit &init,
                                int xres, int yres,
                                const UT_StringArray &aov_names,
                                const UT_IntArray &aov_sizes) = 0;

    /// Return the hash of the arguments for this filter
    SYS_HashType        optionsHash() const { return myOptionsHash; }

    /// Sometimes an oracle can be more efficient when tied to a sampling
    /// filter.  This method allows an oracle to create a sampling filter to
    /// keep track of samples written to the image.  This method is called @b
    /// after @c initializeOracle().
    ///
    /// If the oracle creates a sample filter, it should make sure to call @c
    /// BRAY_SampleFilter::initialize() on the created sample filter.
    virtual BRAY_SampleFilterPtr sampleFilter(BRAY_FilterInit &init,
                                            const UT_StringArray &all_aovs)
                            { return BRAY_SampleFilterPtr(); }

    /// The checkpoint function is called to save the state of the pixel filter
    /// to a checkpoint file.
    ///
    /// The default method prints a warning that checkpointing isn't supported
    /// and fails.
    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);

protected:
    /// Read a pixel from a given AOV.  The aov_index should be the index into
    /// the @c aovnames that was passed into @c initializeOracle() (or the
    /// index returned by @c addAOV());
    ///
    /// For greater efficiency, consider creating a paired SampleFilter.
    const float         *readPixel(const BRAY_PixelState &pstate,
                                int aov_index, int px, int py) const;

    /// Return a random number.  The sequence of random numbers will be
    /// consistent for every render, regardless of threading order.
    ///
    /// The random functions use the same internal state so they should be
    /// called consistently.
    float       randomF(BRAY_PixelState &pstate) const;

    /// Return an integer random number.  This can be used as a seed if
    /// multiple random numbers need to be generated.  The sequence of random
    /// numbers will be conssitent for every render, regardless of threading
    /// order.
    ///
    /// The random functions use the same internal state so they should be
    /// called consistently.
    uint        randomI(BRAY_PixelState &pstate) const;

    /// If the oracle needs an additional AOV, you can call this method during
    /// initializeOracle().  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;
private:
    SYS_HashType        myOptionsHash;
};

using BRAY_PixelOraclePtr = UT_UniquePtr<BRAY_PixelOracle>;

#endif