omni::usd::UsdContext

class UsdContext

Public Types

typedef std::unordered_map<uint32_t, hydra::EngineCreationConfig> EngineWarmupConfig: Extract the engine warmup config from the settings.

Public Functions

bool addHydraEngine(const char *name, omni::usd::hydra::IHydraEngine *hydraEngine, omni::usd::hydra::OpaqueSharedHydraEngineContextPtr ctx, const omni::usd::hydra::HydraEngineContextConfig &config, bool defer)

Adds a hydra engine with associated renderer to context.

The syncScopes determines which rendering thread the hydra engine should run on. It should correspond to the syncScope that was passed into the IHydraEngine during creation

Returns: true if hydra engines are created, false otherwise

void removeAllHydraEngines(): Destroys all hydra engines.

void setActiveHydraEngine(const char *name)

Controls two things:

Specifies the default hydra engine to use with hydraEngine = null in CreateViewport
[TODO] Controls the hydra engine used for selection and picking, this feels wrong and instead the picking api should include a hydra engine, and if non specified use the default. This API should instead be setDefaultHydraEngine

const char *getActiveHydraEngineName(void): Return the name of active hydra engine.

bool addHydraSceneDelegate(const char *name, const char *hydraEngine, const omni::usd::hydra::IHydraSceneDelegate &sceneDelegate, const char *delegateCreateParam)

Adds a hydra scene delegate with associated input data to the context.

Parameters

name – should be unique, and will be used for identifying the scene delegate in future calls. If the name is not unique, the add call will fail.
hydraEngine – a string representing which hydra engine this delegate should be added for. For instance, “rtx”
sceneDelegate – the new scene delegate interface to add
delegateCreateParam – a parameter to pass to the sceneDelegate’s Create function

Returns

true if successfully added, false otherwise

bool removeHydraSceneDelegate(const char *name)

Removes a hydra scene delegate.

Parameters: name – should match the name passed to addHydraSceneDelegate
Returns: true if successfully removed, false otherwise

bool setHydraSceneDelegateRootTransform(const char *name, const PXR_NS::GfMatrix4d &xform)

Sets a global tansform for all content in a named hydra scene delegate.

Parameters

name – should match the name passed to addHydraSceneDelegate
xform – a transform to apply to everything in the delegate

Returns

true if successfully removed, false otherwise

bool getHydraSceneDelegateAttribute(const char *name, const PXR_NS::SdfPath &primPath, const PXR_NS::TfToken &attribueName, PXR_NS::VtValue &attributeValue)

Gets a named attribute of a prim from a named hydra scene delegate.

Parameters

name – should match the name passed to addHydraSceneDelegate
primPath – is the path to the prim containing the attribute
attributeName – name of the attribute
attributeValue – a VtValue to populate with the value of the attribute

Returns

true if successfully accessed the scene delegate, false otherwise

void computeHydraSceneDelegateWorldBoundingBox(const char *name, double *bbox)

Computs a world bounding box for all content in a named hydra scene delegate.

Parameters

name – should match the name passed to addHydraSceneDelegate
bbox – is an array of 12 elements (4 x vector3, min/max bounds, center, size)

bool useFabricSceneDelegate() const

Returns true if the Fabric scene delegate is in use.

This changes behavior in Fabric population, StageReaderWriter copies to the ring buffer, and Fabric USD notice handling

This is the value of the “/app/useFabricSceneDelegate” carb setting when the stage is first loaded, and remains constant until the next stage load to avoid bad behavior with already allocated scene delegates and hydra engines.

bool hasMDLHydraRenderer() const

Checks if any Hydra Renderer supports MDL.

Returns: true if a Hydra renderer supports MDL, false otherwise.

carb::scenerenderer::SceneRenderer *getSceneRenderer() const

Returns the RTX SceneRenderer if a “rtx” hydra engine exists, otherwise nullptr.

Note, tighly coupled with getScene()

[TODO] Remove this API Used for PrimitiveListDrawing Trigger “compile shaders” for F9 MaterialWatcher for getNeurayDbScopeName() Kit.Legacy Editor python bindings for get_current_renderer_status

carb::scenerenderer::Context *getSceneRendererContext() const: Returns the RTX SceneRenderer Context if a “rtx” hydra engine exists, otherwise nullptr.

bool update(float elapsedTime)

Update function to be called once every frame.

Parameters: elapsedTime – Elapsed time in seconds since last update call.
Returns: true if omniverse has new update during this frame.

bool newStage(const OnStageResultFn &resultFn)

Creates a new USD stage.

This is an asynchronous call.

Parameters: fn – the callback function when stage is created or fails to create.

