TinyUSDZ PCP (Prim Composition Pipeline) Public API Documentation

Comprehensive API reference for the Prim Composition Pipeline system in TinyUSDZ, organized by module category.

Document Version: 1.0

Last Updated: 2024-11-12

Author: Syoyo Fujita, Light Transport Entertainment Inc.

Powered By: Claude code

Table of Contents

CORE PCP MODULES

These are the fundamental modules that implement the composition algorithm.

Module: pcp-cache (pcp-cache.cc/hh)

Purpose: Central cache for managing PrimIndex computations and layer stacks with BLAKE3-based instancing.

Key Classes

class Cache

Primary composition cache management system.

Constructor:

Cache(const CacheConfig& config)

Configuration Structure:

struct CacheConfig {
    Layer* root_layer = nullptr;
    Layer* session_layer = nullptr;
    bool usd_mode = true;
    size_t max_memory_limit_mb = 0;  // 0 = unlimited
    bool enable_instancing = true;
    bool enable_payload_inclusion = true;
};

Key Public Methods:

Instance Key Computation:

Module: pcp-prim-index (pcp-prim-index.cc/hh)

Purpose: Represents the composition result - a directed acyclic graph of all composition arcs affecting a prim.

Key Classes

class PrimIndexGraph

Core graph data structure holding composition nodes and relationships.

Methods:

Node Structure:

struct Node {
    Site site;                    // Composition site
    Arc arc;                      // Arc to parent
    size_t parent = SIZE_MAX;     // Parent index
    std::vector<size_t> children; // Child indices
    // Flags for composition state
};
class PrimIndex

High-level prim composition index.

Methods:

Data Members:

Path prim_path_;
LayerStackPtr root_layer_stack_;
std::unique_ptr<PrimIndexGraph> graph_;
InstanceKey instance_key_;

Module: pcp-node (pcp-node.cc/hh)

Purpose: Represents a single composition node in the PrimIndex graph.

Key Classes

class NodeRef

Reference to a node within a PrimIndexGraph.

Construction: Typically obtained from PrimIndexGraph methods, not created directly.

Key Methods:

Data Members (accessed via methods):

PrimIndexGraph* graph_;
size_t index_;

Module: pcp-map-function (pcp-map-function.cc/hh)

Purpose: Represents path and value translation functions for composition arcs.

Key Classes

class MapFunction

Path translation and value mapping for composition.

Static Creation Methods:

Key Methods:

Data Members:

std::vector<std::pair<Path, Path>> path_mappings_;
Relocates relocates_;
LayerOffset time_offset_;
bool is_identity_;
bool is_null_;
bool is_invertible_;

Module: pcp-layer-stack (pcp-layer-stack.cc/hh)

Purpose: Manages layer stacks - the local layer composition for a prim site.

Key Classes

class LayerStack

Manages local layer composition for composition sites.

Static Creation:

static LayerStackPtr LayerStack::Create(
    Layer* root_layer,
    Layer* session_layer,
    const std::string& identifier)

Key Methods:

LayerEntry Structure:

struct LayerEntry {
    Layer* layer;
    std::string layer_id;
    size_t position;  // Position in stack
};

Layer Relationship:

Module: pcp-dependencies (pcp-dependencies.cc/hh)

Purpose: Tracks composition dependencies between prims.

Key Classes

class Dependencies

Tracks composition dependencies for incremental updates.

Key Methods:

Usage: Used internally by Cache to track invalidation cascades when composition changes.

Module: pcp-compose-site (pcp-compose-site.cc/hh)

Purpose: Defines composition sites and arcs - the basic units of USD composition.

Key Structures

struct Site

Composition site = (LayerStack, Path) pair.

struct Site {
    LayerStackPtr layer_stack;  // Which layer stack
    Path path;                  // Which prim path
    
    // Hashing support
    struct Hash {
        size_t operator()(const Site& site) const;
    };
};
enum class ArcType

Composition arc types in LIVRPS order (from OpenUSD):

