Rules and Conventions

Overview

Open Shading Language (OSL) is a specifically designed language for programmable shading in modern physically based render engines. Originally developed by Sony Pictures Imageworks, it has become an industry standard for VFX (visual effects) and animation productions.

The official homepage can be found at Open Shading Language

Basics

OSL provides a high level API for shader authoring and is an alternative to writing C++ shader. It has a C-like syntax, similar to other shader languages and uses the LLVM compiler framework to optimize and translate on-the-fly shader networks into machine code.

OSL shader are source code files written into an .osl file representing a single shader node. They have to be compiled with the shader-compiler oslc to binary .oso files which then have to be placed in the shader search path. The oslc command line compiler can be found in the /bin directory of the appleseed installation.
Here is an example of manual invocation of oslc to compile the as_gama.osl_ source code file.

$ oslc as_gamma.osl
Compiled as_gamma.osl -> as_gamma.oso

Structure

The language structure is described in detail in the OSL Language Specifications

A simple example of a gamma correction shader gamma.osl. The input color Cin is processed and passed to the output Cout.

shader gamma(
    color Cin = color(0, 0, 0),
    float exponent = 1,
    output color Cout = color(0, 0, 0))
{
    Cout = pow(Cin, 1/exponent);
}

Specific Requirements

• All shaders must have unique names.
• appleseed shader names are prefixed with as_
• The shader name and the name of the *.osl file must match.
• Input parameter names should be prefixed with in and output parameter ones with out.
• Parameter names follow the standard Autodesk Maya expects for its attributes and are in camel case (e.g. float in_foo_bar translates to: fooBar)
• Maya attribute names cannot have spaces between them.
• Maya short attribute names are 3 characters max.

Metadata

For OSL shader to be workable in appleseed specific metadata (annotations which describe the shader to the host application) need to be added. They don't influence the execution of the shader but are necessary to generate the user interface elements of the shader nodes in the supported host applications (Autodesk Max, Autodesk Maya, Blender, Image Engine's Gaffer).
Metadata are specified inside double brackets [[ and ]] enclosing a comma-separated list of items.

Example of metadata for the as_asc_cdl.osl shader:

shader as_asc_cdl
[[
    string icon = "asAscCdl.png",
    string help = "Slope/Offset/Power Color Decision List utility shader according to the American Society of Cinematographers",
    string URL = "https://appleseed.readthedocs.io/projects/appleseed-maya/en/latest/shaders/utilities/as_asc_cdl.html#label-as-asc-cdl",
    
    string as_node_name = "asAscCdl",
    string as_category = "utility",
    
    string as_max_class_id = "1669361528 687027596", 
    string as_max_plugin_type = "texture",
    
    int as_maya_type_id = 0x00127a07,
    string as_maya_classification = "drawdb/shader:rendernode/appleseed/utility"
]]

The minimal required metadata are:

string as_node_name = "name_of_the_shader",
string as_category = "utility" or "material",
int as_maya_type_id = 0x00xxxxxx,
string as_maya_classification = "drawdb/shader:rendernode/appleseed/utility"

The type of Maya node classification follows the official standard Maya shading nodes classification

Metadata can be added to the input & output specifier depending on the data type. See section 4.3 Shader metadata in the official OSL documentation.

float in_slope = 1.0
    [[
        string as_maya_attribute_name = "slope",
        string as_maya_attribute_short_name = "slo",
        float min = 0.0,
        float max = 10000.0,
        float softmin = 0.0,
        float softmax = 10.0,
        string label = "Slope",
        string page = "Correction",
        string help = "Slope (adjusts the highlights).",
    ]]

Additionally, Maya requires that shading nodes must have an outColor or outValue attribute. Therefore output closure parameter need to have following metadata specified:

[[
    string as_maya_attribute_name = "outColor",
    string as_maya_attribute_short_name = "oc"
]]

An example of a valid output color declaration is below:

output color out_outColor = color(0)
    [[
        string as_maya_attribute_name = "outColor",
        string as_maya_attribute_short_name = "oc",
        string label = "Output Color",
        string page = "Output",
        string widget = "null"
    ]]

Please consult the appleseed shader OSL source files in ( https://github.com/appleseedhq/appleseed/tree/master/src/appleseed.shaders/src/appleseed ) for further implementation details.