Siggraph Presentation

This guide will be officially introduced at Siggraph 2023 - Houdini Hive on Wednesday, 9. of August 2023 at 11:00 AM PST.

Debugging

The Usd API ships with a debug class, which allows you to log different messages by setting the TF_DEBUG environment variable to one of the symbols. This is useful to see if plugins are loaded or to see if the asset resolver is correctly hooked in.

TL;DR - Debug In-A-Nutshell

  • You can set the TF_DEBUG environment variable to one the the values listed below or symbol name from a plugin.
  • You can also activate a symbol in the active session via Python: pxr.Tf.Debug.SetDebugSymbolsByName("AR_RESOLVER_INIT", True)

What should I use it for?

Tip

Enabling debug symbols, allows you to inspect specific log outputs of Usd. Typical use cases are to check if plugins are loaded correctly or if data is properly being refreshed.

Resources

Overview

Environment Variables:

NameValue
TF_DEBUG'DEBUG_SYMBOL_NAME'
TF_DEBUG_OUTPUT_FILE'stdout' or 'stderr'

Tip

Activating the log output via bash:

export TF_DEBUG=AR_RESOLVER_INIT

Then launch your app.

You can also set them interactively in the active session via Python. Wildcarding is allowd to turn on multiple debug symbols in batch.

Tip

activated_symbols = pxr.Tf.Debug.SetDebugSymbolsByName("AR_RESOLVER_INIT", True) # Returns: ["AR_RESOLVER_INIT"]
activated_symbols = pxr.Tf.Debug.SetDebugSymbolsByName("AR_*", True)

External plugins (like asset resolvers) often register own debug symbols which you can then use to see exactly what is going on.

To get a list of value TF_DEBUGvalues you can run:

from pxr import Tf
# To check if a symbol is active:
Tf.Debug.IsDebugSymbolNameEnabled("MY_SYMBOL_NAME")
# To print all symbols
docs = Tf.Debug.GetDebugSymbolDescriptions()
for name in Tf.Debug.GetDebugSymbolNames():
    desc = Tf.Debug.GetDebugSymbolDescription(name)
    print("{:<50} | {}".format(name, desc))

Full list of debug codes:

