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() or mergeToNewLayer() 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

static std::shared_ptr<LiveSession> create(pxr::UsdStagePtr rootStage, std::shared_ptr<LiveSessionInfo> info)

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