UT_Ramp.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:        UT library (C++)
 *
 * COMMENTS:    Ramp class
 *
 */


#ifndef _UT_Ramp_
#define _UT_Ramp_

#include "UT_API.h"
#include "UT_Array.h"
#include "UT_Color.h"
#include "UT_Map.h"
#include "UT_Pixel.h"
#include "UT_Spline.h"
#include "UT_VectorTypes.h"
#include "UT_SharedPtr.h"

#include <SYS/SYS_Types.h>
#include <SYS/SYS_Hash.h>

#include <tbb/spin_mutex.h>

#include <iosfwd>


class UT_RampOpResolver;
class UT_Raster;
class UT_IStream;

// Pass to redraw
enum UT_RampOrient
{
        UT_RAMP_HORIZONTAL,
        UT_RAMP_VERTICAL,
        UT_RAMP_RADIAL,
        UT_RAMP_CONCENTRIC
};

// Floating point RGBA values
class UT_API UT_ColorNode
{
    struct SerializableFRGBA : public UT_FRGBA
    {
        using UT_FRGBA::operator=;
        
        template <typename ARCHIVER_T>
        bool serialize(ARCHIVER_T &archiver)
        {
            return archiver.serializeUniformArray(&r, 4);
        }
    };
    
public:
    UT_ColorNode() {}
    UT_ColorNode(fpreal offset, const UT_FRGBA &color,
                 UT_SPLINE_BASIS basis_ = UT_SPLINE_LINEAR,
                 bool enable_pos_ = true,
                 bool enable_val_ = true,
                 bool enable_interp_ = true)
    {
        t = offset;
        old_t = t;
        basis = basis_;
        rgba = color;
        old_rgba = rgba;
        enable_pos = enable_pos_;
        enable_val = enable_val_;
        enable_interp = enable_interp_;
    }

    SYS_HashType        hash() const;

    template <typename ARCHIVER_T>
    bool            serialize(ARCHIVER_T &archiver);

    float               t;
    float               old_t;
    SerializableFRGBA   rgba;
    SerializableFRGBA   old_rgba;
    UT_SPLINE_BASIS     basis;
    bool                enable_pos:1,
                        enable_val:1,
                        enable_interp:1;
};

//==========================================================================

/// Utility class for containing a color ramp
class UT_API UT_Ramp
{
public:
     UT_Ramp();
     /// Do not pass by value, you should be passing by
     /// const &. If you really need by value make the copy
     /// internally to your system.
     explicit UT_Ramp(const UT_Ramp &copy);
    ~UT_Ramp();

    /// Return the amount of memory owned by this UT_Ramp in bytes
    int64 getMemoryUsage(bool inclusive) const;

    void                 setColorType(UT_ColorType color_space)
                            { myColorType = color_space; }
    UT_ColorType         getColorType() const
                            { return myColorType; }

    void                 clearAndDestroy();

    /// Force updating of the ramp after being modified.
    void                 ensureRampIsBuilt();

    bool                 getGlobalEnable() const
                            { return myGlobalEnable; }
    void                 setGlobalEnable(bool enable)
                            { myGlobalEnable = enable; }

    int                  getNodeCount() const { return myNodes.entries(); }
    const UT_ColorNode  *getNode(int i) const;

    UT_ColorNode        *getRamp()
                            { return myNodes.entries() > 0 ? &myNodes(0)
                                                           : nullptr; }
    const UT_ColorNode  *getRamp() const
                            { return myNodes.entries() > 0 ? &myNodes(0)
                                                           : nullptr; }

    void                 convertToRaster(   UT_Raster     *raster,
                                            UT_RampOrient  dir,
                                            bool           do_interp = true,
                                            // Currently only for radial and
                                            // concentric
                                            fpreal         cx = 0.0f,
                                            fpreal         cy = 0.0f,
                                            fpreal         phase = 0.0f,
                                            // For radial, this means "repeat"
                                            fpreal         radius = 1.0f);

    const UT_ColorNode  *getClosestNode(fpreal pos) const;
    int                  getClosestNodeIndex(fpreal pos) const;

    const UT_ColorNode  *getClosestNode(fpreal pos, fpreal val) const;
    int                  getClosestNodeIndex(fpreal pos, fpreal val) const;

    const UT_ColorNode  *getCurrentNode() const;
    int                  getCurrentNodeIndex() const;
    void                 setCurrentNodeIndex(int i, bool add_to_selection);

