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

#ifndef __UN_GraphData_h__
#define __UN_GraphData_h__

#include "UN_API.h"
#include "UN_GraphContext.h"
#include "UN_GraphTopology.h"
#include "UN_Include.h"
#include "UN_NodeData.h"
#include "UN_ParmData.h"
#include "UN_PortData.h"
#include "UN_StickyNoteData.h"
#include "UN_SubnetData.h"
#include "UN_WireData.h"

class UN_NodeType;

// ============================================================================
/// A container and a manager for utility nodes, their parameters and ports,
/// and wire connections between them.
///
/// This graph object owns the node data containers, and these containers
/// own the data buffers. It manages node creation and deletion, and
/// maintains the parental relationship between them. This class also
/// establishes and maintains connections between the nodes, 
/// i.e., creates and manages wires via the topology class.
///
/// Having such a central manager has several advantages:
/// - Better memory management by avoiding numerous small heap allocs.
///   It can maintain memory blocks of nodes and wires, and reuse slots
///   freed by deleted items, thus avoiding numerous heap memory allocations 
///   during repeated cycles of node creation/deletion of nodes and wires
///   connection/disconnection.
/// - Enforces structural integrity of the nodes and connections:
///   - No free-floating nodes that belong to nobody.
///   - Ensuring wires connect siblings only (no wires to outside of a subnet).
/// - Easier management and ownership of wires.
/// - Enforces const-correctess: you can edit the graph only if you have
///   non-const reference to it; a const graph reference is not editable.
/// - Thread safety: allows parallel processing of the node chains only 
///   if they belong to different graphs; without graphs, it's hard to know 
///   that two nodes are independent and can be processed in parallel.
/// - the struct-of-arrays approach (ie data-oriented-design) is cache friendly
///    and optimizes performance when iterating over elements.
///
/// Some disadvantages:
///  - Overhead that stems from handles holding an ID rather than a direct 
///    pointer, so access is somewhat slower. 
///  - Adding a single element (eg, a node) potentially requires several
///    allocations of smaller data chunks (data buffer), rather than
///    a single allocation of a larger chunk that array-of-structs would
///    require. Multiple allocs are slower than a single one.
///
/// NOTE: This class is generally not trivially relocatable,
///     because its members (eg, myNodeData) are not trivially relocatable 
///     (see comment there).

using UN_WireDrawStyle = UNI_WireStyle;

class UN_API UN_GraphData 
{
public: 
    /// Constructor. 
    //
    // TODO: FIXME: 
    //      Once UN is very stable and solid, update unit test examples, 
    //      export headers to HDK, and write HDK examples
    //
    /// @param  context The context that knows about allowed categories,
    ///                 node types, port types, and parm types in this graph.
    ///                 Note, UN_GraphData makes a copy of the passed argument,
    ///                 so that it's not dependent on the lifespan of this arg.
    UN_GraphData( UN_GraphContext context = UN_GraphContext() );

    /// Graph data can be very large, so allow the public to use
    /// only cheap move operations.
                        UN_GraphData( UN_GraphData &&other );
    UN_GraphData &      operator=( UN_GraphData &&other );

    /// Returns the graph context used by this graph.
    const UN_GraphContext &context() const 
                            { return myContext; }

protected:
    /// Graph data can be very large, so forbid the public to use
    /// the costly copy operations.
    /// Knowledgeable friends and derived classes can still use them.
                        UN_GraphData( const UN_GraphData &other )   = default;
    UN_GraphData &      operator=( const UN_GraphData &other )      = default;

