Add trace functions in the render delegate hot spots by cpichard · Pull Request #2616 · Autodesk/arnold-usd

cpichard · 2026-04-08T10:14:13Z

Changes proposed in this pull request

Add usd and arnold trace functions

Issues fixed in this pull request
Fixes #2588

autodesk-chorus · 2026-04-30T14:49:23Z

Chorus detected one or more security issues with this pull request. See the Checks tab for more details.

As a reminder, please follow the secure code review process as part of the Secure Coding Non-Negotiable requirement.

Copilot

Pull request overview

This PR adds USD Trace instrumentation to key Hydra render delegate hot paths and introduces an RAII helper to enable/emit a trace report for USD procedural reads, addressing profiling needs from #2588.

Changes:

Add TRACE_FUNCTION() and targeted TRACE_SCOPE() markers across render delegate sync hotspots (plus Arnold AiProfileBlock labels).
Introduce ArnoldUsdTraceDiagnostic (env-var gated) to enable USD trace collection and flush a timing report to the Arnold log.
Add build options/plumbing (ENABLE_TRACING) intended to control trace instrumentation.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
libs/render_delegate/volume.cpp	Adds trace/profiling markers in `HdArnoldVolume::Sync`.
libs/render_delegate/shape.cpp	Adds trace/profiling markers in `HdArnoldShape::Sync`.
libs/render_delegate/reader.cpp	Adds function + scoped tracing around major stage read/sync phases.
libs/render_delegate/node_graph.cpp	Adds trace/profiling markers in NodeGraph sync/material network translation.
libs/render_delegate/mesh.cpp	Adds trace/profiling markers in `HdArnoldMesh::Sync`.
libs/render_delegate/light.cpp	Adds trace/profiling markers in `HdArnoldGenericLight::Sync`.
libs/render_delegate/instancer.cpp	Adds trace/profiling markers in `HdArnoldInstancer::Sync`.
libs/render_delegate/basis_curves.cpp	Adds trace/profiling markers in `HdArnoldBasisCurves::Sync`.
libs/render_delegate/CMakeLists.txt	Attempts to disable trace instrumentation via `TRACE_ENABLE=0` when tracing is off.
libs/common/trace_utils.h	Declares `ArnoldUsdTraceDiagnostic` RAII helper.
libs/common/trace_utils.cpp	Implements trace enable/disable + reporter flush to Arnold logs.
libs/common/procedural_reader.cpp	Installs `ArnoldUsdTraceDiagnostic` during procedural reads.
libs/common/SConscript	Adds `trace_utils.cpp` to common library build.
libs/common/CMakeLists.txt	Adds `trace_utils.{h,cpp}` to the common library.
cmake/utils/options.cmake	Adds `ENABLE_TRACING` CMake option.
SConstruct	Adds `ENABLE_TRACING` and applies `TRACE_ENABLE=0` when disabled (SCons build).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-30T14:55:53Z

 void HdArnoldBasisCurves::Sync(
    HdSceneDelegate* sceneDelegate, HdRenderParam* renderParam, HdDirtyBits* dirtyBits, const TfToken& reprToken)
 {
+    AiProfileBlock("hydra_proc:sync:HdArnoldBasisCurves"); 


The profiling label here doesn’t follow the hydra_proc:<Class>:<Method> pattern used by the other newly-added AiProfileBlock calls (e.g. hydra_proc:HdArnoldMesh:Sync, hydra_proc:HdArnoldVolume:Sync). Please rename this string for consistency so profiles group predictably in the tooling.

Suggested change

AiProfileBlock("hydra_proc:sync:HdArnoldBasisCurves");

AiProfileBlock("hydra_proc:HdArnoldBasisCurves:Sync");

Copilot · 2026-04-30T14:55:53Z

+/// Activated only when the environment variable ARNOLD_USD_TRACE is set to a
+/// non-empty value, so there is no overhead in normal operation.


The docstring says tracing is activated only via ARNOLD_USD_TRACE, but in this PR the instrumentation itself is also controlled at compile time via ENABLE_TRACING / TRACE_ENABLE. Please update the comment to mention the build-time requirement; otherwise users may set the env var and still see no trace data in builds compiled with tracing disabled.

Suggested change

/// Activated only when the environment variable ARNOLD_USD_TRACE is set to a

/// non-empty value, so there is no overhead in normal operation.

/// Trace collection is available only in builds compiled with tracing enabled

/// (for example via ENABLE_TRACING / TRACE_ENABLE). In such builds, it is

/// activated when the environment variable ARNOLD_USD_TRACE is set to a

/// non-empty value, so there is no overhead in normal operation when tracing

/// support is not enabled or the variable is unset.

Copilot · 2026-04-30T14:55:54Z

 option(ENABLE_SHARED_ARRAYS "Enable using shared arrays" OFF)
 option(ENABLE_HYDRA2_RENDERSETTINGS "Enable using RenderSetting hydra prim" OFF)
 option(ENABLE_SCENE_INDEX_IN_BUNDLE "Add the scene index filters in the bundle" OFF)
+option(ENABLE_TRACING "Enable USD trace instrumentation (TRACE_FUNCTION/TRACE_SCOPE)." OFF)


ENABLE_TRACING is introduced as a global switch here, but the CMake changes in this PR only apply TRACE_ENABLE=0 to the render_delegate target. Either adjust the option description/scope or ensure the option consistently controls trace instrumentation for all targets that use TRACE_FUNCTION()/TRACE_SCOPE() in this repo.

Suggested change

option(ENABLE_TRACING "Enable USD trace instrumentation (TRACE_FUNCTION/TRACE_SCOPE)." OFF)

option(ENABLE_TRACING "Enable USD trace instrumentation (TRACE_FUNCTION/TRACE_SCOPE) for the render delegate target." OFF)

Copilot · 2026-04-30T14:55:54Z

+		TRACE_SCOPE("Populate/SetStage");
+		// We want to render the purpose that this reader was assigned to.
+		// We also support the purposes "default" and "geometry" that are always rendered
+		// so we don't need to provide it here
+		TfTokenVector purpose;
+		purpose.push_back(_purpose);
+		arnoldRenderDelegate->SetRenderTags(purpose);
+
+		// This will return a "hidden" render tag if a primitive is of a disabled type
+		if (_imagingDelegate) {
+			_imagingDelegate->SetDisplayRender(_purpose == UsdGeomTokens->render);
+			_imagingDelegate->SetDisplayProxy(_purpose == UsdGeomTokens->proxy);
+			_imagingDelegate->SetDisplayGuides(_purpose == UsdGeomTokens->guide);
+		}
+
+		if (_useSceneIndex) {
+			if (!path.empty()) {
+				UsdStagePopulationMask mask({SdfPath(path)});
+				stage->SetPopulationMask(mask);
+			}
+			_stageSceneIndex->SetStage(stage);
+		} else {
+			SdfPathVector _excludedPrimPaths; // excluding nothing
+			_imagingDelegate->Populate(rootPrim, _excludedPrimPaths);
+		}
+		if (!path.empty() && !_useSceneIndex) {
+			UsdGeomXformCache xformCache(_imagingDelegate->GetTime());
+			const GfMatrix4d xf = xformCache.GetLocalToWorldTransform(rootPrim);
+			_imagingDelegate->SetRootTransform(xf);
+		}


This new TRACE_SCOPE block is indented with tab characters, but the repo’s clang-format config has UseTab: Never. Please replace the tabs in this block with spaces (or run clang-format) to avoid introducing mixed indentation / formatting churn.

Suggested change

TRACE_SCOPE("Populate/SetStage");

// We want to render the purpose that this reader was assigned to.

// We also support the purposes "default" and "geometry" that are always rendered

// so we don't need to provide it here

TfTokenVector purpose;

purpose.push_back(_purpose);

arnoldRenderDelegate->SetRenderTags(purpose);

// This will return a "hidden" render tag if a primitive is of a disabled type

if (_imagingDelegate) {

_imagingDelegate->SetDisplayRender(_purpose == UsdGeomTokens->render);

_imagingDelegate->SetDisplayProxy(_purpose == UsdGeomTokens->proxy);

_imagingDelegate->SetDisplayGuides(_purpose == UsdGeomTokens->guide);

}

if (_useSceneIndex) {

if (!path.empty()) {

UsdStagePopulationMask mask({SdfPath(path)});

stage->SetPopulationMask(mask);

}

_stageSceneIndex->SetStage(stage);

} else {

SdfPathVector _excludedPrimPaths; // excluding nothing

_imagingDelegate->Populate(rootPrim, _excludedPrimPaths);

}

if (!path.empty() && !_useSceneIndex) {

UsdGeomXformCache xformCache(_imagingDelegate->GetTime());

const GfMatrix4d xf = xformCache.GetLocalToWorldTransform(rootPrim);

_imagingDelegate->SetRootTransform(xf);

}

TRACE_SCOPE("Populate/SetStage");

// We want to render the purpose that this reader was assigned to.

// We also support the purposes "default" and "geometry" that are always rendered

// so we don't need to provide it here

TfTokenVector purpose;

purpose.push_back(_purpose);

arnoldRenderDelegate->SetRenderTags(purpose);

// This will return a "hidden" render tag if a primitive is of a disabled type

if (_imagingDelegate) {

_imagingDelegate->SetDisplayRender(_purpose == UsdGeomTokens->render);

_imagingDelegate->SetDisplayProxy(_purpose == UsdGeomTokens->proxy);

_imagingDelegate->SetDisplayGuides(_purpose == UsdGeomTokens->guide);

}

if (_useSceneIndex) {

if (!path.empty()) {

UsdStagePopulationMask mask({SdfPath(path)});

stage->SetPopulationMask(mask);

}

_stageSceneIndex->SetStage(stage);

} else {

SdfPathVector _excludedPrimPaths; // excluding nothing

_imagingDelegate->Populate(rootPrim, _excludedPrimPaths);

}

if (!path.empty() && !_useSceneIndex) {

UsdGeomXformCache xformCache(_imagingDelegate->GetTime());

const GfMatrix4d xf = xformCache.GetLocalToWorldTransform(rootPrim);

_imagingDelegate->SetRootTransform(xf);

}

Copilot · 2026-04-30T14:55:54Z

    target_compile_definitions(render_delegate PUBLIC HYDRA_NORMALIZE_DEPTH=1)
 endif()
+if (NOT ENABLE_TRACING)
+    target_compile_definitions(render_delegate PUBLIC TRACE_ENABLE=0)


ENABLE_TRACING currently only toggles TRACE_ENABLE for the render_delegate target. Other CMake targets in this repo already use TRACE_FUNCTION() (e.g. plugins/usd_imaging/material_param_utils.cpp, plugins/scene_index/renderPassSIP.cpp), so with ENABLE_TRACING=OFF you’ll still end up compiling trace instrumentation in those targets. Consider applying the TRACE_ENABLE=0 definition globally (or via a shared helper used by all targets) so the option behaves consistently across the whole build.

Suggested change

target_compile_definitions(render_delegate PUBLIC TRACE_ENABLE=0)

add_compile_definitions(TRACE_ENABLE=0)

Copilot · 2026-04-30T14:55:55Z

    target_compile_definitions(render_delegate PUBLIC HYDRA_NORMALIZE_DEPTH=1)
 endif()
+if (NOT ENABLE_TRACING)
+    target_compile_definitions(render_delegate PUBLIC TRACE_ENABLE=0)


Since none of render_delegate’s public headers use TRACE_* macros, exporting TRACE_ENABLE=0 as a PUBLIC compile definition is likely unnecessary and can have surprising transitive effects on downstream targets. Prefer making this definition PRIVATE (and, if you want a global toggle, set it in one central place for all targets instead of relying on transitive propagation).

Suggested change

target_compile_definitions(render_delegate PUBLIC TRACE_ENABLE=0)

target_compile_definitions(render_delegate PRIVATE TRACE_ENABLE=0)

cpichard and others added 5 commits April 8, 2026 11:13

Add trace functions in hydra hot spots

7b33998

Merge branch 'master' into issue_2588

e0aa2bf

Merge branch 'master' into issue_2588

228b788

add AiProfileBlock alongside TRACE_FUNCTION

ffb21af

Merge branch 'master' into issue_2588

9fe4d3d

cpichard marked this pull request as ready for review April 30, 2026 14:49

cpichard requested review from Copilot and sebastienblor April 30, 2026 14:49

Copilot started reviewing on behalf of cpichard April 30, 2026 14:49 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

sebastienblor approved these changes May 11, 2026

View reviewed changes

cpichard merged commit 880cd48 into Autodesk:master May 11, 2026
13 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add trace functions in the render delegate hot spots#2616

Add trace functions in the render delegate hot spots#2616
cpichard merged 5 commits into
Autodesk:masterfrom
cpichard:issue_2588

cpichard commented Apr 8, 2026 •

edited

Loading

Uh oh!

autodesk-chorus Bot commented Apr 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	AiProfileBlock("hydra_proc:sync:HdArnoldBasisCurves");
	AiProfileBlock("hydra_proc:HdArnoldBasisCurves:Sync");

		/// Activated only when the environment variable ARNOLD_USD_TRACE is set to a
		/// non-empty value, so there is no overhead in normal operation.

-/// Activated only when the environment variable ARNOLD_USD_TRACE is set to a
-/// non-empty value, so there is no overhead in normal operation.
+/// Trace collection is available only in builds compiled with tracing enabled
+/// (for example via ENABLE_TRACING / TRACE_ENABLE). In such builds, it is
+/// activated when the environment variable ARNOLD_USD_TRACE is set to a
+/// non-empty value, so there is no overhead in normal operation when tracing
+/// support is not enabled or the variable is unset.

	option(ENABLE_TRACING "Enable USD trace instrumentation (TRACE_FUNCTION/TRACE_SCOPE)." OFF)
	option(ENABLE_TRACING "Enable USD trace instrumentation (TRACE_FUNCTION/TRACE_SCOPE) for the render delegate target." OFF)

	target_compile_definitions(render_delegate PUBLIC TRACE_ENABLE=0)
	add_compile_definitions(TRACE_ENABLE=0)

Conversation

cpichard commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

autodesk-chorus Bot commented Apr 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cpichard commented Apr 8, 2026 •

edited

Loading