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
        {
            UT_ASSERT(isParentPrim());
            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
        {
            UT_ASSERT(isParentRange());
            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);
    }

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

    ~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
    /// Note: GU_PackedFolders::FileInfo* can become invalid when rebuildMap() is called.
    const GU_PackedFoldersRO::FileInfo *findFile(const UT_StringRef &path) const;

    /// Fill array with the children of this file at path, if it exists
    /// Note: GU_PackedFolders::FileInfo* can become invalid when rebuildMap() is called.
    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.
    /// Note: GU_PackedFolders::FileInfo* can become invalid when rebuildMap() is called.
    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()
        {
            UT_ASSERT(isParentPrim());
            return std::get<GU_PrimPacked *>(myParentPrim);
        }
        const GU_PrimPacked *parentPrim() const
        {
            UT_ASSERT(isParentPrim());
            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()
        {
            UT_ASSERT(isParentRange());
            return std::get<GA_Range>(myParentPrim);
        }
        const GA_Range &parentRange() const
        {
            UT_ASSERT(isParentRange());
            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
    /// @mark_existing Sets the Existing flag on existing paths.  This affects
    ///  the removeStale() behavior. 
    ///  Use mark_existing=true if you want to keep existing details as is and
    ///  only modify the touched paths.
    ///  Use mark_existing=false if you want to delete existing details that
    ///  aren't touched
    explicit GU_PackedFolders(GU_DetailHandle &d,
        bool reuse_detail_ids=false,
        bool mark_existing=true
        );

    ~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);
    static void splitFilePath(const UT_StringRef &path, UT_Array<UT_StringHolder> &file_names);
    /// @}

    /// Path name validation functions to avoid paths that conflict with the
    /// pattern matching.
    /// @{
    static bool isValidPathName(const UT_StringRef &path);
    static UT_StringHolder forceValidPathName(const UT_StringRef &path);
    /// @}

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

    /// Updates the packed geometry at the given path. If no geometry exists
    /// at the given path, the geometry will not be added.
    /// Returns whether the geometry was successfully updated.
    static bool updatePackedGeometry(GU_DetailHandle packed_gdh,
                                     GU_ConstDetailHandle gdh,
                                     const UT_StringRef &path);

    /// Returns whether the geometry contains a packed folder geometry with the
    /// given path.
    /// @{
    static bool contains(GU_ConstDetailHandle gdh,
                         const UT_StringRef &path,
                         GA_OffsetArray *offsets=nullptr);
    static bool contains(GU_ConstDetailHandle gdh,
                         const UT_Array<UT_StringHolder> &file_names,
                         GA_OffsetArray *offsets=nullptr);
    /// @}

    /// Helper method to set the properties on an existing file
    /// Note: GU_PackedFolders::FileInfo* can become invalid after calling
    ///       setFileProperties(). You'll have to call the find() methods again.
    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
    /// Note: GU_PackedFolders::FileInfo* can become invalid after call insert()
    ///       You'll have to call the find() methods again.
    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);

    /// Merges the contents of 'src_folders' into this folder structure,
    /// filtered by the specified file pattern.
    /// Note: GU_PackedFolders::FileInfo* can become invalid after call insert()
    ///       You'll have to call the find() methods again.
    void merge(
        const GU_PackedFoldersRO &src_folders,
        const UT_StringRef &pattern);

    /// Simple struct holding the args for the remove and insert operations.
    struct EditInfo
    {
        bool myRemove = false;  // true to remove, false to insert.
        UT_StringHolder myPath; // The path to insert or remove

        // Extra args for Insert
        GU_ConstDetailHandle myDetail; // Detail to insert.
        bool myPack = true; // insert pack
        bool myIsFolder = false; //insert is_folder
        bool myIsVisible = true; // insert is_visibled

        bool myRet = false; // Return code for the operation.
    };

    /// Accumulate edit operations in a block.
    class EditOperations
    {
    public:
        /// Insert a detail at the given path.
        void insert(
            const UT_StringRef &path,
            const GU_ConstDetailHandle &d,
            bool pack = true,
            bool is_folder = false,
            bool is_visible = true)
        {
            EditInfo o;
            o.myRemove = false;
            o.myPath = path;
            o.myDetail = d;
            o.myPack = pack;
            o.myIsFolder = is_folder;
            o.myIsVisible = is_visible;
            myOps.append(o);
        }

        /// Remove a path
        void remove(const UT_StringRef &path)
        {
            EditInfo o;
            o.myRemove = true;
            o.myPath = path;
            myOps.append(o);
        }

        /// Remove a FileInfo
        void remove(const FileInfo *fi)
        {
            EditInfo o;
            o.myRemove = true;
            o.myPath = fi->path();
            myOps.append(o);
        }

        /// Move a FileInfo to a new path. Does an insert and remove.
        void move(const FileInfo *fi, const UT_StringRef &new_path, bool pack)
        {
            EditInfo i;
            i.myRemove = false;
            i.myPath = new_path;
            i.myDetail = fi->primGdh();
            i.myPack = pack;
            i.myIsFolder = fi->isFolder();
            i.myIsVisible = fi->isVisible();
            myOps.append(i);

            EditInfo r;
            r.myRemove = true;
            r.myPath = fi->path();
            myOps.append(r);
        }

        UT_Array<EditInfo> myOps;
    };
    /// Perform multiple insert/remove/move operations in a single step.
    /// Returns true if all the operations succeeded.
    /// o.myOps[i].myRet has the return status of individual edit operations.
    /// Note: GU_PackedFolders::FileInfo* can become invalid when rebuildMap()
    ///       is called and it is likely to happen after doing many operations.
    ///       You'll have to call the find() methods again.
    bool edit(EditOperations &o);


    /// 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
    /// Note: GU_PackedFolders::FileInfo* can become invalid when rebuildMap() is called.
    ///       It can happen when calling insert() or setFileProperties()
    const GU_PackedFolders::FileInfo *findFile(const UT_StringRef &path) const;

    /// Fill array with the children of this file at path, if it exists
    /// Note: GU_PackedFolders::FileInfo* can become invalid when rebuildMap() is called.
    ///       It can happen when calling insert() or setFileProperties()
    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.
    /// Note: GU_PackedFolders::FileInfo* can become invalid when rebuildMap() is called.
    ///       It can happen when calling insert() or setFileProperties()
    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.
    ///
    /// This can corrupt GU_PackedFolders::FileInfo* returned by
    // findFile(), findChildren(), findFilesByPattern()
    void rebuildMap(GU_DetailHandle *detail, const UT_StringRef &path,
                    bool mark_existing = true, bool reuse_detail_ids=false);

    /// internal insert call that accumulates the paths to rebuild.
    bool insert(
        const UT_StringRef &path,
        const GU_ConstDetailHandle &d,
        UT_StringArray &rebuild_paths,
        bool pack = true,
        bool is_folder = false,
        bool is_visible = true);

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