context.h

Go to the documentation of this file.

//
// Copyright 2024 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_VALIDATION_USD_VALIDATION_CONTEXT_H
#define PXR_USD_VALIDATION_USD_VALIDATION_CONTEXT_H


#include "pxr/pxr.h"
#include "pxr/base/plug/plugin.h"
#include "pxr/base/tf/stringUtils.h"
#include "pxr/base/tf/token.h"
#include "pxr/usd/usd/primRange.h"
#include "pxr/usdValidation/usdValidation/api.h"
#include "pxr/usdValidation/usdValidation/error.h"
#include "pxr/usdValidation/usdValidation/timeRange.h"
#include "pxr/usdValidation/usdValidation/validator.h"

#include <mutex>

PXR_NAMESPACE_OPEN_SCOPE

class TfType;
class WorkDispatcher;
class Usd_PrimFlagsPredicate;

class UsdValidationContext
{
public:
    USDVALIDATION_API
    explicit UsdValidationContext(const TfTokenVector &keywords,
                                  bool includeAllAncestors = true);

    USDVALIDATION_API
    explicit UsdValidationContext(const PlugPluginPtrVector &plugins,
                                  bool includeAllAncestors = true);

    USDVALIDATION_API
    explicit UsdValidationContext(
        const UsdValidationValidatorMetadataVector &metadata,
        bool includeAllAncestors = true);

    USDVALIDATION_API
    explicit UsdValidationContext(const std::vector<TfType> &schemaTypes);

    USDVALIDATION_API
    explicit UsdValidationContext(
        const std::vector<const UsdValidationValidator *> &validators);

    USDVALIDATION_API
    explicit UsdValidationContext(
        const std::vector<const UsdValidationValidatorSuite *> &suites);

    USDVALIDATION_API
    UsdValidationErrorVector Validate(const SdfLayerHandle &layer) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const UsdStagePtr &stage, 
        const Usd_PrimFlagsPredicate &predicate, 
        const UsdValidationTimeRange &timeRange) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const UsdStagePtr &stage, 
        const Usd_PrimFlagsPredicate &predicate) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(const UsdStagePtr &stage) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const UsdStagePtr &stage, 
        const UsdValidationTimeRange &timeRange) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const UsdStagePtr &stage, 
        const Usd_PrimFlagsPredicate &predicate,
        const std::vector<UsdTimeCode> &timeCodes) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const UsdStagePtr &stage, 
        const std::vector<UsdTimeCode> &timeCodes) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const std::vector<UsdPrim> &prims, 
        const UsdValidationTimeRange &timeRange = {}) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const UsdPrimRange &prims, 
        const UsdValidationTimeRange &timeRange = {}) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const std::vector<UsdPrim> &prims, 
        const std::vector<UsdTimeCode> &timeCodes) const;

    USDVALIDATION_API
    UsdValidationErrorVector Validate(
        const UsdPrimRange &prims, 
        const std::vector<UsdTimeCode> &timeCodes) const;

private:
    // helper to initialize UsdValidationContext, given a vector of metadata
    // and a flag to include all ancestors.
    void _InitializeFromValidatorMetadata(
        const UsdValidationValidatorMetadataVector &metadata,
        bool includeAllAncestors);

    // Distribute the validators into different groups based on the type of
    // validation to be performed. This method distributes the selected
    // validators into _layerValidators, _stageValidators, _primValidators and
    // _schemaTypeValidators.
    void _DistributeValidators(
        const std::vector<const UsdValidationValidator *> &validators);

    // Helper enum to specify the state of time dependency for validation.
    // This is used to determine if context need to run just time dependent, 
    // just non-time dependent or all validators.
    enum class _TimeDependencyState {
        DoTimeDependent,
        DoNonTimeDependent,
        All
    };

    // Private helper functions to validate layers, stages and prims.
    void _ValidateLayer(WorkDispatcher &dispatcher, const SdfLayerHandle &layer,
                        UsdValidationErrorVector *errors,
                        std::mutex *errorsMutex) const;

    // Helper function to validate a stage.
    //    - Layer Validators for all used layers in the stage
    //    - Stage Validators for the stage
    //    - Prim Validators for all prims in the stage, using the predicate
    //      to traverse the prims on the stage.
    //
    // Depending on whether an explicit timeRange is provided or a vector
    // of timeCodes are provided, this function will do the following:
    //  - if timeRange is provided, it uses that to validate the stage and
    //  its prims using the predicate.
    //  - if timeCodes are provided:
    //      - Run all non-time dependent validators once.
    //      - Run all time dependent validators for all timeCodes.
    void _ValidateStage(WorkDispatcher &dispatcher,
                        const UsdStagePtr &stage, 
                        UsdValidationErrorVector *errors,
                        std::mutex *errorsMutex,
                        const Usd_PrimFlagsPredicate &predicate,
                        const std::variant<UsdValidationTimeRange,
                            std::vector<UsdTimeCode>> &times) const;

    // Helper function to validate prims. Generalized for UsdPrimRange and
    // vector of UsdPrims.
    template <typename T>
    void _ValidatePrims(
        WorkDispatcher &dispatcher, const T &prims, 
        UsdValidationErrorVector *errors, std::mutex *errorsMutex,
        UsdValidationTimeRange timeRange,
        _TimeDependencyState timeDependencyState = 
            _TimeDependencyState::All) const;

    // Helper function to run _ValidatePrims within a scoped dispatcher.
    // Templated to handle both PrimRange and vector of UsdPrims.
    // Depending on whether an explicit timeRange is provided or a vector
    // of timeCodes are provided, this function will do the following:
    // - if timeRange is provided, it uses that to validate the prims.
    // - if timeCodes are provided:
    //    - Run all non-time dependent validators once.
    //    - Run all time dependent validators for all timeCodes.
    template <typename T>
    void _RunValidatePrims(
        const T &prims, UsdValidationErrorVector *errors, 
        std::mutex *errorsMutex, 
        const std::variant<UsdValidationTimeRange, 
            std::vector<UsdTimeCode>> &times) const;

    // Validators catering to a specific schemaType
    using _SchemaTypeValidatorPair
        = std::pair<TfToken, std::vector<const UsdValidationValidator *>>;
    using _SchemaTypeValidatorPairVector
        = std::vector<_SchemaTypeValidatorPair>;

    // Vectors of selected sets of validators, which will be run for this
    // UsdValidationContext. Validation tasks will be enqueued for each of these
    // validators on a given layer / stage or prims (traversed or explicitly
    // specified).
    std::vector<const UsdValidationValidator *> _layerValidators;
    std::vector<const UsdValidationValidator *> _stageValidators;
    std::vector<const UsdValidationValidator *> _primValidators;

    // validators here will be used to validate prims based on their schema
    // types, such that:
    // - For every typed schemaType found in here, prim being validated will be
    //   checked if it satisfies the IsA<schemaType> and validation task will be
    //   enqueued.
    // - For every applied schemaType found in here, prim's appliedAPISchemas
    //   will be checked and if found, validation task will be enqueued for the
    //   prim.
    _SchemaTypeValidatorPairVector _schemaTypeValidators;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_USD_VALIDATION_USD_VALIDATION_CONTEXT_H