    /// Constructor intended for sub-class graphs that provide custom data.
    // NB: This does not need to be protected, but for now let's limit exposure.
    //     Currently only used by APEX_GraphData.
    UN_GraphData( UN_GraphContext context,
                  UN_CustomNodeDataPtr custom_node_data,
                  UN_CustomParmDataPtr custom_parm_data,
                  UN_CustomPortDataPtr custom_port_data,
                  UN_CustomWireDataPtr custom_wire_data,
                  UN_CustomSubnetDataPtr custom_subnet_data,
                  UN_CustomStickyNoteDataPtr custom_stickynote_data );

public:
    /// Clears the graph, bringing it to an empty state.
    /// @param reset_ids If true, the next data IDs for nodes, ports, etc
    ///         will reset to the initial state. This may be useful 
    ///         if a graph loads and clears nodes repeatedly, but has the
    ///         danger of anyone holding the previous IDs thinking that
    ///         that data is still valid. So use this option with great caution!
    void                clearData( bool reset_ids = false );

    /// @{ Merges another graph (represented as options) into this one.
    /// @param root_dst_node An existing node in the destination graph 
    ///      to which the source root should map to. 
    ///      Ie, into which node to merge the other (source) graph.
    //
    // TODO: FIXME: pass in policy and other options as a parameter to 
    //      indicate what to do with conflicts:
    //      - ignore other values (this takes precedence)
    //      - layer over (other takes precedence) 
    void                merge( const UN_Options &graph_opts );
    UN_GraphMergeInfo   merge( const UN_GraphData &src_graph_data,
                               UN_NodeID root_dst_node = UN_ROOT_NODE_ID );
    /// @}

    /// Returns options that represent this graph.
    UN_OptionsPtr       asOptions() const;


    /// Returns an ID of the graph's root node.
    /// Root is a special node that holds graph's top-level nodes.
    /// It cannot be deleted or renamed.
    ///
    /// NOTE: Within the graph, nodes are arranged in a parental hierarchy,
    ///     where any node can be a parent of other nodes, as long as 
    ///     it has UN_SubnetData attached to it. We call such a node a subnet.
    ///     The top-level nodes in a graph don't really have an explicitly 
    ///     created parent, however it's convenient to reuse UN_NodeData to 
    ///     hold them. We call such implicitly created node a root. 
    ///     It holds top-level nodes.  All nodes except the root must have 
    ///     a valid parent.
    UN_NodeID           rootNode() const
                            { return UN_ROOT_NODE_ID; }

    /// Returns true if the given name can be used for naming a node.
    bool                    isValidNodeName( const UT_StringRef &name ) const;

    /// Returns a validated name for a graph item (eg, node, sticky note, etc).
    /// @param force_valid_name If true, the returned name will have valid
    ///                 characters (C-style variable, ie, alphanum and '_').
    /// @param force_unique_name If true, the teturned name will be unique
    ///                 among the sibling inside the given @parent_node subnet.
    /// @parent_node The node inside which to check for the unique node name.
    ///                 Used only if @p force_unique_name is true,
    ///                 otherwise it can be an invalid ID.
    /// @default_name The default name to use if forcing a valid name,
    ///                 and the child name is an empty string.
    UT_StringHolder     findValidChildItemName( 
                                const UT_StringRef &child_name,
                                bool force_valid_name, 
                                bool force_unique_name, 
                                UN_NodeID parent_node,
                                const UT_StringRef &default_name = 
                                                    UT_StringRef()) const;

    /// Creates a new node by the given name with the given parent.
    UN_NodeID           createNode( 
                                UN_NodeID parent_node, 
                                const UT_StringRef &name = UT_StringRef(), 
                                const UT_StringRef &type = UT_StringRef(),
                                const UT_StringRef &category = UT_StringRef(),
                                const UT_StringRef &signature = UT_StringRef());


    /// Returns the node type object for the given node, or null if unavailable.
    const UN_NodeType * nodeType( UN_NodeID node_id ) const;

    /// Sets the name of the given node.
    void                setNodeName( UN_NodeID node_id, 
                                const UT_StringRef &name );

    /// Sets the signature for the given node.
    void                setNodeSignature( UN_NodeID node_id, 
                                const UT_StringRef &signature_name );

