Templating Tutorial

At it's simplest the smart_batch command can be called as a drop in replacement for the standard batch command. It takes the same arguments as batch and returns the same result. EG: To set a camera instance transform and resolution in one call you can use:

Example: Mimicking normal batch command.

{
    "method": "smart_batch",
    "params": {
        "commands": [
            {
                "name": "instance_set_world_to_obj",
                "params" : {
                    "instance_name": "cam_inst",
                    "transform": {
                        "xx": 1, "xy": 0, "xz": 0, "xw": 0,
                        "yx": 0, "yy": 1, "yz": 0, "yw": 0,
                        "zx": 0, "zy": 0, "zz": 1, "zw": 0,
                        "wx": 2, "wy": -3, "wz": -10, "ww": 1
                    }
                }
            },
            {
                "name": "camera_set_resolution",
                "params" : {
                    "camera_name": "cam",
                    "resolution": {
                        "x": 500,
                        "y": 500
                    }
                }
            },
            {
                "name": "camera_set_aspect",
                "params" : {
                    "camera_name": "cam",
                    "aspect": 1
                }
            }
        ]
    }
}

Environment

The power of the smart_batch command comes in with the specification of an environment. The environment is specified alongside the commands parameter and provides a set of environment variables which can be substituted into command parameters using ${var_name} notation. For example:

Example: Use environment to provide names

{
    "method": "smart_batch",
    "params": {
        "environment": {
            "camera_instance": "cam_inst",
            "camera": "cam"
        },
        "commands": [
            {
                "name": "instance_set_world_to_obj",
                "params" : {
                    "instance_name": "${camera_instance}",
                    "transform": {
                        "xx": 1, "xy": 0, "xz": 0, "xw": 0,
                        "yx": 0, "yy": 1, "yz": 0, "yw": 0,
                        "zx": 0, "zy": 0, "zz": 1, "zw": 0,
                        "wx": 2, "wy": -3, "wz": -10, "ww": 1
                    }
                }
            },
            {
                "name": "camera_set_resolution",
                "params" : {
                    "camera_name": "${camera}",
                    "resolution": {
                        "x": 500,
                        "y": 500
                    }
                }
            },
            {
                "name": "camera_set_aspect",
                "params" : {
                    "camera_name": "${camera}",
                    "aspect": 1
                }
            }
        ]
    }
}

This static substitution can be especially useful to define command templates on a client.

Note that environment values can be any type, not just strings.

Dynamic Environment

The environment can also be dynamically updated by commands. In this example the client needs to know both the camera instance and camera name. However, the camera name can be queried from the instance using the instance_get_item command. If an id is given with a command then the command result is added to the environment and can be used by subsequent commands.

Example: Dynamically discover camera name

{
    "method": "smart_batch",
    "params": {
        "environment": {
            "camera_instance": "cam_inst"
        },
        "commands": [
            {
                "name": "instance_set_world_to_obj",
                "params" : {
                    "instance_name": "${camera_instance}",
                    "transform": {
                        "xx": 1, "xy": 0, "xz": 0, "xw": 0,
                        "yx": 0, "yy": 1, "yz": 0, "yw": 0,
                        "zx": 0, "zy": 0, "zz": 1, "zw": 0,
                        "wx": 2, "wy": -3, "wz": -10, "ww": 1
                    }
                }
            },
            {
                "name": "instance_get_item",
                "params" : {
                    "instance_name": "${camera_instance}"
                },
                "id": "camera"
            },
            {
                "name": "camera_set_resolution",
                "params" : {
                    "camera_name": "${camera}",
                    "resolution": {
                        "x": 500,
                        "y": 500
                    }
                }
            },
            {
                "name": "camera_set_aspect",
                "params" : {
                    "camera_name": "${camera}",
                    "aspect": 1
                }
            }
        ]
    }
}

Here, the instance_get_item command writes it's result into the environment variable camera where it is used by camera_set_resolution and camera_set_aspect.

Environment lookups can also use dot notation to step into objects to find values. We can use this to provide the scene name to obtain the camera from rather than the camera instance.

Example: Setting on scene

{
    "method": "smart_batch",
    "params": {
        "environment": {
            "scene_name": "my_scene"
        },
        "commands": [
            {
                "name": "get_scene",
                "params": {
                    "scene_name": "${scene_name}"
                },
                "id": "scene"
            },
            {
                "name": "instance_get_item",
                "params" : {
                    "instance_name": "${scene.camera_instance}"
                },
                "id": "camera"
            },
            {
                "name": "instance_set_world_to_obj",
                "params" : {
                    "instance_name": "${scene.camera_instance}",
                    "transform": {
                        "xx": 1, "xy": 0, "xz": 0, "xw": 0,
                        "yx": 0, "yy": 1, "yz": 0, "yw": 0,
                        "zx": 0, "zy": 0, "zz": 1, "zw": 0,
                        "wx": 2, "wy": -3, "wz": -10, "ww": 1
                    }
                }
            },
            {
                "name": "camera_set_resolution",
                "params" : {
                    "camera_name": "${camera}",
                    "resolution": {
                        "x": 500,
                        "y": 500
                    }
                }
            },
            {
                "name": "camera_set_aspect",
                "params" : {
                    "camera_name": "${camera}",
                    "aspect": 1
                }
            }
        ]
    }
}

Return values

In addition to the command responses smart_batch also returns the final environment.

Example: Response

{
    "result": {
        "environment": {
            "scene_name": "my_scene",
            "scene": {
                "camera_instance": "cam_inst",
                "options": "opt",
                "root_group": "rootgroup"
            },
            "camera": "cam"
        },
        "responses": [
            { "result": {
                    "camera_instance": "cam_inst",
                    "options": "opt",
                    "root_group": "rootgroup"
              }
            },
            { "result": "cam" },
            { "result": {} },
            { "result": {} },
            { "result": {} },
        ],
        "has_sub_error_response": false
    }
}