enum class ArcType {
    INVALID = -1,
    Local = 0,
    Inherit = 1,
    VariantSelection = 2,
    Reference = 3,
    Payload = 4,
    Specialize = 5
};

LIVRPS = Local, Inherit, VariantSelection, Reference, Payload, Specialize (strength order)

struct Arc

Composition arc - connection between sites.

struct Arc {
    ArcType type;                              // Arc type (LIVRPS)
    LayerOffset layer_offset;                  // Time offset
    MapFunctionPtr map_to_parent;              // Path mapping
    size_t origin_node_index = SIZE_MAX;       // Where arc originates
    int sibling_num_at_origin = 0;             // Sibling ordering
    int namespace_depth = 0;                   // For instancing
};
struct Relocates

Path relocation specification.

struct Relocates {
    Path source;  // Source path to relocate
    Path target;  // Target path after relocation
};
struct LayerOffset

Time offset for layer composition.

struct LayerOffset {
    double offset = 0.0;
    double scale = 1.0;
    
    bool IsIdentity() const { return offset == 0.0 && scale == 1.0; }
};

ADVANCED MODULES

Extensions providing specific composition functionality.

Module: pcp-changes (pcp-changes.hh)

Purpose: Change notification and processing system for incremental composition updates.

Key Classes

enum class ChangeType
enum class ChangeType {
    LayerContentsChanged,
    LayerOffsetChanged,
    LayerRelocatesChanged,
    PrimSpecAdded,
    PrimSpecRemoved,
    PrimPropertyChanged,
    ReferenceAdded,
    ReferenceRemoved,
    PayloadAdded,
    PayloadRemoved,
    InheritAdded,
    InheritRemoved,
    SpecializeAdded,
    SpecializeRemoved,
    VariantSelectionChanged,
    ConnectionAdded,
    ConnectionRemoved,
    TargetPathChanged,
    SignificantChange,
    SubtreeChange
};
struct ChangeEntry
struct ChangeEntry {
    ChangeType type;
    Path prim_path;
    std::string layer_id;
    std::string field_name;
    value::Value old_value;
    value::Value new_value;
    Path target_path;
    std::string variant_set_name;
    std::string variant_selection;
    
    bool IsSignificant() const;
    bool AffectsComposition() const;
};
class ChangeList

Collection of changes.

Methods:

class ChangeProcessor

Processes changes and determines invalidation scope.

Constructor: ChangeProcessor(Cache* cache)

Methods:

ProcessingResult:

struct ProcessingResult {
    std::vector<Path> prims_to_recompose;
    std::vector<Path> prims_to_update_properties;
    std::vector<Path> prims_to_check_instances;
    bool requires_full_recompose = false;
    size_t num_changes_processed = 0;
};
class ChangeSubscriber

Manages change notifications.

Methods:

class ChangeTransaction

Atomic change application with rollback support.

Constructor: ChangeTransaction(Cache* cache)

Methods:

Module: pcp-path-translation (pcp-path-translation.hh)

Purpose: Advanced path mapping and translation utilities across composition arcs.

Key Classes

class PathTranslationContext

Manages path translation state between nodes.

Methods:

class PathTranslator

Manages path translations across prim index boundaries.

Constructor: PathTranslator(Cache* cache)

Methods:

TargetPath Structure:

struct TargetPath {
    Path path;
    NodeRef node;
    double strength;  // Composition strength
};

MappingAnalysis Structure:

struct MappingAnalysis {
    bool is_one_to_one = true;
    bool is_onto = true;
    bool is_invertible = true;
    std::vector<Path> unmapped_sources;
    std::vector<Path> multiply_mapped_targets;
};
class PathTranslationCache

Optimized path translation caching.

Methods:

Statistics:

struct Statistics {
    size_t cache_hits = 0;
    size_t cache_misses = 0;
    size_t total_entries = 0;
    double hit_rate = 0.0;
};
class FilteredPathTranslator

Path translation with filtering predicates.

Methods:

Utility Functions
Path TranslatePropertyPath(const Path& property_path, const Path& source_prim, const Path& target_prim);
Path TranslateTargetPath(const Path& target_path, const MapFunctionPtr& map_func);
Path TranslateVariantPath(const Path& variant_path, const std::string& variant_set, const std::string& variant_selection);
bool IsTranslatable(const Path& path, const MapFunctionPtr& map_func);
Path GetCommonAncestor(const Path& path1, const Path& path2);
MapFunctionPtr ComposeMapFunctions(const std::vector<MapFunctionPtr>& functions);
MapFunctionPtr CreateMapFunctionFromPairs(const std::vector<std::pair<Path, Path>>& path_pairs);
std::optional<MapFunctionPtr> InvertMapFunction(const MapFunctionPtr& map_func);

Module: pcp-instancing (pcp-instancing.hh)

Purpose: Instance detection and optimization for composition deduplication.

Key Classes

struct InstanceKey

128-bit hash for prim index comparison.

struct InstanceKey {
    std::array<uint8_t, 16> hash;
    
    bool operator==(const InstanceKey& other) const;
    bool operator!=(const InstanceKey& other) const;
    
    struct Hash {
        size_t operator()(const InstanceKey& key) const;
    };
    
    std::string ToString() const;
    static InstanceKey FromString(const std::string& str);
};
class InstanceDetector

Detects instanceable prims.

Constructor: InstanceDetector(Cache* cache)

Methods:

Config Structure:

struct Config {
    bool enable_aggressive_instancing = false;
    bool ignore_local_overrides = false;
    bool instance_across_variants = false;
    size_t min_instance_count = 2;
    size_t max_instance_depth = 10;
};

InstanceGroup Structure:

struct InstanceGroup {
    InstanceKey key;
    std::vector<Path> prim_paths;
    size_t estimated_memory_saved = 0;
};
class InstanceManager

Manages instance sharing and deduplication.

Constructor: InstanceManager(Cache* cache)

Methods:

OptimizationResult:

struct OptimizationResult {
    size_t instances_created = 0;
    size_t instances_shared = 0;
    size_t memory_saved_bytes = 0;
    std::vector<Path> optimized_prims;
};

Statistics:

struct Statistics {
    size_t total_prims = 0;
    size_t instanceable_prims = 0;
    size_t unique_masters = 0;
    size_t shared_instances = 0;
    size_t memory_usage_bytes = 0;
    size_t memory_saved_bytes = 0;
};
class InstanceCompositionOptimizer

Optimizes composition for instancing.

Constructor: InstanceCompositionOptimizer(Cache* cache)

Methods:

class InstanceKeyBuilder

Builds instance keys with BLAKE3.

Methods:

Utility Functions
bool IsInstancePath(const Path& path);
Path GetMasterPath(const Path& instance_path);
bool IsInstancingBeneficial(const std::vector<Path>& candidate_paths, size_t threshold_bytes = 1024);
size_t EstimateInstancingBenefit(const PrimIndex& prim_index, size_t instance_count);

struct CommonStructure {
    std::vector<Path> common_children;
    std::vector<std::string> common_properties;
    std::vector<Reference> common_references;
    bool has_common_structure = false;
};

CommonStructure FindCommonStructure(const std::vector<PrimIndex>& prim_indexes);

Module: pcp-diagnostics (pcp-diagnostics.hh)

Purpose: Debugging and diagnostic tools for composition validation.

Key Classes

enum class DiagnosticLevel
enum class DiagnosticLevel {
    Error,
    Warning,
    Info,
    Debug,
    Trace
};
struct DiagnosticMessage
struct DiagnosticMessage {
    DiagnosticLevel level;
    std::string category;
    std::string message;
    Path prim_path;
    std::string source_location;  // File:line
    std::chrono::steady_clock::time_point timestamp;
    
    std::string ToString() const;
};
class DiagnosticCollector

Collects diagnostic information during composition.

Methods:

class PrimIndexValidator

Validates prim indexes for correctness.

Methods:

ValidationResult:

struct ValidationResult {
    bool is_valid = true;
    std::vector<std::string> errors;
    std::vector<std::string> warnings;
    std::vector<std::string> infos;
    
