Open Shading Language

https://open-shading-language.readthedocs.io/en/latest
Admin
Open Shading Language (OSL) is a small but rich language for programmable shading in advanced...
Tokens:59,534
Snippets:552
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### OSL Shader Group Definition Example

Source: https://open-shading-language.readthedocs.io/en/latest/shadergroups

This example demonstrates the syntax for defining a shader group in Open Shading Language. It shows how to set parameter values using `param`, declare shader instances using `shader`, and connect shader outputs to inputs using `connect`. This is a standard way to serialize a full shader group, including instance values and connectivity.

```osl
param string name "rings.tx" ;      # set pending `name'
param float scale 3.5 ;             # set pending `scale'
shader "texturemap" "tex1" ;        # tex1 layer, picks up `name', `scale'
param string name "grain.tx" ;
shader "texturemap" "tex2" ;
param float gam 2.2 ;
shader "gamma" "gam1" ;
param float gam 1.0 ;
shader "gamma" "gam2" ;
param color woodcolor 0.42 0.38 0.22 ;       # example of a color param
shader "wood" "wood1" ;
connect tex1.Cout gam1.Cin ;        # connect tex1's Cout to gam1's Cin
connect tex2.Cout gam2.Cin ;
connect gam1.Cout wood1.rings ;
connect gam2.Cout wood1.grain ;

```

--------------------------------

### OSL Shader with Metadata Example

Source: https://open-shading-language.readthedocs.io/en/latest/grosssyntax

This example demonstrates how to declare metadata for an OSL shader and its parameters. Metadata is used to provide hints for UI elements, such as help text, value ranges, and widget types. The metadata is embedded within the shader code inside double brackets `[[ ]]`.

```osl
surface wood 
            [[ string help = "Realistic wood shader" ]]
    ( 
       float Kd = 0.5
           [[ string help = "Diffuse reflectivity",
              float min = 0, float max = 1 ]] ,
       color woodcolor = color (.7, .5, .3)
           [[ string help = "Base color of the wood" ]],
       color ringcolor = 0.25 * woodcolor
           [[ string help = "Color of the dark rings" ]],
       string texturename = "wood.tx"
           [[ string help = "Texture map for the grain",
              string widget = "filename" ]],
       int pattern = 0
           [[ string widget = "mapper",
              string options = "oak:0|elm:1|walnut:2" ]]
    )
{
   ... 
}
```

--------------------------------

### OSL Shader Declaration Example

Source: https://open-shading-language.readthedocs.io/en/latest/grosssyntax

A comprehensive example of an OSL shader declaration ('surface wood'). It showcases various parameter types including simple parameters, computed parameters, fixed-length arrays, variable-length arrays, and an output parameter.

```OSL
surface wood (
           /* Simple params with constant initializers */
               float Kd = 0.5,
               color woodcolor = color (.7, .5, .3),
               string texturename = "wood.tx",
           /* Computed from an earlier parameter */
               color ringcolor = 0.25 * woodcolor,
           /* Fixed-length array */
               color paintcolors[3] = { color(0,.25,0.7), color(1,1,1),
                                        color(0.75,0.5,0.2) },
           /* variable-length array */
               int pattern[] = { 2, 4, 2, 1 },
           /* output parameter */
               output color Cunlit = 0
             )
{
   ...
}
```

--------------------------------

### OSL: Array Declaration Examples

Source: https://open-shading-language.readthedocs.io/en/latest/syntax

Shows how to declare arrays in OSL. This includes declaring uninitialized arrays with a fixed size and initializing arrays with a list of values during declaration. Array lengths must be constant.

```OSL
float d[10];                       // Declare an uninitialized array
float c[3] = { 0.1, 0.2, 3.14 };   // Initialize the array
```

--------------------------------

### Check if string starts with a prefix (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

The `startswith` function checks if a string `s` begins with a specified `prefix` substring. It returns 1 if it does, and 0 otherwise.

```OSL
int startswith(string s, string prefix)
```

--------------------------------

### OSL: Variable Declaration Examples

Source: https://open-shading-language.readthedocs.io/en/latest/syntax

Illustrates various ways to declare variables in OSL. This includes simple declarations, initialization with constants or computed values, and declaring multiple variables of the same type in a single statement.

```OSL
float a;           // Declare; current value is undefined
float b = 1;       // Declare and assign a constant initializer
float c = a*b;     // Computed initializer
float d, e = 2, f; // Declare several variables of the same type
```

--------------------------------

### OSL Type Casting Examples

Source: https://open-shading-language.readthedocs.io/en/latest/syntax

Illustrates type casting in OSL using both C-style (parentheses) and C++-style (constructor) syntax. This allows conversion between compatible data types like points, vectors, colors, and floats.

```osl
vector (P)            /* Means the same thing */
point (f)
color (P)

