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

#ifndef __GU_PackedFolders__
#define __GU_PackedFolders__

#include "GU_API.h"
#include "GU_DetailHandle.h"
#include "GU_PrimPacked.h"
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_ArrayStringSet.h>
#include <UT/UT_PathPattern.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <variant>

class GU_PackedFolders;

/// Read-Only Packed Folder Structure
class GU_API GU_PackedFoldersRO
{
public:
    /// Class representing a file in the file map
    class FileInfo
    {
    public:

        /// Path that this file represents
        const UT_StringHolder &path() const { return myPath; };

        /// The parent can be in one of three states
        /// @{
        bool isParentEmpty() const
        {
            return std::holds_alternative<std::monostate>(myParentPrim);
        }
        bool isParentPrim() const
        {
            return std::holds_alternative<const GU_PrimPacked *>(myParentPrim);
        }
        bool isParentRange() const
        {
            return std::holds_alternative<GA_Range>(myParentPrim);
        }
        /// @}

        /// Obtain parent as a GU_PrimPacked*, throws if !isParentPrim()
        /// @{
        const GU_PrimPacked *parentPrim() const
        {
            return std::get<const GU_PrimPacked *>(myParentPrim);
        }
        /// @}

        /// Get parent as a packed primitive, returns nullptr if not a prim
        /// @{
        const GU_PrimPacked *getIfParentPrim() const
        {
            if (!isParentPrim())
                return nullptr;
            return parentPrim();
        }
        /// @}

        /// Get parent as a GA_Range, throws if !isParentRange()
        /// @{
        const GA_Range &parentRange() const
        {
            return std::get<GA_Range>(myParentPrim);
        }
        /// @}

        /// Return true if parent is a packed primitive and has treatasfolder
        /// intrinsic enabled
        bool treatAsFolder() const;

        /// Return true if we're the root or treatAsFolder()
        bool isFolder() const
        {
            return (myPath == "/" || treatAsFolder());
        }

        /// Accessor to GU_DetailHandle of file contents
        /// @{
        const GU_ConstDetailHandle &primGdh() const  { return myPrimGdh; }
        /// @}

        /// Flag accessors
        /// @{
        bool isExisting() const     { return myExisting; }
        void setExisting(bool f)    { myExisting = f; }

        bool isModified() const     { return myModified; }
        void setModified(bool f)    { myModified = f; }

        bool isTouched() const      { return myTouched; }
        void setTouched(bool f)     { myTouched = f; }

        bool isCleared() const      { return myCleared; }
        void setCleared(bool f)     { myCleared = f; }

        bool isVisible() const      { return myVisible; }
        void setVisible(bool f)     { myVisible = f; }
        /// @}

    private:
        friend class GU_PackedFoldersRO;

        UT_StringHolder myPath;

        // myParentPrim is initially monostate.
        // When myParent is a GU_PrimPacked*/GA_Range, these are primitives
        // inside its parent's FileInfo::myPrimGdh.
        std::variant<std::monostate, const GU_PrimPacked *, GA_Range> myParentPrim;

        // Geometry contents of this file
        GU_ConstDetailHandle myPrimGdh;

        bool myExisting = false;
        bool myModified = false;
        bool myTouched = false;
        bool myCleared = false;
        bool myVisible = true;
    };

    /// Construct a folder structure with its own detail
    GU_PackedFoldersRO();

    /// Construct and build the map over the given detail, holding references
    /// to it
    explicit GU_PackedFoldersRO(const GU_DetailHandle &d)
    {
        replaceDetail(d);
    }

    ~GU_PackedFoldersRO() = default;

    /// Copy geometry and hierarchy from another GU_PackedFoldersRO
    /// @{
    GU_PackedFoldersRO(const GU_PackedFoldersRO &src)
        : GU_PackedFoldersRO()
    {
        *this = src;
    }
    GU_PackedFoldersRO &operator=(const GU_PackedFoldersRO &src);
    /// @}

    /// Rebuild file map over the given detail, holding references to it
    void replaceDetail(const GU_DetailHandle &d);

    /// Check if file at given path is a folder; returns false if file does not
    /// exist
    bool isFolder(const UT_StringRef &path) const;

    /// Get file access for read; returns nullptr if file does not exist
    const GU_PackedFoldersRO::FileInfo *findFile(const UT_StringRef &path) const;

    /// Fill array with the children of this file at path, if it exists
    void findChildren(UT_Array<const GU_PackedFoldersRO::FileInfo *> &out,
                      const UT_StringRef &path) const;

    /// Fill array with files which path the given apex syntax pattern; returns
    /// false on bad pattern_str
    /// @param sorted Sorts the output list by file path. If disabled, the list
    /// is in an arbitrary order.
    bool findFilesByPattern(
        UT_Array<const GU_PackedFoldersRO::FileInfo *> &out,
        const UT_StringRef &pattern_str,
        bool sorted,
        UT_StringHolder &error) const;

    /// Verifies packed primitive implementation pointers. Only does something
    /// on Windows debug builds.
    bool verify() const;

    /// Returns a string representing the topology of the whole
    UT_StringHolder getTopoFormat() const;

    /// Returns a string representing the topology of the whole folder structure
    /// but without actually building the GU_PackedFolders.
    static UT_StringHolder getTopoFormat(const GU_ConstDetailHandle &root_h);

private:
    FileInfo &rootFileInfo();
    const FileInfo &rootFileInfo() const;

    /// Rebuild the file map from myDetail if it was changed externally.
    void rebuildMap(const GU_ConstDetailHandle &detail);

    static void rebuildMap( const GU_ConstDetailHandle &detail,
        UT_ArrayStringMap<FileInfo> &file_map, bool create_details);

private:
    UT_ArrayStringMap<FileInfo> myFileMap;

    friend GU_PackedFolders;
};

/// Packed Folder Structure
class GU_API GU_PackedFolders
{
public:
    /// Class representing a file in the file map
    class FileInfo
    {
    public:

        /// Path that this file represents
        const UT_StringHolder &path() const { return myPath; };

        /// The parent can be in one of three states
        /// @{
        bool isParentEmpty() const
        {
            return std::holds_alternative<std::monostate>(myParentPrim);
        }
        bool isParentPrim() const
        {
            return std::holds_alternative<GU_PrimPacked *>(myParentPrim);
        }
        bool isParentRange() const
        {
            return std::holds_alternative<GA_Range>(myParentPrim);
        }
        /// @}

        /// Obtain parent as a GU_PrimPacked*, throws if !isParentPrim()
        /// @{
        GU_PrimPacked *parentPrim()
        {
            return std::get<GU_PrimPacked *>(myParentPrim);
        }
        const GU_PrimPacked *parentPrim() const
        {
            return std::get<GU_PrimPacked *>(myParentPrim);
        }
        /// @}

        /// Get parent as a packed primitive, returns nullptr if not a prim
        /// @{
        GU_PrimPacked *getIfParentPrim()
        {
            auto *pp_prim = std::get_if<GU_PrimPacked *>(&myParentPrim);
            return pp_prim ? *pp_prim : nullptr;
        }
        const GU_PrimPacked *getIfParentPrim() const
        {
            auto *pp_prim = std::get_if<GU_PrimPacked *>(&myParentPrim);
            return pp_prim ? *pp_prim : nullptr;
        }
        /// @}

        /// Get parent as a GA_Range, throws if !isParentRange()
        /// @{
        GA_Range &parentRange()
        {
            return std::get<GA_Range>(myParentPrim);
        }
        const GA_Range &parentRange() const
        {
            return std::get<GA_Range>(myParentPrim);
        }
        /// @}

        /// Return true if parent is a packed primitive and has treatasfolder
        /// intrinsic enabled
        bool treatAsFolder() const
        {
            const GU_PrimPacked *prim = getIfParentPrim();
            return prim && GU_PackedFolders::treatAsFolder(prim);
        }

        /// Return true if we're the root or treatAsFolder()
        bool isFolder() const
        {
            return myPath == "/" || treatAsFolder();
        }

        /// Safe accessors to GU_ConstDetailHandle/GU_DetailHandle of file contents
        /// @{
        GU_DetailHandle safePrimGdhNC()
        {
            return primGdh().castAwayConst();
        }


