Live Updates#

Enumerations#

OmniClientLiveUpdateType

Live Update Type.

Functions#

void omniClientLiveConfigureJitterReduction(uint32_t delayConstantMilliseconds, uint32_t delayMultiple, uint32_t delayMaximumMilliseconds)

Set parameters that control jitter reduction.

OmniClientRequestId omniClientLiveCreate(char const *url, struct OmniClientContent *content, void *userData, OmniClientLiveCreateCallback callback)

Create a live object.

uint64_t omniClientLiveGetLatestServerTime(const char *url)

Returns the server timestamp of the most recently received message (0 if no messages have been received)

void omniClientLiveProcess()

Call this to send live updates to the server and process live updates received from the server.

void omniClientLiveProcessUpTo(const char *url, uint64_t serverTime)

Same as omniClientLiveProcess() but you can specify a server time to stop processing updates.

OmniClientRequestId omniClientLiveRead(char const *url, uint64_t haveObjectId, uint64_t haveSequenceNum, void *userData, OmniClientLiveReadCallback callback)

Read a live object and set up a subscription to be notified of new updates to that object.

OmniClientRequestId omniClientLiveRead2(char const *url, uint64_t haveObjectId, uint64_t haveSequenceNum, void *userData, OmniClientLiveReadCallback callback)

This is the same as omniClientLiveRead except you don't need to call omniClientLiveProcess.

uint32_t omniClientLiveRegisterProcessUpdatesCallback(void *userData, OmniClientLiveProcessUpdatesCallback callback)

Register a callback to be notified that we are about to begin processing live updates.

uint32_t omniClientLiveRegisterQueuedCallback2(void *userData, OmniClientLiveQueuedCallback2 callback)

Register a function to be called any time there's an update in the queue that needs to be processed.

void omniClientLiveSetQueuedCallback(OmniClientLiveQueuedCallback callback)

Set a function to be called any time there's an update in the queue that needs to be processed.

OmniClientRequestId omniClientLiveUpdate(char const *url, uint64_t objectId, struct OmniClientContent *content, void *userData, OmniClientLiveUpdateCallback callback)

Update a live object.

OmniClientRequestId omniClientLiveUpdate2(char const *url, uint64_t objectId, struct OmniClientContent *content, void *userData, OmniClientLiveUpdateCallback callback)

This is the same as omniClientLiveUpdate except you don't need to call omniClientLiveProcess.

void omniClientLiveWaitForPendingUpdates()

Call this to wait for all pending live updates to complete.

Structs#

OmniClientLiveUpdateInfo

This holds information about a live update that was queued.

Typedefs#

OmniClientLiveCreateCallback

Called with the result of omniClientLiveCreate .

OmniClientLiveProcessUpdatesCallback

This is called any time omniClientLiveProcess , omniClientLiveProcessUpTo or omniClientLiveWaitForPendingUpdates is called.

OmniClientLiveQueuedCallback

This is called any time we receive a live update from the network.

OmniClientLiveQueuedCallback2

This is called any time we receive a live update from the network.

OmniClientLiveReadCallback

Called with the result of omniClientLiveRead .

OmniClientLiveUpdateCallback

Called with the result of omniClientLiveUpdate .

Enumerations#

enum OmniClientLiveUpdateType#

Live Update Type.

Indicates the type of live update being processed

Values:

enumerator eOmniClientLiveUpdateType_Remote#

A remote client sent an update.

enumerator eOmniClientLiveUpdateType_Local#

The server acknowledged a local update.

enumerator eOmniClientLiveUpdateType_More#

Due to Jitter reduction, a queued update may not be processed by omniClientLiveProcess. When this happens, the callback is called with this update type indicating that it’s now time to process the update.

enumerator Count_eOmniClientLiveUpdateType#

Functions#

void omniClientLiveConfigureJitterReduction(
uint32_t delayConstantMilliseconds,
uint32_t delayMultiple,
uint32_t delayMaximumMilliseconds,
)#

Set parameters that control jitter reduction.

Jitter is a variance in latency. For example if your ping times are variable from 100ms up to 250ms, then your received updates will not be smooth.