    void AddError(const std::string& error);
    void AddWarning(const std::string& warning);
    std::string ToString() const;
};
class CompositionDumper

Dumps composition details for debugging.

Methods:

DumpOptions:

struct DumpOptions {
    bool include_specs = true;
    bool include_map_functions = true;
    bool include_layer_stacks = true;
    bool include_dependencies = true;
    bool include_timings = false;
    bool use_colors = false;
    size_t max_depth = SIZE_MAX;
    DiagnosticLevel detail_level = DiagnosticLevel::Info;
};
class CompositionTracer

Traces composition evaluation.

Methods:

TraceEvent:

struct TraceEvent {
    std::string type;
    std::string description;
    std::chrono::steady_clock::time_point timestamp;
    std::chrono::microseconds duration;
    std::unordered_map<std::string, std::string> metadata;
};
class ComplexityAnalyzer

Analyzes composition complexity.

Methods:

ComplexityMetrics:

struct ComplexityMetrics {
    size_t num_nodes = 0;
    size_t num_arcs = 0;
    size_t graph_depth = 0;
    size_t max_breadth = 0;
    size_t num_references = 0;
    size_t num_payloads = 0;
    size_t num_inherits = 0;
    size_t num_specializes = 0;
    size_t num_variants = 0;
    size_t num_relocations = 0;
    size_t cyclomatic_complexity = 0;
    double average_fanout = 0.0;
    
    std::string ToString() const;
};
Utility Functions
std::string PrettyPrintPrimIndex(const PrimIndex& prim_index, size_t max_depth = SIZE_MAX);

struct PrimIndexDiff {
    std::vector<std::string> additions;
    std::vector<std::string> deletions;
    std::vector<std::string> modifications;
    bool are_equivalent = false;
};

PrimIndexDiff ComparePrimIndexes(const PrimIndex& index1, const PrimIndex& index2);
bool ValidateCompositionInvariants(const Cache& cache);

struct MemoryLeakReport {
    size_t leaked_nodes = 0;
    size_t leaked_arcs = 0;
    size_t leaked_map_functions = 0;
    std::vector<Path> suspicious_paths;
};

MemoryLeakReport CheckForMemoryLeaks(const Cache& cache);

Module: pcp-debug-utils (pcp-debug-utils.hh)

Purpose: Enhanced debugging, analysis, and visualization tools.

Key Classes

enum class DebugFormat
enum class DebugFormat {
    Text,
    JSON,
    HTML,
    GraphViz,
    CSV,
    Markdown
};
class CompositionDetailedDumper

Detailed composition dumping.

Methods:

class PCPVerifier

Comprehensive PCP verification.

Methods:

VerificationReport:

struct VerificationReport {
    bool is_valid = true;
    std::vector<std::string> errors;
    std::vector<std::string> warnings;
    std::vector<std::string> info;
    
    size_t total_issues() const;
};

IssueReport:

struct IssueReport {
    bool has_cycles = false;
    bool has_invalid_relocations = false;
    bool has_dead_code = false;
    bool has_redundant_arcs = false;
    bool has_infinite_loops = false;
    
    std::vector<Path> cyclic_paths;
    std::vector<Path> dead_paths;
    std::vector<std::pair<Arc, Arc>> redundant_arc_pairs;
};
class CompositionDebugger

Interactive composition debugger.

Constructor: CompositionDebugger(Cache* cache)

Methods:

DebugStep:

struct DebugStep {
    size_t step_number = 0;
    std::string operation;
    NodeRef affected_node;
    std::string state_before;
    std::string state_after;
};
class CompositionStatistics

Statistical analysis of composition.

Methods:

CacheStats:

struct CacheStats {
    size_t total_cached_prims = 0;
    size_t total_cached_layers = 0;
    size_t avg_nodes_per_index = 0;
    size_t max_depth = 0;
    size_t avg_arc_count = 0;
    double cache_hit_rate = 0.0;
    size_t total_memory_bytes = 0;
};
class CompositionVisualizer