    /// Returns the list of the signature names provided for the given node.
    const UT_StringArray &nodeSignatureNames( UN_NodeID node_id ) const;

    /// Deletes the node given its index.
    void                deleteNode( UN_NodeID node );

    /// Clears node to a pristine state (no parameters or ports),
    /// equivalent to node being just created.
    void                clearNode( UN_NodeID node );

    /// Sets the aspects of the node based on the information given in the
    /// options dictionary. Leaves other aspects (not present in opt) intact.
    void                mergeNode( 
                                UN_NodeID node,
                                const UN_Options &node_opts );

    /// Returns the representation of a node as options given its data index.
    UN_OptionsPtr       nodeAsOptions( UN_NodeID node ) const;

    /// @{ Returns a parent node ID of the given child node.
    /// Note, for top-level nodes, this will return a graph's root node.
    UN_NodeID           parent( UN_NodeID child ) const
                            { return myTopology.nodeParent( child ); }
    UN_NodeID           parent( UN_StickyNoteID child ) const
                            { return myTopology.stickyNoteParent( child ); }
    /// @}


    /// Returns a non-root parent node ID of the given child node.
    /// Note, for top-level nodes, this will return an invalid node ID, 
    /// because their parent is the implicitly created graph's root node.
    UN_NodeID           nonRootParent( UN_NodeID child ) const
                            { return myTopology.nonRootNodeParent( child ); }

    /// Returns true if the given node is a subnet (ie, can have children).
    bool                isSubnet( UN_NodeID node ) const
                            { return myTopology.nodeSubnet(node).isValid(); }

    /// Returns an ID iterator range for all the valid subnets in the graph.
    UN_SubnetData::IDRange allSubnets() const
                            { return mySubnetData.idRange();  }


    // TODO: FIXME: rename to reparent
    /// Moves a node from one parent to another.
    void                moveNode( UN_NodeID node, UN_NodeID new_parent )
                            { myTopology.moveNode( node, new_parent ); }

    /// Moves all children of the given parent node to another one.
    void                moveAllChildNodes( UN_NodeID old_parent, 
                                UN_NodeID new_parent )
                            { 
                                myTopology.moveAllChildNodes( 
                                        old_parent, new_parent ); 
                            }


    /// Returns the number of all nodes in the graph.
    UN_DataSize         nodeCount() const
                            { 
                                return UN_DataSize( // account for the root
                                    myNodeData.size().exintValue() - 1 ); 
                            }

    /// Returns a node ID iterator range for all the valid nodes in the graph.
    UN_NodeData::IDRange  allNodes() const
                            { return myNodeData.idRange();  }

    /// @{ Returns a list of direct children of the given node (subnet).
    const UN_NodeIDList & childNodes( UN_NodeID parent ) const
                            { return myTopology.nodeChildNodes( parent ); }
    const UN_NodeIDList & childNodes( UN_SubnetID parent ) const
                            { return myTopology.subnetChildNodes( parent ); }
    /// @}


    /// Returns the number of all wires in the graph.
    UN_DataSize           wireCount() const
                            { return myWireData.size(); }

    /// Returns a wire ID iterator range for all the valid wires in the graph.
    UN_WireData::IDRange  allWires() const
                            { return myWireData.idRange();  }

    /// @{ Returns a list of wires directly inside the given node (subnet).
    const UN_WireIDList & childWires( UN_NodeID parent ) const
                            { return myTopology.nodeChildWires( parent ); }
    const UN_WireIDList & childWires( UN_SubnetID parent ) const
                            { return myTopology.subnetChildWires( parent ); }
    /// @}

    /// @{ Returns a node ID of a child in a given subnet given its name.
    UN_NodeID           findChildNode( 
                                UN_NodeID parent,
                                const UT_StringRef &child_name ) const;
    UN_StickyNoteID     findChildStickyNote( 
                                UN_NodeID parent,
                                const UT_StringRef &child_name ) const;
    /// @}

