A stylesheet is a collection of styles. A style contains target conditions that match certain primitives, and instructions for how to change the material and/or material parameters on the matching primitives. For example, you could create a style that essentially says "In the char1 object, in the skin packed primitive, on faces in the shirt group, change the diffuse color to blue".

• Stylesheets are a workaround for the limitation that you can’t select and apply materials to geometry inside a packed primitive. Instead, you must "target" the packed geometry with a style to set/change its materials.

• Stylesheets can target geometry that is only "real" at render time. They let you apply material changes (including scripted/random changes) to instanced geometry and agents at render time. This gives you the benefit of instancing the same geometry, but still allows you to make the instances look different.

• Stylesheets can let you change looks without having to edit the geometry or regenerate the scene description (IFD) file. This may be useful for studios working with huge scenes, where a quick tweak with a stylesheet might be faster than regenerating a huge IFD.

You can apply stylesheets at different levels:

• Stylesheet specified on the Mantra command line using the -S option.

• You can save stylesheets in a scene (.hip) file that can target any geometry in the file.

• You can add a stylesheet parameter to a Houdini object that can target any geometry inside the object.

• You can specify a stylesheet on primitives using a material_stylesheet attribute. On a packed primitive, this can target the packed geometry inside.

Each level can target geometry at lower levels.

If two levels target the same geometry, the higher level stylesheet overrides the lower level. This ordering has a few advantages:

• A stylesheet on a packed primitive can override any material assignments/parameters on the geometry inside.

• It lets you override anything at render time by specifying a top-level stylesheet at the command line. This can be useful for huge scenes because you can change material assignments and parameters without having to regenerate the IFD.

Styles listed later in a stylesheet override styles listed earlier.

The viewport shows stylesheet material assignments and overrides on geometry. You can use controls in the viewport display options to enable or disable certain stylesheet features (overrides, packed primitive targets) or turn off stylesheet display completely.

There are some limitations to stylesheet display in the viewport:

• The effects of stylesheets are only visible in the viewport if the stylesheet assigns a material – or overrides a material parameter – with a GL tag.

• By default, the viewport will only display up to 100 materials on a single object to keep the display responsive. You can change this limit in the display options window’s Optimize tab.

• Materials defined "on the fly" in a stylesheet do not appear in the viewport.

• The viewport will update when the stylesheet changes. However, Houdini will not detect changes to any external scripts or CVEX nodes referenced by the stylesheet. To manually update the display, right click the View Materials button on the display options toolbar (to the right of the viewer) and choose Update stylesheets.

  (Alternatively you can click the Update button on the display options window’s Optimize tab.)

• The viewport cannot currently show material changes for stylesheets that change the target per packed instance if the target is within the packed primitive, when there are more than one of that instance.

The target part of a style specifies which geometry to apply the style’s overrides to.

A target can contain four items:

A target can have the following conditions. If you have multiple conditions, the must all match. If you have no conditions, the style matches everything.

The overrides of a style specifies how to change the material assigned to the matched geometry. You can assign a new material, and/or change parameter values on the material. You can also specify a CVEX script to compute the override values instead of using static values.

A style can contain different types of overrides. Each override type can be set using a constant value for all targeted geometry, or as a CVEX script that gets run for each targeted component to calculate that component’s value.

A script can "bind" the value of attributes on the matched geometry to named arguments of the CVEX function.

Higher target levels in a targeting hierarchy can also bind the value of attributes at that level. You can then make those bound data available as arguments to the CVEX script.

For example, suppose a style targets packed primitives 1 and 2, and a sub-target matches the color_prims group inside the packed primitive. If you use a parameter override script, Mantra will run the script for each primitive in color_prims. You might need the script to know the primitive number of the packed primitive. To accomplish this, you can bind the value of the intrinsic:indexorder attribute to the name top_level_prim in the top target. When the script is called, Mantra will pass it a top_level_prim argument containing the packed primitive number.

The importFiles top-level key maps to a list of strings representing stylesheet locations (file paths or URLs). The data from these files are included in the current stylesheet. Shared scripts and override sets in the current file will override things with the same name in included stylesheets.

{
    "importFiles" : [ "mss/main_style.json", "prim_style.json" ]
}

The scriptDefinitions top-level key maps to an object mapping shared script names to script objects.

