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

#ifndef __UNI_Manager_h__
#define __UNI_Manager_h__

#include "UNI_API.h"
#include "UNI_Category.h"
#include <UT/UT_Function.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Notifier.h>
#include <UT/UT_IteratorRange.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_UniquePtr.h>
#include <iterator>

#define UNI_ROOT_CATEGORY "UniNet"

// ============================================================================
/// The manager of UNI graphs. It is a point of entry into the UNI framework. 
/// 
/// It provides information about known categories (ie, goups of node types that
/// work together in a domain-specific specialization context of a UNI graph). 
/// It also provides the list of existing UNI graphs in the session.
/// 
class UNI_API UNI_Manager : public UT_NonCopyable
{
public:
    /// Cata structure used for internal mapping of categories.
    using CategoryMap = UT_StringMap< UT_UniquePtr< UNI_Category >>;

    /// @{ Constructor and destructor.
    //     Note, there is a global manger accessible thru UNImanager() function,
    //     but we allow local managers too, since there is no absolute need for
    //     singelton here. This allows using it for small scoped tasks,
    //     independent of global UNI manager framework.
                         UNI_Manager();
                        ~UNI_Manager();
    /// @}

    /// Returns the reference to the global UNI manager, which is accessible 
    /// in a single Houdini session. 
    static UNI_Manager  &get();

    /// Returns the names of the categorires the manager knows about.
    /// @parm include_non_loaded    If true the returned result includes
    //      categories that have been discovered/registered but not loaded yet.
    UT_StringArray      categoryNames( bool include_not_loaded = true ) const;

    /// A factory function that creates and returns a new category.
    using CategoryFactory = UT_Function<UNI_CategoryHandle()>;

    /// Registers a new category factory function that returns a newly created
    /// category by the given name.
    void addCategoryFactory( const UT_StringRef &category_name,
            const CategoryFactory &factory );

    /// Returns true if the manager has a factory function for the category by
    /// the given name.
    bool hasCategoryFactory( const UT_StringRef &category_name );

    /// @{ Returns a node category by the given name, or null if not found.
    const UNI_Category *
    findCategory( const UT_StringRef &category_name ) const
    { 
        return SYSconst_cast(this)->findCategory( category_name );
    }

    UNI_Category *
    findCategory( const UT_StringRef &category_name )
    { 
        auto it = myCategories.find( category_name );
        return it != myCategories.end() 
            ? it->second.get() 
            : loadCategory( category_name );
    }
    /// @}
  

    /// Iterator for traversing loaded categories.
    class CategoryIterator
    {
    public:
        using iterator_category = std::forward_iterator_tag;
        using value_type = UNI_Category;
        using difference_type = std::ptrdiff_t;
        using pointer = UNI_Category*;
        using reference = UNI_Category&;

        CategoryIterator( CategoryMap::mapped_iterator underlying_it )
            : myIterator( underlying_it ) {}
        bool operator ==( const CategoryIterator &other ) const
                    { return myIterator == other.myIterator; }
        bool operator !=( const CategoryIterator &other) const
                    { return myIterator != other.myIterator; }
        CategoryIterator &operator++()  
                    { ++myIterator; return *this; }
        UNI_Category *operator*() const
                    { return myIterator->get(); }

    private:
        CategoryMap::mapped_iterator myIterator;
    };

    /// Returns a range for iterating loaded categories.
    using CategoryRange = UT_IteratorRange< CategoryIterator >;
    CategoryRange loadedCategoryRange()
    {
        auto cat_range = myCategories.mapped_range();
        return CategoryRange( CategoryIterator(cat_range.begin()),
                              CategoryIterator(cat_range.end()));
    }

    /// Class containing info about magager's change event.
    class Event
    {
    public:
        /// Enumeration of event types.
        enum class Type
        {
            CategoryAdded,      // Category added
            CategoryRemoved     // Category removed
        };

        /// Constructor.
        Event(UNI_Manager &mgr, Type type, const UT_StringRef name) 
            : myManager(mgr)
            , myType(type)
            , myName(name)
        {}

        /// The manager issuing the event
        UNI_Manager &           manager() const
                                    { return myManager; }
        /// Event type;
        Type                    type() const 
                                    { return myType; }

        /// Name of added/removed category.
        const UT_StringHolder & name() const 
                                    { return myName; }

    private:
        UNI_Manager &           myManager;  // Manager issuing the event
        Type                    myType;     // The Type of the event
        const UT_StringHolder   myName;     // Name of affected category
    };

    /// Returns an object used for notifying interested parties about
    /// changes to the known categories (adding a new or removing old one).
    UT_NotifierImpl<const Event &> &getEventNotifier()
    {
        return myEventNotifier;
    }

    /// Adds a node type to our special "root node types" category. This is
    /// a category for all the "root" nodes of UNI_Graphs.
    void                addRootType( const UT_StringHolder &type_name,
                                const UT_StringArray &child_category_names );

private:
    /// Loads and returns a category by the given name. 
    /// Returns null if no factory is found for the given name.
    UNI_Category *      loadCategory( const UT_StringRef &category_name );

private:
    /// The node categories known to the manager.
    /// Each category is identified by a name, on which we key the dictionary.
    CategoryMap myCategories;

    /// Object that sends notifications about manager changes.
    UT_NotifierImpl<const Event &>  myEventNotifier;

    /// Category factory functions associated with category names.
    UT_StringMap<CategoryFactory>   myCategoryFactories;
};

// ============================================================================
/// Returns the reference to the global UNI manager.
static inline UNI_Manager &
UNImanager()
{ 
    return UNI_Manager::get(); 
}

#endif