```

--------------------------------

### Surface Shader Example: Calculating Color with Texture and Diffuse

Source: https://open-shading-language.readthedocs.io/en/latest/bigpicture

This OSL code snippet demonstrates a basic surface shader. It samples a texture to get a 'paint' color and then combines it with a diffuse closure using the surface normal (N) to compute the final surface appearance (Ci). The 'diffuse(N)' function returns a color closure, representing a parameterized formula for light reflection.

```OSL
color paint = texture ("file.tx", u, v);
Ci = paint * diffuse (N);
```

--------------------------------

### OSL: Structure Declaration and Usage Examples

Source: https://open-shading-language.readthedocs.io/en/latest/syntax

Demonstrates the definition and usage of structures in OSL. This includes defining a structure type, declaring structure variables, initializing them, and accessing individual fields using the dot operator.

```OSL
struct ray {
    point pos;
    vector dir;
};

ray r;   // Declare a structure
ray s = { point(0,0,0), vector(0,0,1) };  // declare and initialize
r.pos = point (1, 0, 0);  // Assign to one field
```

--------------------------------

### Ray Tracing with Options in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Traces a ray from a starting position in a given direction. Returns 1 if any geometry is hit within the distance range, 0 otherwise. Supports optional arguments for minimum/maximum distance, shading control, and specifying trace sets.

```OSL
int trace(point pos, vector dir, ...)
// Optional arguments:
// "mindist", float
// "maxdist", float
// "shade", int
// "traceset", string
```

--------------------------------

### Mapper Widget Metadata Example - OSL

Source: https://open-shading-language.readthedocs.io/en/latest/grosssyntax

This OSL code snippet demonstrates how to use the 'mapper' widget metadata for an integer parameter. This is useful for enumerated types where integer values correspond to specific choices. The 'options' metadata provides key-value pairs, separated by '|', where keys are user-friendly names and values are the corresponding integers.

```osl
int pattern = 0
      [[ string widget = "mapper",
         string options = "oak:0|elm:1|walnut:2" ]]
```

--------------------------------

### OSL: Scoping Example

Source: https://open-shading-language.readthedocs.io/en/latest/syntax

Demonstrates variable scoping in OSL. Variables declared within an inner scope are only accessible within that scope, while variables from outer scopes are accessible unless shadowed. This example shows how 'a' is shadowed and 'c' is out of scope after the inner block.

```OSL
float a = 1;      // Call this the "outer" 'a'
float b = 2;
{
    float a = 3;  // Call this the "inner" 'a'
    float c = 1;
    b = a;        // b gets 3, because a is resolved to the inner scope
}
b += c;           // ERROR -- c was only in the inner scope
```

--------------------------------

### Popup Widget Metadata Example - OSL

Source: https://open-shading-language.readthedocs.io/en/latest/grosssyntax

This OSL code snippet illustrates the usage of the 'popup' widget metadata for a string parameter. It specifies a list of options for a dropdown menu, along with an optional 'editable' flag. The 'options' metadata is a string where menu items are delimited by the '|' character.

```osl
string wrap = "default"
      [[ string widget = "popup",
         string options = "default|black|clamp|periodic|mirror" ]]
```

--------------------------------

### Get Blackbody Emission with `blackbody`

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Returns the blackbody emission of an object given its temperature in Kelvin. The output is in W/m², and may require scaling factors for radiance units.

```openshadinglanguage
color blackbody(float temperatureK)
```

--------------------------------

### Get Transformation Matrix with `getmatrix`

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Retrieves the matrix that transforms coordinates from a source space to a destination space. It returns success status and modifies an output matrix parameter.

```openshadinglanguage
int getmatrix(string fromspace, string tospace, output matrix M)
```

--------------------------------

### Single-line Comments in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/lexical

Shows the syntax for single-line comments in OSL, which start with '//' and extend to the end of the current line. This is useful for brief explanations or temporarily disabling code.

```osl
// This is a comment
a = 3;   // another comment

```

--------------------------------

### Unit Conversion Example with transformu()

Source: https://open-shading-language.readthedocs.io/en/latest/bigpicture

This code snippet shows a direct application of the transformu() function to determine the number of millimeters per unit of 'object' space. It converts a unit value from 'object' space to 'mm', illustrating the function's ability to handle named coordinate systems and unit conversions.

```osl
float x = transformu ("object", "mm", 1);

```

--------------------------------

### Valid and Invalid Identifiers in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/lexical

Illustrates the rules for creating valid identifiers in OSL, which are used for naming variables, parameters, functions, and shaders. Identifiers must start with a letter or underscore and can subsequently contain letters, underscores, or numbers. Examples show correct and incorrect usage.

```osl
opacity       // valid
Long_name42   // valid - letters, underscores, numbers are ok
_foo          // valid - ok to start with an underscore

2smart        // invalid - starts with a numeral
bigbuck$      // invalid - $ is an illegal character

```

--------------------------------

### Initializing `color` Variables in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Demonstrates various ways to initialize `color` variables in Open Shading Language. This includes creating colors from three floats, a single float, or by specifying a color space like 'rgb' or 'hsv'. Colors can also be initialized by assigning a float value, which is then replicated across all three components.

```OSL
color (0, 0, 0)              // black
color ("rgb", .75, .5, .5)   // pinkish
color ("hsv", .2, .5, .63)   // specify in "hsv" space
color (0.5)                  // same as color (0.5, 0.5, 0.5)
```

--------------------------------

### Extract substring from a string (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

The `substr` function extracts a portion of a string `s`. It takes a starting index `start` and an optional `length`. If `length` is omitted, it returns the rest of the string from `start`. Negative `start` values count from the end of the string.

```OSL
string substr(string s, int start, int length)
string substr(string s, int start)
```

--------------------------------

### Declare OSL Output Parameters

Source: https://open-shading-language.readthedocs.io/en/latest/grosssyntax

Demonstrates the syntax for declaring output parameters in OSL using the 'output' keyword. These parameters can be modified within the shader and used for returning values.

```OSL
output type parametername = expr
```

--------------------------------

### Shader Group Assembly using API

Source: https://open-shading-language.readthedocs.io/en/latest/bigpicture

Demonstrates how to assemble a shader group using a renderer's API. It shows the sequence of calls to define shaders, set parameters, and connect shader outputs to inputs.

```pseudocode
ShaderGroupBegin ()
    Shader ("texturemap",               /* shader name */
            "tex1",                     /* layer name */
            "string name", "rings.tx")  /* instance variable */
    Shader ("texturemap", "tex2", "string name", "grain.tx")
    Shader ("gamma", "gam1", "float gam", 2.2)
    Shader ("gamma", "gam2", "float gam", 1)
    Shader ("wood", "wood1")
    ConnectShaders ("tex1",     /* layer name A */
                    "Cout",     /* an output parameter of A */
                    "gam1",     /* layer name B */
                    "Cin")      /* Connect this layer of B to A's Cout */
    ConnectShaders ("tex2", "Cout", "gam2", "Cin")
    ConnectShaders ("gam1", "Cout", "wood1", "rings")
    ConnectShaders ("gam2", "Cout", "wood1", "grain")
    ShaderGroupEnd ()

