10.10.4.9. Macro

Macros can be used in settings and mutable attributes in certain ways to retrieve a value from another setting or mutable attribute. The are 3 types of macros, ${string macros}, $[value macros] and $(reference macros).

${string macro}

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

For example, we 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 will be 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 output description file, it will show up as

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, instead of a string. Another difference is that after evaluation, it will 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, specially, seed works in a way that every frame has 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 2, 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] retrives value from the global settings.

Using macros, we are able to describe complex scenes that has 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