namespaceEditor.h

Go to the documentation of this file.

//
// Copyright 2023 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_USD_NAMESPACE_EDITOR_H
#define PXR_USD_USD_NAMESPACE_EDITOR_H
 
 
#include "pxr/pxr.h"
#include "pxr/usd/usd/api.h"
#include "pxr/usd/usd/common.h"
#include "pxr/usd/usd/stage.h"
#include "pxr/usd/pcp/dependentNamespaceEditUtils.h"
#include "pxr/usd/sdf/namespaceEdit.h"
 
PXR_NAMESPACE_OPEN_SCOPE
 
class UsdNamespaceEditor 
{
public:
    struct EditOptions {
 
        bool allowRelocatesAuthoring = true;
    };
 
    // Structure returned by CanApplyEdits that stores errors and warnings 
    // encountered while processing the edits. This struct evaluates to false
    // if any errors were found, and true otherwise (even if there are warnings).
    struct CanApplyResult 
    {
        std::vector<std::string> errors;
        std::vector<std::string> warnings;
 
        operator bool() const
        {
            return errors.empty();
        }
    }; 
 
    USD_API
    explicit UsdNamespaceEditor(const UsdStageRefPtr &stage);
 
    USD_API
    UsdNamespaceEditor(
        const UsdStageRefPtr &stage, 
        EditOptions &&editOptions);
 
    USD_API
    UsdNamespaceEditor(
        const UsdStageRefPtr &stage, 
        const EditOptions &editOptions);
 
 
    USD_API
    void AddDependentStage(const UsdStageRefPtr &stage);
 
    USD_API
    void RemoveDependentStage(const UsdStageRefPtr &stage);
 
    USD_API
    void SetDependentStages(const UsdStageRefPtrVector &stages);
 
 
    USD_API
    bool DeletePrimAtPath(
        const SdfPath &path);
 
    USD_API
    bool MovePrimAtPath(
        const SdfPath &path, 
        const SdfPath &newPath);
 
    USD_API
    bool DeletePrim(
        const UsdPrim &prim);
 
    USD_API
    bool RenamePrim(
        const UsdPrim &prim, 
        const TfToken &newName);
 
    USD_API
    bool ReparentPrim(
        const UsdPrim &prim, 
        const UsdPrim &newParent);
 
    USD_API
    bool ReparentPrim(
        const UsdPrim &prim, 
        const UsdPrim &newParent,
        const TfToken &newName);
 
    USD_API
    bool DeletePropertyAtPath(
        const SdfPath &path);
 
    USD_API
    bool MovePropertyAtPath(
        const SdfPath &path, 
        const SdfPath &newPath);
 
    USD_API
    bool DeleteProperty(
        const UsdProperty &property);
 
    USD_API
    bool RenameProperty(
        const UsdProperty &property, 
        const TfToken &newName);
 
    USD_API
    bool ReparentProperty(
        const UsdProperty &property, 
        const UsdPrim &newParent);
 
    USD_API
    bool ReparentProperty(
        const UsdProperty &property, 
        const UsdPrim &newParent,
        const TfToken &newName);
 
    USD_API
    bool ApplyEdits();
 
    USD_API
    bool CanApplyEdits(std::string *whyNot) const;
 
    USD_API
    CanApplyResult CanApplyEdits() const;
 
    USD_API
    SdfLayerHandleVector GetLayersToEdit();
 
private:
 
    // The type of edit that an edit description is describing.
    enum class _EditType {
        Invalid, 
 
        Delete,
        Rename,
        Reparent
    };
 
    // Description of an edit added to this namespace editor.
    struct _EditDescription {
        // Path to the existing object.
        SdfPath oldPath;
        // New path of the object after the edit is performed. An empty path 
        // indicates that the edit operation will delete the object.
        SdfPath newPath;
 
        // Type of the edit as determined by the oldPath and the newPath.
        _EditType editType = _EditType::Invalid;
 
        // Whether this describes a property edit or, otherwise, a prim edit.
        bool IsPropertyEdit() const { return oldPath.IsPrimPropertyPath(); }
    };
 
    // Struct representing the Sdf layer edits necessary to apply an edit 
    // description to the stage. We need this to gather all the information we 
    // can about what layer edits need to be performed before we start editing 
    // any specs so that we can avoid partial edits when a composed stage level
    // namespace would fail.
    struct _ProcessedEdit
    {
        // List of errors encountered that would prevent the overall namespace
        // edit of the composed stage object from being completed successfully.
        std::vector<std::string> errors;
 
        // List of warnings encountered that will not prevent the main edit from 
        // being completed but indicate that some supporting operations may not 
        // have been performed.
        std::vector<std::string> warnings;
 
        // The edit description of the primary edit.
        _EditDescription editDescription;
 
        // The list of layers that have specs that need to have the Sdf 
        // namespace edit applied.
        SdfLayerHandleVector layersToEdit;
 
        // Whether performing the edit will author new relocates.
        bool willAuthorRelocates = false;
 
        // Layer edits that need to be performed to update path-bearing fields 
        // (like connection and relationship targets) in order to keep them 
        // referring to the same object after applying this processed edit.
        struct PathBearingFieldEdit {
            // Prim or property spec to author the new value to. Note that we
            // store the spec handle for the object as the object's path could 
            // change if it is moved or deleted by the primary namespace edit.
            SdfSpecHandle spec;
 
            // Name of the path-bearing field.  
            TfToken fieldName;
 
            // Updated field value to set.
            VtValue newFieldValue;
        };
        std::vector<PathBearingFieldEdit> pathBearingFieldEdits;
 
        // Full set of namespace edits that need to be performed for all the
        // dependent stages of this editor as a result of dependencies on the
        // initial spec move edits.
        PcpDependentNamespaceEdits dependentStageNamespaceEdits;
 
        // Applies this processed edit, performing the individual edits 
        // necessary to each layer that needs to be updated.
        bool Apply();
 
        // Returns whether this processed edit can be applied and any errors
        // or warnings that it would produce.
        UsdNamespaceEditor::CanApplyResult CanApply() const;
    };
 
    // Adds an edit description for a prim delete operation.
    bool _AddPrimDelete(const SdfPath &oldPath);
 
    // Adds an edit description for a prim rename or reparent operation.
    bool _AddPrimMove(const SdfPath &oldPath, const SdfPath &newPath);
 
    // Adds an edit description for a property delete operation.
    bool _AddPropertyDelete(const SdfPath &oldPath);
 
    // Adds an edit description for a property rename or reparent operation.
    bool _AddPropertyMove(const SdfPath &oldPath, const SdfPath &newPath);
 
    // Clears the current procesed edits.
    void _ClearProcessedEdits();
 
    // Processes and caches the layer edits necessary for the current edit 
    // operation if there is no cached processecd edit.
    void _ProcessEditsIfNeeded() const;
 
    // Helper class for _ProcessEditsIfNeeded. Defined entirely in 
    // implementation. Declared here for private access to the editor 
    // structures.
    class _EditProcessor;
 
    UsdStageRefPtr _stage;
    // Dependent stage order should be arbitrary but we want don't want 
    // duplicates which can cause unnecessary work.
    using _StageSet = std::unordered_set<UsdStageRefPtr, TfHash>;
    _StageSet _dependentStages;
    EditOptions _editOptions;
    _EditDescription _editDescription;
    mutable std::optional<_ProcessedEdit> _processedEdit;   
};
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_USD_USD_NAMESPACE_EDITOR_H