```

--------------------------------

### String Manipulation

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Functions for concatenating strings, getting their length, checking for prefixes/suffixes, and extracting substrings.

```APIDOC
## concat

### Description
Concatenates a list of strings into a single aggregate string.

### Method
`string concat(string s1, ..., string sN)`

### Parameters
- **s1, ..., sN** (string) - Required - The strings to concatenate.

### Response Example
```json
{
  "concatenated_string": "exampleoutput"
}
```
```

```APIDOC
## strlen

### Description
Returns the number of characters in a given string.

### Method
`int strlen(string s)`

### Parameters
- **s** (string) - Required - The input string.

### Response Example
```json
{
  "length": 10
}
```
```

```APIDOC
## startswith

### Description
Checks if a string begins with a specified prefix.

### Method
`int startswith(string s, string prefix)`

### Parameters
- **s** (string) - Required - The string to check.
- **prefix** (string) - Required - The prefix to look for.

### Response Example
```json
{
  "starts_with": 1
}
```
```

```APIDOC
## endswith

### Description
Checks if a string ends with a specified suffix.

### Method
`int endswith(string s, string suffix)`

### Parameters
- **s** (string) - Required - The string to check.
- **suffix** (string) - Required - The suffix to look for.

### Response Example
```json
{
  "ends_with": 1
}
```
```

```APIDOC
## substr

### Description
Extracts a portion of a string.

### Method
`string substr(string s, int start, [int length])`

### Parameters
- **s** (string) - Required - The input string.
- **start** (int) - Required - The starting index (0-based).
- **length** (int) - Optional - The number of characters to extract.

### Response Example
```json
{
  "substring": "example"
}
```
```

--------------------------------

### Get Array Length in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Returns the number of elements in a given array. The array can be of any data type.

```OSL
int arraylength(type A[])
```

--------------------------------

### Declare and Initialize 1D Arrays in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Demonstrates how to declare and initialize 1D arrays in OSL. Arrays must be statically sized. Multi-dimensional arrays are not supported.

```osl
float d[10];                       // Declare an uninitialized array
float c[3] = { 0.1, 0.2, 3.14 };   // Initialize the array

float f = c[1];                    // Access one element

float d[10][3];                    // Invalid, multi-dimensional arrays not supported
```

--------------------------------

### Use arraylength() Function in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Shows how to use the built-in `arraylength()` function to get the number of elements in an OSL array. This function is essential for iterating over arrays.

```osl
float c[3];
int clen = arraylength(c);        // should return 3
```

--------------------------------

### Get string length (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

The `strlen` function returns the number of characters in a given string `s`. This is a fundamental operation for understanding string size.

```OSL
int strlen(string s)
```

--------------------------------

### Constructing Point-like Types in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Demonstrates how to create 'point', 'vector', and 'normal' data types in OSL using their respective constructors. These constructors can optionally specify the coordinate system for the new type.

```OSL
point (0, 2.3, 1)
vector (a, b, c)
normal (0, 0, 1)
```

```OSL
Q = point ("object", 0, 0, 0);
```

--------------------------------

### OSL Type Constructors

Source: https://open-shading-language.readthedocs.io/en/latest/syntax

Demonstrates the creation of color, point, and other multi-component types using constructor syntax in OSL. These can be used to initialize variables or define literal values.

```osl
color (1, 0.75, 0.5)
point ("object", 1, 2, 3)

```

--------------------------------

### Get character by index (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

The `getchar` function returns the numeric value of the character at a specific index `n` within a string `s`. If the index is invalid, it returns 0.

```OSL
int getchar(string s, int n)
```

--------------------------------

### Use Constructor Expressions for Structures in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Shows how to use constructor expressions for OSL structure types, similar to built-in types. This allows for concise initialization and return values from functions.

```osl
RGBA c = RGBA(col,alpha);        // Constructor syntax

