This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
SdfBatchNamespaceEdit Class Reference

A description of an arbitrarily complex namespace edit. More...

#include <namespaceEdit.h>

Public Types

typedef std::function< bool(const SdfPath &)> HasObjectAtPath
 Functor that returns true iff an object exists at the given path.
 
typedef std::function< bool(const SdfNamespaceEdit &, std::string *)> CanEdit
 Functor that returns true iff the namespace edit will succeed.
 

Public Member Functions

SDF_API SdfBatchNamespaceEdit ()
 Create an empty sequence of edits.
 
SDF_API SdfBatchNamespaceEdit (const SdfBatchNamespaceEdit &)
 
SDF_API SdfBatchNamespaceEdit (const SdfNamespaceEditVector &)
 
SDF_API SdfBatchNamespaceEditoperator= (const SdfBatchNamespaceEdit &)
 
void Add (const SdfNamespaceEdit &edit)
 Add a namespace edit.
 
void Add (const SdfNamespaceEdit::Path &currentPath, const SdfNamespaceEdit::Path &newPath, SdfNamespaceEdit::Index index=SdfNamespaceEdit::AtEnd)
 Add a namespace edit.
 
const SdfNamespaceEditVectorGetEdits () const
 Returns the edits.
 
SDF_API bool Process (SdfNamespaceEditVector *processedEdits, const HasObjectAtPath &hasObjectAtPath, const CanEdit &canEdit, SdfNamespaceEditDetailVector *details=NULL, bool fixBackpointers=true) const
 Validate the edits and generate a possibly more efficient edit sequence.
 

Detailed Description

A description of an arbitrarily complex namespace edit.

A SdfBatchNamespaceEdit object describes zero or more namespace edits. Various types providing a namespace will allow the edits to be applied in a single operation and also allow testing if this will work.

Clients are encouraged to group several edits into one object because that may allow more efficient processing of the edits. If, for example, you need to reparent several prims it may be faster to add all of the reparents to a single SdfBatchNamespaceEdit and apply them at once than to apply each separately.

Objects that allow applying edits are free to apply the edits in any way and any order they see fit but they should guarantee that the resulting namespace will be as if each edit was applied one at a time in the order they were added.

Note that the above rule permits skipping edits that have no effect or generate a non-final state. For example, if renaming A to B then to C we could just rename A to C. This means notices may be elided. However, implementations must not elide notices that contain information about any edit that clients must be able to know but otherwise cannot determine.

Definition at line 194 of file namespaceEdit.h.

Member Typedef Documentation

◆ CanEdit

typedef std::function<bool(const SdfNamespaceEdit&,std::string*)> CanEdit

Functor that returns true iff the namespace edit will succeed.

If not it returns false and sets the string argument.

Definition at line 229 of file namespaceEdit.h.

◆ HasObjectAtPath

typedef std::function<bool(const SdfPath&)> HasObjectAtPath

Functor that returns true iff an object exists at the given path.

Definition at line 225 of file namespaceEdit.h.

Constructor & Destructor Documentation

◆ SdfBatchNamespaceEdit()

SDF_API SdfBatchNamespaceEdit ( )

Create an empty sequence of edits.

Member Function Documentation

◆ Add() [1/2]

void Add ( const SdfNamespaceEdit edit)
inline

Add a namespace edit.

Definition at line 205 of file namespaceEdit.h.

◆ Add() [2/2]

void Add ( const SdfNamespaceEdit::Path currentPath,
const SdfNamespaceEdit::Path newPath,
SdfNamespaceEdit::Index  index = SdfNamespaceEdit::AtEnd 
)
inline

Add a namespace edit.

Definition at line 211 of file namespaceEdit.h.

◆ GetEdits()

const SdfNamespaceEditVector & GetEdits ( ) const
inline

Returns the edits.

Definition at line 219 of file namespaceEdit.h.

◆ Process()

SDF_API bool Process ( SdfNamespaceEditVector processedEdits,
const HasObjectAtPath hasObjectAtPath,
const CanEdit canEdit,
SdfNamespaceEditDetailVector details = NULL,
bool  fixBackpointers = true 
) const

Validate the edits and generate a possibly more efficient edit sequence.

Edits are treated as if they were performed one at time in sequence, therefore each edit occurs in the namespace resulting from all previous edits.

Editing the descendants of the object in each edit is implied. If an object is removed then the new path will be empty. If an object is removed after being otherwise edited, the other edits will be processed and included in processedEdits followed by the removal. This allows clients to fixup references to point to the object's final location prior to removal.

This function needs help to determine if edits are allowed. The callbacks provide that help. hasObjectAtPath returns true iff there's an object at the given path. This path will be in the original namespace not any intermediate or final namespace. canEdit returns true iff the object at the current path can be namespace edited to the new path, ignoring whether an object already exists at the new path. Both paths are in the original namespace. If it returns false it should set the string to the reason why the edit isn't allowed. It should not write either path to the string.

If hasObjectAtPath is invalid then this assumes objects exist where they should and don't exist where they shouldn't. Use this with care. If canEdit in invalid then it's assumed all edits are valid.

If fixBackpointers is true then target/connection paths are expected to be in the intermediate namespace resulting from all previous edits. If false and any current or new path contains a target or connection path that has been edited then this will generate an error.

This method returns true if the edits are allowed and sets processedEdits to a new edit sequence at least as efficient as the input sequence. If not allowed it returns false and appends reasons why not to details.


The documentation for this class was generated from the following file: