Macro

Macros can be used in settings and mutable attributes in certain ways to retrieve a value from another setting or mutable attribute. The three types of macros are:

• ${string macros}

• $[value macros]

• $(reference macros)

${string macro}

This macro supports substitution of strings. The value is evaluated as the actual value during runtime, while substituted back to macro form to be saved to the output description file in the logging stage.

For example, you can define a macro for the path to load a USD file:

resources_root: [PATH_TO_MAIN_OBJECTS]
main_object:
  ...
  usd_path:
    distribution_type: folder
    suffix: usd
    value: ${resources_root}/main_objects

At runtime, the folder to sample from is resolved as [PATH_TO_MAIN_OBJECTS]/main_objects, so that usd_path is [PATH_TO_MAIN_OBJECTS]/main_objects/[SAMPLED_FILE].usd While in the logging stage, when main_object is written to the output description file:

resources_root: [PATH_TO_MAIN_OBJECTS]
main_object:
  ...
  usd_path: ${resources_root}/[SAMPLED_FILE].usd

$[value macro]

Value macro substitutes a numeric value from the scope it’s in. After evaluation, it does not go back to the macro form in the logging stage.

A scope of the value macro consists of the global settings of the description file and the attributes of the mutable that the value macro is in.

For global settings, seed allows every frame to have a specific seed and frame refers to the frame index.

For example:

seed: 3
penguin:
  ...
  count: 2
  transform_operators:
  - rotateY: ($[index] + $[seed]) % $[count] * 60

At frame two, this is equivalent to:

seed: 5
penguin_0:
  ...
  count: 2
  index: 0
  transform_operators:
  - rotateY: (0 + 5) % 2 * 60
penguin_1:
  ...
  count: 2
  index: 1
  transform_operators:
  - rotateY: (1 + 5) % 2 * 60

Here, $[index] and $[count] retrieve values from the local scope of the mutable they are in, while $[seed] retrieves values from the global settings.

Using macros, you can describe complex scenes that have a combination of randomized transform operators for each mutable.

$(reference macro)

Reference macro substitutes the whole value from the scope it is in. For example:

screen_width: 960
screen_height: 544
camera_parameters:
  far_clip: 100000
  focal_length: $(focal_length)
  horizontal_aperture: $(horizontal_aperture)
  near_clip: 0.1
  screen_height: $(screen_height)
  screen_width: $(screen_width)
default_camera:
  type: camera
  camera_parameters: $(camera_parameters)

Evaluates to:

screen_width: 960
screen_height: 544
camera_parameters:
  focal_length: 14.228393962367306
  horizontal_aperture: 20.955
  near_clip: 0.1
  far_clip: 100000
  screen_width: 960
  screen_height: 544
default_camera:
  type: camera
  camera_parameters:
    focal_length: 14.228393962367306
    horizontal_aperture: 20.955
    near_clip: 0.1
    far_clip: 100000
    screen_width: 960
    screen_height: 544