Software: Unreal Engine 4.25 *Also tested on Unreal Engine 5.0.1
Disclaimer: I’m probably the 10th guy that’s documenting these steps on the web, I didn’t come up with this solution myself, I learned it from the sources listed below. The reason I’m documenting this (again) myself is to have a clear source I can come back to for this issue because I’m absolutely incapable of remembering subjects like this…… :-\ If you find inaccuracies in the steps I’m detailing or my explanation, I’ll be very grateful if you share a comment.
In short: AFAIK since version 4.21 UE doesn’t load custom node shader code from your project/Shaders folder by default anymore, but only from the shaders folder in the engine installation, which makes it less practical for developing shaders for specific projects.
Steps for setting the UE project to load shaders from the project folder in UE 4.22:
> The examples here are for a project named: “Tech_Lab”
A. The project must be a C++ project:
So either create a new project, define as such or just create a new C++ class and compile the project with it to convert it to a C++ project. Notes: a. You may need to right click the .uproject file icon and and Generate Visual Studio Project Files for the project to load correctly into Visual Studio and compile. b. You can delete the unneeded C++ class you added after the new settings took place.
B. Create a folder for the shader files:
Typically, it will be called “Shaders” and will be placed in the project root folder.
C. Add the RenderCore module to the project:
This is done by adding string “RenderCore” to array of public dependency modules in the <project>.build.cs file:
Notes: a. In UE 4.21 it should be ShaderCore. b. This addition is needed in-order to compile a new primary project module (next step).
D. Define a custom primary module for your project:
In <project_name>.h file add a new module named F<project_name>Module, with a StartupModule function overrides. Notes: a. We have add an include statement for “Modules/ModuleManager”. b. The <project_name>.h file is located in the /Source/<project_name> folder. c. Some sources state that you also have to override the ShutdownModule function, with an empty override, it works for me without this (maybe its just a mistake..)
E. Implement the function override, and set the custom module as the project primary module:
In <project_name>.cpp file, add the StartupModule override, With the definition of the added shaders path: FString ShaderDirectory = FPaths::Combine(FPaths::ProjectDir(), TEXT("Shaders"));
and mapping this new path as “/Project” for conveniently including it: AddShaderSourceDirectoryMapping("/Project", ShaderDirectory);
Last thing to do is to replace “FDefaultGameModuleImpl” with our custom module name in the IMPLEMENT_PRIMARY_GAME_MODULE macro: IMPLEMENT_PRIMARY_GAME_MODULE(FTech_LabModule, Tech_Lab, "Tech_Lab" );
Notes: a. We must include “Misc/Paths” b. Note that the addition of this folder mapping is restricted to versions 4.22 and higher via a compiler directive condition. for version 4.21, you should state “ENGINE_MINOR_VERSION >= 21: Note for UE5: Unreal Engine 5 supports this from the get go so this compiler directive condition should be deleted for this to work.
F. Wrapping up:
After taking these steps and compiling the project. You should be able to include .ush and .usf files stored in <your_ue_project>/Shaders with the “Project” path mapping: include "/Project/test.usf"
That’s it! 🙂
I hope you found this helpful, And if you encountered errors, or inaccuracies, I’ll be grateful if you’ll take the time to comment.
The cglSurfaceCarPaint car-paint material combines 3 layers: Base: A blend of diffuse/metallic shading with a view-angle color mix Metallic flakes: Distance blended procedural metallic flakes Clear coat: Glossy clear coat layer with built-in procedural bump irregularity
And has been tested with:
Blender & Cycles
Maya & Arnold
3ds max & V-Ray
The following is an introduction to basic OSL shader syntax using a simple color blending shader example. a more general explanation of the subject can be read here.
Notes: > It’s highly recommended to get acquainted with basic C language syntax, since it’s the basis for common shading languages like OSL, HLSL and GLSL. > More detailed information about writing OSL shaders can be found in the osl-languagespec PDF document from ImageWorks’s OSL GitHub.
This example shader blends 2 color sources according to the surface viewing angle (aka “facing ratio” or “incident angle” or “Perpendicular-Parallel”). the user can choose a facing (“front”) color or texture, a side color or texture, and the shader’s output bell be a mix of the these 2 inputs that depends on the angle the surface is viewed at.
[[ string help = "Blend colors by view angle" ]]
color facing_color = color(0, 0, 0)
[[ string help = "The color (or texture) that will appear at perpendicular view angle" ]],
color side_color = color(1, 1, 1)
[[ string help = "The color (or texture) that will appear at grazing view angle" ]],
float base_blend = 0.0
[[ string help = "The percent of side_color that is mixed with facing_color at perpendicular view angle",
float min = 0.0, float max = 1.0]],
float curve_exponent = 1.0
[[ string help = "A power exponent value by which the blend value is raised to control the blend curve",
float min = 0.001, float max = 10.0]],
output color color_out = color(1, 1, 1))
// calculate the linear facing ratio:
float facing_ratio = acos(abs(dot(-I,N))) / M_PI_2;
// calculate the curve facing ratio:
float final_blend_ratio = pow(facing_ratio , curve_exponent);
// blend the facing color:
color final_facing_color = (facing_color * (1 - base_blend)) + (side_color * base_blend);
// blend and output the final color:
color_out = ((final_facing_color * (1 - final_blend_ratio)) + (side_color * final_blend_ratio));
The first statment:
The #include statement is a standard C compiler directive to link the OSL source code library code file stdosl.h to the shader’s code, so that the OSL data types and functions in the code will be recognized.
* Some systems compile the code successfully without this statement. I’m not sure if their compiler links stdosl.h automatically or not.
The double-square bracketed statements provide both help annotations and value range limits for the shader parameters:
[[ string help = "The percent of side_color that is mixed with facing_color at perpendicular view angle", float min = 0.0, float max = 1.0]]
Note that these statements are appended to single parameters in the shader right before the comma character that ends the parameter statement.
* Not all shading systems that supprt OSL also implement the annotations in the shader’s interface generated by the host software (the shader will work, but it’s parameters wont be described and limited to the defined value range).
Removing the #include statement, annotations and comments,
We can see that the OSL shader structure is very similar to a C function:
First the data type, in this case shader, followed by the shader identifier, in this case “cglColorAngleBlend”:
After the shader’s type and identifier, a list of parameters is defined within parentheses, separated by comma’s. these parameters define the shader’s input’s, outputs, and default values. Output parameters are preceded by the outputmodifier.
color facing_color = color(0, 0, 0),
color side_color = color(1, 1, 1),
float base_blend = 0.0,
float curve_exponent = 1.0,
output color color_out = color(1, 1, 1)
In this case the shader has 4 user input parameters, and 1 output parameter.
2 colortype parameters, “facing_color” and “side_color” for the facing and side color that will be blended together, a float*parameter “base_blend” that specifies how much of the side color will be mixed with the facing color regardless of view angle, and a second floatparameter “curve_exponent” specifying a power exponent by which the blend value will be raised to create a non-linear blend curve.
The outputparameter “color_out” is a colorthat will calculated by the shader.
* Note that even though the the output parameter will be calculated by the shader, it is required to define a default value for it for the shader to compile.
After the shader parameters, enclosed within curly braces is the actual body of the shader code, containing the instructions, each ending by a semicolon ; character:
calculates incident angle, i.e. angle between 2 vectors, originating at the surface shading point, one pointing towards the origin of the incoming ray, and the other the surface normal, as a factor of 0 to 1 representing 0 – 90 degrees.
These 2 vector are easily obtained through the built in OSL global variables N and I. N is the surface normal at the shading point, and I is the incoming ray vector pointing to the shading point which is inverted in this case to point backwards by typing a minus before it: -I.
The incident angle is calculated in radians as the arc-cosine of the dot-product of N and -I and then divided by half a π to convert it to a linear factor of 0 to 1 representing 0 to 90 degrees in radians, M_PI_2 being a convenient half π constant.
* M_PI being a full π, M_2PI being 2π representing 180 degrees in radians and 360 degrees respectively (OSL provides there are more constants in this series).
The second instruction raises the facing ratio that was calculated in the previous instruction by a power value provided by the curve_exponent input parameter, to create a non linear angle/color blend in values other than 1.0.
The resulting modified blend value is stored in a new internal variable final_blend_ratio:
But I decided to keep it separated into 2 variable and 2 instructions for clarity.
* try modifying the code as an exercise
The third instruction modifies the input color facing_color by premixing it with the input side_color according to the percent give by the input parameter base_blend and assigns the resulting color to a new internal variable named final_facing_color:
Calculates a linear combination** (linear interpolation) between the 2 input colors using the base_blend as a 0 – 1 factor between them.
* Note that OSL allows to define arithmatic operations freely between colors and floats.
The forth and final instruction creates the final mix between the modified facing color stored in final_facing_color variable and the side color given by the input color parameter side_color, by again, calculating a linear combination between the 2 colors, this time using final_blend_ratio variable value we calculated previously as the combination factor, and very importantly, finally, assigning the mixed result to the shader output parameter color_out so it will be the final output of the shader:
This screen capture shows this shader at work in Blender and Cycles, connected to a Principled BSDF shader as it’s base color source:
Thats it! 🙂
Hope you find this article informative and useful.
* A “float” data type is simply the the computer-science geeky way of saying “accurate non-integer number”. when we have to store numbers that can describe geometry and color, we need a data type that isn’t limited to integers so for that purpose we use float values. there’s actually a lot more to the float formal definition in computer science, but for our purpose here this will suffice.
** A Linear Combination, or Linear interpolation (lerp) is one of the most useful numerical operations in 3D geometry and color processing (vector math): A * ( 1 – t ) + B * t
A and B being your source and target locations or colors or any other value you need to interpolate and t being the blending factor from 0 – 1.
I recently found that some of my OSL shaders don’t work in Blender 2.83.
More specifically, shaders compiled with Blender 2.83 had their microfacet bsdf not recognized by the renderer and return 0.
* Shaders that were compiled by previous versions did work.
Looking into the problem I found that the OSL source files that ship with Blender 2.83 are significantly different than the files shipped with previous versions.
Copy the stdosl.h and oslutil.h from Blender 2.82 to 2.83.
On Windows these files are found in this folder:
C:\Program Files\Blender Foundation\Blender 2.83\2.83\scripts\addons\cycles\shader
* I’m not suggesting to download the files strait from ImageWorks GitHub because I’m not sure the ones that ship with Blender & Cycles are not modified.
The Cycles render engine in Blender has a very convenient OSL Shader development and usage workflow.
Shaders can be both loaded from external files or written and compiled directly inside Blender.
Before you begin:
Make sure your Blender scene is set to use the Cycles render engine, in CPU rendering mode, and also check the option Open Shading Language:
To write an OSL shader in Blender:
Write your shader code in Blender‘s Text Editor:
In your object’s material shader graph (Shader Editor view),
Create a Script node:
Set the Script node‘s mode to Internal,
And select your shader’s text from the Script node‘s source drop-down:
If the shader compiles successfully, the Script node will display its input and output parameters, and you can connect it’s output to an appropriate input in your shading graph.
* If your shader is a material (color closure) connect it directly to the Material Output node’s Surface input, is it’s a volume to the Volume input, or if its a texture to other material inputs as needed.
If the shader code contains errors, it will fail to compile, and you’l be able to read the error messages in Blender‘s System Console window:
After fixing errors or updating the shader’s code, press the Script Noe Update button on the Script node to re-compile the shader:
Loading an external OSL shader into Cycles:
Exactly the same workflow described in the previous section, except setting the Script node‘s mode to External and either typing a path to the shader file in the Script node or pressing the little folder button to locate it using the file browser:
V-Ray for 3ds max supports compiling and rendering OSL shaders,
And also offers some handy shaders for download on the V-Ray documentation website. Note: OSL shaders are supported only in V-Ray Advanced and not in V-Ray GPU.
To load an external OSL shader:
For a material (color closure) shader, create a: Materials > V-Ray > VRayOSLMtl
For a texture shader create a: Maps > V-Ray > VRayOSLTex
In the VRayOSLMtl or VRayOSLTex‘s General properties,
Click the Shader File slot-button to locate and load the *.osl file.
Provided that the shader has loaded and compiled successfully,
You will now be able to set it’s custom parameters in its Parameters section:
If compile errors will be found you’l be able to read the error messages in the V-Ray messages window:
To write an OSL shader:
To write a material shader (color closure) create a: Materials > V-Ray > VRayOSLMtl
To write a texture shader create a: Maps > V-Ray > VRayOSLTex
Expend the Quick Shader section of the node’s properties,
And check the Enable option.
Write you’r OSL code, and press Compile.
Provided that the shader compiled successfully,
You will now be able to set it’s custom parameters in its Parameters section:
If compile errors will be found you’l be able to read the error messages in the V-Ray messages window.
Autodesk Maya 2020 & Arnold 6 offer a flexible OSL development and usage workflow.
You can both load or write OSL shaders on the fly, compile, test, and render them,
And also define a shader folder path for shaders to be available as part of your library for all projects.
Steps for using OSL shaders in Maya & Arnold:
Writing an OSL shader or loading it for single use (just the current project):
Create a new aiOslShader node:
Select the new aiOslShader node and in its attributes either write new OSL code in the code OSL Code section, or press Import to Load an OSL shader file (*.osl):
When new shader code is imported, it’s automatically compiled:
I f you’ve written new code, or changed the code it will have to be re-compiled.
In that case press Compile OSL Code:
The code may contain errors, in that case you will see a red Compile Failure message:
You can read the error message in the Maya output window, or in the Maya Script Editor, Correct the code and press Compile OSL Code again.
After the OSL code is compiled successfully, the shader’s input parameters can be accessed in the OSL Attributes section below the code:
Depending on the type of output the OSL shader generates, the aiOSLShader node should to be connected to an input in the object’s shader graph or Shading Group.
* OSL shaders can be surface shaders, volume shaders, procedural textures, texture processors and more..
To Apply the OSL shader to an object as a surface shader, disconnect the object’s current surface shader if it has one,
And then drag and drop the aiOSLShader node from the Hypershade window onto the object.
In the Connection Editor select outValue on the left side (node outputs) and surfaceShader in the right side (object inputs):
When compiling OSL shaders “on the fly” using the above steps, the shader’s input parameters don’t necessarily appear at their intended order that is defined in the shader code.
Installing OSL shaders so they will always be available as custom nodes in the Hypershade library
Create a folder for storing your OSL shaders, and place you OSL shader files (*.osl) in this folder.
Locate Maya’s Maya.env file.
This is an ascii text file containing environment variables that Maya loads at startup.
The Maya.env will usually be located at: C:\Users\<your user>\Documents\maya\<maya version>
Open Maya.env in a text editor and add the following line to it: ARNOLD_PLUGIN_PATH=<path to your OSL shaders folder> for example:
When Maya loads, the MtoA (Maya to Arnold) plugin will automatically compile the shaders that are found in the folder, report about the compilations or found errors in the Maya output window, and create compiled *.oso files for each shader:
The compiled shaders will now be available as custom nodes in the Hypershade Arnold library with the typical “ai” (Arnold Interface) prefix added to their names:
The OSL shaders will be created as nodes with their editable attributes, that can be connected to an object’s shading network graph:
* Connecting the node to the graph is the same as described in the previous part (7)
OSL is an acronym forOpen Shading Language. Developed Originally at Sony Pictures Imageworks for the Arnold render engine, Open Shading language is a C like programming language with which custom material, textures and shading effects can be developed –OSL shaders (*.osl files), that are supported many by popular render engines.
OSL allows development of complex texturing and shading effects using scene input parameters like the shading point’s world position vector, normal vector, UV coordinates etc., and optical ray-tracing functions – BSDF*’s or “Color Closures” as they are called in OSL, like Diffuse, Glossy, Refraction light scattering etc. that can be combined with C logic and math programming.
*.osl files are compiled to *.oso file for rendering.
Most render engines supporting OSL shaders ship with an OSL compiler.
> OSL Shaders for download at the Autodesk Developer Network Github repository: https://github.com/ADN-DevTech/3dsMax-OSL-Shaders
These are the OSL shaders that ship with 3ds max 2019 or newer, and are providing texture and pattern processing tools, but not materials.
* Material shaders or “Closures” as they are referred to in OSL are not supported by 3ds max’s native implementation of OSL.
In general, OSL shaders are supported only in CPU Rendering, but not supported by GPU renderers. There are some attempts to develop OSL support for GPU renderers, But as far as I know they are limited.
Some OSL shaders will work on one or more render engines, and not work as expected on other render engines. the reason being that each render engine has it’s own implementation of OSL.
These differences may show in a different rendered result and also compile failure.
The following example renders show how a combination of two basic OSL shaders iv’e written, one of which is a dielectric material shader, and the other a color/angle blend procedural texture, produce fairly consistent results when rendered in different render engines.
* note the difference in specular glossy roughness interpretation for the same 0.1 value..
> You’r welcome to download these two basic OSL shadershere.