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

#ifndef __UN_NodeData_h__
#define __UN_NodeData_h__

#include "UN_API.h"
#include "UN_Data.h"
#include "UN_Utils.h"
#include <UT/UT_Color.h>
class UN_GraphData;
class UN_NodeData;

// ============================================================================
using UN_CustomNodeData     = UN_CustomDataT< UN_NodeID, UN_NodeIndex >;
using UN_CustomNodeDataPtr  = UT_UniquePtr< UN_CustomNodeData >;

/// Convenience typedef for a generic data buffer reference on node data.
using UN_GenericNodeDataBufferRef =
    UN_GenericDataBufferRef<UN_NodeData, UN_NodeID>;

// ============================================================================
/// Container of data for all the nodes in the graph.
/// 
/// NOTE: This class is generally not trivially relocatable, because 
/// its base class (UN_Data) is not trivially relocatable (see comment there).

class UN_API UN_NodeData : public UN_Data
{
public:
    /// Constructors and destructors.
     UN_NodeData( UN_CustomNodeDataPtr custom_data = UN_CustomNodeDataPtr() );
    ~UN_NodeData() = default;

                                UN_NodeData(UN_NodeData &&);
    UN_NodeData &               operator=(UN_NodeData &&);

protected:
    /// This container can have large data, so generally, forbid 
    /// the costly copy operations to the public.
    /// Knowledgable friends and derived classes can still use them.
    friend UN_GraphData;
                                UN_NodeData(const UN_NodeData &) = default;
    UN_NodeData &               operator=(const UN_NodeData &)  = default;

public:
    /// Increases the capacity of the data buffer arrays to the given minimum,
    /// unless the capacity is already greater or equal to that minimum,
    /// in which case the capacity remains unchanged.
    void                        setCapacityIfNeeded(UN_DataSize min_capacity);

    /// @{ Returns node's custom data container, if one was provided.
    UN_CustomNodeData *         customNodeData()
    { 
        return UTverify_cast<UN_CustomNodeData*>( customData() );
    }

    const UN_CustomNodeData *   customNodeData() const
    { 
        return UTverify_cast<const UN_CustomNodeData*>( customData() ); 
    }
    /// @}
    
    /// Merges another node data container into this one.
    /// Returns a mapping between the data IDs in the merge source 
    /// and destination (this) data buffers.
    UN_NodeIDRemap              merge( const UN_NodeData &src_node_data );

    /// Sets the attributes of the node, based on the information given in 
    /// the options dictionary. Leaves other attributes of this node intact.
    void                        merge( UN_NodeID node_id, 
                                       const UN_Options &node_opts );

    /// Returns the options object representing node's properties,
    /// such as name, type, category, and also parameters and ports, but
    /// not the children.
    /// This can be then used for serialization to JSON, etc.
    UN_OptionsPtr               asOptions( UN_NodeID node_id ) const;


    /// Adds a slot for a new node in this container.
    /// Returns an ID that should be used to refer to this new node
    /// for accessing its data (eg, name, label, etc).
    UN_NodeID                   addNode();

    /// Adds a root node to the container, or returns one if it already exists.
    UN_NodeID                   findOrAddRootNode();

protected:
    // These methods require careful coodrination with other nodes,
    // or with a root node. Only UN_GraphData knows how to do that correctly.
    friend UN_GraphData;

    /// Clears the data for the given node to the default state.
    void                        clearNode( UN_NodeID node_id );

    /// Removes the node from this container and frees the
    /// data slot it occupied. After calling this method, 
    /// the container will have no knowledge of the node by this ID.
    /// Returns true on successs; false if the node was not found.
    bool                        removeNode( UN_NodeID node_id );

    /// Frees the data slots occupied by all the nodes.
    /// @param 'reset_next_id' If true, the node ID generator is reset to zero.
    void                        removeAllNodes( bool reset_next_id );

public:
    /// Returns true if the given ID refers to a valid node entry 
    /// in the data buffers. Ie, such a node exists and is valid.
    bool                        isValid( UN_NodeID node_id ) const
                                    { return UN_Data::isValid( node_id ); }


    /// Iterator for traversing valid node IDs.
    class IDIterator : public UN_DataIndexMap::IDIterator
    {
    public:
        using value_type = UN_NodeID;

        IDIterator( const UN_DataIndexMap::IDIterator &id_iterator )
            : UN_DataIndexMap::IDIterator( id_iterator )
        {}

        value_type operator*() const
        { return UN_NodeID( UN_DataIndexMap::IDIterator::operator*() ); }
    };

    /// Iterator for traversing valid node IDs in an ascending order.
    class OrderedIDIterator : public UN_DataIndexMap::OrderedIDIterator
    {
    public:
        using value_type = UN_NodeID;

        OrderedIDIterator(const UN_DataIndexMap::OrderedIDIterator &id_iterator)
            : UN_DataIndexMap::OrderedIDIterator( id_iterator )
        {}

        value_type operator*() const
        { return UN_NodeID( UN_DataIndexMap::OrderedIDIterator::operator*() ); }
    };


    /// Returns a range for iterating valid node IDs. 
    /// Does not include the root node.
    using IDRange = UT_IteratorRange< IDIterator >;
    IDRange idRange() const;

    /// Returns a range for iterating valid node IDs. 
    /// Does not include the root node.
    using OrderedIDRange = UT_IteratorRange< OrderedIDIterator >;
    OrderedIDRange orderedIDRange() const;

    /// Returns a list of all the valid node IDs in the graph.
    /// Does not include the root node.
    UN_NodeIDList nodeIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_NodeID) == sizeof(UN_DataID) );
        auto node_ids = 
            reinterpret_cast<UN_NodeIDList&&>( std::move( dataIDs() ));
        node_ids.findAndRemove( UN_ROOT_NODE_ID );
        return node_ids;
    }

    /// Returns a list of all the valid node IDs in the graph.
    /// Does not include the root node.
    UN_NodeIDList sortedNodeIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_NodeID) == sizeof(UN_DataID) );
        auto node_ids = 
            reinterpret_cast<UN_NodeIDList&&>( std::move( sortedDataIDs() ));
        node_ids.findAndRemove( UN_ROOT_NODE_ID );
        return node_ids;
    }

protected:
    /// Sets the node name that differentiates it among its siblings. 
    /// Only the friend UN_GraphData can call it because it may need to
    /// enforce a unique node name.
    void setName( UN_NodeID node_id, const UT_StringRef &name )
    {
        UT_ASSERT( !myCheckValidNodeNames 
                || UN_Utils::isValidNodeName( name, myNodeNameSafeChars ));
        setData( myName, node_id, name );
    }

    /// Sets the node's category that groups it with other nodes
    /// that are operationally compatible (and connectable).
    /// Only the friend UN_GraphData can call it because it makes little
    /// sense to change the category of a node without also changing the
    /// node type, the parent child type categories, and other aspects
    /// of the graph.
    void setCategoryName( UN_NodeID node_id, const UT_StringRef &category_name )
    {
        UT_ASSERT( UN_Utils::isValidCategoryName( category_name ));
        setData( myCategoryName, node_id, category_name );
    }

    /// Sets the node's signature. 
    /// Node signature determines node inputs and outputs, and their types.
    void setSignatureName(UN_NodeID node_id, const UT_StringRef &signature_name)
    {
        setData( mySignatureName, node_id, signature_name );
    }