Jitter reduction attempts to reduce jitter by holding incoming updates in a queue and releasing them at a consistent rate. The amount of delay is a multiple of your average ping time, plus some constant, up to a maximum amount.

The formula is: delay = sentTime + min(delayMaximum, delayConstant + delayMultiple * averageLatency) - receivedTime

  • sentTime is the (actual) server time when the update was sent

  • receivedTime is the (estimated) server time when the update was received

  • averageLatency is the average amount of latency measured from periodic pings

  • delay is the amount of time to wait before processing the update

The default values are 10ms of constant delay, 2x average ping time, and 1 second maximum.

Pass (0,0,0) to completely disable jitter reduction.

Parameters:

  • delayConstantMilliseconds – The constant delay in milliseconds

  • delayMultiple – The multiplier for the average latency

  • delayMaximumMilliseconds – The maximum delay in milliseconds

OmniClientRequestId omniClientLiveCreate(
char const *url,
struct OmniClientContent *content,
void *userData,
OmniClientLiveCreateCallback callback,
)#

Create a live object.

Used by omni-usd-resolver.

Parameters:

  • url – The URL where the live object should be created

  • content – The content buffer for the live object (ownership is transferred)

  • userData – User data passed to the callback

  • callback – The callback function to register

Returns:

A request ID that can be used with omniClientStop

uint64_t omniClientLiveGetLatestServerTime(const char *url)#

Returns the server timestamp of the most recently received message (0 if no messages have been received)

Parameters:

url – The URL of the live file to get the latest server time for

Returns:

The server timestamp of the most recently received message, or 0 if no messages have been received

void omniClientLiveProcess()#

Call this to send live updates to the server and process live updates received from the server.

Make sure that no other threads are accessing the USD library at the time this is called. This function should be called from the main thread after receiving a callback from omniClientLiveRegisterQueuedCallback2.

void omniClientLiveProcessUpTo(const char *url, uint64_t serverTime)#

Same as omniClientLiveProcess() but you can specify a server time to stop processing updates.

These can be used to synchronize machines in multi-node rendering. One machine calls omniClientLiveGetLatestServerTime then all machines call omniClientLiveProcessUpTo to process updates received up to that time. This ensures that all machines have the same set of updates, and are therefore rendering the same version scene.

See also

omniClientLiveGetLatestServerTime

Parameters:

  • url – The URL of the live file to process updates for

  • serverTime – The server time to process updates up to

OmniClientRequestId omniClientLiveRead(
char const *url,
uint64_t haveObjectId,
uint64_t haveSequenceNum,
void *userData,
OmniClientLiveReadCallback callback,
)#

Read a live object and set up a subscription to be notified of new updates to that object.

haveObjectId & haveSequenceNum: If you already have some version of this live object, you can provide the object id and sequence number that you already have. The server will attempt to build a delta that brings you up to date. If you do not have any version of this live layer, you set both to 0.

The callback will be called with the exact objectId and sequenceNum that you have read. Both objectId and sequenceNum may be different from haveObjectId and haveSequenceNum. For example, if the object was deleted and recreated, then objectId will be different from haveObjectId. If additional changes were made to the object, sequenceNum will be different from haveSequenceNum.

Once you’ve received a callback with one objectId, all further callbacks will provide the same objectId, because if the object is deleted while you are reading it, you will receive a result of eOmniClientResult_ErrorAccessLost

The callback will be called with zero or more eOmniClientResult_Ok results, followed by eOmniClientResult_OkLatest, followed by zero or more eOmniClientResult_Ok results. Unless there is an error result (which could come at any time).

The callback will not be called again after an error result.

Used by omni-usd-resolver.

Parameters:

  • url – The URL of the live object to read

  • haveObjectId – The object ID you already have, or 0 if you don’t have any version

  • haveSequenceNum – The sequence number you already have, or 0 if you don’t have any version

  • userData – User data passed to the callback

  • callback – The callback function to register

Returns:

A request ID that can be used with omniClientStop

OmniClientRequestId omniClientLiveRead2(
char const *url,
uint64_t haveObjectId,
uint64_t haveSequenceNum,
void *userData,
OmniClientLiveReadCallback callback,
)#

This is the same as omniClientLiveRead except you don’t need to call omniClientLiveProcess.