RGBA add (RGBA a, RGBA b)
{
    return RGBA (a.rgb+b.rgb, a.a+b.a);   // return expression
}

// pass constructor expression as a parameter:
RGBA d = add (c, RGBA(color(.3,.4,.5), 0));
```

--------------------------------

### Deprecated Surface Closures (OSL 1.12+)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

These surface closure functions are deprecated starting from OSL 1.12 and will be removed in OSL 2.0. They represent various light scattering and transmission properties of surfaces.

```APIDOC
## Deprecated Surface Closures

These closures are deprecated as of OSL 1.12 and planned for removal in OSL 2.0.

### diffuse(normal N)

*   **Description**: Returns a closure color representing Lambertian diffuse reflectance of a smooth surface.
*   **Method**: N/A (Function call within shader code)
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None

### phong(normal N, float exponent)

*   **Description**: Returns a closure color representing specular reflectance using the Phong BRDF. `exponent` controls surface smoothness.
*   **Method**: N/A
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None

### oren_nayar(normal N, float sigma)

*   **Description**: Returns a closure color for diffuse reflectance of a rough surface using the Oren-Nayar model. `sigma` controls roughness.
*   **Method**: N/A
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None

### ward(normal N, vector T, float xrough, float yrough)

*   **Description**: Returns a closure color for anisotropic specular reflectance. `N` and `T` define local coordinates, `xrough` and `yrough` specify roughness.
*   **Method**: N/A
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None

### microfacet(string distribution, normal N, float alpha, float eta, int refract)

*   **Description**: Returns a closure color representing microfacet scattering. Simplified isotropic version.
*   **Method**: N/A
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None

### reflection(normal N, float eta)

*   **Description**: Returns a closure color for sharp mirror-like reflection. `eta` is the index of refraction.
*   **Method**: N/A
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None

### refraction(normal N, float eta)

*   **Description**: Returns a closure color for sharp glass-like refraction. `eta` is the ratio of indices of refraction.
*   **Method**: N/A
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None

### transparent()

*   **Description**: Returns a closure color that shows light behind the surface without refraction.
*   **Method**: N/A
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None

### translucent()

*   **Description**: Returns a closure color for Lambertian diffuse translucence, gathering light from the far side of the surface.
*   **Method**: N/A
*   **Endpoint**: N/A
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**: None
*   **Response**:
    *   **Success Response (200)**: `closure color`
*   **Response Example**: None
```

--------------------------------

### Get Ray Trace Hit Information in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Retrieves detailed information about the closest object hit by a ray traced with the `trace()` function. This uses the renderer's message passing mechanism.

```OSL
getmessage("trace", ...)
```

--------------------------------

### Declare Function Parameters and Shader Parameters as Arrays in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Illustrates how to declare array parameters for functions and shader parameters in OSL using empty brackets. This allows for dynamically sized arrays within these contexts.

```osl
float sum (float x[])
{
    float s = 0;
    for (int i = 0;  i < arraylength(x);  ++i)
        s += x[i];
    return s;
}
```

--------------------------------

### String Formatting and Output

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Functions for formatting strings similar to C's printf, with options for console output, returning as a string, error/warning reporting, and file output.

```APIDOC
## printf

### Description
Prints a formatted string to the console, similar to C's `printf`.

### Method
`void printf(string fmt, ...)`

### Parameters
- **fmt** (string) - Required - The format string.
- **...** - Variable arguments - Data to be formatted according to `fmt`.

### Response Example
(No direct response, output is to console)
```

```APIDOC
## format

### Description
Returns a formatted string, similar to C's `printf`, but instead of printing, it returns the result as a string.

### Method
`string format(string fmt, ...)`

### Parameters
- **fmt** (string) - Required - The format string.
- **...** - Variable arguments - Data to be formatted according to `fmt`.

### Response Example
```json
{
  "formatted_string": "example output"
}
```
```

```APIDOC
## error

### Description
Prints a formatted string as a renderer error message, potentially including diagnostic information.

