USDGENSCHEMAFROMSDR(1)

NAME
usdgenschemafromsdr - manual page for usdgenschemafromsdr 26.08

DESCRIPTION
usage: usdgenschemafromsdr [-h] [--noreadme] [-v]

    [schemaConfig] [schemaGenerationPath]

    This script generates dynamic schema.usda, generatedSchema.usda and plugInfo.json. The schema.usda is generated by parsing appropriate sdrNodes provided in a config file. Along with providing sdrNodes types and identifier, the config file also provides a list of subLayers which the auto populated schema.usda should sublayer. Code generation can also be optionally enabled via the json config, note that code generation is disabled by default.

    The script takes 3 arguments:

    - a json config, providing sdrNodes via sourceType, sdrNodeIdentifiers

    or explicit list of absolute asset file paths (sourceAssetNodes) and a list of sublayers. The asset file paths might also contain environment variables, so users must set these prior to running the script.

    - a destination directory. Note that a schema.usda with appropriate

    GLOBAL prim providing a libraryName in its customData, must be present at this location. This is also the location where generatedSchema.usda, plugInfo.json will get exported. In the case code generation is explicitly enabled in the config, libraryPath must also be provided along with libraryName in the customData, else usdGenSchema will fail.

    - an optional noreadme to ignore generating a README.md providing brief

    explaination of the contents of the directory.

    This script will run usdGenSchema on the auto populated schema.usda.

    If regenerating schemas, it's recommended to set the USD_DISABLE_AUTO_APPLY_API_SCHEMAS environment variable to true in order to prevent any previously generated auto-apply API schemas from being applied to the specified schema bases which can result in extra properties being pruned.

    The schema.usda populated specifications from the provided sdrNodes using UsdUtils.UpdateSchemaWithSdrNode and skipCodeGeneration metadata will be set to true, unless explicitly marked False in the config for this schema.usda.

    UsdUtils.UpdateSchemaWithSdrNode is responsible for:

Updates the given schemaLayer with primSpec and propertySpecs from sdrNode metadata.

A renderContext can be provided which is used in determining the shaderId namespace, which follows the pattern: "<renderContext>:<SdrShaderNodeContext>:shaderId". Note that we are using a node's context (SDR_NODE_CONTEXT_TOKENS) here to construct the shaderId namespace, so shader parsers should make sure to use appropriate SDR_NODE_CONTEXT_TOKENS in the node definitions.

overrideIdentifier parameter is the identifier which should be used when the identifier of the node being processed differs from the one Sdr will discover at runtime, such as when this function is def a node constructed from an explicit asset path. This should only be used when clients know the identifier being passed is the true identifier which sdr Runtime will provide when querying using GetShaderNodeByIdentifierAndType, etc.

It consumes the following attributes (that manifest as Sdr metadata) in addition to many of the standard Sdr metadata specified and parsed (via its parser plugin).

  Node Level Metadata:

    - "schemaName": Name of the new schema populated from the given sdrNode

    (Required)

    - "schemaKind": Specifies the UsdSchemaKind for the schema being

    populated from the sdrNode. (Note that this does not support multiple apply schema kinds).

    - "schemaBase": Base schema from which the new schema should inherit

    from. Note this defaults to "APISchemaBase" for an API schema or "Typed" for a concrete scheme.

    - "apiSchemasForAttrPruning": A list of core API schemas which will be

    composed together and any shared shader property from this prim definition is pruned from the resultant schema.

    - "typedSchemaForAttrPruning": A core typed schema which will be

    composed together with the apiSchemasForAttrPruning and any shared shader property from this prim definition is pruned from the resultant schema. If no typedSchemaForAttrPruning is provided then only the apiSchemasForAttrPruning are composed to create a prim definition. This will only be used when creating an APISchema.

    - "apiSchemaAutoApplyTo": The schemas to which the sdrNode populated

    API schema will autoApply to.

    - "apiSchemaCanOnlyApplyTo": If specified, the API schema generated

    from the sdrNode can only be validly applied to this set of schemas.

    - "providesUsdShadeConnectableAPIBehavior": Used to enable a

    connectability behavior for an API schema.

    - "isUsdShadeContainer": Only used when

    providesUsdShadeConnectableAPIBehavior is set to true. Marks the connectable prim as a UsdShade container type.

    - "requiresUsdShadeEncapsulation": Only used when

    providesUsdShadeConnectableAPIBehavior is set to true. Configures the UsdShade encapsulation rules governing its connectableBehavior.

    - "tfTypeNameSuffix": Class name which will get registered with TfType

    system. This gets appended to the domain name to register with TfType.

    - "schemaPropertyNSPrefixOverride": Node level metadata which can drive

    all node's properties namespace prefix. This can be useful for non connectable nodes which should not get UsdShade inputs and outputs namespace prefix.

  Property Level Metadata:

    - "usdVariability": Property level metadata which specifies a specific

    sdrNodeProperty should have its USD variability set to Uniform or Varying

    - "usdSuppressProperty": A property level metadata which determines if

    the property should be suppressed from translation from args to property spec.

    - "propertyNSPrefixOverride": Provides a way to override a property's

    namespace from the default (inputs:/outputs:) or from a node's schemaPropertyNSPrefixOverride metadata.