Parameters:

  • url – The URL of the live object to read

  • haveObjectId – The object ID you already have, or 0 if you don’t have any version

  • haveSequenceNum – The sequence number you already have, or 0 if you don’t have any version

  • userData – User data passed to the callback

  • callback – The callback function to register

Returns:

A request ID that can be used with omniClientStop

uint32_t omniClientLiveRegisterProcessUpdatesCallback(
void *userData,
OmniClientLiveProcessUpdatesCallback callback,
)#

Register a callback to be notified that we are about to begin processing live updates.

Used by omni-usd-resolver.

Parameters:

  • userData – User data passed to the callback

  • callback – The callback function to register

Returns:

A handle that you can use with omniClientUnregisterCallback

uint32_t omniClientLiveRegisterQueuedCallback2(
void *userData,
OmniClientLiveQueuedCallback2 callback,
)#

Register a function to be called any time there’s an update in the queue that needs to be processed.

When this function is called, you should call omniClientLiveProcess() FROM THE MAIN THREAD. DO NOT CALL omniClientLiveProcess() FROM THIS CALLBACK! DO NOT CALL omniClientLiveProcess() WHEN SOME OTHER THREAD IS USING THE USD LIBRARY!

Parameters:

  • userData – User data passed to the callback

  • callback – The callback function to register

Returns:

A handle that you can use with omniClientUnregisterCallback

void omniClientLiveSetQueuedCallback(
OmniClientLiveQueuedCallback callback,
)#

Set a function to be called any time there’s an update in the queue that needs to be processed.

DEPRECATED: Use omniClientLiveRegisterQueuedCallback2

Parameters:

callback – The callback function to register, or nullptr to clear the callback

OmniClientRequestId omniClientLiveUpdate(
char const *url,
uint64_t objectId,
struct OmniClientContent *content,
void *userData,
OmniClientLiveUpdateCallback callback,
)#

Update a live object.

Used by omni-usd-resolver.

Parameters:

  • url – The URL of the live object to update

  • objectId – The object ID of the live object to update

  • content – The content buffer for the update (ownership is transferred)

  • userData – User data passed to the callback

  • callback – The callback function to register

Returns:

A request ID that can be used with omniClientStop

OmniClientRequestId omniClientLiveUpdate2(
char const *url,
uint64_t objectId,
struct OmniClientContent *content,
void *userData,
OmniClientLiveUpdateCallback callback,
)#

This is the same as omniClientLiveUpdate except you don’t need to call omniClientLiveProcess.

Parameters:

  • url – The URL of the live object to update

  • objectId – The object ID of the live object to update

  • content – The content buffer for the update (ownership is transferred)

  • userData – User data passed to the callback

  • callback – The callback function to register

Returns:

A request ID that can be used with omniClientStop

void omniClientLiveWaitForPendingUpdates()#

Call this to wait for all pending live updates to complete.

You should only have to call this at shutdown.

Typedefs#

typedef void (*OmniClientLiveCreateCallback)(void *userData, OmniClientResult result, uint64_t objectId, uint64_t sequenceNum)#

Called with the result of omniClientLiveCreate.

typedef void (*OmniClientLiveProcessUpdatesCallback)(void *userData)#

This is called any time omniClientLiveProcess, omniClientLiveProcessUpTo or omniClientLiveWaitForPendingUpdates is called.

See also

omniClientLiveRegisterProcessUpdatesCallback

typedef void (*OmniClientLiveQueuedCallback)()#

This is called any time we receive a live update from the network.

DEPRECATED: Use OmniClientLiveQueuedCallback2 instead

typedef void (*OmniClientLiveQueuedCallback2)(void *userData, struct OmniClientLiveUpdateInfo *info)#

This is called any time we receive a live update from the network.

Param info:

contains information about the live update

typedef void (*OmniClientLiveReadCallback)(void *userData, OmniClientResult result, uint64_t objectId, uint64_t sequenceNum, struct OmniClientContent *content)#

Called with the result of omniClientLiveRead.

typedef void (*OmniClientLiveUpdateCallback)(void *userData, OmniClientResult result, uint64_t sequenceNum, uint64_t requestId)#

Called with the result of omniClientLiveUpdate.