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 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.
Material Functions encapsulate shading flow graphs (material blueprints) into reusable shading nodes that have their own inputs and outputs.
This allows development of custom shading nodes, and saving the time it takes to recreate the same flow graphs multiple times or even copy and paste material flow graphs.
Common shading processes and operations that have to be performed in many different materials, and even multiple times in a single material can be defined as a Material Function for quick and easy re-usability. Material functions can also be used to encapsulate a full material blueprint with a Material Attributes output. this provides a convenient workflow for blending different materials together.
In this post I’ll detail the steps needed to create and use a Material Function.
The Material Function example we’ll create, called “ColorAngleBlend” performs a commonly needed shading operation of blending 2 colors or textures according to the surface viewing angle (facing ratio).
The ColorAngleBlendMaterial Function will have the following inputs:
The color or texture appearing when viewing the surface at perpendicular angle.
The color or texture appearing when viewing the surface at grazing view angle.
The steepness of the blend curve between the colors, 1 being a linear blend and higher values displaying color a at more angles “pushing” color b to be seen only at grazing angle.
base color blend:
The percent of color b seen at perpendicular view angle.
bump normals input.
The final “ColorAngleBlend”Material Function Blueprint:
* The internals of the “ColorAngleBlend”Material Function
An example of the “ColorAngleBlend”Material Function node used to create a reach view-angle dependent color blend for a steampunk metal material:
An example of the “ColorAngleBlend”Material Function node used to create a reach color for a car-paint material:
An example of the “ColorAngleBlend”Material Function node used to create a washed-out effect for a cloth material:
Steps for creating the “ColorAngleBlend” Material Function:
In the content browser, create a Material Function Object and name it “ColorAngleBlend”:
Double click the ColorAngleBlend Material Function to open it for editing:
Click the background of the work space to deselect the Output Result Node,
So that the Details panel on the left will display the Material Functions‘s properties.
Type a description into the Description field, check the Expose to Library option so that the new Material Function will be available to all materials in the Palate and node search, and define in which node categories it should appear:
Select the Output Result node and in the Details panel on the left set its output name to “color”:
Add a Linear Interpolate (Lerp) node, a Fresnel node and a Transform Vector (Tangent space to World space) node to the Blueprint and connect the nodes like this:
* The Lerp node will blend the 2 color inputs with the Fresnelproviding view angle data as the alpha for the Lerp.
The Transform Vector node is needed to convert normal (bump) input to world space for the Fresnelnode.
Adding function inputs:
Create 2 Function Input nodes, in their Details panel, name them “color a” and “color b”, leave their Input Type as default Vector3D, check the option Use Preview Value as Default, number their Sort Priority parameters 0 and 1 to make them appear as the first inputs of the ColorAngleBlend node as it will appear when used in a material, and connect them to the Lerp node’s A and B inputs:
Adding function inputs:
Create 2 new Function Input nodes, name them “curve exponent” and “base color blend”, this time set their Input Type to Scalar, check the option Use Preview Value as Default, set their Sort Priority parameters to 2 and 3 and connect their outputs to the Fresnel node’s ExpoentIn and BaseReflectFractionIn inputs:
Adding function inputs: Create the final Function Input node, name it “normal“, set its Input Type to Vector3D, check its Preview Value as Default option, set its Sort Priority to 4, and connect its output to the Fresnel node’s Normal input:
Adding default inputs:
Finally, add constant nodes to serve as default input values for the Material Function.
A pure white Constant3Vector (color) constant as the default value for “color a” input,
A pure black Constant3Vector (color) constant as the default value for “color a” input,
A Constant with value 1.0 as the default value for “curve exponent” input,
A Constant with value 0.0 as the default value for”base color blend” input,
A pure blue Constant3Vector (color) constant as the default value for “normal” input. > Tip for quick creation of constant value nodes
Save the new Material Function.
To use the new ColorAngleBlend Material Function create a new material, in the node search start typing color… to locate the ColorAngleBlend node and create it, and connect it to the desired material input.
>Material Functions can also be used by dragging them from the Content Browser into the Material Blueprint.
Having to remap a value range is very common in designing shaders, whether it’s to perform a traditional “levels” operation on a texture, or use just a specific range of values in a float input.
The RemapValueRange node let’s us do just that. this node has 5 inputs:
Input: The input value
Input Low: Input mapping range minimum
Input High: Input mapping range maximum
Target Low: Output range minimum
Target Height: Output range maximum
Mono Noise examples:
The original noise pattern:
Mapping input 0 -> 1 to output 0 -> 1 obviously has no effect:
Mapping input 0 -> 1 to output 0.3 -> 0.7 reduces the pattern contrast:
Mapping input 0.3 -> 0.7 to output 0 -> 1 increases the pattern contrast:
Mapping input 0 -> 1 to output 1 -> 0 inverts the pattern:
In this example RemapValueRange nodes are applied to a texture’s individual color channels to increase contrast (Levels): > Note that this operation can be performed using a simpler graph by using float3d adding and multiplication operations on the texture color (this will be a subject for a different post) > Note that a different remapping operation can be performed on each color channel of a texture to adjust its color balance.
Before the value remapping:
After the value remapping tha value in each channel 0.1 -> 0.9 to 0.0 to 1.0:
The same operation performed by multiplication by 1.2 and subtracting 0.1:
The UE4 Fresnel node is actually a “Facing Ratio” node (aka Perpendicular / Parallel) with some extra control.
It basically allows controlling material effects according to the incident angle the surface is viewed at, which is a hugely important feature for designing advanced material effects.
The steepness of the value / angle curve.
Base Reflect Fraction:
The value at perpendicular angle.
An option to connect World Space surface normals input to affect the output of the Fresnel node.
* Tangent Space normals must be converted to World Space by using a Transform Vector node.
A value of 1.0 for the Exponent parameter, and a value of 0.0 for the Base Reflect Fraction will produce a linear “Facing Ratio” (“Perpendicular / Parallel”) falloff blend.