    void                 getColor(fpreal pos, UT_FRGBA *clr,
                                  bool do_interp = true) const;
    void                 getColor(fpreal pos, float fvals[4],
                                  bool do_interp = true) const;
    void                 getColor(UT_FRGBA *values, int num,
                                  bool do_interp = true) const;

    /// Warning: If setting scalar ramps, make sure all of the fvals
    /// have the same value, as evaluators will pick a channel at whim.
    void                 setColorAt(int i, float fvals[4]);
    void                 setColorAt(int i, const UT_FRGBA &clr);
    void                 setCurrentNodeColor(fpreal32 fvals[4]);
    void                 setCurrentNodeColor(fpreal64 fvals[4]);
    void                 setCurrentNodeColor(const UT_FRGBA &clr);

    void                 setCurrentNodeBasis(UT_SPLINE_BASIS basis);
    void                 setNodeBasis(int i, UT_SPLINE_BASIS basis);

    void                 setEnable(int i, bool enable_pos, bool enable_val,
                                          bool enable_interp);
    bool                 getEnablePos(int i) const;
    bool                 getEnableVal(int i) const;
    bool                 getEnableInterp(int i) const;

    bool                 getStrictOrder() const;
    void                 setStrictOrder(bool strict);

    void                 clearSelection();
    bool                 isNodeSelected(int i) const;
    void                 selectNode(int i, bool add);
    void                 selectRange(int first_i, int last_i, bool add);
    void                 deselectNode(int i);
    void                 toggleSelectNode(int i);
    void                 getSelectionIndices(UT_IntArray &indices);
    void                 setSelectionIndices(const UT_IntArray &indices);

    /// Returns the index of the inserted node.
    int                  addNode(fpreal pos);
    /// WARNING: If building scalar ramps, set ALL the fvals to the same
    /// value.  Code will randomly evaluate .r or .a
    int                  addNode(fpreal pos, fpreal32 fvals[4],
                                 UT_SPLINE_BASIS basis = UT_SPLINE_LINEAR,
                                 bool current = true);
    int                  addNode(fpreal pos, fpreal64 fvals[4],
                                 UT_SPLINE_BASIS basis = UT_SPLINE_LINEAR,
                                 bool current = true);
    int                  addNode(fpreal pos, const UT_FRGBA &color,
                                 UT_SPLINE_BASIS basis = UT_SPLINE_LINEAR,
                                 bool current = true);

    int                  insertNode(int i, fpreal pos, fpreal32 fvals[4],
                                 UT_SPLINE_BASIS basis = UT_SPLINE_LINEAR,
                                 bool current = true);
    int                  insertNode(int i, fpreal pos, fpreal64 fvals[4],
                                 UT_SPLINE_BASIS basis = UT_SPLINE_LINEAR,
                                 bool current = true);

    void                 reorderNodes();

    void                 recordNodePositions();

    bool                 deleteNode(fpreal pos);
    bool                 deleteNodeAt(int i);
    void                 deleteSelectedNodes();

    bool                 isNodeHandle(int i) const;
    bool                 isNodeLeftHandle(int i) const;
    bool                 isNodeRightHandle(int i) const;

    void                 moveNode(int i, fpreal pos);
    void                 moveNode(const UT_ColorNode *node, fpreal pos);

    fpreal               solveSpline(fpreal pos) const;

    int                  load(const char *pathname);
    bool                 load(UT_IStream &is);
    bool                 load(UT_JSONParser &p);
    int                  save(const char *pathname) const;
    int                  save(std::ostream &os) const;

    UT_Ramp             &operator=(const UT_Ramp &from);

    // Equality does not consider the selected or current node, only the ramp
    // values themselves.
    bool                 operator==(const UT_Ramp &from) const;
    bool                 operator!=(const UT_Ramp &from) const { return !(*this == from); }
    // Hash likewise only includes ramp values.
    SYS_HashType         hash() const;
    
    void                 setRamp(const UT_ColorNode *r, int size);

    // For interpolated lookups, order > 0 finds the derivative wrt pos
    void                 rampLookup(fpreal pos, float values[4],
                                    int order = 0) const;
    void                 rampLookupNoInterp(fpreal pos, float values[4]) const;
    void                 rampLookup(fpreal u0, fpreal u1, float values[4],
                                    int ns, int order = 0) const;
    void                 rampLookupNoInterp(fpreal u0, fpreal u1, float values[4],
                                            int ns) const;

    template <typename ARCHIVER_T>
    bool                 serialize(ARCHIVER_T &archiver);