    /// @{ Returns an ID of a node at a given path,
    ///  or an invalid ID if not found.
    ///
    /// @parm current_node - When the given node path is relative, 
    ///     this is the anchor node from which the relative path is followed 
    ///     to find the desired node. 
    /// 
    /// @parm node_path - The node path identifying the node to find.
    ///     This can be either an absolute path (starting with a slash, '/')
    ///     or a relative path. 
    ///     In particular, when the node path is just a name, this function 
    ///     will look for a child by that name directly inside the given parent.
    ///     The path can contain '.' for the current node, and '..' for 
    ///     the parent node.
    UN_NodeID           findNode( 
                                UN_NodeID current_node,
                                const UT_StringRef &node_path ) const;
    UN_StickyNoteID     findStickyNote( 
                                UN_NodeID current_node,
                                const UT_StringRef &sticky_note_path ) const;
    /// @}

    /// Creates a parameter data object, and returns its index.
    UN_ParmID           createParm( 
                                UN_NodeID node,
                                const UT_StringRef &name = UT_StringRef(), 
                                const UT_StringRef &type_name = UT_StringRef());

    /// Deletes the parameter.
    void                deleteParm( UN_ParmID parm );

    /// Returns the parameters of the given node.
    const UN_ParmIDList &parms( UN_NodeID node ) const
                            { return myTopology.nodeParms( node ); }

    /// Returns the parameter of a given name on a given node.
    UN_ParmID           parm( UN_NodeID node,
                                const UT_StringRef &parm_name ) const;

    /// Returns the owner node of the given parameter.
    UN_NodeID           node( UN_ParmID parm ) const
                            { return myTopology.parmNode( parm ); }



    /// Creates a port, and returns its index.
    /// @param node The owner (parent) node on which the port appears.
    /// @param kind The port kind (ie, input or output).
    /// @param name The port name.
    /// @param type_name The name of the port type.
    /// @param label The port label that shows up in the graph editor.
    /// @param index The index at which to insert the port on a node.
    //      This will determine the order of ports that show up in the graph
    //      editor. Note, negative index values are allowed, and denote
    //      the port position counting backwards from the end.
    //      Eg, -1 will insert the new port at the current last port's
    //      position, making it the second last port, since the current 
    //      last port will be pushed up by that insertion.  To make 
    //      the newly created port last, don't pass any index (to append it).
    UN_PortID           createPort( 
                                UN_NodeID node,
                                UN_PortKind kind, 
                                const UT_StringRef &name = UT_StringRef(), 
                                const UT_StringRef &type_name = UT_StringRef(),
                                const UT_StringRef &label = UT_StringRef(),
                                const UT_Optional<exint> &index = std::nullopt);

    /// Sets the name of the given port.
    void                setPortName( UN_PortID port_id, 
                                const UT_StringRef &name );

    /// Deletes the port.
    void                deletePort( UN_PortID port );

    /// Returns the number of all ports in the graph.
    UN_DataSize         portCount() const
                            { return myPortData.size(); }

    /// Returns a port ID iterator range for all the valid ports in the graph.
    UN_PortData::IDRange allPorts() const
                            { return myPortData.idRange();  }

    /// Returns the port of a given kind on a given node.
    UN_PortID           port( UN_NodeID node, UN_PortKind kind,
                                const UT_StringRef &port_name ) const;

    /// Returns the ports of the given kind for the given node.
    const UN_PortIDList & ports( UN_NodeID node, UN_PortKind kind ) const
                            { 
                                return kind == UN_PortKind::Input 
                                        ? inputPorts( node ) 
                                        : outputPorts( node ); 
                            }

    /// Returns input ports of the given node.
    const UN_PortIDList & inputPorts( UN_NodeID node ) const
                            { return myTopology.nodeInputPorts( node ); }

    /// Returns output ports of the given node.
    const UN_PortIDList & outputPorts( UN_NodeID node ) const
                            { return myTopology.nodeOutputPorts( node ); }

