Open Shading Language¶

Open Shading Language (OSL) is a programmable shading system developed for advanced rendering engines. It allows technical artists and developers to write custom shader code using a C-like scripting language.

In Blender, OSL can be used within Cycles to define custom surface, volume, and displacement shaders. This gives users full control over shading behavior, enabling procedural effects, advanced lighting models, and custom geometry-based material logic that may not be possible with built-in shader nodes alone.

Unlike node-based materials, OSL shaders are authored as text scripts using Blender’s internal Text Editor or loaded from external .osl or .oso files. These scripts are then compiled and used in the Shader Editor through the Script Node.

Dica

OSL is especially useful for generating procedural textures, custom BRDFs, or implementing research prototypes. It also allows sharing shaders across compatible rendering applications that support the OSL standard.

Uso¶

To use Open Shading Language (OSL) in Blender, follow these steps:

Enable OSL Rendering

In the Render Properties enable Open Shading Language.
Add a Script Node

In the Shader Editor add Script Node then in the node’s properties:
- Set the Mode to Internal to use a Blender text data-block, or
- Set it to External to load a shader file from disk (either .osl or compiled .oso).
For the internal mode, create a new text data-block in the Text Editor, then write or paste your OSL code there.

Blender will compile the OSL source file automatically. If the source is .osl, it will be compiled into .oso bytecode. Compilation errors will be shown in the system console.
Use Shader Outputs

Once compiled, the node’s outputs will reflect the output parameters defined in the OSL code. These outputs can be connected to any part of the material node tree.

Escrevendo Sombreadores¶

For more details on how to write shaders, see the OSL Documentation.

Here is a simple example:

shader simple_material(
    color Diffuse_Color = color(0.6, 0.8, 0.6),
    float Noise_Factor = 0.5,
    output closure color BSDF = diffuse(N))
{
    color material_color = Diffuse_Color * mix(1.0, noise(P * 10.0), Noise_Factor);
    BSDF = material_color * diffuse(N);
}

Encerramentos¶

LSA é diferente de, por exemplo, RSL ou GLSL, no fato de que não possui um laço de luz. Não há acesso a luzes na cena, e o material deve ser construído a partir de encerramentos que são implementados no próprio renderizador. Isso é mais limitado, mas também torna possível o renderizador fazer otimizações e assegura que todos os sombreadores possam ter importância amostrada.

The available closures in Cycles correspond to the shader nodes and their sockets; for more details on what they do and the meaning of the parameters, see the shader nodes manual.

Veja também

Documentation on OSL’s built-in closures.

BSDF¶

diffuse(N)
oren_nayar(N, roughness)
diffuse_ramp(N, colors[8])
phong_ramp(N, exponent, colors[8])
diffuse_toon(N, size, smooth)
glossy_toon(N, size, smooth)
translucent(N)
reflection(N)
refraction(N, ior)
transparent()
microfacet_ggx(N, roughness)
microfacet_ggx_aniso(N, T, ax, ay)
microfacet_ggx_refraction(N, roughness, ior)
microfacet_beckmann(N, roughness)
microfacet_beckmann_aniso(N, T, ax, ay)
microfacet_beckmann_refraction(N, roughness, ior)
ashikhmin_shirley(N, T, ax, ay)
ashikhmin_velvet(N, roughness)

Hair¶

hair_reflection(N, roughnessu, roughnessv, T, offset)
hair_transmission(N, roughnessu, roughnessv, T, offset)
principled_hair(N, absorption, roughness, radial_roughness, coat, offset, IOR)

BSSRDF¶

Used to simulate subsurface scattering.

bssrdf(method, N, radius, albedo)¶

Parâmetros:

method (string) –
Rendering method to simulate subsurface scattering.
- burley: An approximation to physically-based volume scattering. This method is less accurate than random_walk however, in some situations this method will resolve noise faster.
- random_walk_skin: Provides accurate results for thin and curved objects. Random Walk uses true volumetric scattering inside the mesh, which means that it works best for closed meshes. Overlapping faces and holes in the mesh can cause problems.
- random_walk: Behaves similarly to random_walk_skin but modulates the Radius based on the Color, Anisotropy, and IOR. This method thereby attempts to retain greater surface detail and color than random_walk_skin.
N (vector) – Normal vector of the surface point being shaded.
radius (vector) – Average distance that light scatters below the surface. Higher radius gives a softer appearance, as light bleeds into shadows and through the object. The scattering distance is specified separately for the RGB channels, to render materials such as skin where red light scatters deeper. The X, Y and Z values are mapped to the R, G and B values, respectively.
albedo (color) – Color of the surface, or physically speaking, the probability that light is reflected for each wavelength.