public:
    /// Returns the name that identifies the node among its siblings.
    const UT_StringHolder & name( UN_NodeID node_id ) const
    {
        return getDataRef( myName, node_id, UT_StringHolder::theEmptyString );
    }


    /// Sets the node's type that determines its functional behavour.
    void setTypeName( UN_NodeID node_id, const UT_StringRef &type_name )
    {
        setData( myTypeName, node_id, type_name );
    }

    /// Returns the name of node's type that determines its functional behavour.
    const UT_StringHolder & typeName( UN_NodeID node_id ) const
    {
        return getDataRef(myTypeName, node_id, UT_StringHolder::theEmptyString);
    }
    
    /// Returns the node's category that groups it with other nodes
    /// that are operationally compatible (and connectable).
    const UT_StringHolder & categoryName( UN_NodeID node_id ) const
    {
        return getDataRef( myCategoryName, node_id, 
                UT_StringHolder::theEmptyString );
    }
    
    /// Returns the node's signature.
    const UT_StringHolder & signatureName( UN_NodeID node_id ) const
    {
        return getDataRef( mySignatureName, node_id, theDefSignatureName );
    }

    /// Sets the node's comment.
    void setComment( UN_NodeID node_id, const UT_StringRef &comment )
    {
        setData( myComment, node_id, comment );
    }

    /// Returns the node's comment.
    const UT_StringHolder & comment( UN_NodeID node_id ) const
    {
        return getDataRef( myComment, node_id, theDefComment );
    }

    /// Sets the node's location in the graph editor.
    void setPosition( UN_NodeID node_id, const UT_Vector2D &position )
    {
        setData( myPosition, node_id, position );
    }

    /// Returns the node's location in the graph editor.
    const UT_Vector2D & position( UN_NodeID node_id ) const
    {
        return getDataRef( myPosition, node_id, theDefPos );
    }

    /// Sets the node's color in the graph editor.
    void setColor( UN_NodeID node_id, const UT_Color &color )
    {
        setData( myColor, node_id, color );
    }

    /// Returns the node's color in the graph editor.
    const UT_Color & color( UN_NodeID node_id ) const
    {
        return getDataRef( myColor, node_id, theDefColor );
    }

    // TODO: FIXME:  consider refactoring buffers into UN-friendly objects
    //          for reuse. Eg UN_StringArrayBuffer, wchich would have
    //          set(), get(), steal(), and update(). Then UN_NodeData class
    //          would just return that buffer object.
    //          The calls would loo like node_data.tags().set(id, val);
    //
    //          Another variation would be to return a data entry handle
    //          that has set(), get(), steal(), and update() methods.
    //          node_data.tags(id).set(val).
    
    /// Updates the node tags in-place.
    /// Usage: updateTags(id, [&t](auto &tags) { tags.append(t); });
    template <typename OP>
    void updateTags( UN_NodeID node_id, const OP &op )
    {
        updateData( myTags, node_id, op );
    }

    /// Sets new tags on a node via copy-assignment.
    void setTags( UN_NodeID node_id, const UT_StringArray &tags )
    {
        setData( myTags, node_id, tags );
    }

    /// Sets new tags on a node via move-assignment.
    void setTags( UN_NodeID node_id, UT_StringArray &&tags )
    {
        setData( myTags, node_id, std::move(tags) );
    }

    /// Returns node tags.
    const UT_StringArray & tags( UN_NodeID node_id ) const
    {
        return getDataRef( myTags, node_id, theDefTags );
    }

    /// Returns node tags moved from the data buffer entry.
    UT_StringArray stealTags( UN_NodeID node_id )
    {
        return stealData( myTags, node_id, theDefTags );
    } 

    /// Updates node tags in-place.
    /// Usage: updateMetadata(id, [&k, &v](auto &m) { m[k] = v); });
    template <typename OP>
    void updateMetadata( UN_NodeID node_id, const OP &op )
    { 
        updateData( myMetadata, node_id, op ); 
    }

    /// Simpler method to update a single metadata value in-place.
    void updateMetadata( UN_NodeID node_id,
        const UT_StringHolder &key,
        UT_OptionEntryPtr &&value )
    {
        updateData(myMetadata, node_id, [&key, &value](UT_OptionsHolder &m)
            {
                m.update( [&key, &value](UT_Options &options)
                {
                    options.setOption(key, std::move(value));
                });
            });
    }

    /// Sets node's new metadata via copy-assignment.
    void setMetadata( UN_NodeID node_id, const UN_MetadataHolder &metadata )
    {
        setData( myMetadata, node_id, metadata );
    }

    /// Sets node's new metadata via move-assignment.
    void setMetadata( UN_NodeID node_id, UN_MetadataHolder &&metadata )
    {
        setData( myMetadata, node_id, std::move(metadata) );
    }

    /// Returns nodes's metadata.
    const UN_MetadataHolder & metadata( UN_NodeID node_id ) const
    {
        return getDataRef( myMetadata, node_id, theDefMetadata );
    }

    /// Returns node's metadata moved from the data buffer entry.
    UN_MetadataHolder stealMetadata( UN_NodeID node_id )
    {
        return stealData( myMetadata, node_id, theDefMetadata );
    }


    /// Adds a new named generic data buffer and returns a lightweight
    /// reference that bundles the buffer ID with this container.
    template<typename D>
    UN_GenericNodeDataBufferRef
    addGenericNodeDataBuffer( const UT_StringRef &name,
                              UN_GenericBufferType type,
                              const D &default_value )
    {
        return { *this, addGenericBuffer(name, type, default_value) };
    }

    /// Sets the data value in a generic buffer for a given node.
    template<typename T>
    void setGenericData( UN_GenericBufferID buf_id, UN_NodeID node_id,
                         const T &value )
    { UN_Data::setGenericData( buf_id, node_id, value ); }

    /// Sets the data value in a generic buffer via move.
    template<typename T>
    void setGenericData( UN_GenericBufferID buf_id, UN_NodeID node_id,
                         T &&value )
    { UN_Data::setGenericData( buf_id, node_id, std::forward<T>(value) ); }

    /// Returns a const ref to the data value in a generic buffer.
    template<typename T>
    const T & genericDataRef( UN_GenericBufferID buf_id,
                           UN_NodeID node_id ) const
    { return UN_Data::genericDataRef<T>( buf_id, node_id ); }

    /// Returns a copy of a data value from a generic buffer.
    template<typename T>
    T genericDataVal( UN_GenericBufferID buf_id, UN_NodeID node_id ) const
    { return UN_Data::genericDataVal<T>( buf_id, node_id ); }


    /// Moves the data value out of a generic buffer.
    template<typename T>
    T stealGenericData( UN_GenericBufferID buf_id, UN_NodeID node_id )
    { return UN_Data::stealGenericData<T>( buf_id, node_id ); }

    /// Updates the data value in a generic buffer in-place via a callable.
    template<typename T, typename OP>
    void updateGenericData( UN_GenericBufferID buf_id, UN_NodeID node_id,
                            const OP &op )
    { UN_Data::updateGenericData<T>( buf_id, node_id, op ); }


    /// Asserts that the node names are alphanumeric.
    void            setCheckValidNodeNames( bool flag )
                        { myCheckValidNodeNames = flag; }

    /// A set of additional characters that are legal in node names.
    void            setNodeNameSafeChars( const UT_StringRef &safe_chars )
                        { myNodeNameSafeChars = safe_chars; }