bool newStage()

Synchronous version of.

bool attachStage(long int stageId, const OnStageResultFn &resultFn)

Attaches an opened USD stage.

This is an asynchronous call.

Parameters

stageId – The stage id saved into UsdUtilsStageCache.
fn – The callback function when stage is attached successfully or fails to attach.

bool openStage(const char *fileUrl, const OnStageResultFn &resultFn, UsdContextInitialLoadSet loadSet = UsdContextInitialLoadSet::eLoadAll)

Opens a existing USD stage.

This is an asynchronous call.

Parameters

url – The file path. For Omniverse file, you must connect to Omniverse first and pass the url with prefix “omniverse:”.
fn – The callback function when stage is opened or fails to open.
loadSet – Specifies the initial set of prims to load when opening a UsdStage.

bool openStage(const char *fileUrl, UsdContextInitialLoadSet loadSet = UsdContextInitialLoadSet::eLoadAll)

Synchronous version of.

See also

openStage(const char* fileUrl, const OnStageResultFn& resultFn);

bool reopenStage(const OnStageResultFn &resultFn, UsdContextInitialLoadSet loadSet = UsdContextInitialLoadSet::eLoadAll)

Reopens current USD stage.

This is an asynchronous call.

Parameters: fn – The callback function when stage is reopened or fails to reopen.

bool reopenStage(UsdContextInitialLoadSet loadSet = UsdContextInitialLoadSet::eLoadAll)

Synchronous version of.

See also

reopenStage(const OnStageResultFn& resultFn);

bool closeStage(const OnStageResultFn &resultFn)

Close current USD stage.

This is an asynchronous call.

Parameters: fn – The callback function when stage is closed for fails to close.

bool closeStage()

Synchronous version of.

bool saveLayer(const std::string &layerIdentifier, const OnLayersSavedResultFn &resultFn)

Saves specific layer only.

This is an asynchronous call.

Parameters

layerIdentifier – The layer to save.
fn – The callback function when stage is saved or fails to save.

Returns

true if it’s saved successfully.

bool saveLayer(const std::string &layerIdentifier)

Synchronous version of.

See also

saveLayer(const std::string& layerIdentifier, const OnStageResultFn& resultFn);

bool saveLayers(const std::string &newRootLayerPath, const std::vector<std::string> &layerIdentifiers, const OnLayersSavedResultFn &resultFn)

Saves specific layers only.

This is an asynchronous call.

Parameters

newRootLayerPath – If it’s not empty, it means to do save root layer to new place. This will trigger stage reload to open new root layer.
layerIdentifiers – The layers to save. It will save all dirty changes of them.
fn – The callback function when stage is saved or fails to save.

Returns

true if it’s saved successfully.

bool saveLayers(const std::string &newRootLayerPath, const std::vector<std::string> &layerIdentifiers)

Synchronous version of.

See also

saveLayers

bool saveStage(const OnLayersSavedResultFn &resultFn)

Saves current USD stage.

This is an asynchronous call.

Parameters: fn – The callback function when stage is saved or fails to save.

bool saveStage()

Synchronous version of.

See also

saveStage(const OnStageResultFn& resultFn);

bool saveAsStage(const char *url, const OnLayersSavedResultFn &resultFn)

Saves current USD stage to a different location.

This is an asynchronous call.

Parameters

url – The new location to save the USD stage.
fn – The callback function when stage is saved or fails to save.

bool saveAsStage(const char *url)

Synchronous version of.

See also

saveAsStage(const char* url, const OnStageResultFn& resultFn);

bool exportAsStage(const char *url, const OnStageResultFn &resultFn) const

Exports current USD stage to a different location.

This is an asynchronous call. It will composite current stage into a single flattened layer.

Parameters

url – The new location to save the USD stage.
fn – The callback function when stage is saved or fails to save.

bool exportAsStage(const char *url) const

Synchronous version of.

bool isNewStage() const

Checks if currently opened stage is created by calling newStage.

Returns: true if current stage is a new stage.

bool canCloseStage() const

Checks if it’s safe to close stage at calling time.

Returns: true if it is safe to close the stage (when current stage is fully opened). false if it’s unsafe to close current stage (when current stage is still being opened or closed).

bool canSaveStage() const

Checks if a USD stage is opened and in a savable stage (not opening/closing in progress).

Returns: true if the stage is opened and savable, false is no stage is opened or opened stage is not savable.

bool canOpenStage() const

Checks if it’s safe to open a different stage at calling time.

Returns: true if it is safe to open a different stage (when current stage is fully opened or closed). false if it’s unsafe to open different stage (when current stage is still being opened or closed).