Variable NameDescription
AR_RESOLVER_INITPrint debug output during asset resolver initialization
GLF_DEBUG_CONTEXT_CAPSGlf report when context caps are initialized and dump contents
GLF_DEBUG_DUMP_SHADOW_TEXTURESGlf outputs shadows textures to image files
GLF_DEBUG_ERROR_STACKTRACEGlf dump stack trace on GL error
GLF_DEBUG_POST_SURFACE_LIGHTINGGlf post surface lighting setup
GLF_DEBUG_SHADOW_TEXTURESGlf logging for shadow map management
GUSD_STAGECACHEGusdStageCache details.
HDST_DISABLE_FRUSTUM_CULLINGDisable view frustum culling
HDST_DISABLE_MULTITHREADED_CULLINGForce the use of the single threaded version of frustum culling
HDST_DRAWReports diagnostics for drawing
HDST_DRAWITEMS_CACHEReports lookups from the draw items cache.
HDST_DRAW_BATCHReports diagnostics for draw batches
HDST_DRAW_ITEM_GATHERReports when draw items are fetched for a render pass.
HDST_DUMP_FAILING_SHADER_SOURCEPrint generated shader source code for shaders that fail compilation
HDST_DUMP_FAILING_SHADER_SOURCEFILEWrite out generated shader source code to files for shaders that fail compilation
HDST_DUMP_GLSLFX_CONFIGPrint composed GLSLFX configuration
HDST_DUMP_SHADER_SOURCEPrint generated shader source code
HDST_DUMP_SHADER_SOURCEFILEWrite out generated shader source code to files
HDST_FORCE_DRAW_BATCH_REBUILDForces rebuild of draw batches.
HDST_MATERIAL_ADDEDReport when a material is added
HDST_MATERIAL_REMOVEDReport when a material is removed
HDX_DISABLE_ALPHA_TO_COVERAGEDisable alpha to coverage transpancy
HDX_INTERSECTOutput debug info of intersector
HDX_SELECTION_SETUPOutput debug info during creation of selection buffer
HD_BPRIM_ADDEDReport when bprims are added
HD_BPRIM_REMOVEDReport when bprims are removed
HD_BUFFER_ARRAY_INFOReport detail info of HdBufferArrays
HD_BUFFER_ARRAY_RANGE_CLEANEDReport when bufferArrayRange is cleaned
HD_CACHE_HITSReport every cache hit
HD_CACHE_MISSESReport every cache miss
HD_COUNTER_CHANGEDReport values when counters change
HD_DIRTY_ALL_COLLECTIONSReports diagnostics when all collections are marked dirty
HD_DIRTY_LISTReports dirty list state changes
HD_DISABLE_MULTITHREADED_RPRIM_SYNCRun RPrim sync on a single thread
HD_DRAWITEMS_CULLEDReport the number of draw items culled in each render pass
HD_ENGINE_PHASE_INFOReport the execution phase of the Hydra engine
HD_EXT_COMPUTATION_ADDEDReport when ExtComputations are added
HD_EXT_COMPUTATION_EXECUTIONReport when ExtComputations are executed
HD_EXT_COMPUTATION_REMOVEDReport when ExtComputations are removed
HD_EXT_COMPUTATION_UPDATEDReport when ExtComputations are updated
HD_FREEZE_CULL_FRUSTUMFreeze the frustum used for culling at it's current value
HD_INSTANCER_ADDEDReport when instancers are added
HD_INSTANCER_CLEANEDReport when instancers are fully cleaned
HD_INSTANCER_REMOVEDReport when instancers are removed
HD_INSTANCER_UPDATEDReport when instancers are updated
HD_RENDER_SETTINGSReport render settings changes
HD_RPRIM_ADDEDReport when rprims are added
HD_RPRIM_CLEANEDReport when rprims are fully cleaned
HD_RPRIM_REMOVEDReport when rprims are removed
HD_RPRIM_UPDATEDReport when rprims are updated
HD_SAFE_MODEEnable additional security checks
HD_SELECTION_UPDATEReport when selection is updated
HD_SHARED_EXT_COMPUTATION_DATAReport info related to deduplication of ext computation data buffers
HD_SPRIM_ADDEDReport when sprims are added
HD_SPRIM_REMOVEDReport when sprims are removed
HD_SYNC_ALLReport debugging info for the sync all algorithm.
HD_TASK_ADDEDReport when tasks are added
HD_TASK_REMOVEDReport when tasks are removed
HD_VARYING_STATEReports state tracking of varying state
HGIGL_DEBUG_ERROR_STACKTRACEHgiGL dump stack trace on GL error
HGIGL_DEBUG_FRAMEBUFFER_CACHEDebug framebuffer cache management per context arena.
HGI_DEBUG_DEVICE_CAPABILITIESHgi report when device capabilities are initialized and dump contents
HIO_DEBUG_DICTIONARYglslfx dictionary parsing
HIO_DEBUG_FIELD_TEXTURE_DATA_PLUGINSHio field texture data plugin registration and loading
HIO_DEBUG_GLSLFXHio GLSLFX info
HIO_DEBUG_TEXTURE_IMAGE_PLUGINSHio image texture plugin registration and loading
NDR_DEBUGAdvanced debugging for Node Definition Registry
NDR_DISCOVERYDiagnostics from discovering nodes for Node Definition Registry
NDR_INFOAdvisory information for Node Definition Registry
NDR_PARSINGDiagnostics from parsing nodes for Node Definition Registry
NDR_STATSStatistics for registries derived from NdrRegistry
PCP_CHANGESPcp change processing
PCP_DEPENDENCIESPcp dependencies
PCP_NAMESPACE_EDITPcp namespace edits
PCP_PRIM_INDEXPrint debug output to terminal during prim indexing
PCP_PRIM_INDEX_GRAPHSWrite graphviz 'dot' files during prim indexing (requires PCP_PRIM_INDEX)
PLUG_INFO_SEARCHPlugin info file search
PLUG_LOADPlugin loading
PLUG_LOAD_IN_SECONDARY_THREADPlugins loaded from non-main threads
PLUG_REGISTRATIONPlugin registration
SDF_ASSETSdf asset resolution
SDF_ASSET_TRACE_INVALID_CONTEXTPost stack trace when opening an SdfLayer with no path resolver context
SDF_CHANGESSdf change notification
SDF_FILE_FORMATSdf file format plugins
SDF_LAYERSdfLayer loading and lifetime
SDR_TYPE_CONFORMANCEDiagnostcs from parsing and conforming default values for Sdr and Sdf type conformance
TF_ATTACH_DEBUGGER_ON_ERRORattach/stop in a debugger for all errors
TF_ATTACH_DEBUGGER_ON_FATAL_ERRORattach/stop in a debugger for fatal errors
TF_ATTACH_DEBUGGER_ON_WARNINGattach/stop in a debugger for all warnings
TF_DEBUG_REGISTRYdebug the TfDebug registry
TF_DISCOVERY_DETAILEDdetailed debugging of TfRegistryManager
TF_DISCOVERY_TERSEcoarse grain debugging of TfRegistryManager
TF_DLCLOSEshow files closed by TfDlclose
TF_DLOPENshow files opened by TfDlopen
TF_ERROR_MARK_TRACKINGcapture stack traces at TfErrorMark ctor/dtor, enable TfReportActiveMarks debugging API.
TF_LOG_STACK_TRACE_ON_ERRORlog stack traces for all errors
TF_LOG_STACK_TRACE_ON_WARNINGlog stack traces for all warnings
TF_PRINT_ALL_POSTED_ERRORS_TO_STDERRprint all posted errors immediately, meaning that even errors that are expected and handled will be printed, producing possibly confusing output
TF_SCRIPT_MODULE_LOADERshow script module loading activity
TF_TYPE_REGISTRYshow changes to the TfType registry
USDGEOM_BBOXUsdGeom bounding box computation
USDGEOM_EXTENTReports when Boundable extents are computed dynamically because no cached authored attribute is present in the scene.
USDIMAGING_CHANGESReport change processing events
USDIMAGING_COLLECTIONSReport collection queries
USDIMAGING_COMPUTATIONSReport Hydra computation usage in usdImaging.
USDIMAGING_COORDSYSCoordinate systems
USDIMAGING_INSTANCERReport instancer messages
USDIMAGING_PLUGINSReport plugin status messages
USDIMAGING_POINT_INSTANCER_PROTO_CREATEDReport PI prototype stats as they are created
USDIMAGING_POINT_INSTANCER_PROTO_CULLINGReport PI culling debug info
USDIMAGING_POPULATIONReport population events
USDIMAGING_SELECTIONReport selection messages
USDIMAGING_SHADERSReport shader status messages
USDIMAGING_TEXTURESReport texture status messages
USDIMAGING_UPDATESReport non-authored, time-varying data changes
USDMTLX_READERUsdMtlx reader details
USDSKEL_BAKESKINNINGUsdSkelBakeSkinningLBS() method.
USDSKEL_CACHEUsdSkel cache population.
USDUTILS_CREATE_USDZ_PACKAGEUsdUtils USDZ package creation details
USD_AUTO_APPLY_API_SCHEMASUSD API schema auto application details
USD_CHANGESUSD change processing
USD_CLIPSUSD clip details
USD_COMPOSITIONUSD composition details
USD_DATA_BDUSD BD file format traces
USD_DATA_BD_TRYUSD BD call traces. Prints names, errors and results.
USD_INSTANCINGUSD instancing diagnostics
USD_PATH_RESOLUTIONUSD path resolution diagnostics
USD_PAYLOADSUSD payload load/unload messages
USD_PRIM_LIFETIMESUSD prim ctor/dtor messages
USD_SCHEMA_REGISTRATIONUSD schema registration details.
USD_STAGE_CACHEUSD stage cache details
USD_STAGE_INSTANTIATION_TIMEUSD stage instantiation timing
USD_STAGE_LIFETIMESUSD stage ctor/dtor messages
USD_STAGE_OPENUSD stage opening details
USD_VALIDATE_VARIABILITYUSD attribute variability validation
USD_VALUE_RESOLUTIONUSD trace of layers inspected as values are resolved

You scrolled all the way to the end 🥳. Congratulations, you have now earned the rank of "Usd Nerd"!