        GU_ConstDetailHandle primGdh() const
        {
            if (myPrimGdh.isValid())
            {
                return myPrimGdh;
            }

            GU_DetailHandle new_gdh;
            new_gdh.allocateAndSet(new GU_Detail);
            if (getIfParentPrim())
            {
                parentPrim()->unpack(*new_gdh.gdpNC());
            }

            myPrimGdh = new_gdh;
            return myPrimGdh;
        }

        void setPrimGdh(const GU_ConstDetailHandle &prim_gdh) { myPrimGdh = prim_gdh; }
        /// @}

        /// Flag accessors
        /// @{
        bool isExisting() const     { return myExisting; }
        void setExisting(bool f)    { myExisting = f; }

        bool isModified() const     { return myModified; }
        void setModified(bool f)    { myModified = f; }

        bool isTouched() const      { return myTouched; }
        void setTouched(bool f)     { myTouched = f; }

        bool isCleared() const      { return myCleared; }
        void setCleared(bool f)     { myCleared = f; }

        bool isVisible() const      { return myVisible; }
        void setVisible(bool f)     { myVisible = f; }
        /// @}

    private:
        friend class GU_PackedFolders;

        UT_StringHolder myPath;

        // myParentPrim is initially monostate.
        // When myParent is a GU_PrimPacked*/GA_Range, these are primitives
        // inside its parent's FileInfo::myPrimGdh.
        std::variant<std::monostate, GU_PrimPacked *, GA_Range> myParentPrim;

        // Geometry contents of this file
        mutable GU_ConstDetailHandle myPrimGdh;

        bool myExisting = false;
        bool myModified = false;
        bool myTouched = false;
        bool myCleared = false;
        bool myVisible = true;
    };

    /// Construct a folder structure with its own detail
    GU_PackedFolders();

    /// Construct and build the map over the given detail, holding references
    /// to it
    explicit GU_PackedFolders(GU_DetailHandle &d, bool reuse_detail_ids=false);

    ~GU_PackedFolders() = default;

    /// Copy geometry and hierarchy from another GU_PackedFolders
    /// @{
    GU_PackedFolders(const GU_PackedFolders &src)
        : GU_PackedFolders()
    {
        *this = src;
    }
    GU_PackedFolders &operator=(const GU_PackedFolders &src);
    /// @}

    /// Get and set treatasfolder intrinsic on a packed prim
    static bool treatAsFolder(const GU_PrimPacked *pack);
    static void setTreatAsFolder(GU_PrimPacked *pack, bool b);

    /// Return whether the given primitive is in _3d_hidden_primitives
    static bool isPrimVisible(const GA_Primitive *prim);

    /// Path and name processing functions
    /// @{
    static void splitFirstDirectory(UT_WorkBuffer &path, UT_WorkBuffer &out);
    static void splitLastDirectory(UT_WorkBuffer &path, UT_WorkBuffer &out);
    static void splitFileName(const UT_StringRef &label, UT_WorkBuffer &name,
                              UT_WorkBuffer &type);
    /// @}

    /// Return packed prim if the detail is a single, packed object; return
    /// null if not
    static const GU_PrimPacked *getPackedFromDetail(const GU_Detail *gdp);

    /// Helper method to set the properties on an existing file
    bool setFileProperties(const UT_StringRef &path, bool treat_as_folder, bool visible);

    /// Rebuild file map over the given detail, holding references to it
    void replaceDetail(GU_DetailHandle &d);

    /// Update the chain of packed primitives up the path to the root detail
    void updatePath(const UT_StringRef &path_str);

    /// Build a path of folders if it does not exist already.
    /// Returns true if successful; fails if a file in path_str exists and is
    /// not a folder
    bool buildPath(const UT_StringRef &path_str);

    /// Insert/replace a file at the given path, creating the path if it does
    /// not exist. If pack is true, pack d before adding to the folder. 
    /// If is_folder is true, set the treatasfolder intrinsic on the inserted
    /// file.
    /// Returns true if successful; fails if it can't create the path to the
    /// file
    bool insert(
        const UT_StringRef &path,
        const GU_ConstDetailHandle &d,
        bool pack = true,
        bool is_folder = false,
        bool is_visible = true);