Volume¶

henyey_greenstein(g)
absorption()

Other¶

emission()
ambient_occlusion()
holdout()
background()

Atributos¶

Geometry attributes can be read through the getattribute() function. This includes UV maps, color attributes and any attributes output from geometry nodes.

The following built-in attributes are available through getattribute() as well.

geom:generated: Automatically generated texture coordinates, from non-deformed mesh.
geom:uv: Mapa UV padrão para a renderização.
geom:tangent: Default tangent vector along surface, in object space.
geom:undisplaced: Position before displacement, in object space.
geom:dupli_generated: For instances, generated coordinate from instancer object.
geom:dupli_uv: For instances, UV coordinate from instancer object.
geom:trianglevertices: Three vertex coordinates of the triangle.
geom:numpolyvertices: Número de vértices no polígono (sempre retorna três atualmente).
geom:polyvertices: Matriz de coordenadas de vértices do polígono (sempre três vértices atualmente).
geom:name: Nome do objeto.
geom:is_smooth: Is mesh face smooth or flat shaded.
geom:is_curve: Is object a curve or not.
geom:curve_intercept: 0..1 coordinate for point along the curve, from root to tip.
geom:curve_thickness: Thickness of the curve in object space.
geom:curve_length: Length of the curve in object space.
geom:curve_tangent_normal: Normal Tangente da vertente.
geom:is_point: Is point in a point cloud or not.
geom:point_radius: Radius of point in point cloud.
geom:point_position: Center position of point in point cloud.
geom:point_random: Random number, different for every point in point cloud.
path:ray_length: Distância do raio desde o último encontro.
object:random: Random number, different for every object instance.
object:index: Object unique instance index.
object:location: Localização do objeto.
material:index: Material unique index number.
particle:index: Particle unique instance number.
particle:age: Idade da partícula em quadros.
particle:lifetime: Vida útil total da partícula em quadros.
particle:location: Localização das partículas.
particle:size: Tamanho das partículas.
particle:velocity: Velocidade das partículas.
particle:angular_velocity: Velocidade angular das partículas.

Traço¶

CPU Only

Nós suportamos a função traço(pos ponto, dir vetor, ...), para traçar raios a partir do sombreador LSA. O parâmetro «sombreador» não é suportado atualmente, mas atributos podem ser recuperados do objeto que foi atingido usando a função getmessage("traço", ..). Veja a especificação LSA para mais detalhes em como usar isso.

Essa função não pode ser usada em vez de iluminação; o principal objetivo é permitir sombreadores «examinar» a geometria próxima, por exemplo para aplicar uma textura projetada que pode ser bloqueada por geometria, aplicar mais «roupa» à geometria exposta, ou fazer outros efeitos tipo oclusão ambiente.

Metadata¶

Metadata on parameters controls how they are displayed in the user interface. The following metadata entries are supported:

[[ string label = "My Label" ]]: Custom display name of the parameter in the user interface.
[[ string widget = "null" ]]: Hides the parameter from the user interface.
[[ string widget = "boolean" ]] or [[ string widget = "checkbox" ]]: Displays an integer parameter as a boolean checkbox.
[[ string widget = "filename" ]]: Displays the parameter as a file path selector.
[[ string widget = "mapper", string options = "left:0|right:1" ]]: Displays an integer parameter as an enumerated menu. The options string defines a list of label-value pairs separated by |.
[[ string vecsemantics = "POINT" ]]: Marks a vector parameter as a translation input (position vector).
[[ string vecsemantics = "NORMAL" ]]: Marks a vector parameter as a normal input (direction vector).
[[ string unit = "radians" ]]: Marks a float parameter as an angle input, displayed in radians.
[[ string unit = "m" ]]: Marks a float parameter as a distance input, displayed in meters.
[[ string unit = "mm" ]]: Marks a float parameter as a distance input, displayed in millimeters.
[[ string unit = "s" ]] or [[ string unit = "sec" ]]: Marks a float parameter as a time input, displayed in seconds.

Limitações¶

Importante

OSL is not supported with GPU rendering unless using the OptiX backend.

Some OSL features are not available when using the OptiX backend. Examples include:

Texture lookups require OSL to be able to determine a constant image file path for each
texture call.
Some noise functions are not available. Examples include Cell, Simplex, and Gabor.
The trace function is not functional. As a result of this, the Ambient Occlusion and Bevel nodes do not work.