bool isWritable() const

Checks if there is enough permissions to save the stage at calling time.

Returns: true if it is possible to save the stage. false if it’s not possible to save current stage.

omni::usd::StageState getStageState() const

Gets the state of current stage.

Returns: state of current stage.

PXR_NS::UsdStageWeakPtr getStage() const

Gets UsdStage.

Returns: UsdStageWeakPtr of current stage.

long int getStageId() const

Gets UsdStage id.

Returns: id of current stage.

const std::string &getStageUrl() const

Gets the url of current stage.

Returns: url of current stage.

bool hasPendingEdit() const

Checks if current stage is dirty.

Returns: true if current stage is dirty.

void setPendingEdit(bool edit)

Marks the edits state of current opened stage.

It means changes are pending to be saved if you set it to true, or false otherwise. This will disgard the real state of opened stage. For example, if the opened stage has real changes to be saved, hasPendingEdit() will still return false if you set it to false.

Parameters: edit – true to set pending edits state, false to unset pending edits state

carb::events::IEventStreamPtr getStageEventStream()

Gets the carb::events::IEventStreamPtr for StageEvent.

Returns: the carb::events::IEventStream for StageEvent.

carb::events::IEventStreamPtr getRenderingEventStream()

Gets the carb::events::IEventStreamPtr for RenderingEvent.

Returns: the carb::events::IEventStream for RenderingEvent.

void sendEvent(carb::events::IEventPtr &event, bool blockingAsync = false)

Sends a StageEvent to UsdStageEvent stream.

It chooses to send event sync/async based on syncUsdLoads option.

Parameters

event – The event to be sent.
blockingAsync – If the event is sent as async, true to wait on the event until it has been processed by all subscribers. false to return immediately.

bool isOmniStage() const

Gets if the current stage is opened from Omniverse.

Returns: true if the stage is opened from Omniverse.

void saveRenderSettingsToCurrentStage(): Saves render settings to current opened USD stage.

void loadRenderSettingsFromStage(long int stageId)

Loads render settings from stage.

Parameters: stageId – The stage id saved into UsdUtilsStageCache.

bool getPickedWorldPos(ViewportHandle handle, carb::Double3 &outWorldPos)

Gets the picked position in world space since last picking request.

Parameters: outWorldPos – The picked world space position.
Returns: true if the result is valid, false if result is not valid.

bool getPickedGeometryHit(ViewportHandle handle, carb::Double3 &outWorldPos, carb::Float3 &outNormal)

Gets the picked geometry hit data - position in world space and normal since last picking request.

Parameters

outWorldPos – The picked world space position.
outNormal – The picked normal.

Returns

true if the result is valid, false if result is not valid.

PXR_NS::GfRange3d computePrimWorldBoundingBox(const pxr::UsdPrim &prim)

Gets the AABB of a prim.

Parameters: prim – The prim to get AABB from.
Returns: The AABB of the prim.

void computePathWorldBoundingBox(const std::string &path, carb::Double3 &aabbMin, carb::Double3 &aabbMax)

Gets the AABB of a path as carb::Doubles3 (primarily for Python).

Parameters

path – The path to get AABB from.
aabbMin – Where to store the min-extents.
aabbMax – Where to store the max-extents.

PXR_NS::GfMatrix4d computePrimWorldTransform(const pxr::UsdPrim &prim)

Gets the GfMatrix4 of a prim as stored in the current bbox cache.

Parameters: prim – The prim to get the transform of.
Returns: The world-space GfMatrix4 of the prim.

void computePrimWorldTransform(const std::string &path, std::array<double, 16> &flattened)

Gets the GfMatrix4 of a path as stored in the current bbox cache.

Parameters: path – The path to a prim to get the transform of.
Returns: The world-space GfMatrix4 of the prim at the path.

void getStageLoadingStatus(std::string &message, int32_t &filesLoaded, int32_t &totalFiles)

Gets the stage loading status.

Parameters

The – message of current stage loading.
filesLoaded – Number of files already loaded.
totalFiles – Total number of files to be loaded.

void getRenderablePaths(PXR_NS::SdfPath primPath, SdfPathUSet &unOrderedRenderablePathSet)

Returns all renderable paths for given prim path and its descendatns.

Renderable paths are prims of type instancer or geometry.

Parameters

primPath – Prim path
renderablePathSet – An unordered output path set.

template<typename T> void getRenderablePaths(PXR_NS::SdfPath primPath, T &renderablePathSet)

Returns all renderable paths for given prim path and its descendatns.

Renderable paths are prims of type instancer or geometry.

Parameters

primPath – Prim path
renderablePathSet – An ordered output path set.