### Method
`void error(string fmt, ...)`

### Parameters
- **fmt** (string) - Required - The format string.
- **...** - Variable arguments - Data to be formatted according to `fmt`.

### Response Example
(No direct response, output is to renderer errors)
```

```APIDOC
## warning

### Description
Prints a formatted string as a renderer warning message, potentially including diagnostic information.

### Method
`void warning(string fmt, ...)`

### Parameters
- **fmt** (string) - Required - The format string.
- **...** - Variable arguments - Data to be formatted according to `fmt`.

### Response Example
(No direct response, output is to renderer warnings)
```

```APIDOC
## fprintf

### Description
Concatenates a formatted string onto the end of a specified text file.

### Method
`void fprintf(string filename, string fmt, ...)`

### Parameters
- **filename** (string) - Required - The name of the file to append to.
- **fmt** (string) - Required - The format string.
- **...** - Variable arguments - Data to be formatted according to `fmt`.

### Response Example
(No direct response, output is to a file)
```

--------------------------------

### Constructing OSL Matrices

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Demonstrates various ways to construct `matrix` types in OSL. Matrices can be initialized with a single float (scaling the identity matrix), 16 floats (row-major order), or from coordinate system names. They can also be initialized to zero or the identity matrix.

```OSL
matrix zero = 0;
matrix ident = 1;

matrix m = matrix (m00, m01, m02, m03, m10, m11, m12, m13, 
                       m20, m21, m22, m23, m30, m31, m32, m33);

matrix q = matrix ("shader", 1);
matrix m = matrix ("world", m00, m01, m02, m03, m10, m11, m12, m13, 
                               m20, m21, m22, m23, m30, m31, m32, m33);

matrix m = matrix ("object", "world");
```

--------------------------------

### Declare OSL Shader Parameters with Initializers

Source: https://open-shading-language.readthedocs.io/en/latest/grosssyntax

Defines the basic syntax for declaring shader parameters in OSL. Parameters require a type, a name, and a default initializer expression. Multiple parameters are comma-separated.

```OSL
type parametername = default-expression
```

```OSL
type1 parameter1 = expr1, type2 parameter2 = expr2, ...
```

--------------------------------

### Environment Map Lookup - environment()

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Performs an environment map lookup using the specified filename and direction. Supports optional parameters for controlling blur, width, channel lookup, fill value, missing color, colorspace, and alpha channel retrieval.

```APIDOC
## POST /environment

### Description
Performs an environment map lookup of an image file, indexed by direction R, antialiased over a region defined by the differentials dRdx, dRdy.

### Method
POST

### Endpoint
`/environment`

### Parameters
#### Query Parameters
- **filename** (string) - Required - The path to the environment map image file.
- **R** (vector) - Required - The direction vector for the lookup.
- **dRdx** (vector) - Optional - The derivative of R with respect to x.
- **dRdy** (vector) - Optional - The derivative of R with respect to y.
- **blur** (float) - Optional - Additional blur when looking up the texture value (default: 0). Relative to texture size.
- **sblur** (float) - Optional - Separate blur control for the s-direction.
- **tblur** (float) - Optional - Separate blur control for the t-direction.
- **width** (float) - Optional - Scales the filter size defined by differentials (default: 1). A width of 0 turns off filtering.
- **swidth** (float) - Optional - Separate width control for the s-direction.
- **twidth** (float) - Optional - Separate width control for the t-direction.
- **firstchannel** (int) - Optional - The first channel to look up from the texture map (default: 0).
- **fill** (float) - Optional - The value to return for requested but missing channels (default: 0).
- **missingcolor** (color) - Optional - A color value to use for missing or broken textures instead of reporting an error.
- **missingalpha** (float) - Optional - An alpha value to use for missing or broken textures.
- **colorspace** (string) - Optional - Specifies the color space of the data in the texture file.
- **alpha** (floatvariable) - Optional - Variable to store the alpha channel value.

