core

Fully qualified name: usdex::core

namespace core

usdex::core provides higher-level convenience functions on top of lower-level OpenUSD concepts, so developers can quickly adopt OpenUSD best practices when mapping their native data sources to OpenUSD-legible data models.

Classes

PrimvarData

A templated read-only class to manage the components of UsdGeomPrimvar data as a single object without risk of detaching (copying) arrays.

ValidChildNameCache

A caching mechanism for valid and unique child prim names.

Enumerations

ColorSpace

Texture color space (encoding) types.

DiagnosticsLevel

Controls the diagnostics that will be emitted when the Delegate is active.

DiagnosticsOutputStream

Control the output stream to which diagnostics are logged.

RotationOrder

Enumerates the rotation order of the 3-angle Euler rotation.

Functions

void activateDiagnosticsDelegate()

Activates the Delegate to specialize TfDiagnostics handling.

bool addDiffuseTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a diffuse texture to a preview material.

bool addMetallicTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel metallic texture to a preview material.

bool addNormalTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a normals texture to a preview material.

bool addOpacityTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel opacity texture to a preview material.

bool addOrmTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds an ORM (occlusion, roughness, metallic) texture to a preview material.

bool addPreviewMaterialInterface(pxr::UsdShadeMaterial &material)

Adds UsdShadeInputs to the material prim to create an "interface" to the underlying Preview Shader network.

bool addRoughnessTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel roughness texture to a preview material.

bool bindMaterial(pxr::UsdPrim prim, const pxr::UsdShadeMaterial &material)

Authors a direct binding to the given material on this prim.

bool blockDisplayName(pxr::UsdPrim prim)

Block this prim's display name (metadata)

bool clearDisplayName(pxr::UsdPrim prim)

Clears this prim's display name (metadata) in the current EditTarget (only)

std::string computeEffectiveDisplayName(const pxr::UsdPrim &prim)

Calculate the effective display name of this prim.

pxr::UsdShadeShader computeEffectivePreviewSurfaceShader(const pxr::UsdShadeMaterial &material)

Get the effective surface Shader of a Material for the universal render context.

bool configureStage(pxr::UsdStagePtr stage, const std::string &defaultPrimName, const pxr::TfToken &upAxis, const double linearUnits, std::optional< std::string_view > authoringMetadata=std::nullopt)

Configure a stage so that the defining metadata is explicitly authored.

pxr::UsdShadeMaterial createMaterial(pxr::UsdPrim parent, const std::string &name)

Create a UsdShadeMaterial as a child of the Prim parent.

pxr::UsdStageRefPtr createStage(const std::string &identifier, const std::string &defaultPrimName, const pxr::TfToken &upAxis, const double linearUnits, const std::string &authoringMetadata, const pxr::SdfLayer::FileFormatArguments &fileFormatArgs=pxr::SdfLayer::FileFormatArguments())

Create and configure a UsdStage so that the defining metadata is explicitly authored.

void deactivateDiagnosticsDelegate()

Deactivates the Delegate to restore default TfDiagnostics handling.

pxr::UsdGeomCamera defineCamera(pxr::UsdPrim parent, const std::string &name, const pxr::GfCamera &cameraData)

Defines a basic 3d camera on the stage.

pxr::UsdGeomCamera defineCamera(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::GfCamera &cameraData)

Defines a basic 3d camera on the stage.

