Add default render settings prim path sections

code/core/elements.py

@@ -1030,8 +1030,25 @@ def "cube" (
 attr_spec.SetInfo("custom", True)
 #// ANCHOR_END: metadataCustom
 
-#// ANCHOR: metadataLayerMetrics
+# // ANCHOR: metadataRenderSettingsPrimPath
+### High Level ###
+from pxr import Usd
+
+stage = Usd.Stage.CreateInMemory()
+stage.GetRootLayer().pseudoRoot.SetInfo(
+    "renderSettingsPrimPath", "/Render/rendersettings"
+)
+### Low Level ###
+from pxr import Sdf
+
+layer = Sdf.Layer.CreateAnonymous()
+layer.pseudoRoot.SetInfo("renderSettingsPrimPath", "/Render/rendersettings")
+# // ANCHOR_END: metadataRenderSettingsPrimPath
+
+
+# // ANCHOR: metadataLayerMetrics
 from pxr import Sdf, Usd, UsdGeom
+
 ### High Level ###
 stage = Usd.Stage.CreateInMemory()
 prim_path = Sdf.Path("/bicycle")
@@ -1050,10 +1067,11 @@ def "cube" (
 UsdGeom.SetStageMetersPerUnit(stage, UsdGeom.LinearUnits.centimeters)
 # To map 24 fps (default) to 25 fps we have scale by 24/25 when loading the layer in the Sdf.LayerOffset
 # Scene Up Axis
-UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.y) # Or  UsdGeom.Tokens.z
+UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.y)  # Or  UsdGeom.Tokens.z
 
 ### Low Level ###
 from pxr import Sdf
+
 layer = Sdf.Layer.CreateAnonymous()
 prim_path = Sdf.Path("/bicycle")
 prim_spec = Sdf.CreatePrimInLayer(layer, prim_path)
