Class ShaderNode

java.lang.Object
com.codename1.gpu.shader.ShaderNode
public final class ShaderNode extends Object

One value in a portable shader: a constant, a uniform, a built-in input such as the world position, a texture sample, or an operation on other nodes. Nodes are immutable and can be shared; a node used twice is computed once in the generated program.

A graph is plain Java, so it is checked by the compiler, needs no parser on the device and prints as GLSL, Metal or HLSL depending on the backend. The types follow the shading languages' own rules: two operands of an arithmetic operation have the same type, or one of them is a FLOAT that is applied to every component of the other.

ShaderNode uv = ShaderNode.uv().mul(4f).add(ShaderNode.time().mul(0.05f));
ShaderNode wave = ShaderNode.sin(uv.x().mul(6.2831f)).mul(0.5f).add(0.5f);
ShaderNode color = ShaderNode.mix(ShaderNode.vec3(0.1f, 0.3f, 0.5f),
        ShaderNode.vec3(0.6f, 0.8f, 0.9f), wave);

The built-in inputs that a stage can read are listed on each factory. Reading a fragment input from the VERTEX_OFFSET hook, or the reverse, fails when the material is compiled.

  • Method Details

    • f

      public static ShaderNode f(float v)

      A float constant.

      Parameters
      • v: the value
      Returns

      a FLOAT node

    • vec2

      public static ShaderNode vec2(float x, float y)

      A two component constant.

      Parameters

      • x: the first component

      • y: the second component

      Returns

      a VEC2 node

    • vec3

      public static ShaderNode vec3(float x, float y, float z)

      A three component constant.

      Parameters

      • x: the first component

      • y: the second component

      • z: the third component

      Returns

      a VEC3 node

    • vec4

      public static ShaderNode vec4(float x, float y, float z, float w)

      A four component constant.

      Parameters

      • x: the first component

      • y: the second component

      • z: the third component

      • w: the fourth component

      Returns

      a VEC4 node

    • color

      public static ShaderNode color(int rgb)

      An RGB colour constant from a packed 0xRRGGBB (the alpha byte is ignored), in the 0 to 1 range.

      Parameters
      • rgb: the colour
      Returns

      a VEC3 node

    • vec

      public static ShaderNode vec(ShaderNode... parts)

      Builds a vector from nodes whose components add up to 2, 3 or 4, as vec3(v.xy, 1.0) does in GLSL.

      Parameters
      • parts: the nodes, in order
      Returns

      a vector node

    • uniform

      public static ShaderNode uniform(String name, ShaderType type)

      A value the application sets per draw with ShaderMaterial.setUniform. It must be declared on the material with ShaderMaterial.declareUniform (the library shaders do that for you).

      Parameters

      • name: a name made of letters, digits and underscores

      • type: its type

      Returns

      a node of that type

    • sample

      public static ShaderNode sample(String textureName, ShaderNode uv)

      Samples a texture declared on the material with ShaderMaterial.declareTexture. Works in the fragment stage only.

      Parameters

      • textureName: the declared name

      • uv: the VEC2 coordinate

      Returns

      a VEC4 texel

    • sceneColor

      public static ShaderNode sceneColor(ShaderNode uv)

      Reads the frame in a custom full screen pass (com.codename1.gpu.PostProcess.addPass): the scene, or the output of the pass before. Means nothing on an ordinary material.

      Parameters
      • uv: the VEC2 place on screen, 0,0 top left; usually screenUv() or an offset from it
      Returns

      a VEC4 colour

    • screenUv

      public static ShaderNode screenUv()

      The place of the pixel on screen in a custom full screen pass, from 0,0 top left to 1,1 bottom right. In a pass it is the same as uv().

      Returns

      a VEC2 node

    • position

      public static ShaderNode position()

      The vertex position in model space. Vertex stage.

      Returns

      a VEC3 node

    • normal

      public static ShaderNode normal()

      The vertex normal in model space, or up when the mesh has none. Vertex stage.

      Returns

      a VEC3 node

    • uv

      public static ShaderNode uv()

      The first texture coordinate, or zero when the mesh has none. Both stages.

      Returns

      a VEC2 node

    • worldPos

      public static ShaderNode worldPos()

      The position in world space: in the vertex stage before the VERTEX_OFFSET hook moves it, in the fragment stage after. Both stages.

      Returns

      a VEC3 node

    • worldNormal

      public static ShaderNode worldNormal()

      The interpolated surface normal in world space, normalized, before the NORMAL hook replaces it. Fragment stage.

      Returns

      a VEC3 node

    • viewDir

      public static ShaderNode viewDir()

      The unit direction from the surface toward the camera. Fragment stage.

      Returns

      a VEC3 node

    • cameraPos

      public static ShaderNode cameraPos()

      The camera position in world space. Both stages.

      Returns

      a VEC3 node

    • sunDir

      public static ShaderNode sunDir()

      The unit direction toward the light (the sun). Both stages.

      Returns

      a VEC3 node

    • sunColor

      public static ShaderNode sunColor()

      The light colour. Both stages.

      Returns

      a VEC3 node

    • instanceId

      public static ShaderNode instanceId()

      The index of the copy GraphicsDevice.drawInstanced is drawing, 0 for an ordinary draw. Both stages. Reading it (or instanceRandom, instanceColor) declares the uniform it needs on the material.

      Returns

      a FLOAT node

    • instanceRandom

      public static ShaderNode instanceRandom()

      A random number in 0 to 1 that stays the same for each copy drawn by GraphicsDevice.drawInstanced (and 0 otherwise): vary the size, tint or sway phase of a field of grass or a crowd with it. Both stages.

      Returns

      a FLOAT node

    • instanceColor

      public static ShaderNode instanceColor()

      The colour GraphicsDevice.drawInstanced gives the copy being drawn, white when it gives none. Both stages.

      Returns

      a VEC4 node

    • time

      public static ShaderNode time()

      The clock in seconds that GraphicsDevice.setTime sets; the scene renderer advances it every frame. Both stages.

      Returns

      a FLOAT node

    • baseColor

      public static ShaderNode baseColor()

      The material colour times its texture, before the BASE_COLOR hook replaces it. Fragment stage.

      Returns

      a VEC4 node

    • add

      public ShaderNode add(ShaderNode o)

      Returns this plus o.

      Parameters
      • o: the other operand
      Returns

      the sum

    • add

      public ShaderNode add(float o)

      Returns this plus a constant.

      Parameters
      • o: the constant
      Returns

      the sum

    • sub

      public ShaderNode sub(ShaderNode o)

      Returns this minus o.

      Parameters
      • o: the other operand
      Returns

      the difference

    • sub

      public ShaderNode sub(float o)

      Returns this minus a constant.

      Parameters
      • o: the constant
      Returns

      the difference

    • mul

      public ShaderNode mul(ShaderNode o)

      Returns this times o, component by component.

      Parameters
      • o: the other operand
      Returns

      the product

    • mul

      public ShaderNode mul(float o)

      Returns this times a constant.

      Parameters
      • o: the constant
      Returns

      the product

    • div

      public ShaderNode div(ShaderNode o)

      Returns this divided by o, component by component.

      Parameters
      • o: the divisor
      Returns

      the quotient

    • div

      public ShaderNode div(float o)

      Returns this divided by a constant.

      Parameters
      • o: the divisor
      Returns

      the quotient

    • negate

      public ShaderNode negate()

      Returns minus this.

      Returns

      the negation

    • oneMinus

      public ShaderNode oneMinus()

      Returns 1 - this, the usual way to invert a mask.

      Returns

      the complement

    • swizzle

      public ShaderNode swizzle(String components)

      Picks components by name, as GLSL's v.xz does: one to four of x, y, z, w (or r, g, b, a).

      Parameters
      • components: the component names
      Returns

      a node with as many components as named

    • x

      public ShaderNode x()

      Returns the first component.

      Returns

      a FLOAT node

    • y

      public ShaderNode y()

      Returns the second component.

      Returns

      a FLOAT node

    • z

      public ShaderNode z()

      Returns the third component.

      Returns

      a FLOAT node

    • w

      public ShaderNode w()

      Returns the fourth component.

      Returns

      a FLOAT node

    • rgb

      public ShaderNode rgb()

      Returns the first three components, the colour of a texel.

      Returns

      a VEC3 node

    • xy

      public ShaderNode xy()

      Returns the first two components.

      Returns

      a VEC2 node

    • xz

      public ShaderNode xz()

      Returns the first and third components, the ground plane of a world position.

      Returns

      a VEC2 node

    • sin

      public static ShaderNode sin(ShaderNode a)

      Returns sin(a), per component.

      Parameters
      • a: radians
      Returns

      the sine

    • cos

      public static ShaderNode cos(ShaderNode a)

      Returns cos(a), per component.

      Parameters
      • a: radians
      Returns

      the cosine

    • abs

      public static ShaderNode abs(ShaderNode a)

      Returns the absolute value, per component.

      Parameters
      • a: the value
      Returns

      the absolute value

    • floor

      public static ShaderNode floor(ShaderNode a)

      Returns the largest integer not greater than a, per component.

      Parameters
      • a: the value
      Returns

      the floor

    • fract

      public static ShaderNode fract(ShaderNode a)

      Returns a - floor(a), per component.

      Parameters
      • a: the value
      Returns

      the fractional part

    • sqrt

      public static ShaderNode sqrt(ShaderNode a)

      Returns the square root, per component.

      Parameters
      • a: a non negative value
      Returns

      the square root

    • exp

      public static ShaderNode exp(ShaderNode a)

      Returns e raised to a, per component.

      Parameters
      • a: the exponent
      Returns

      the exponential

    • normalize

      public static ShaderNode normalize(ShaderNode a)

      Returns the unit vector in the direction of a.

      Parameters
      • a: a non zero vector
      Returns

      the normalized vector

    • saturate

      public static ShaderNode saturate(ShaderNode a)

      Returns a clamped to 0 to 1, per component.

      Parameters
      • a: the value
      Returns

      the saturated value

    • length

      public static ShaderNode length(ShaderNode a)

      Returns the length of a vector.

      Parameters
      • a: the vector
      Returns

      a FLOAT node

    • distance

      public static ShaderNode distance(ShaderNode a, ShaderNode b)

      Returns the distance between two points.

      Parameters

      • a: a point

      • b: another point of the same type

      Returns

      a FLOAT node

    • dot

      public static ShaderNode dot(ShaderNode a, ShaderNode b)

      Returns the dot product.

      Parameters

      • a: a vector

      • b: another vector of the same type

      Returns

      a FLOAT node

    • cross

      public static ShaderNode cross(ShaderNode a, ShaderNode b)

      Returns the cross product of two VEC3 nodes.

      Parameters

      • a: a vector

      • b: another vector

      Returns

      a VEC3 node

    • reflect

      public static ShaderNode reflect(ShaderNode i, ShaderNode n)

      Returns the reflection of incident direction i about normal n.

      Parameters

      • i: the incident direction

      • n: the unit normal

      Returns

      a node of the type of i

    • min

      public static ShaderNode min(ShaderNode a, ShaderNode b)

      Returns the smaller of two values, per component.

      Parameters

      • a: a value

      • b: another value

      Returns

      the minimum

    • max

      public static ShaderNode max(ShaderNode a, ShaderNode b)

      Returns the larger of two values, per component.

      Parameters

      • a: a value

      • b: another value

      Returns

      the maximum

    • pow

      public static ShaderNode pow(ShaderNode a, ShaderNode b)

      Returns a raised to b, per component. a must not be negative.

      Parameters

      • a: the base

      • b: the exponent, of the type of a or a FLOAT

      Returns

      the power

    • pow

      public static ShaderNode pow(ShaderNode a, float b)

      Returns a raised to a constant.

      Parameters

      • a: the base, not negative

      • b: the exponent

      Returns

      the power

    • mod

      public static ShaderNode mod(ShaderNode a, ShaderNode b)

      Returns a modulo b with the sign of b, as GLSL's mod does (HLSL's fmod differs for negative values, so this is printed as a - b * floor(a / b) everywhere).

      Parameters

      • a: the dividend

      • b: the divisor

      Returns

      the remainder

    • atan2

      public static ShaderNode atan2(ShaderNode y, ShaderNode x)

      Returns the angle of the vector (x, y) in radians, -pi to pi.

      Parameters

      • y: the second coordinate

      • x: the first coordinate

      Returns

      the angle

    • clamp

      public static ShaderNode clamp(ShaderNode a, float lo, float hi)

      Returns a clamped between lo and hi, per component.

      Parameters

      • a: the value

      • lo: the lower bound

      • hi: the upper bound

      Returns

      the clamped value

    • mix

      public static ShaderNode mix(ShaderNode a, ShaderNode b, ShaderNode t)

      Linear interpolation from a to b by t.

      Parameters

      • a: the value at 0

      • b: the value at 1, of the type of a

      • t: the weight, of the type of a or a FLOAT

      Returns

      the blend

    • smoothstep

      public static ShaderNode smoothstep(float e0, float e1, ShaderNode x)

      Hermite step from 0 at e0 to 1 at e1.

      Parameters

      • e0: the lower edge

      • e1: the upper edge

      • x: the value

      Returns

      a node of the type of x

    • smoothstep

      public static ShaderNode smoothstep(ShaderNode e0, ShaderNode e1, ShaderNode x)

      Hermite step from 0 at e0 to 1 at e1, with node edges.

      Parameters

      • e0: the lower edge

      • e1: the upper edge

      • x: the value

      Returns

      a node of the type of x

    • step

      public static ShaderNode step(ShaderNode edge, ShaderNode x)

      Returns 0 where x is below edge and 1 elsewhere.

      Parameters

      • edge: the edge

      • x: the value

      Returns

      a node of the type of x

    • select

      public static ShaderNode select(ShaderNode condition, ShaderNode a, ShaderNode b)

      Returns a where condition is above 0.5, otherwise b. Both branches are computed; this is a select, not a branch.

      Parameters

      • condition: a FLOAT, usually a step

      • a: the value when true

      • b: the value when false, of the type of a

      Returns

      the selected value

    • unpackNormal

      public static ShaderNode unpackNormal(ShaderNode texel, float strength)

      Decodes a texel of a tangent space normal map (the usual blue-ish image) into a direction, scaling its slope by strength.

      Parameters

      • texel: a VEC4 read with sample

      • strength: 1 for the map as authored, 0 for flat

      Returns

      a VEC3 tangent space normal, not normalized

    • perturbNormal

      public static ShaderNode perturbNormal(ShaderNode tangentNormal)

      Bends the world space surface normal by a tangent space normal, for the NORMAL hook. The tangent frame is derived from the surface normal and the world axes, so it needs no tangents in the mesh and is the same on every backend: on ground and water, tangent x runs along world x and y along world z; on walls it runs around the vertical. That suits tiling detail, noise and terrain maps. A map painted for one model's UV layout reads correctly where that layout follows the world axes.

      Parameters
      • tangentNormal: a VEC3, such as unpackNormal's
      Returns

      the unit world space normal

    • blendNormals

      public static ShaderNode blendNormals(ShaderNode base, ShaderNode detail)

      Blends two tangent space normals so the detail rides on the base rather than averaging it flat ("whiteout" blend).

      Parameters

      • base: a VEC3 tangent space normal

      • detail: another

      Returns

      the combined VEC3, not normalized

    • widen

      public static ShaderNode widen(ShaderNode n, ShaderType t)

      Repeats a FLOAT into a vector of t, or returns the node itself when it already has that type.

      Parameters

      • n: the node

      • t: the target type

      Returns

      a node of type t

    • getType

      public ShaderType getType()

      Returns the type of the value.

      Returns

      the type