protected:
    /// Returns the node's data index into the data buffer arrays.
    UN_NodeIndex nodeIndex( UN_NodeID id ) const
    {
        return UN_NodeIndex( UN_Data::dataIndex( id ));
    }

private:
    /// Returns the current size of the internals data buffers.
    /// The number of valid entries (slots) in data buffers is less than 
    /// or equal to that number, since some data slots may be free.
    UN_DataSize coreDataBufferSize() const
    { 
        UN_DataSize size( myName.size() );
        UT_ASSERT( isCoreDataSizeConsistent( size ));
        return size;
    }

    /// Helper that adds a new data slot for the given node.
    UN_NodeID   addNodeData( UN_NodeID node_id, UN_NodeIndex node_index );


    /// Handles merging of another node data container into this one.
    void        mergeCoreData( const UN_NodeData &src, 
                               const UN_DataMergeInfo &merge_info );

    /// Adds a new data slot to accommodate a new data piece at the given index.
    void        addCoreData( UN_NodeIndex node_index );

    /// Clears the data for the given node to the default state.
    void        clearCoreData( UN_NodeIndex node_index );

    /// Frees the data slot occupied by the given node,
    /// clearing it if necessary.
    void        removeCoreData() //, index)
                    // Nothing urgent to free; will clear lazily
                    { UT_ASSERT( isDataSizeConsistent() ); }

    /// Frees all the data slots.
    void        removeAllCoreData();

    /// Sets the capacity of core data buffers if needed.
    void        setCoreDataCapacityIfNeeded( UN_DataSize min_capacity );

    /// @{ Returns true if the sizes of all core data buffers are equal.
    bool        isCoreDataSizeConsistent( UN_DataSize expected_size ) const;
    bool        isCoreDataSizeConsistent() const
                    { return isCoreDataSizeConsistent( myName.size() ); }
    /// @}

    /// Returns true if the sizes of data buffers and index map are equal.
    bool        isDataSizeConsistent() const;

public:
    // The default values for the UN node data.
    // TODO: FIXME: the (1,1,1) is what APEX_Node had as a default color.
    //      Revisit it and decide what the default color for generic
    //      UN nodes should be.
    static inline const UT_StringHolder    theDefSignatureName;
    static inline const UT_StringHolder    theDefComment;
    static inline const UT_StringArray     theDefTags;
    static inline const UN_MetadataHolder  theDefMetadata;
    static inline const auto theDefColor = UT_Color( UT_RGB, 1.0F, 1.0F, 1.0F );
    static inline const auto theDefPos   = UT_Vector2D(0.0);

private: 
    /// The name of the node.
    UN_StringDataBuffer         myName;

    /// An identifier that determines node's functional behaviour.
    UN_StringDataBuffer         myTypeName;

    /// The name of the unique group this node belongs to. 
    /// Nodes in the same category can be connected to each other, have 
    /// the same input/output types, and be processed in a similar way.
    /// Ie, a category is similar to a language (eg, VEX, MaterialX) that 
    /// imposes data types, connectivity rules, auto-conversion, etc.
    UN_StringDataBuffer         myCategoryName;

    /// Node's signature.
    UN_StringDataBuffer         mySignatureName;

    /// Node's comment.
    UN_StringDataBuffer         myComment;

    /// Node's position.
    UN_Vector2DDataBuffer       myPosition;

    /// Node's color (an RGB float triplet).
    UN_ColorDataBuffer          myColor;

    /// Node's tags.
    UN_StringArrayDataBuffer    myTags;

    /// Node's metadata.
    UN_MetaDataBuffer           myMetadata;

    /// Extra characters that are legal in the node names,
    /// in addition to the standard C-var style alphanumerics.
    UT_StringHolder             myNodeNameSafeChars;

    /// Check an assertion that the node names are alphanumeric.
    bool                        myCheckValidNodeNames = false;
};


#endif