omni::connect::core::LiveSession
Defined in omni/connect/core/LiveSession.h
-
class LiveSession
An interface class provides Live Session lifetime management.
Public Functions
-
~LiveSession()
-
pxr::SdfLayerHandle join(const std::string &sessionName, const bool makeEditTarget = true)
Join an existing or create a new live session.
This function performs these steps:
Init the LiveSessionInfo
If session config file exists, validate the version
Create new session config file if it doesn’t exist
Create and join the LiveSessionChannel
Create a new .live layer if it doesn’t exist
Add the session’s .live layer the root stage’s session layer if it’s not already a sublayer
If
makeEditTarget
is set then make the new .live layer the stage’s edit target
Note, if the sessionName is invalid (see the rules in LiveSessionInfo::init()), an error log message is sent and the returned layer will be invalid, indicating a failure.
If the app chooses to not set
makeEditTarget
, then it must set the stage’s edit target to the live layer using something like:rootStage->SetEditTarget(pxr::UsdEditTarget(liveLayer))
- Parameters
sessionName – The intended name of the live session
makeEditTarget – If true the rootStage edit target will be set to the live layer
- Returns
A valid live layer if the session was joined successfully, note that this is a weak pointer that expires after merging or leaving the session.
-
bool mergeToRoot(const char *checkpointComment = nullptr, const bool resetEditTarget = true)
Merge live changes to root layer.
This function will merge changes from a live session layer into the root stage layer.
Specifically, this function performs these steps:
Check if the current user has the authority to merge the session and ACL to write the changes
Send a message to the live channel that the merge has started
Checkpoint the .live layer
Checkpoint the root stage
Merge the changes into the root stage (root layer or a new layer and insert the new sublayer into the root stage)
This depends on whether
mergeToRoot()
ormergeToNewLayer()
is called
Save and checkpoint the stage’s root layer
Clear the .live layer
Remove the .live layer from the root stage’s session layer
Set the stage’s edit target to the root layer (if
resetEditTarget
true)Send a message to the live channel that the merge is finished
- Parameters
checkpointComment – An optional checkpoint comment added to the root and live layers
resetEditTarget – Set the edit target to the stage’s root layer if true
- Returns
Whether the session was merged
-
bool hasPrimSpecsInRootLayer()
Returns whether there are any prim specs defined in the layer.
If a stage’s root layer contains prim specs, then “overs” from a sublayer that affect those prim specs may be hidden. This is useful to know when merging a live session layer back to the stage. The general guidance is that if there are any prim specs defined in a stage’s root layer then the live layer should be merged into the stage’s root layer. If there are no prim specs defined in a stage’s root layer then either merging to the root layer or a new sublayer will work.
See the USD Strength Ordering docs for more information regarding USD strength ordering.
See LiveSession::mergeToRoot() and LiveSession::mergeToNewLayer() for more merging live changes to the root stage
- Returns
Whether the stage’s root layer has any prim specs defined
-
bool mergeToNewLayer(const char *targetLayerUri = nullptr, const char *checkpointComment = nullptr, const bool resetEditTarget = true, const pxr::SdfLayer::FileFormatArguments &fileFormatArgs = pxr::SdfLayer::FileFormatArguments())
Merge live changes to target layer, insert as a root stage sublayer.
This function will merge changes from a live session layer into a new sublayer of the root stage. It will also execute all of the steps defined in
mergeToRoot()
.Note, if the target layer already exists the contents will be cleared
Note, if
targetLayerUri
is null, the layer name will be autogenerated as $(stage parent URI)/_$(sessionName)_nn.usd (_nn only appended if required for uniqueness)- Parameters
targetLayerUri – The absolute URI for the new targetLayerUri, if null then it will be autogenerated in the root stage’s directory
checkpointComment – An optional checkpoint comment added to the root and live layers
resetEditTarget – Set the edit target to the stage’s root layer if true
fileFormatArgs – Additional file format-specific arguments to be supplied during target layer creation.
- Returns
Whether the session was merged
-
void leave(const bool resetEditTarget = true)
Leave the live session without merging.
This function performs these steps:
Remove the .live layer from the root stage’s session layer
Set the stage’s edit target to the root layer (if
resetEditTarget
true)Send a message to the live channel that the merge is finished
- Parameters
resetEditTarget – Set the edit target to the stage’s root layer if true
-
std::shared_ptr<LiveSessionChannel> getChannel() const
Get the Live Session Channel interface.
Note
The returned channel interface is disconnected after the LiveSession is deleted
- Returns
The LiveSessionChannel interface, null if session was not joined
-
std::shared_ptr<LiveSessionInfo> getInfo() const
Get the Live Session Info interface.
Note
The returned info interface is invalid after the LiveSession is deleted
- Returns
The LiveSessionInfo interface, null if root stage was invalid upon creation
Public Static Functions
-
static std::shared_ptr<LiveSession> create(pxr::UsdStagePtr rootStage)
Create an Omniverse live session class.
Note, live sessions are only supported on stages resident on Omniverse Nucleus servers, not local disk.
- Parameters
rootStage – The root USD stage in the live session (must reside on a Nucleus server)
- Returns
A live session interface shared pointer (std::shared_ptr<LiveSession>), null if rootStage is invalid
Create an Omniverse live session class.
Note, live sessions are only supported on stages resident on Omniverse Nucleus servers, not local disk.
- Parameters
rootStage – The root USD stage in the live session (must reside on a Nucleus server)
info – The LiveSessionInfo to attach to
- Returns
A live session interface shared pointer (std::shared_ptr<LiveSession>), null if rootStage or info is invalid
-
~LiveSession()