    /// Returns the owner node of the given port.
    UN_NodeID           node( UN_PortID port ) const
                            { return myTopology.portNode( port ); }


    /// Creates a new connection wire between the two ports.
    /// Returns the wire data index of the created connection.
    UN_WireID           connectPorts( 
                                UN_PortID src_port,
                                UN_PortID dst_port )
                            { return createWire( src_port, dst_port ); }

    /// Removes the wire connection between the two ports.
    void                disconnectPorts( 
                                UN_PortID src_port,
                                UN_PortID dst_port );

    /// Returns source wires connected to the given port.
    /// Ie, connection wires from which this port takes (receives) data.
    const UN_WireIDList & srcWires( UN_PortID port ) const
                            { return myTopology.portSrcWires( port ); }

    /// Returns destination wires connected to the given port.
    /// Ie, connection wires to which this port provides (sends) data.
    const UN_WireIDList & dstWires( UN_PortID port ) const
                            { return myTopology.portDstWires( port ); }


    /// Creates a connection wire between the two given ports.
    UN_WireID           createWire( 
                                UN_PortID src_port, 
                                UN_PortID dst_port );

    /// Returns the wire that connects the two ports, or an invalid wire ID
    /// if the ports are not connected.
    UN_WireID           findWire(
                                UN_PortID src_port,
                                UN_PortID dst_port ) const;

    /// Deletes the wire, effectively disconnecting the ports it connects.
    void                deleteWire( UN_WireID wire );

    /// Returns the source port of the given wire.
    /// Ie, the port that provides (sends) the data.
    UN_PortID           srcPort( UN_WireID wire ) const
                            { return myTopology.wireSrcPort( wire ); }

    /// Returns the destination port of the given wire.
    /// Ie, the port that consumes (receives) the data.
    UN_PortID           dstPort( UN_WireID wire ) const
                            { return myTopology.wireDstPort( wire ); }


    /// Creates and adds a new sticky note to the graph
    UN_StickyNoteID     createStickyNote( UN_NodeID parent_node, 
                                const UT_StringRef &name = UT_StringRef(), 
                                const UT_StringRef &text = UT_StringRef() );

    /// Deletes the node given its index.
    void                deleteStickyNote( UN_StickyNoteID sticky_note );

    /// Sets the name of the given sticky note.
    void                setStickyNoteName( UN_StickyNoteID sticky_note, 
                                const UT_StringRef &name );

    /// @{ Returns a list of direct children of the given node (subnet).
    const UN_StickyNoteIDList & childStickyNotes( UN_NodeID parent ) const
                        { return myTopology.nodeChildStickyNotes( parent ); }
    const UN_StickyNoteIDList & childStickyNotes( UN_SubnetID parent ) const
                        { return myTopology.subnetChildStickyNotes( parent ); }
    /// @}


    /// @{ Returns true if the given ID refers to a valid entry 
    /// in the data buffers. Ie, such an item exists and is valid.
    bool                isValid( UN_NodeID node ) const
                            { return myNodeData.isValid( node ); }
    bool                isValid( UN_SubnetID subnet ) const
                            { return mySubnetData.isValid( subnet ); }
    bool                isValid( UN_ParmID parm ) const
                            { return myParmData.isValid( parm ); }
    bool                isValid( UN_PortID port ) const
                            { return myPortData.isValid( port ); }
    bool                isValid( UN_WireID wire ) const
                            { return myWireData.isValid( wire ); }
    bool                isValid( UN_StickyNoteID sticky_note ) const
                            { return myStickyNoteData.isValid( sticky_note ); }
    /// @}


    /// @{ Returns the container of data for the nodes in the graph.
    UN_NodeData &       nodeData()
                            { return myNodeData; }
    const UN_NodeData & nodeData() const
                            { return myNodeData; }
    /// @}

    /// @{ Returns the container of data for the parameters in the graph.
    UN_ParmData &       parmData()
                            { return myParmData; }
    const UN_ParmData & parmData() const
                            { return myParmData; }
    /// @}
    
    /// @{ Returns the container of data for the ports in the graph.
    UN_PortData &       portData()
                            { return myPortData; }
    const UN_PortData & portData() const
                            { return myPortData; }
    /// @}
    
    /// @{ Returns the container of data for the wires in the graph.
    UN_WireData &       wireData()
                            { return myWireData; }
    const UN_WireData & wireData() const
                            { return myWireData; }
    /// @}

    /// @{ Returns the container of data for the subnets in the graph.
    UN_SubnetData &     subnetData()
                            { return mySubnetData; }
    const UN_SubnetData & subnetData() const
                            { return mySubnetData; }
    /// @}
    
    /// @{ Returns the container of data for the sticky notes in the graph.
    UN_StickyNoteData & stickyNoteData()
                            { return myStickyNoteData; }
    const UN_StickyNoteData & stickyNoteData() const
                            { return myStickyNoteData; }
    /// @}
    
    /// @{ Drawing style of the connection wires in the editor
    void                setWireDrawStyle( UN_WireDrawStyle style )
                            { myWireDrawStyle = style; }
    UN_WireDrawStyle    wireDrawStyle() const
                            { return myWireDrawStyle; }
    /// @}

protected:
    /// Returns the topology object containing info about interconnections
    /// between graph elements such as nodes, ports, and wires.
    const UN_GraphTopology  &topology() const
                                { return myTopology; }

    /// Returns a subnet for the given (parent) node,
    /// either an existing or newly created one.
    UN_SubnetID         findOrCreateSubnet( UN_NodeID node );

    /// @{ Deletes the subnet structure associated with the given (parent) node.
    void                deleteSubnet( UN_NodeID node );
    void                deleteSubnet( UN_SubnetID subnet );
    /// @}

    /// Sets the new order for the children.
    // This method is needed for APEX. But it is protected, because 
    // it's easy to break topology by passing impostor children. 
    void reorderChildren( UN_SubnetID subnet, 
            const UT_Array<UN_NodeID> &child_order)
    {
        myTopology.reorderChildren( subnet, child_order );
    }

    /// Updates the internal dictionaries after nodes have been moved to a
    /// new subnet.  This method is needed for APEX. 
    void                updateSubnetWires( UN_SubnetID old_subnet )
                            { myTopology.updateSubnetWires( old_subnet ); }

private: 
    /// Creates the root node.
    void                createRootNode();

    /// Makes sure the given (parent) node has an associated subnet structure.
    void                ensureSubnetCreated( UN_NodeID node );

    /// Returns the representation of a node as options, in a classic format
    /// (array of struct) which is more human-readable.
    UN_OptionsPtr       nodeAsOptionsClassic( UN_NodeID node ) const;
    void                mergeNodeClassic( UN_NodeID node,
                                const UN_Options &graph_opts );

private:
    /// Contains information about parentage and connections between nodes.
    /// Also stores relation between nodes and their parms, ports, metadata etc.
    UN_GraphTopology    myTopology;

    /// A context that describes the graph framework, and knows about
    /// categories, and types of nodes, ports, and parameters available
    /// in this graph.
    UN_GraphContext     myContext;

    /// A container for data of all nodes in the graph.
    UN_NodeData         myNodeData;

    /// A container for data of all parameters in the graph.
    UN_ParmData         myParmData;

    /// A container for data of all ports in the graph.
    UN_PortData         myPortData;

    /// A container for data of all wires in the graph.
    UN_WireData         myWireData;
    
    /// A container for data of all subnets in the graph.
    UN_SubnetData       mySubnetData; 

    /// A container for data of all sticky notest in the graph.
    UN_StickyNoteData   myStickyNoteData;

    /// UI drawing style for the wire connections.
    UN_WireDrawStyle    myWireDrawStyle = UN_WireDrawStyle::Straight;
};


#endif