### Request Example
```json
{
  "filename": "path/to/environment.hdr",
  "R": [0.5, 0.5, 0.5],
  "dRdx": [0.1, 0.0, 0.0],
  "dRdy": [0.0, 0.1, 0.0],
  "blur": 0.2,
  "width": 0.8,
  "firstchannel": 1,
  "missingcolor": [1.0, 0.0, 0.0],
  "colorspace": "srgb"
}
```

### Response
#### Success Response (200)
- **result** (color or float) - The sampled texture color or float value.
- **alpha** (float) - If the 'alpha' parameter is used, this will contain the alpha channel value.

#### Response Example
```json
{
  "result": [0.8, 0.7, 0.6],
  "alpha": 0.9
}
```
```

--------------------------------

### Hashing and Regular Expressions

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Functions for generating deterministic string hashes and searching for patterns using regular expressions.

```APIDOC
## hash

### Description
Returns a deterministic and repeatable hash value for a given string.

### Method
`int hash(string s)`

### Parameters
- **s** (string) - Required - The input string.

### Response Example
```json
{
  "hash_value": 123456789
}
```
```

```APIDOC
## regex_search

### Description
Searches for a POSIX regular expression pattern within a subject string.

### Method
`int regex_search(string subject, [int results[]], string regex)`

### Parameters
- **subject** (string) - Required - The string to search within.
- **results** (int[]) - Optional - An array to store match indices (start/end of full match and sub-expressions).
- **regex** (string) - Required - The POSIX regular expression pattern.

### Response Example
```json
{
  "match_found": 1,
  "results": [0, 3] // Example: start and end index of the first match
}
```
```

--------------------------------

### Format string and return as string (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

The `format` function is similar to `printf` but returns the formatted text as a string instead of printing it. This is useful for constructing strings that will be used elsewhere in the shader. It supports standard C-style format specifiers.

```OSL
string format(string fmt, ...)
```

--------------------------------

### Get Surface Area (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Returns the surface area of an area light geometry. This function is intended for use with emission() to achieve correct emissive radiance based on a desired total wattage for the area light source. Its value is not meaningful for non-light shaders.

```OSL
float area = surfacearea();

```

--------------------------------

### Light Emission Closures

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Functions for creating emissive materials.

```APIDOC
## Light Emission Closures

### `uniform_edf`

Constructs an EDF emitting light uniformly in all directions. Used for glowing/emissive materials. For surfaces, it emits in a hemisphere; for volumes, it emits evenly in all directions.

**Parameters:**
- **emittance** (color) - Amount of emission, in units of radiance (e.g., W⋅sr−1⋅m−2).
```

--------------------------------

### Get Shader Message (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

The `getmessage` function retrieves a named message from another shader attached to the same object. It returns 1 if a message with a matching name and type is found and stored in `destination`, otherwise 0. An optional `source` parameter can specify the origin of the message, such as the result of a `trace` call.

```OSL
int getmessage(string name, output type destination)
int getmessage(string source, string name, output type destination)
```

--------------------------------

### OSL Matrix Operations and Access

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Illustrates how to perform operations on `matrix` types in OSL, including component access using array notation, equality/inequality checks, matrix multiplication, and inversion. Component indices range from 0 to 3.

```OSL
matrix M;
float x = M[row][col];
M[row][col] = 1;

matrix result = m1 * m2;
matrix inverse_result = m1 / m2;
matrix inverted_m = 1 / m;
```

--------------------------------

### Get Point Cloud Attributes by Index (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Retrieves specified attributes for a list of points identified by their indices from a point cloud. It supports retrieving attributes into corresponding data arrays and returns 1 on success, 0 on failure. This function is often used after `pointcloud_search` to fetch additional data.

```OSL
int n = pointcloud_search ("particles.ptc", P, r, 10,
                               "index", indices);
    float temp[10];         // presumed to be "float" attribute
    float quaternions[40];  // presumed to be "float[4]" attribute
    int ok = pointcloud_get ("particles.ptc", indices, n,
                             "temperature", temp,
                             "quat", quaternions);