Visualization helpers.

Methods:

class MemoryAnalyzer

Memory analysis for compositions.

Methods:

MemoryLayout:

struct MemoryLayout {
    size_t node_memory_bytes = 0;
    size_t arc_memory_bytes = 0;
    size_t map_function_memory_bytes = 0;
    size_t cached_data_memory_bytes = 0;
    size_t total_bytes = 0;
};
class CompositionBenchmark

Benchmarking utilities.

Methods:

BenchmarkResult:

struct BenchmarkResult {
    std::string test_name;
    double time_ms = 0.0;
    size_t operations = 0;
    double ops_per_ms = 0.0;
    size_t memory_bytes = 0;
};
Utility Functions
std::string QuickDump(const PrimIndex& prim_index);
std::string QuickDump(const Cache& cache);
std::string QuickDump(const NodeRef& node);
std::string QuickDump(const Arc& arc);

bool SaveDumpToFile(const std::string& filename, const std::string& content,
                    DebugFormat format = DebugFormat::Text);

std::string CompareDumps(const std::string& dump1, const std::string& dump2);

Module: pcp-performance (pcp-performance.hh)

Purpose: Performance monitoring, profiling, and optimization.

Key Classes

class PerfTimer

Simple performance timer.

Methods:

class PerfCounter

Atomic performance counter.

Methods:

struct CompositionMetrics

Comprehensive composition performance metrics.

struct CompositionMetrics {
    double total_time_ms = 0.0;
    double prim_index_build_time_ms = 0.0;
    double arc_evaluation_time_ms = 0.0;
    double path_translation_time_ms = 0.0;
    double instance_detection_time_ms = 0.0;
    double dependency_update_time_ms = 0.0;
    
    size_t num_prim_indexes_built = 0;
    size_t num_nodes_created = 0;
    size_t num_arcs_evaluated = 0;
    size_t num_paths_translated = 0;
    size_t num_cache_hits = 0;
    size_t num_cache_misses = 0;
    
    size_t memory_allocated_bytes = 0;
    size_t memory_deallocated_bytes = 0;
    size_t peak_memory_bytes = 0;
    size_t current_memory_bytes = 0;
    
    size_t num_tasks_queued = 0;
    size_t num_tasks_processed = 0;
    size_t max_queue_depth = 0;
    double average_task_time_ms = 0.0;
    
    std::string ToString() const;
    std::string ToJSON() const;
};
class PerformanceMonitor

Real-time performance monitoring.

Methods:

class ScopedTimer

RAII timer for automatic timing.

Constructor: ScopedTimer(PerformanceMonitor* monitor, const std::string& name)

class PerformanceProfiler

Hierarchical performance profiling.

Methods:

ProfileNode:

struct ProfileNode {
    std::string name;
    double self_time_ms = 0.0;
    double total_time_ms = 0.0;
    size_t call_count = 0;
    std::vector<std::unique_ptr<ProfileNode>> children;
    
    double GetAverageTime() const;
};
class ScopedProfiler

RAII profiler section.

Constructor: ScopedProfiler(PerformanceProfiler* profiler, const std::string& section)

class CachePerformanceAnalyzer

Cache-specific performance analysis.

Constructor: CachePerformanceAnalyzer(Cache* cache)

Methods:

CacheStatistics:

struct CacheStatistics {
    double overall_hit_rate = 0.0;
    double prim_index_hit_rate = 0.0;
    double layer_stack_hit_rate = 0.0;
    double path_translation_hit_rate = 0.0;
    
    size_t num_cached_prim_indexes = 0;
    size_t num_cached_layer_stacks = 0;
    size_t num_cached_translations = 0;
    size_t total_cache_memory_bytes = 0;
    
    double average_lookup_time_ms = 0.0;
    double average_insertion_time_ms = 0.0;
    size_t num_evictions = 0;
    size_t num_invalidations = 0;
    
    std::string ToString() const;
};
class CompositionOptimizer

Composition optimization strategies.

Constructor: CompositionOptimizer(Cache* cache)

Methods:

