NGL is a material description language based on the GLSL shader language. It is used in 3DCoat to create nodes for materials, effects, deformations, and more.<\/p>\n\n\n\n
The language includes a preprocessor that handles custom defines and provides additional features needed for node description.<\/p>\n\n\n\n
Unlike standard GLSL, NGL offers flexibility in how you structure your code.<\/p>\n\n\n\n
You are not required to define a main function. You can write your shader code directly in the global scope, similar to Python scripts.<\/p>\n\n\n\n
Example:<\/p>\n\n\n\n
in vec3 Color;\nout vec3 Result;\n\n\/\/ Direct code execution\nResult = Color * 2.0;\n<\/code><\/pre>\n\n\n\nExplicit Main with Arguments<\/h3>\n\n\n\n
If you prefer to define a main function, you can declare your in<\/code> and out<\/code> properties directly as arguments to the function. This keeps the global namespace clean and groups property definitions with the main logic.<\/p>\n\n\n\nExample:<\/p>\n\n\n\n
void main(\n in vec3 FragCoord(value= 1, knot= ioFragCoord, expression= R=(V*K), min= -10.0, max= 10.0),\n in float Scale,\n out float Closest,\n out float SecondClosest,\n out float CellID\n) {\n \/\/ Shader logic here\n vec3 p = floor(FragCoord * Scale);\n \/\/ ...\n}\n<\/code><\/pre>\n\n\n\nProperties<\/h2>\n\n\n\n
To create incoming or outgoing properties, you can simply prefix the variable with in<\/code> or out<\/code>. Properties can be global variables (as seen above) or arguments of the main function.<\/p>\n\n\n\nSyntax:<\/p>\n\n\n\n
in type VariableName;\nout type VariableName;\n<\/code><\/pre>\n\n\n\nExample:<\/p>\n\n\n\n
in vec3 Color;\nout vec4 Result;\n<\/code><\/pre>\n\n\n\nProperty Options<\/h3>\n\n\n\n
Additional options for each property can be specified in round brackets after the variable declaration.<\/p>\n\n\n\n
Syntax:<\/p>\n\n\n\n
in type VariableName(option1 = value1, option2 = value2, ...);\n<\/code><\/pre>\n\n\n\nAvailable Options:<\/p>\n\n\n\n
\nvalue<\/code>: Default value for the property.<\/li>\n\n\n\nknot<\/code>: Specifies a knot type (e.g.,\u00a0ioFragCoord<\/code>).<\/li>\n\n\n\nexpression<\/code>: Defines a custom expression for the property value (e.g.,\u00a0R=V*D(K.x)<\/code>).<\/li>\n\n\n\nmin<\/code>: Minimum allowed value.<\/li>\n\n\n\nmax<\/code>: Maximum allowed value.<\/li>\n\n\n\nAllowCurve<\/code>: (Boolean) Allows curve control. Default is false.<\/li>\n\n\n\nAllowTexture<\/code>: (Boolean) Allows texture input. Default is false.<\/li>\n<\/ul>\n\n\n\nExample:<\/p>\n\n\n\n
in vec3 FragCoord(value = 1, knot = ioFragCoord, expression = R=V*D(K.x), min = -10.0, max = 10.0, AllowCurve = false, AllowTexture = false);\n<\/code><\/pre>\n\n\n\nExpressions<\/h2>\n\n\n\n
Expressions allow you to define custom logic for property values directly in the declaration. They share the same features as NGL but are designed for compactness. You cannot create new in<\/code> or out<\/code> properties within an expression.<\/p>\n\n\n\nShorthand Variables:<\/p>\n\n\n\n
\nR<\/code>: (vec4<\/code>) Result variable. The output of the expression is written here.<\/li>\n\n\n\nV<\/code>: (vec4<\/code>) Input value. The value entered by the user in the Node Inspector.<\/li>\n\n\n\nK<\/code>: (vec4<\/code>) Knot value. The value connected to the property from another node. Defaults to\u00a0vec4(1,1,1,1)<\/code>\u00a0if nothing is connected.<\/li>\n<\/ul>\n\n\n\nShorthand Functions:<\/p>\n\n\n\n
\nDC(value)<\/code>: Deform Curve. Applies the curve (configurable by the user for this property) to a vec4 or color value.<\/li>\n\n\n\nD(value)<\/code>: Deform Curve (Scalar). Applies the curve to a float value or a single scalar.<\/li>\n<\/ul>\n\n\n\nAccessing Other Properties<\/h3>\n\n\n\n
You can access the values of other properties (including custom user-created properties not defined in the code) using dot notation:<\/p>\n\n\n\n
\nOtherProp.V<\/code>: The value of\u00a0OtherProp<\/code>\u00a0defined in the Inspector (User Value).<\/li>\n\n\n\nOtherProp.K<\/code>: The value connected to\u00a0OtherProp<\/code>\u00a0from another node (Knot Value).<\/li>\n<\/ul>\n\n\n\nExample:<\/p>\n\n\n\n
\/\/ Result = UserValue * AnotherPropertyValue * AnotherPropertyConnectedValue\nin float Scale(expression = R = V * AnotherProp.V * AnotherProp.K);\n<\/code><\/pre>\n\n\n\nExample:<\/p>\n\n\n\n
\/\/ Result = UserValue * DeformCurve(ConnectedValue.x)\nin float Scale(expression = R=V*D(K.x));\n<\/code><\/pre>\n\n\n\nMath Operations & Type Casting<\/h2>\n\n\n\n
When writing equations involving addition<\/strong> or subtraction<\/strong> between a float<\/code> and a vector of any size (e.g., vec3<\/code>, vec4<\/code>, color<\/code>), you MUST ALWAYS<\/strong> explicitly cast the float<\/code> to the corresponding vector type. Failure to do so will result in GLSL compilation errors in 3DCoat. (Note: Multiplication and division are usually fine, but addition\/subtraction strictly require matching types).<\/em><\/p>\n\n\n\nExample (Incorrect):<\/p>\n\n\n\n
vec3 myColor = vec3(1.0, 0.5, 0.2);\nfloat bias = 0.1;\n\n\/\/ This will cause a compilation error in NGL!\nvec3 result = myColor + bias; \n<\/code><\/pre>\n\n\n\nExample (Correct):<\/p>\n\n\n\n
vec3 myColor = vec3(1.0, 0.5, 0.2);\nfloat bias = 0.1;\n\n\/\/ Correct: explicitly cast the float to a vec3\nvec3 result = myColor + vec3(bias);\n<\/code><\/pre>\n\n\n\nSpecial Data Types<\/h2>\n\n\n\ncolor<\/h3>\n\n\n\n
The color<\/code> type is essentially a vec4<\/code>, handled by the preprocessor.<\/p>\n\n\n\n\n- In the Editor: It appears as a color picker with a specialized UI, rather than four separate float sliders.<\/li>\n\n\n\n
- Usage: Use it exactly like a\u00a0
vec4<\/code>\u00a0in your code.<\/li>\n<\/ul>\n\n\n\nExample:<\/p>\n\n\n\n
in color DiffuseColor;\n<\/code><\/pre>\n\n\n\nOne2DCurve<\/h3>\n\n\n\n
The One2DCurve<\/code> type represents a custom 1D correction curve defined by the user in the UI.<\/p>\n\n\n\n\n- In the Editor: It is accessed via a curve editor.<\/li>\n\n\n\n
- Usage: In code, it acts as a fixed array of 256 floats (
float[256]<\/code>). You can access values using an index from 0 to 255.<\/li>\n<\/ul>\n\n\n\nExample:<\/p>\n\n\n\n
in One2DCurve MyCurve;\n\n\/\/ access value at index 128\nfloat midValue = MyCurve[128];\n\n\/\/ map 0.0-1.0 to 0-255 range\nfloat value = MyCurve[int(inputVal * 255.0)];\n<\/code><\/pre>\n\n\n\nProperty Modifiers and Accessors<\/h2>\n\n\n\n
For in<\/code> properties, you can access additional attributes and modifiers using dot notation.<\/p>\n\n\n\n.INV<\/h3>\n\n\n\n
Checks if the user has inverted the input property.<\/p>\n\n\n\n
\n- Usage:\u00a0
PropertyName.INV<\/code>\u00a0returns a boolean (or integer 0\/1).<\/li>\n\n\n\n- Context: Use this to manually apply inversion logic if needed, for example, when the input controls a texture lookup rather than a direct value.<\/li>\n<\/ul>\n\n\n\n
.DC()<\/h3>\n\n\n\n
Accesses the \u201cDeform Curve\u201d function associated with the property. Users can adjust an input\u2019s curve in the UI. By default, this is applied to the input value. However, if you are using the input to control something else (like a texture coordinate or a fetched texture sample), you can apply the same curve modification to that new value.<\/p>\n\n\n\n
\n- Syntax:\u00a0
PropertyName.DC(value)<\/code><\/li>\n<\/ul>\n\n\n\nExample:<\/p>\n\n\n\n
\/\/ Apply the same curve configured for 'Color' input to a texture sample\nvec4 texColor = texture(MyMap, uv);\nvec4 correctedColor = Color.DC(texColor);\n<\/code><\/pre>\n\n\n\nMaterial Object<\/h2>\n\n\n\n
The Material<\/code> type is a specialized structure used to represent a full PBR material. Under the hood, it is packed into an array of 7 vectors: vec4[7]<\/code>.<\/p>\n\n\n\nStructure and Packing<\/h3>\n\n\n\n
To allow mixing different material types (e.g., Glass vs. Metal) and to optimize storage, multiple properties may share the same scalar value in the underlying vectors. For example, a generic \u201cscalar\u201d might represent Refraction in the 0.0-0.5 range and Metalness in the 0.5-1.0 range.<\/p>\n\n\n\n
Accessing Properties<\/h3>\n\n\n\n
You can access unpacked properties using the io<\/code> prefix on the Material<\/code> object properties.<\/p>\n\n\n\nSyntax: materialInstance.ioPropertyName<\/code><\/p>\n\n\n\nAvailable Properties:<\/p>\n\n\n\n
\n- ioAlbedoColor (vec3)<\/li>\n\n\n\n
- ioEmissive (vec3)<\/li>\n\n\n\n
- ioOpacity (float)<\/li>\n\n\n\n
- ioIridescence (float)<\/li>\n\n\n\n
- ioAnisotropy (float)<\/li>\n\n\n\n
- ioClearCoat (float)<\/li>\n\n\n\n
- ioIOR (float)<\/li>\n\n\n\n
- ioClearCoatRoughness (float)<\/li>\n\n\n\n
- ioVolume (float)<\/li>\n\n\n\n
- ioMicroprotrusionsRoughness (float)<\/li>\n\n\n\n
- ioReflectionColor (vec3)<\/li>\n\n\n\n
- ioRefractionBlur (float)<\/li>\n\n\n\n
- ioSpecularEdgePower (float)<\/li>\n\n\n\n
- ioEmissiveColor (vec3)<\/li>\n\n\n\n
- ioSubSurfaceColor (vec3)<\/li>\n\n\n\n
- ioSpecularEdgeColor (vec3)<\/li>\n\n\n\n
- ioMicroprotrusionsColor (vec3)<\/li>\n\n\n\n
- ioDiffuseSSS (float)<\/li>\n\n\n\n
- ioSpecularSSS (float)<\/li>\n\n\n\n
- ioRefractionChromatic (float)<\/li>\n\n\n\n
- ioAmbientOcclusion (float)<\/li>\n\n\n\n
- ioClearCoatEdgePower (float)<\/li>\n\n\n\n
- ioMicroprotrusions (float)<\/li>\n\n\n\n
- ioTSNormal (Color) – Tangent Space Normal<\/li>\n\n\n\n
- ioMetalness (float)<\/li>\n\n\n\n
- ioRefraction (float)<\/li>\n\n\n\n
- ioRefractionMetalness (float)<\/li>\n\n\n\n
- ioGloss (float)<\/li>\n\n\n\n
- ioRoughness (float)<\/li>\n\n\n\n
- ioVelvet (float)<\/li>\n<\/ul>\n\n\n\n
Example:<\/p>\n\n\n\n
out Material result;\n\/\/ ...\nresult.ioAlbedoColor = vec3(1.0, 0.0, 0.0);\nresult.ioMetalness = 1.0;\nresult.ioRoughness = 0.2;\n<\/code><\/pre>\n\n\n\nImplicit Material Properties<\/h3>\n\n\n\n
If you write io<\/code> + [PropertyName]<\/code> (for example ioAlbedoColor<\/code>, ioGloss<\/code>, ioMetalness<\/code>) directly without a material object instance, the values will be written to or read from the default material to which the node scheme is applied. (Note: ioPropertyName<\/code> itself is not a real variable, it just represents the naming schema). You do not need to declare these variables<\/strong>; they are present in the node graph by default.<\/p>\n\n\n\nExample:<\/p>\n\n\n\n
\/\/ Directly writing to default material properties\nioAlbedoColor = vec3(1.0, 0.0, 0.0);\nioMetalness = 1.0;\nioGloss = 0.8;\n<\/code><\/pre>\n\n\n\nGlobal Built-in Variables<\/h2>\n\n\n\n
NGL provides a set of global built-in variables that are always available out of the box. You can use them anywhere in your code, but you must not declare them<\/strong> (e.g., using in<\/code> or out<\/code>), as this will lead to a re-declaration compilation error.<\/p>\n\n\n\nAvailable global variables:
ioResolution<\/code>,\u00a0ioMaskLayer<\/code>,\u00a0ioLayerColor<\/code>,\u00a0ioLayerBytes<\/code>,\u00a0ioLayerFloat<\/code>,\u00a0ioTime<\/code>,\u00a0ioTimeDelta<\/code>,\u00a0
ioFrame<\/code>,\u00a0ioMouse<\/code>,\u00a0ioDate<\/code>,\u00a0ioReplaceAlpha<\/code>,\u00a0ioFragCoord<\/code>,\u00a0ioUV<\/code>,\u00a0ioPosition<\/code>,\u00a0ioGlobalPosition<\/code>,\u00a0
ioNormal<\/code>,\u00a0ioGlobalNormal<\/code>,\u00a0ioFragCoord_DX<\/code>,\u00a0ioUV_DX<\/code>,\u00a0ioPosition_DX<\/code>,\u00a0ioNormal_DX<\/code>,\u00a0
ioFragCoord_DY<\/code>,\u00a0ioUV_DY<\/code>,\u00a0ioPosition_DY<\/code>,\u00a0ioNormal_DY<\/code>,\u00a0ioSpecularMask<\/code>,\u00a0ioCavity<\/code>,\u00a0
ioOcclusion<\/code>,\u00a0ioCameraPosition<\/code>,\u00a0ioRayDir<\/code>,\u00a0ioLightDir<\/code>,\u00a0ioIteration<\/code>.<\/p>\n\n\n\nGlobal Functions: mixMTL<\/h3>\n\n\n\n
A global helper function to correctly mix two materials. It handles the packed structure of the Material<\/code> type to ensure all properties (even those sharing scalars) are interpolated correctly.<\/p>\n\n\n\nSyntax:<\/p>\n\n\n\n
Material mixMTL(Material m1, Material m2, float t);\n<\/code><\/pre>\n\n\n\nParameters:<\/p>\n\n\n\n
\nm1<\/code>: The first material.<\/li>\n\n\n\nm2<\/code>: The second material.<\/li>\n\n\n\nt<\/code>: Interpolation factor (0.0 to 1.0).<\/li>\n<\/ul>\n\n\n\nPreprocessor Directives<\/h2>\n\n\n\n
NGL supports custom preprocessor directives to generate different source code based on settings or to create UI elements.<\/p>\n\n\n\n
#enum<\/a><\/h3>\n\n\n\nCreates a dropdown menu in the node settings.
Syntax:<\/p>\n\n\n\n
#enum DEFINE_NAME OPTION1 OPTION2 OPTION3 ...\n<\/code><\/pre>\n\n\n\nIn this case, DEFINE_NAME<\/code> will be replaced by the selected element from the list. This is particularly useful for creating generic types or switching keywords.<\/p>\n\n\n\nExample 1 (Type switching):<\/p>\n\n\n\n
#enum genType float vec2 vec3 vec4\n\n\/\/ genType will be replaced by the selected type (e.g. float, vec2, etc.)\nin genType Value;\n<\/code><\/pre>\n\n\n\nExample 2 (Photoshop-like layer blending):<\/p>\n\n\n\n
\/\/ NGL Node for Photoshop-like layer blending \n#enum BlendMode Normal Multiply Screen Overlay Darken Lighten ColorDodge ColorBurn HardLight SoftLight Difference Exclusion \n\nin color Base(value=vec4(0.5, 0.5, 0.5, 1.0));\nin color Blend(value=vec4(0.5, 0.5, 0.5, 1.0));\nin float Opacity(value=1.0, min=0.0, max=1.0);\nout color Result;\n\nvec3 Normal(vec3 b, vec3 a) { return a; } \nvec3 Multiply(vec3 b, vec3 a) { return b * a; } \nvec3 Screen(vec3 b, vec3 a) { return 1.0 - (1.0 - b) * (1.0 - a); } \nvec3 Overlay(vec3 b, vec3 a) { \n vec3 mult = 2.0 * b * a; \n vec3 screen = 1.0 - 2.0 * (1.0 - b) * (1.0 - a); \n return mix(mult, screen, step(0.5, b)); \n} \nvec3 Darken(vec3 b, vec3 a) { return min(b, a); } \nvec3 Lighten(vec3 b, vec3 a) { return max(b, a); } \nvec3 ColorDodge(vec3 b, vec3 a) { \n return mix(min(vec3(1.0), b \/ max(1.0 - a, vec3(0.00001))), vec3(1.0), step(1.0, a)); \n} \nvec3 ColorBurn(vec3 b, vec3 a) { \n return mix(max(vec3(0.0), 1.0 - (1.0 - b) \/ max(a, vec3(0.00001))), vec3(0.0), step(a, vec3(0.0))); \n} \nvec3 HardLight(vec3 b, vec3 a) { \n vec3 mult = 2.0 * b * a; \n vec3 screen = 1.0 - 2.0 * (1.0 - b) * (1.0 - a); \n return mix(mult, screen, step(0.5, a)); \n} \nvec3 SoftLight(vec3 b, vec3 a) { \n vec3 darken = b - (1.0 - 2.0 * a) * b * (1.0 - b); \n vec3 lighten = b + (2.0 * a - 1.0) * (sqrt(b) - b); \n return mix(darken, lighten, step(0.5, a)); \n} \nvec3 Difference(vec3 b, vec3 a) { return abs(b - a); } \nvec3 Exclusion(vec3 b, vec3 a) { return b + a - 2.0 * b * a; } \n\n\/\/ Clamping to avoid artifacts on overbright colors \nvec3 baseCol = clamp(Base.rgb, 0.0, 1.0); \nvec3 blendCol = clamp(Blend.rgb, 0.0, 1.0); \n \n\/\/ Selecting blending math via #enum substitution \nvec3 blended = BlendMode(baseCol, blendCol); \n \n\/\/ Opacity and Alpha factoring \nfloat totalBlendFactor = clamp(Blend.a * Opacity, 0.0, 1.0); \n \nvec3 finalColor = mix(Base.rgb, blended, totalBlendFactor); \nfloat finalAlpha = max(Base.a, Blend.a * Opacity); \n \nResult = vec4(finalColor, finalAlpha); \n<\/code><\/pre>\n\n\n\n#int<\/a><\/h3>\n\n\n\nAllows you to set an integer value via the UI.
Syntax:<\/p>\n\n\n\n
#int DEFINE_NAME DEFAULT_VALUE MIN_VALUE MAX_VALUE\n<\/code><\/pre>\n\n\n\nExample:<\/p>\n\n\n\n
#int ITERATIONS 5 0 10\n<\/code><\/pre>\n\n\n\n#bool<\/a><\/h3>\n\n\n\nCreates a checkbox in the settings.
Syntax:<\/p>\n\n\n\n
#bool DEFINE_NAME\n<\/code><\/pre>\n\n\n\n