```

--------------------------------

### OSL Periodic Noise (pnoise) Overloads

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Illustrates the different signatures for the `pnoise` function in OSL, which generates periodic noise. It allows specifying periods for each dimension of the input coordinates, enabling seamless tiling.

```OSL
_type_**`pnoise`**(string noisetype, float u, float uperiod)
_type_**`pnoise`**(string noisetype, float u, float v, float uperiod, float vperiod)
_type_**`pnoise`**(string noisetype, point p, point pperiod)
_type_**`pnoise`**(string noisetype, point p, float t, point pperiod, float tperiod)
```

--------------------------------

### Get Hit Information (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Retrieves information about the closest object hit by a ray. The available information depends on whether the ray was shaded. For shaded rays, shader outputs and messages can be retrieved. For unshaded rays, globals, interpolated vertex variables, shader instance values, and graphics state attributes are available.

```OSL
float hitdist = getmessage("hitdist");
string geom_name = getmessage("geom:name");

```

--------------------------------

### Construct Matrix with `matrix`

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Creates a 4x4 matrix. Matrices can be constructed from 16 float values in row-major order, a single float value for diagonal elements, or relative to a named coordinate space.

```openshadinglanguage
matrix matrix(float m00, ..., float m33)
matrix matrix(float f)
matrix matrix(string fromspace, float m00, ..., float m33)
matrix matrix(string fromspace, float f)
matrix matrix(string fromspace, string tospace)
```

--------------------------------

### Get Texture Information

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Retrieves various parameters from a named texture file. Supports UDIM textures with optional coordinates. Returns 1 on success, 0 on failure. Parameters include existence, resolution, channel count, type, subimages, format, data/display windows, transformation matrices, and average color/alpha. Added in OSL 1.12.

```c++
int gettextureinfo(string texturename, string paramname, output \
_type_ destination);
int gettextureinfo(string texturename, float s, float t, string paramname, output \
_type_ destination);
```

--------------------------------

### OSL Integer Hash Function Overloads

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

Shows the various overloads for the `hash` function in OSL, which returns a deterministic, repeatable integer hash for 1D, 2D, 3D, or 4D coordinates, as well as for an integer input.

```OSL
int **`hash`** (float u)
int **`hash`** (float u, float v)
int **`hash`** (point p)
int **`hash`** (point p, float t)
int **`hash`** (int i)
```

--------------------------------

### OSL String Literals and Concatenation

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Shows how to define string literals in OSL using double quotes and how whitespace can be used to concatenate adjacent string literals. It also highlights common escape sequences.

```OSL
string literal = "This is a string literal";
string escaped_string = "This string has a \"quote\" and a \\backslash\n";

string concatenated = "foo" "bar"; // equivalent to "foobar"
```

--------------------------------

### Get Renderer Attribute or Geometric Variable (OSL)

Source: https://open-shading-language.readthedocs.io/en/latest/stdlib

The `getattribute` function retrieves named renderer attributes or interpolated geometric variables. It supports searching specific objects or global attributes and performs automatic type conversions. It returns 1 if found and convertible, otherwise 0. Forms with `arrayindex` retrieve elements from named array attributes.

```OSL
int getattribute(string name, output type destination)
int getattribute(string name, int arrayindex, output type destination)
int getattribute(string object, string name, output type destination)
int getattribute(string object, string name, int arrayindex, output type destination)
```

--------------------------------

### Define and Use Structures in OSL

Source: https://open-shading-language.readthedocs.io/en/latest/datatypes

Demonstrates the definition and usage of structures in OSL, similar to C/C++. Structures group different data types into a single object, and their fields are accessed using the dot operator (`.`).

```osl
struct RGBA {
    color rgb;
    float alpha;
};

RGBA col;                        // Declare a structure
col.rgb = color (1, 0, 0);         // Assign to one field
color c = col.rgb;                 // Read from a structure field

RGBA b = { color(.1,.2,.3), 1 }; // Member-by-member initialization
```
Tokens:
Raw