pxr::UsdGeomBasisCurves defineCubicBasisCurves(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::VtIntArray &curveVertexCounts, const pxr::VtVec3fArray &points, const pxr::TfToken &basis=pxr::UsdGeomTokens->bezier, const pxr::TfToken &wrap=pxr::UsdGeomTokens->nonperiodic, std::optional< const FloatPrimvarData > widths=std::nullopt, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a batched Cubic UsdGeomBasisCurves prim on the stage.

pxr::UsdGeomBasisCurves defineCubicBasisCurves(pxr::UsdPrim parent, const std::string &name, const pxr::VtIntArray &curveVertexCounts, const pxr::VtVec3fArray &points, const pxr::TfToken &basis=pxr::UsdGeomTokens->bezier, const pxr::TfToken &wrap=pxr::UsdGeomTokens->nonperiodic, std::optional< const FloatPrimvarData > widths=std::nullopt, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a batched Cubic UsdGeomBasisCurves prim on the stage.

pxr::UsdLuxDomeLight defineDomeLight(pxr::UsdPrim parent, const std::string &name, float intensity=1.0f, std::optional< std::string_view > texturePath=std::nullopt, const pxr::TfToken &textureFormat=pxr::UsdLuxTokens->automatic)

Creates a dome light with an optional texture.

pxr::UsdLuxDomeLight defineDomeLight(pxr::UsdStagePtr stage, const pxr::SdfPath &path, float intensity=1.0f, std::optional< std::string_view > texturePath=std::nullopt, const pxr::TfToken &textureFormat=pxr::UsdLuxTokens->automatic)

Creates a dome light with an optional texture.

pxr::UsdGeomBasisCurves defineLinearBasisCurves(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::VtIntArray &curveVertexCounts, const pxr::VtVec3fArray &points, const pxr::TfToken &wrap=pxr::UsdGeomTokens->nonperiodic, std::optional< const FloatPrimvarData > widths=std::nullopt, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a batched Linear UsdGeomBasisCurves prim on the stage.

pxr::UsdGeomBasisCurves defineLinearBasisCurves(pxr::UsdPrim parent, const std::string &name, const pxr::VtIntArray &curveVertexCounts, const pxr::VtVec3fArray &points, const pxr::TfToken &wrap=pxr::UsdGeomTokens->nonperiodic, std::optional< const FloatPrimvarData > widths=std::nullopt, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a batched Linear UsdGeomBasisCurves prim on the stage.

pxr::UsdGeomPoints definePointCloud(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::VtVec3fArray &points, std::optional< const pxr::VtInt64Array > ids=std::nullopt, std::optional< const FloatPrimvarData > widths=std::nullopt, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a UsdGeomPoints prim on the stage.

pxr::UsdGeomPoints definePointCloud(pxr::UsdPrim parent, const std::string &name, const pxr::VtVec3fArray &points, std::optional< const pxr::VtInt64Array > ids=std::nullopt, std::optional< const FloatPrimvarData > widths=std::nullopt, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a UsdGeomPoints prim on the stage.

pxr::UsdGeomMesh definePolyMesh(pxr::UsdPrim parent, const std::string &name, const pxr::VtIntArray &faceVertexCounts, const pxr::VtIntArray &faceVertexIndices, const pxr::VtVec3fArray &points, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec2fPrimvarData > uvs=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a basic polygon mesh on the stage.

pxr::UsdGeomMesh definePolyMesh(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::VtIntArray &faceVertexCounts, const pxr::VtIntArray &faceVertexIndices, const pxr::VtVec3fArray &points, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec2fPrimvarData > uvs=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a basic polygon mesh on the stage.

pxr::UsdShadeMaterial definePreviewMaterial(pxr::UsdPrim parent, const std::string &name, const pxr::GfVec3f &color, const float opacity=1.0f, const float roughness=0.5f, const float metallic=0.0f)

Defines a PBR UsdShadeMaterial driven by a UsdPreviewSurface shader network for the universal render context.

pxr::UsdShadeMaterial definePreviewMaterial(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::GfVec3f &color, const float opacity=1.0f, const float roughness=0.5f, const float metallic=0.0f)

Defines a PBR UsdShadeMaterial driven by a UsdPreviewSurface shader network for the universal render context.

pxr::UsdLuxRectLight defineRectLight(pxr::UsdStagePtr stage, const pxr::SdfPath &path, float width, float height, float intensity=1.0f, std::optional< std::string_view > texturePath=std::nullopt)

Creates a rectangular (rect) light with an optional texture.

pxr::UsdLuxRectLight defineRectLight(pxr::UsdPrim parent, const std::string &name, float width, float height, float intensity=1.0f, std::optional< std::string_view > texturePath=std::nullopt)

Creates a rectangular (rect) light with an optional texture.

pxr::UsdGeomXform defineXform(pxr::UsdStagePtr stage, const pxr::SdfPath &path, std::optional< const pxr::GfTransform > transform=std::nullopt)

Defines an xform on the stage.

pxr::UsdGeomXform defineXform(pxr::UsdPrim parent, const std::string &name, std::optional< const pxr::GfTransform > transform=std::nullopt)

Defines an xform on the stage.

bool exportLayer(pxr::SdfLayerHandle layer, const std::string &identifier, const std::string &authoringMetadata, std::optional< std::string_view > comment=std::nullopt, const pxr::SdfLayer::FileFormatArguments &fileFormatArgs=pxr::SdfLayer::FileFormatArguments())

Export the given SdfLayer to an identifier with an optional comment.

const pxr::TfToken & getColorSpaceToken(ColorSpace value)

Get the TfToken matching a given ColorSpace

DiagnosticsLevel getDiagnosticsLevel()

Get the current DiagnosticsLevel for the Delegate .

DiagnosticsOutputStream getDiagnosticsOutputStream()

Get the current DiagnosticsOutputStream for the Delegate .

std::string getDisplayName(const pxr::UsdPrim &prim)

Return this prim's display name (metadata)

pxr::UsdAttribute getLightAttr(const pxr::UsdAttribute &defaultAttr)

Get the "correct" light attribute for a light that could have any combination of authored old and new UsdLux schema attributes.

pxr::GfTransform getLocalTransform(const pxr::UsdPrim &prim, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of a prim at a given time.

void getLocalTransformComponents(const pxr::UsdPrim &prim, pxr::GfVec3d &translation, pxr::GfVec3d &pivot, pxr::GfVec3f &rotation, RotationOrder &rotationOrder, pxr::GfVec3f &scale, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of a prim at a given time in the form of common transform components.

pxr::GfMatrix4d getLocalTransformMatrix(const pxr::UsdPrim &prim, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Get the local transform of a prim at a given time in the form of a 4x4 matrix.

pxr::TfToken getValidChildName(const pxr::UsdPrim &prim, const std::string &name)

Take a prim and a preferred name. Return a valid and unique name as the child name of the given prim.

pxr::TfTokenVector getValidChildNames(const pxr::UsdPrim &prim, const std::vector< std::string > &names)

Take a prim and a vector of the preferred names. Return a matching vector of valid and unique names as the child names of the given prim.

pxr::TfToken getValidPrimName(const std::string &name)

Produce a valid prim name from the input name.

pxr::TfTokenVector getValidPrimNames(const std::vector< std::string > &names, const pxr::TfTokenVector &reservedNames={})

Take a vector of the preferred names and return a matching vector of valid and unique names.

pxr::TfToken getValidPropertyName(const std::string &name)

Produce a valid property name using the Bootstring algorithm.

pxr::TfTokenVector getValidPropertyNames(const std::vector< std::string > &names, const pxr::TfTokenVector &reservedNames={})

Take a vector of the preferred names and return a matching vector of valid and unique names.

bool hasLayerAuthoringMetadata(pxr::SdfLayerHandle layer)

Check if the SdfLayer has metadata indicating the provenance of the data.

bool isDiagnosticsDelegateActive()

Test whether the Delegate is currently active.

bool isEditablePrimLocation(const pxr::UsdPrim &prim, const std::string &name, std::string *reason)

Validate that prim opinions could be authored for a child prim with the given name.

bool isEditablePrimLocation(const pxr::UsdStagePtr stage, const pxr::SdfPath &path, std::string *reason)

Validate that prim opinions could be authored at this path on the stage.

bool isLight(const pxr::UsdPrim &prim)

Determines if a UsdPrim has a UsdLuxLightAPI schema applied.

pxr::GfVec3f linearToSrgb(const pxr::GfVec3f &color)

Translate a linear color value to sRGB color space.

bool removeMaterialInterface(pxr::UsdShadeMaterial &material, bool bakeValues=true)

Removes any UsdShadeInputs found on the material prim.

pxr::GfVec3f sRgbToLinear(const pxr::GfVec3f &color)

Translate an sRGB color value to linear color space.

bool saveLayer(pxr::SdfLayerHandle layer, std::optional< std::string_view > authoringMetadata=std::nullopt, std::optional< std::string_view > comment=std::nullopt)

Save the given SdfLayer with an optional comment.

void saveStage(pxr::UsdStagePtr stage, std::optional< std::string_view > authoringMetadata=std::nullopt, std::optional< std::string_view > comment=std::nullopt)

Save the given UsdStage with metadata applied to all dirty layers.

void setDiagnosticsLevel(DiagnosticsLevel value)

Set the DiagnosticsLevel for the Delegate to filter TfDiagnostics by severity.

void setDiagnosticsOutputStream(DiagnosticsOutputStream value)

Set the DiagnosticsOutputStream for the Delegate to redirect TfDiagnostics to different streams.

bool setDisplayName(pxr::UsdPrim prim, const std::string &name)

Sets this prim's display name (metadata).

void setLayerAuthoringMetadata(pxr::SdfLayerHandle layer, const std::string &value)

Set metadata on the SdfLayer indicating the provenance of the data.

bool setLocalTransform(pxr::UsdPrim prim, const pxr::GfMatrix4d &matrix, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of a prim from a 4x4 matrix.

bool setLocalTransform(pxr::UsdPrim prim, const pxr::GfVec3d &translation, const pxr::GfVec3d &pivot, const pxr::GfVec3f &rotation, const RotationOrder rotationOrder, const pxr::GfVec3f &scale, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of a prim from common transform components.

bool setLocalTransform(pxr::UsdPrim prim, const pxr::GfTransform &transform, pxr::UsdTimeCode time=pxr::UsdTimeCode::Default())

Set the local transform of a prim.

const char * version()

Verify the expected usdex modules are being loaded at runtime.

bool withPython()

Verify whether Python support is available.

Typedefs

FloatPrimvarData

An alias for PrimvarData that holds VtFloatArray values (e.g widths or scale factors).

Int64PrimvarData

An alias for PrimvarData that holds VtInt64Array values (e.g ids that might be very large).

IntPrimvarData

An alias for PrimvarData that holds VtIntArray values (e.g simple switch values or booleans consumable by shaders).

StringPrimvarData

An alias for PrimvarData that holds VtStringArray values (e.g human readable descriptors).

TokenPrimvarData

An alias for PrimvarData that holds VtTokenArray values (e.g more efficient human readable descriptors).

Vec2fPrimvarData

An alias for PrimvarData that holds VtVec2fArray values (e.g texture coordinates).

Vec3fPrimvarData

An alias for PrimvarData that holds VtVec3fArray values (e.g normals, colors, or other vectors).

Variables

pxr::TfEnvSetting< bool > USDEX_ENABLE_OMNI_TRANSCODING

Set the USDEX_ENABLE_OMNI_TRANSCODING environment variable to enable/disable the use of omni_transcoding within getValidPrimName(s) , getValidChildName(s) , and getValidPropertyName(s) . Defaults true (transcoding is enabled).