    /// Remove a file or folder at the given path.
    /// Returns true if successful; fails if the given path is the root "/" or
    /// doesn't exist.
    bool remove(const UT_StringRef &path_str);

    /// Set flags to true on a given file and if desired, its children
    void setFlags(
        const UT_StringRef &path, 
        bool existing, 
        bool modified, 
        bool touched, 
        bool and_children = false);

    /// Clear flags to false on a given file and if desired, its children
    void clearFlags(
        const UT_StringRef &path, 
        bool existing, 
        bool modified, 
        bool touched, 
        bool and_children = false);

    /// Sets touch flag on a given file & its children if and_children is true
    void touch(const UT_StringRef &path, bool and_children = false);

    /// Mark all folders in the path given as touched
    void touchFolders(const UT_StringRef &path_str);

    /// Removes stale files which are flagged as untouched.
    /// Files flagged existing if found by replaceDetail()/rebuildMap() are
    /// protected.  If backup is provided, files which are untouched, modified,
    /// and existing will be replaced by the copy in backup.  Files are marked
    /// modified if created/replaced by insert().
    void removeStale(const GU_PackedFolders *backup = nullptr);

    /// Check if file at given path is a folder; returns false if file does not
    /// exist
    bool isFolder(const UT_StringRef &path) const;

    /// Get file access for read; returns nullptr if file does not exist
    const GU_PackedFolders::FileInfo *findFile(const UT_StringRef &path) const;

    /// Fill array with the children of this file at path, if it exists
    void findChildren(UT_Array<const GU_PackedFolders::FileInfo *> &out,
                      const UT_StringRef &path) const;

    /// Fill array with files which path the given apex syntax pattern; returns
    /// false on bad pattern_str
    /// @param sorted Sorts the output list by file path. If disabled, the list
    /// is in an arbitrary order.
    bool findFilesByPattern(
        UT_Array<const GU_PackedFolders::FileInfo *> &out,
        const UT_StringRef &pattern_str,
        bool sorted,
        UT_StringHolder &error) const;

    /// Verifies packed primitive implementation pointers. Only does something
    /// on Windows debug builds.
    bool verify() const;

    /// Returns a string representing the topology of the whole
    UT_StringHolder getTopoFormat() const;

private:
    FileInfo &rootFileInfo();
    const FileInfo &rootFileInfo() const;

    /// Rebuild the file map from myDetail if it was changed externally.
    /// It will clear children of the given path before rebuilding.
    /// If path does not exist in the map, it will fail silently.
    /// If mark_existing, myExisting flag will be set on files.
    void rebuildMap(GU_DetailHandle *detail, const UT_StringRef &path,
                    bool mark_existing = true, bool reuse_detail_ids=false);

private:
    UT_ArrayStringMap<FileInfo> myFileMap;
};

SYS_FORCE_INLINE
bool
GU_PackedFoldersRO::FileInfo::treatAsFolder() const
{
    const GU_PrimPacked *prim = getIfParentPrim();
    return prim && GU_PackedFolders::treatAsFolder(prim);
}

namespace UT
{
template <typename T>
struct DefaultClearer;

template <>
struct DefaultClearer<GU_PackedFoldersRO::FileInfo>
{
    static void clear(GU_PackedFoldersRO::FileInfo &v) { v.setCleared(true); }
    static bool isClear(const GU_PackedFoldersRO::FileInfo &v)
    {
        return v.isCleared();
    }
    static void clearConstruct(GU_PackedFoldersRO::FileInfo *p) 
    {
        new ((void *)p) GU_PackedFoldersRO::FileInfo();
    }
    static const bool clearNeedsDestruction = true;
};

template <>
struct DefaultClearer<GU_PackedFolders::FileInfo>
{
    static void clear(GU_PackedFolders::FileInfo &v) { v.setCleared(true); }
    static bool isClear(const GU_PackedFolders::FileInfo &v)
    {
        return v.isCleared();
    }
    static void clearConstruct(GU_PackedFolders::FileInfo *p) 
    {
        new ((void *)p) GU_PackedFolders::FileInfo();
    }
    static const bool clearNeedsDestruction = true;
};
} // namespace UT

#endif