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/layerRelocatesEditBuilder.h"
#include "pxr/usd/sdf/namespaceEdit.h"
 
 
PXR_NAMESPACE_OPEN_SCOPE
 
class UsdNamespaceEditor 
{
public:
    struct EditOptions {
 
        bool allowRelocatesAuthoring = true;
    };
 
    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
    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 = nullptr) const;
 
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;
 
        // The Sdf batch namespace edit that needs to be applied to each layer
        // with specs.
        SdfBatchNamespaceEdit edits;
        
        // The list of layers that have specs that need to have the Sdf 
        // namespace edit applied.
        SdfLayerHandleVector layersToEdit;
 
        // The list of relocates edits that need to be made to layers in order
        // to relocate a prim.
        PcpLayerRelocatesEditBuilder::LayerRelocatesEdits relocatesEdits;
 
        // Layer edits that need to be performed to update connection and 
        // relationship targets of other properties in order to keep them 
        // targeting the same object after applying this processed edit.
        struct TargetPathListOpEdit {
            // Property spec to author the new targets value to. Note that we
            // store the spec handle for the property as the property spec's
            // path could change if the property is moved or deleted by the 
            // primary namespace edit.
            SdfPropertySpecHandle propertySpec;
 
            // Name of the field that holds the path targets for the property
            // which differs for attributes vs relationships.  
            TfToken fieldName;
 
            // Updated list op value to set for the property spec.
            SdfPathListOp newFieldValue;
        };
        std::vector<TargetPathListOpEdit> targetPathListOpEdits;
 
        // List of errors encountered that would prevent connection and 
        // relationship target edits from being performed in response to the
        // namespace edits.
        std::vector<std::string> targetPathListOpErrors;
 
        // Reparent edits may require overs to be created for the new parent if
        // a layer doesn't have any specs for the parent yet. This specifies the
        // path of the parent specs to create if need.
        SdfPath createParentSpecIfNeededPath;
 
        // Some edits want to remove inert ancestor overs after a prim is
        // removed from its parent spec in a layer.
        bool removeInertAncestorOvers = false;
 
        // 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.
        bool CanApply(std::string *whyNot) 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;
    EditOptions _editOptions;
    _EditDescription _editDescription;
    mutable std::optional<_ProcessedEdit> _processedEdit;   
};
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_USD_USD_NAMESPACE_EDITOR_H