{
    "scriptDefinitions" : {
        "mss_shared_script" : {
            "code" : "cvex mySharedFn(int packed_id=0; int unpacked_id=0; export vector c={0,0,0}) { c.r = 0.3 * float(packed_id); c.g = 0.2 * float(unpacked_id); }",
            "bindings": {
                "unpacked_id" : "intrinsic:indexorder",
                "packed_id" : "top_level_prim"
            }
        }
    }
}

Theoretically, you can define materials inside a stylesheet. This would allow you to make a self-contained stylesheet that could introduce new materials into an already-generated IFD file. In practice, this requires that you know enough about IFD to write a raw IFD shader string.

Additionally, the VEX code to define the material’s surface or displacement shader can be embedded into the material definition. This requires using the reserved shader names "mss:surface_shader" or "mss:displace_shader" depending on the type of shader. The VEX code is then added as a property with that same name to the material definition. Again, this is most likely to be useful in a large pipeline where style sheets can be generated automatically by python scripts, rather than created manually.

{
    "materialDefinitions" : {
        "mss_const_mat" : {
            "properties" : {
                "surface" : "opdef:/Shop/v_constant clr 0.1 0.1 0.8",
                "displace" : "mss:displace_shader parm 0 0 1",
                "mss:displace_shader" : "displace disp1(vector parm=0) { P = P
+ parm; }"
            }
        }
    }
}

The styles top-level key maps to a list of style objects.

A style object can have the following keys:

• target: target object

• overrides: overrides object

{
    "styles" : [
        {
            "target" : {
                "type": "self",
                "objectName" : "/obj/colored_object"
            },
            "overrides" : {
                "material" : {
                    "name" : "mss_const_mat"
                },
                "materialParameters" : {
                    "clr" : [ 0.8, 0.1, 0.2 ]
                }
            }
        }
    ]
}

{
    "target" : {
        "group" : "1 2",
        "preBindings" : {
            "top_level_prim" : "intrinsic:indexorder"
        },
        "subTarget" : {
            "subTarget" : {
                "group" : "color_prims"
            }
        }
    },
    "overrides" : {
        "materialParameters" : {
            "clr" : {
                "script" : { "importScript" : "mss_shared_script" }
            }
        }
    }
}

A target object specifies which entities the style will affect. See targeting geometry.

It can have the following keys:

{
    "target" : { "group" : "0 5 10 some_group" }
}

{
    "target" : { "group" : "@Cd.r>0.5" }
}

{
    "target" : {
        "group" : "0",
        "subTarget" : {
            "group": "10"
        }
    }
}

An overrides object specifies how to change the material on the primitives targeted by a style. See overrides.

An overrides object can have the following keys:

{
    "material" : {
        "name" : "/shop/material1"
    },
    "materialParameters" : {
        "clr" : [ 0.8, 0.1, 0.2 ],
        "reflect": 0.5,
    }
}

The values inside the three keys can be a literal value (a string, number, or array), or an object like {"script": script object}, where the value of the script key is a script object referencing a CVEX script to use to compute the value. See using CVEX scripts.

{
    "materialParameters" : {
        "clr" : {
            "script" : { "importScript" : "mss_shared_script" }
        }
    }
}

See how to use CVEX scripts. The object has the following keys:

{
    "command" : "$HIP/cvex/recolor.vex",
    "bindings": {
        "unpacked_id" : "intrinsic:indexorder",
        "packed_id" : "top_level_prim"
    }
}

A bindings object maps function arguments to attributes or other values by name. The keys in the object represent the function argument names. The stylesheet format supports a few different binding methods for the values.

The default binding style associates an argument name with an attribute name (note that this can include intrinsic attributes). The value is a string naming an attribute. If no attribute with the given name is found, it looks for a target binding by that name.

Alternatively you can specify a different type of binding using an object instead of a string. This object has a sourceType key that determines the binding method:

"bindings": {
    "foo": {
        "sourceType": "default",
        "name": "P"
    },
    "bar": {
        "sourceType": "default",
        "name": "intrinsic:indexorder"
    }
}

"bindings": {
    "foo": {
        "sourceType": "preBinding",
        "name": "aTargetName"
    }
}

"bindings": {
    "stringArg": {
        "sourceType": "constant",
        "value": "string"
    },
    "intArg": {
        "sourceType": "constant",
        "value": 23
    },
    "vectorArg": {
        "sourceType": "constant",
        "value": [1.0, 1.0, 2.0]
    }
}