@@ -1071,8 +1089,10 @@ def "cube" (
 # Scene Unit Scale
 layer.pseudoRoot.SetInfo(UsdGeom.Tokens.metersPerUnit, UsdGeom.LinearUnits.centimeters)
 # Scene Up Axis
-layer.pseudoRoot.SetInfo(UsdGeom.Tokens.upAxis, UsdGeom.Tokens.y) # Or  UsdGeom.Tokens.z
-#// ANCHOR_END: metadataLayerMetrics
+layer.pseudoRoot.SetInfo(
+    UsdGeom.Tokens.upAxis, UsdGeom.Tokens.y
+)  # Or  UsdGeom.Tokens.z
+# // ANCHOR_END: metadataLayerMetrics
 
 #// ANCHOR: debuggingTokens
 from pxr import Tf
@@ -3691,7 +3711,7 @@ def traversal_kernel(path):
 layer = stage.GetRootLayer()
 metadata = layer.customLayerData
 metadata["myCustomRootData"] = 1
-layer.metadata = metadata
+layer.customLayerData = metadata
 # As with layers, we can also set the default prim
 stage.SetDefaultPrim(bicycle_prim)
 # Is the same as:

docs/src/core/elements/layer.md

@@ -18,13 +18,14 @@ Layers and stages are the main entry point to accessing our data stored in USD.
     1. [Traversal and Prim/Property Access](#layerTraversal)
     1. [Time Samples](#layerTimeSamples)
     1. [Metadata](#layerMetadata)
-1. [Stages](#exampleA)
+1. [Stages](#stageOverview)
     1. [Configuration](#stageConfiguration)
         1. [Asset Resolver](#stageAssetResolver)
         1. [Stage Metrics](#stageMetrics)
         1. [Stage Time Sample Interpolation](#stageTimeSampleInterpolation)
         1. [Variant/Prim Type Fallbacks](#stageFallbacks)
         1. [Color Management](#stageColormanagement)
+        1. [Default Render Settings](#stageRenderSettingsDefault)
         1. [Metadata](#stageMetadata)
     1. [Composition](#stageComposition)
     1. [Loading mechanisms ](#stageLoadingMechanisms)
@@ -384,6 +385,13 @@ This sub-section is still under development, it is subject to change and needs e
 ```
 ~~~
 
+#### Default Render Settings <a name="stageRenderSettingsDefault"></a>
+
+We can supply a render settings prim path on our root layer that can be used as a default by applications.
+
+See our [Metadata](./metadata.md#metadataRenderSettingsPrimPath) section for more information.
+
+
 #### Metadata <a name="stageMetadata"></a>
 Setting metadata on the stage, redirects the edits to the root layer.
 We discuss this in detail in our [metadata section](./metadata.md).

docs/src/core/elements/metadata.md

@@ -26,8 +26,9 @@ Metadata is the smallest building block in Usd. It is part of the base class fro
         1. [Support for animation (USD speak **variability**)](#metadataVariability)
         1. [Custom vs schema defined properties](#metadataCustom)
     1. [Special metadata fields for layers and stages](#metadataLayerStage)
-        1. [Reading/writing stage and layer metrics (FPS/Scene Unit Scale/Up Axis) (High/Low level API)](#metadataMetricsLayer)
-        2. [Reading/writing stage and layer customData metadata (High/Low level API)](#metadataCustomDataLayer)
+        1. [Stage/Root Layer Default Render Settings (High/Low level API)](#metadataRenderSettingsPrimPath)
+        1. [Stage and layer metrics (FPS/Scene Unit Scale/Up Axis) (High/Low level API)](#metadataMetricsLayer)
+        1. [Stage and layer customData metadata (High/Low level API)](#metadataCustomDataLayer)
 
 
 ## TL;DR - Metadata In-A-Nutshell <a name="summary"></a>
@@ -269,7 +270,22 @@ With the lower level API, we have to mark it ourselves.
 ### Special metadata fields for layers and stages <a name="metadataLayerStage"></a>
 For stages (root layer/session layer) and layers, we can also write a few special fields as covered below.
 
-#### Reading/writing stage and layer metrics (FPS/Scene Unit Scale/Up Axis) (High/Low level API) <a name="metadataMetricsLayer"></a>
+#### Stage/Root Layer Default Render Settings (High/Low level API) <a name="metadataRenderSettingsPrimPath"></a>
+
+We can supply a default render settings prim path on our root layer. This will be used in DCCs as the default render settings to drive Hydra rendering.
+
+~~~admonish info title=""
+```python
+{{#include ../../../../code/core/elements.py:metadataRenderSettingsPrimPath}}
+```
+~~~
+
+For example in Houdini we can then see it marked with the "Default" prefix in our viewport display options.
+
+![Houdini Viewport Display Options - Default Render Settings](metadataRenderSettingsPrimPath.jpg)
+
+
+#### Stage and layer metrics (FPS/Scene Unit Scale/Up Axis) (High/Low level API) <a name="metadataMetricsLayer"></a>
 
 For more info about the FPS, see our [animation](./animation.md#frames-per-second) section.
 
@@ -279,14 +295,13 @@ The default scene `metersPerUnit` value is centimeters (0.01) and the default `u
 
 See [Scene Up Axis API Docs](https://openusd.org/dev/api/group___usd_geom_up_axis__group.html) and [Scene Unit API Docs](https://openusd.org/dev/api/group___usd_geom_linear_units__group.html) for more info.
 
-
 ~~~admonish info title=""
 ```python
 {{#include ../../../../code/core/elements.py:metadataLayerMetrics}}
 ```
 ~~~
 
-#### Reading/writing stage and layer customData metadata (High/Low level API) <a name="metadataCustomDataLayer"></a>
+#### Stage and layer customData metadata (High/Low level API) <a name="metadataCustomDataLayer"></a>
 ~~~admonish tip
 This is often used to track pipeline relevant data in DCCs. For node based DCCs, this is a convenient way to pass general data down through the node network. For layer based DCCs, this can be used to tag layers (for example to anonymous layers that carry specific pipeline data).
 ~~~