void setPickable(const char *primPath, bool isPickable)

Sets the mouse pickable state of a prim.

Parameters

primPath – The path of the prim to set pickable state.
isPickable – true if to set the prim to be pickable, false to set to unpickable.

carb::scenerenderer::SceneId getRendererScene()

Returns the SceneId from the RTX SceneRenderer if a “rtx” hydra engine exists.

Note, usage coupled with getSceneRenderer()

Returns: carb::scenerenderer::SceneId of current scene.

void stopAsyncRendering()

Stops all async hydra rendering.

Waits for completion of in-flight tasks then requests RunLoops for rendering to exit

void enableUsdWrites(bool enabled)

Currently writing to usd during async rendering can cause a data race.

This necessitates the prescence of certain mutex to protect usd data access. This call controls the usage of this mutex and will block until it is safe to begin writes.

If a usd write occurs while this is disabled, undefined behavior is likely.

Can only be called from the main thread for safety reasons.

Note

This function is deprecated.

Parameters: enabled – if true enables the usage of a mutex to protect usd write operations.

void enableUsdLocking()

USD is a global shared resource.

Invoking enableUsdLocking() lets UsdContext manage the locking of this resource.

enableUsdLocking will lock() the resource and manage locking/unlocking going forward

disableUsdLokcing() will unlock() the resource and make no subsequent lock/unlock calls

WARNING: enableUsdLocking and disableUsdLocking will only work when called from the main thread.

void disableUsdLocking()

bool isUsdLockingEnabled()

bool usdWritesEnabled()

Returns the status of usd write back.

If not true, writing to usd may cause undefined behavior.

Note

This function is deprecated.

Returns: true if write back is enabled and false otherwise.

ViewportHandle createViewport(const char *hydraEngine, uint32_t tickrate, omni::usd::hydra::EngineCreationFlags hydraEngineFlags)

Creates a new ViewportHandle for the hydraEngine at the specified tick rate A tickrate of -1 means “render as fast as possible”.

Will not create a new HydraEngine, a HydraEngine must be available. HydraEngines are added by addHydraEngine()

Returns: ViewportHandle that’s used in addRender(), getRenderResults(), destroyViewport()

void destroyViewport(ViewportHandle viewportHandle): Destroys the ViewportHandle that was created in createViewport then requests RunLoops for rendering to exit.

const omni::usd::hydra::ViewportHydraRenderResults *getRenderResults(ViewportHandle viewportHandle, bool bBlock = false)

Returns the latest available rendering result.

It is assumed main/simulation thread runs at the same rate or faster than hydra engine tick rate. If you query the FPS of the returned value, it will match the hydra engine render rate

bBlock == true will trigger hydraRendering() + checkForHydraResults() outside of defined update order in omni::kit::update::UpdateOrderings if necessary

Returns: ViewportHydraRenderResults the latest available hydra render result

void addRender(ViewportHandle handle, omni::usd::PathH renderProductPrimPath, const Picking *picking = nullptr): The ViewportHandle and the RenderProduct USD Prim Path to render.

Selection *getSelection(): Gets Selection instance.

const Selection *getSelection() const: Gets const Selection instance.

audio::AudioManager *getAudioManager() const

Retrieves the stage audio manager for use in the IStageAudio interface.

Returns: The USD context’s stage audio manager instance. This is valid until the USD context is destroyed.
Returns: nullptr if the stage audio manager was not loaded or failed to load.

void enableSaveToRecentFiles()

void disableSaveToRecentFiles()

void toggleAutoUpdate(bool enabled)

By default UsdContext subscribes to IApp for updates.

That can be disabled. Temp function until we refactor Editor.cpp

size_t GetGeometryInstanceId(const PXR_NS::SdfPath &path, uint32_t *instanceList): Query for instance IDs that are returned to synthetic data.

size_t GetGeometryId(const PXR_NS::SdfPath &path, uint32_t *geometryList): Query for geometry IDs that are returned to synthetic data.

const std::string &GetGeometryInstancePath(uint32_t instanceId): Query for mesh instance path that is returned to synthetic data.

const std::string &GetGeometryPath(uint32_t geometryId): Query for mesh geometry path that is returned to synthetic data.

bool addToPendingCreatingMdlPaths(const std::string &path, bool recreate = false, bool loadInputs = true)

Adds path to material/shader loading queue.

Parameters

path – the path of UsdShadeShader to create MDL materials.
recreate – If to force recreating the inputs if it’s already populated
loadInputs – If to create MDL inputs as UsdAttribute on the UsdShadeShader prim.

Returns

true if scheduled successfully, false if inputs are already created and recreate is false.