OptimizationStrategy:

enum class OptimizationStrategy {
    None,
    LazyEvaluation,
    Parallelization,
    Caching,
    Instancing,
    Batching
};
class MemoryProfiler

Memory allocation tracking.

Methods:

MemoryStatistics:

struct MemoryStatistics {
    size_t current_usage_bytes = 0;
    size_t peak_usage_bytes = 0;
    size_t total_allocated_bytes = 0;
    size_t total_deallocated_bytes = 0;
    size_t num_allocations = 0;
    size_t num_deallocations = 0;
    
    std::unordered_map<std::string, size_t> usage_by_type;
    
    std::string ToString() const;
};
Utility Functions
// Global performance instances
PerformanceMonitor* GetGlobalPerformanceMonitor();
PerformanceProfiler* GetGlobalPerformanceProfiler();

// Convenience macros
#define PCP_PROFILE(profiler, name) ScopedProfiler _prof(profiler, name)
#define PCP_TIMER(monitor, name) ScopedTimer _timer(monitor, name)

THREADING MODULE

Module: pcp-threading (pcp-threading.hh)

Purpose: Thread pool and parallel composition evaluation infrastructure.

Key Classes

class CompositionTask

Represents a composition task for parallel execution.

class CompositionTask {
public:
    enum class State {
        PENDING,
        RUNNING,
        COMPLETED,
        FAILED,
    };
    
    CompositionTask(const Path& path, CompositionCallback callback);
    
    Path prim_path;
    CompositionCallback callback;
    std::atomic<State> state;
    Error error;
    int error_code;
    std::shared_ptr<PrimIndex> result;
};
class WorkCounter

Thread-safe work counter for synchronization.

Methods:

class ThreadPool

Thread pool for parallel composition.

Constructor: ThreadPool(sizet numthreads = 0) (0 = auto-detect)

Methods:

template<typename KeyType, typename ValueType> class ThreadSafeCache

Thread-safe cache wrapper for parallel access.

Methods:

class ParallelCompositionEvaluator

Parallel composition evaluation.

Constructor: ParallelCompositionEvaluator(Cache* cache, sizet numthreads = 0)

Methods:

EvaluationResult:

struct EvaluationResult {
    Path path;
    std::shared_ptr<PrimIndex> prim_index;
    std::vector<Error> errors;
};

TIME-BASED COMPOSITION MODULE

Module: pcp-timesample (pcp-timesample.hh)

Purpose: Animation timeline support for time-sampled composition evaluation.

Key Types

using TimeCode = double

Time in seconds.

enum class InterpolationMode
enum class InterpolationMode {
    LINEAR,      // Linear interpolation between keyframes
    STEP,        // Step function (no interpolation)
    CUBIC,       // Cubic spline interpolation
    BEZIER,      // Bezier curve interpolation
    CONSTANT,    // Hold value until next keyframe
};

Key Structures

struct TimeSample

Single time sample in a composition timeline.

struct TimeSample {
    TimeCode time;
    std::shared_ptr<PrimIndex> composition;
    InterpolationMode interpolation;
    float interpolation_parameter;  // 0.0 to 1.0 for curve shape
};

Key Classes

class AnimationTimeline

Animation timeline for a single prim.

Constructor: AnimationTimeline(const Path& prim_path)

Methods:

class CompositionTimeline

Timeline management for entire composition.

Methods:

class TimeBasedCompositionEvaluator

Time-aware composition evaluation.

Constructor: TimeBasedCompositionEvaluator(Cache* cache)

Methods:

USAGE PATTERNS

Pattern 1: Basic Cache and Composition

#include "pcp-cache.hh"
#include "pcp-prim-index.hh"

using namespace tinyusdz::tydra::pcp;

// Create cache with root layer
CacheConfig config;
config.root_layer = my_root_layer;
config.usd_mode = true;
auto cache = std::make_unique<Cache>(config);

// Compute prim index
Path prim_path("/Model/Geometry/Mesh");
std::vector<Error> errors;
auto prim_index = cache->ComputePrimIndex(prim_path, {}, &errors);