Sdr Property Metadata to SdfPropertySpec Translations

    - A "null" value for Widget SdrShaderProperty metadata translates to

    'hidden' in the SdfPropertySpec's uiHints metadata dictionary.

    - SdrShaderProperty's Help metadata (Label metadata if Help metadata not

    provided) translates to the SdfPropertySpec's userDocBrief and userDoc custom metadata strings.

    - SdrShaderProperty's Page metadata translates to 'displayGroup'

    in the SdfPropertySpec's uiHints metadata dictionary.

    - SdrShaderProperty's Label metadata translates to 'displayName'

    in the SdfPropertySpec's uiHints metadata dictionary.

    - SdrShaderProperty's Options translates to either 'allowedTokens'

    (when either labels or values are provided) or 'valueLabels' (when both labels and values are provided) in the SdfPropertySpec's uiHints metadata dictionary. For backwards compatibility, set USD_POPULATE_LEGACY_ALLOWED_TOKENS to write allowedTokens in addition to valueLabels for string- and token-valued attributes that provide both labels and values.

    - SdrShaderProperty's Default value translates to the SdfPropertySpec's

    Default value.

    - Connectable input properties translates to InterfaceOnly

    SdfPropertySpec's CONNECTABILITY.

  positional arguments:

schemaConfig
    A json config providing sdrNodes via sourceType, sdrNodeIdentifiers or explicit list of absolute asset file paths (sourceAssetNodes). Note that for nodes specified under sourceAssetNodes we will use the basename stripped of extension as the shaderId for nodes we create. If node paths specified in sourceAssetNodes contain any environment variables, user is required to set these prior to running the script. And also optionally providing a list of sublayers which the schema.usda will sublayer. Code generation can also be optionally enabled via the json config, note that code generation is disabled by default. [Default: ./schemaConfig.json]'). Example json config file:

{   "sdrNodes": {

"renderContext": "myRenderContext",
    "sourceType": [

"sdrIdentifier1",
    "sdrIdentifier2", "sdrIdentifier3"

],  "sourceAssetNodes": [

"/absolutepath/to/sdrNodeIdentifyingAsset1.extension,
    "/absolutepath/to/sdrNodeIdentifyingAsset1.extension,

],  }, "sublayers": [

"usd/schema.usda",
    "usdGeom/schema.usda", "usdLux/schema.usda" ],

"skipCodeGeneration": True
    }

schemaGenerationPath
    The target directory where the code should be generated. The script assumes a basic schema.usda is defined at this location with a GLOBAL prim configured with appropriate libraryName. [Default: .]

  options:

-h, --help
    show this help message and exit

--noreadme
    When specified a README.md will not be created in the schemaGenerationPath explaining the source of the contents of this directory.

-v, --validate
    This is passed to usdGenSchem to verify that the source files are unchanged.