uint32_t getGizmoUID(const PXR_NS::SdfPath &path)

Get unique gizmo id.

When it not needed freeGizmoUID should be called so that it can be reused. If it is not called this method return the same uid on next call with given path.

Parameters: path – Prim path that will be used for prim selection when gizmo uid is picked.

void freeGizmoUID(uint32_t uid)

Allows to notify that gizmo uid is no longer used.

Parameters: uid – Gizmo unique id.

const PXR_NS::SdfPath *getPathForGizmoUID(uint32_t uid)

Returns prim path for given gizmo uid.

Parameters: uid – Gizmo unique id.
Returns: A pointer to path for given uid or nullptr for invalid uid.

uint8_t registerSelectionGroup()

Register selection group.

Note: Supposed that this function called once at app initialization.

void setSelectionGroupOutlineColor(uint8_t groupId, const carb::Float4 &color): Setup selection group outline color.

void setSelectionGroupShadeColor(uint8_t groupId, const carb::Float4 &color): Setup selection group shade color.

void setSelectionGroup(uint8_t groupId, const std::string &path): Set selection group for specified primitives path.

omni::usd::hydra::CameraSettings getCameraSettings(const PXR_NS::SdfPath &path, double aspectRatio): Query for camera settings for the camera prim.

void setCameraWindowPolicy(carb::scenerenderer::CameraFit policy): Set the aperture fit policy.

void getFrameData(carb::renderer::FrameDataType dataType, uint32_t deviceIndex, void **data, size_t *dataSize, uint32_t engineIndex = -1)

Returns the current frame data based on the requested feature, such as profiler data.

If frame is not finished processing the data, the result of the previous frame is returned. For multi-GPU, query the device count and then set deviceIndex to the desired device index.

Parameters

dataType – Specified the requested data type to return.
deviceIndex – The index of GPU device to get the frame data from. Set to zero in Single-GPU mode. You may query the number of devices with FrameDataType::eGpuProfilerDeviceCount. deviceIndex is ignored when the type is set to eGpuProfilerDeviceCount.
data – A pointer to the returned data. Returns nullptr for failures or eGpuProfilerDeviceCount. You may pass nullptr if you only need dataSize.
dataSize – The size of the returned data in bytes, the number of structures, or device count based on the dataType. For strings, it includes the null-termination.
engineIndex – The index of an attached HydraEngine or -1 for the -active- HydraEngine.

size_t getAttachedHydraEngineCount() const

const char *getAttachedHydraEngineName(size_t hydraEngineIdx) const

HydraEngineDesc getHydraEngineDesc(ViewportHandle handle) const

void registerViewOverrideToHydraEngines(omni::usd::hydra::IViewOverrideBase *viewOverride): Allow for viewoverrides to be added through the usd context.

void unregisterViewOverrideToHydraEngines(omni::usd::hydra::IViewOverrideBase *viewOverride): Allow for viewoverrides to be removed through the usd context.

void setUsdContextSchedulingOverride(IUsdContextSchedulingOverride *schedulingOverride): Allow scheduling override to be set for usd context.

void resetUsdContextSchedulingOverride(): Reset scheduling override.

IUsdMutex &getMutex(): Retrieves the mutex for *this

void stopAllPickingForView(ViewPickingId pickingId): Stop any picking in flight for a specific View.

void setTimeline(const std::string &name = "")

Sets the timeline.

This must be called before the context is used, right after its creation.

std::string getTimelineName() const: Retrieves the name of the timeline.

timeline::TimelinePtr getTimeline() const: Retrieves the timeline.

std::string getName() const: Retrieves the name of the context.

int32_t getOrCreateRunloopThread(const char *name, const hydra::EngineCreationConfig &engineConfig, bool setWarmup): Trigger creation of the runloop associated with the given hydraengine configuration (otherwise it will only be created the first time an associated viewport is renderer)

bool openStageWithSessionLayer(const char *fileUrl, const char *sessionLayerUrl, const OnStageResultFn &resultFn, UsdContextInitialLoadSet loadSet = UsdContextInitialLoadSet::eLoadAll)

void tryCancelSave()

Public Static Functions

static UsdContext *getContext(const std::string &name = "")

Gets a UsdContext.

Parameters: name – of the UsdContext to get. The default context is named with empty string “”.

static bool getEngineWarmupConfig(const carb::settings::ISettings &settings, const char *hydraEngineName, EngineWarmupConfig &config)

static hydra::EngineCreationConfig getDefaultEngineCreationConfig(const carb::settings::ISettings &settings, const char *engineName, uint32_t engineIndex): Return the default config for hydraengine creation for this engine type, and index.