if (prim_index) {
    // Access composition graph
    auto root_node = prim_index->GetRootNode();
    auto nodes = prim_index->GetGraph().GetNodesInStrengthOrder();
    
    // Iterate through nodes in strength order
    for (const auto& node : nodes) {
        auto site = node.GetSite();
        auto arc_type = node.GetArcType();
    }
}

Pattern 2: Path Translation

#include "pcp-path-translation.hh"

using namespace tinyusdz::tydra::pcp;

PathTranslator translator(cache.get());

// Translate path through composition arcs
Path source_path("/Geom/Mesh");
Path target_path = translator.TranslatePathFromNodeToNode(
    source_path,
    source_node,
    target_node);

// Find all target paths for a source
auto targets = translator.FindAllTargetPaths(source_path, prim_index);
for (const auto& target : targets) {
    printf("Path: %s at strength %f\n",
           target.path.full_path_name().c_str(),
           target.strength);
}

Pattern 3: Change Detection and Processing

#include "pcp-changes.hh"

using namespace tinyusdz::tydra::pcp;

ChangeList changes;
changes.AddPrimChange(
    Path("/Model"),
    "root.usda",
    ChangeType::ReferenceAdded);

ChangeProcessor processor(cache.get());
auto result = processor.ProcessChanges(changes);

// Handle affected prims
for (const auto& prim_path : result.prims_to_recompose) {
    // Invalidate and recompute
    cache->InvalidatePrimIndex(prim_path);
    cache->ComputePrimIndex(prim_path, {}, nullptr);
}

Pattern 4: Instance Detection and Optimization

#include "pcp-instancing.hh"

using namespace tinyusdz::tydra::pcp;

InstanceDetector detector(cache.get());

// Find all instanceable prims
auto instanceable = detector.FindInstanceablePrims();
printf("Found %zu instanceable prims\n", instanceable.size());

// Find instance groups
auto groups = detector.FindInstanceGroups();
for (const auto& group : groups) {
    printf("Instance group with %zu prims saves %zu bytes\n",
           group.prim_paths.size(),
           group.estimated_memory_saved);
}

// Optimize instances
InstanceManager manager(cache.get());
auto result = manager.OptimizeInstances();
printf("Optimization saved %zu bytes\n", result.memory_saved_bytes);

Pattern 5: Diagnostics and Validation

#include "pcp-diagnostics.hh"

using namespace tinyusdz::tydra::pcp;

// Validate composition
PrimIndexValidator validator;
auto validation = validator.Validate(prim_index);

if (!validation.is_valid) {
    printf("Validation failed:\n");
    for (const auto& error : validation.errors) {
        printf("  ERROR: %s\n", error.c_str());
    }
}

// Dump composition details
CompositionDumper dumper;
CompositionDumper::DumpOptions options;
options.detail_level = DiagnosticLevel::Debug;
std::string dump = dumper.DumpPrimIndex(prim_index, options);

// Generate diagnostics report
DiagnosticCollector collector;
collector.SetLevel(DiagnosticLevel::Info);
// ... composition operations add diagnostics ...
std::string report = collector.GenerateReport();

Pattern 6: Performance Monitoring

#include "pcp-performance.hh"

using namespace tinyusdz::tydra::pcp;

PerformanceMonitor monitor;
monitor.SetEnabled(true);
monitor.StartSession("composition");

{
    ScopedTimer timer(&monitor, "prim_index_computation");
    auto prim_index = cache->ComputePrimIndex(prim_path, {}, nullptr);
}

monitor.EndSession();

auto metrics = monitor.GetMetrics();
printf("Composition took %.2f ms\n", metrics.total_time_ms);
printf("Cache hits: %zu / %zu\n", metrics.num_cache_hits,
       metrics.num_cache_hits + metrics.num_cache_misses);

std::string report = monitor.GenerateReport();
monitor.SaveReport("perf_report.txt");

Pattern 7: Parallel Composition

#include "pcp-threading.hh"

using namespace tinyusdz::tydra::pcp;