    /// Returns a ramp constructed from the canonical default strings.
    static UT_SharedPtr<UT_Ramp> buildFromDefault(const char *def);

    /// Install an OP node resolver for ramp parameters.
    /// Required for resolveOpRamp() to work. OP_Director calls this.
    static  void         setRampOpResolver(UT_RampOpResolver *resolver);

    /// Fetch the ramp from an OP node's ramp parm. May return false
    /// if the OP or parm is not found, if the parm is not a ramp, or if the
    /// UT_RampOpResolver is not assigned by setRampOpResolver().
    /// is_rgb, op_id, and op_version are optional return values for the type
    /// of ramp, the parent node's unique ID, and the parent node's version
    /// parm serial (as reported by getVersionParms()).
    bool                 resolveOpRamp(const char *op_path,
                                       const char *ramp_parm,
                                       bool *is_rgb = nullptr,
                                       int  *op_id = nullptr,
                                       int  *op_version = nullptr);
    
    /// Ramp registration to allow ramp to be converted
    /// to integers across HOM boundaries.
    
    /// Registers & returns the handle, adding the handle to the registered
    /// list
    static int       registerRamp(UT_SharedPtr<UT_Ramp> ramp, UT_IntArray &registered);
    /// Unregister all layers corresponding to the provided list,
    /// erase the list afterwards.   Assertion if handle wasn't regsitered
    static void      unregisterRamps(UT_IntArray &registered);
    /// Look up a registered layer by handle.
    static UT_SharedPtr<UT_Ramp> lookupRamp(int handle);

private:
    bool                 loadAsPoly(UT_IStream &is);
    bool                 loadAsJSON(UT_JSONParser &p);

    UT_RGBA             *sampleColors(int nsamples, bool do_interp);
    UT_BIG_RGBA         *sampleColors16(int nsamples, bool do_interp);
    void                 convertToRaster8(UT_Raster *raster,UT_RampOrient dir,
                            bool do_interp, fpreal cx, fpreal cy, fpreal phase,
                            fpreal radius);
    void                 convertToRaster16(UT_Raster *raster,UT_RampOrient dir,
                            bool do_interp, fpreal cx, fpreal cy, fpreal phase,
                            fpreal radius);

    void                 getColorAndMultiply(fpreal pos, bool do_interp,
                                             UT_RGBA *pixel);
    void                 getColorAndMultiply(fpreal pos, bool do_interp,
                                             UT_BIG_RGBA *pixel);

    void                 interpColor(fpreal pos, float vals[4],
                                     int order = 0) const;

    void                 updateSplineIfNeeded() const;
    void                 evaluateSpline(fpreal pos, fpreal t0, fpreal t1,
                                        int i, float *val, int order = 0) const;

private:
    template <typename T>
    int                          addNodeImpl(
                                        fpreal pos,
                                        T fvals[4],
                                        UT_SPLINE_BASIS basis,
                                        bool current);
    template <typename T>
    int                          insertNodeImpl(
                                        int i,
                                        fpreal pos,
                                        T fvals[4],
                                        UT_SPLINE_BASIS basis,
                                        bool current);

    typedef tbb::spin_mutex      SplineLock;

    UT_Array<UT_ColorNode>       myNodes;
    UT_ColorNode                *myCurrentNode;

    UT_Map<int, UT_ColorNode *>  mySelectedNodes;

    UT_ColorType                 myColorType;

    mutable UT_Spline            mySpline;
    mutable bool                 mySplineUpToDate;
    mutable SplineLock           mySplineLock;

    bool                         myGlobalEnable;
    bool                         myStrictOrder;
};

/// Class to create a UT_Ramp from an OP node path and parameter string.
class UT_API UT_RampOpResolver
{
public:
             UT_RampOpResolver();
    virtual ~UT_RampOpResolver();

    UT_RampOpResolver(const UT_RampOpResolver &) = delete;
    UT_RampOpResolver &operator=(const UT_RampOpResolver &) = delete;

    /// Fetch a UT_Ramp from an OP node's ramp parm. May return false
    /// if the OP or parm is not found, or if the parm is not a ramp.
    /// is_rgb, op_id, and op_version are optional return values for the type
    /// of ramp, the parent node's unique ID, and the parent node's version
    /// parm serial (as reported by getVersionParms()
    virtual bool resolveRampParm(UT_Ramp &target_ramp,
                                 const char *op_path,
                                 const char *ramp_parm,
                                 bool *is_rgb = nullptr,
                                 int  *op_id = nullptr,
                                 int  *op_version = nullptr);
};

#endif