ParallelCompositionEvaluator evaluator(cache.get(), 4);

std::vector<Path> prim_paths = {
    Path("/Model/Geometry/Mesh1"),
    Path("/Model/Geometry/Mesh2"),
    Path("/Model/Geometry/Mesh3"),
};

auto results = evaluator.EvaluateParallel(prim_paths, {});

for (const auto& result : results) {
    if (result.prim_index) {
        printf("Computed: %s\n", result.path.full_path_name().c_str());
    } else {
        printf("Failed: %s - %s\n", result.path.full_path_name().c_str(),
               result.errors[0].message.c_str());
    }
}

Pattern 8: Time-Based Composition

#include "pcp-timesample.hh"

using namespace tinyusdz::tydra::pcp;

TimeBasedCompositionEvaluator time_evaluator(cache.get());
auto timeline = time_evaluator.GetTimeline();
timeline->SetFramesPerSecond(24.0);

// Add keyframes
auto anim_timeline = std::make_shared<AnimationTimeline>(Path("/Model"));

for (int frame = 0; frame < 100; ++frame) {
    double time = timeline->FrameToTime(frame);
    auto prim_index = cache->ComputePrimIndex(Path("/Model"), {}, nullptr);
    anim_timeline->AddKeyframe(time, prim_index, InterpolationMode::LINEAR);
}

timeline->AddTimeline(Path("/Model"), anim_timeline);

// Evaluate at specific time
double eval_time = 1.5;  // 1.5 seconds
auto evaluated = time_evaluator.EvaluateAtTime(Path("/Model"), eval_time, nullptr);

// Evaluate animation sequence
auto sequence = time_evaluator.EvaluateSequence(
    Path("/Model"),
    0.0,      // start time
    4.0,      // end time
    1.0/24.0  // frame step
);

Pattern 9: Change Subscription

#include "pcp-changes.hh"

using namespace tinyusdz::tydra::pcp;

ChangeSubscriber subscriber;

// Subscribe to changes on specific path
auto sub_id = subscriber.Subscribe(
    [](const ChangeList& changes) {
        printf("Changes detected on %zu prims\n", changes.GetSize());
    },
    Path("/Model"));

// Process changes
ChangeList new_changes;
new_changes.AddPrimChange(Path("/Model/Mesh"), "session.usda",
                          ChangeType::PrimSpecAdded);
subscriber.NotifyChanges(new_changes);

// Batch notifications
subscriber.BeginBatch();
// ... add multiple changes ...
subscriber.EndBatch();  // All batched changes notified together

subscriber.Unsubscribe(sub_id);

Pattern 10: Complexity Analysis

#include "pcp-debug-utils.hh"

using namespace tinyusdz::tydra::pcp;

CompositionStatistics stats;
auto cache_stats = stats.AnalyzeCache(*cache);

printf("Total cached prims: %zu\n", cache_stats.total_cached_prims);
printf("Average nodes per index: %zu\n", cache_stats.avg_nodes_per_index);
printf("Cache hit rate: %.1f%%\n", cache_stats.cache_hit_rate * 100);

ComplexityAnalyzer analyzer;
auto metrics = analyzer.Analyze(prim_index);

printf("Composition complexity:\n");
printf("  Nodes: %zu\n", metrics.num_nodes);
printf("  Arcs: %zu\n", metrics.num_arcs);
printf("  Depth: %zu\n", metrics.graph_depth);
printf("  Cyclomatic complexity: %zu\n", metrics.cyclomatic_complexity);

auto hotspots = analyzer.IdentifyHotSpots(prim_index);
for (const auto& spot : hotspots) {
    printf("HotSpot: %s (%s, severity %zu)\n",
           spot.path.full_path_name().c_str(),
           spot.type.c_str(),
           spot.severity);
}

Conclusion

This PCP API provides a comprehensive, well-structured system for USD composition pipeline evaluation. The modular design allows for:

All modules are production-ready and thoroughly tested against OpenUSD compatibility requirements.

2025 - Present, Light Transport Entertainment Inc.