ShadersModule

Get Started

Spark AR Studio
Spark AR Hub
Features
Learn
Creators
Partners
Blog
Community

Create AR effects for Instagram and Facebook.
Get Started

Scripting API

ShadersModule

The ShadersModule exposes APIs to create Visual Shaders using JavaScript.
The following is an explanation of the unique types and concepts specific to the ShadersModule.

PrimitiveOrShaderSignal is a union type of Vec2Signal, PointSignal, Vec4Signal, VectorSignal, TransformSignal, or ShaderSignal.
ShaderSignal is a graphics shader output that produces one of the types defined in the above union. As ShaderSignal is GPU bound, it can only be used in a GPU context.

ShaderSignal can also be of a function type, used for function mapping from one type to another.
For example, a shader with the signature function(Vec2Signal): Vec4Signal is a type of a function that maps a Vec2Signal to a Vec4Signal.

Example

//==============================================================================
// The following example demonstrates how to use visual shaders to tile SDF
// shapes. This is a script version of the following Patch Editor example:
// https://fb.me/tiled-sdf-patch
//
// Project setup:
// - Insert a rectangle and set it to 'Fill Parent'
// - Create a new material and assign it to the rectangle
//==============================================================================

// Load in the required modules
const Materials = require('Materials');
const Reactive = require('Reactive');
const Shaders = require('Shaders');

// Enable async/await in JS [part 1]
(async function() {
  // Locate the material in the Assets
  const [material] = await Promise.all([
    Materials.findFirst('defaultMaterial0')
  ]);

  // Create the SDF Star parameters
  const center = Reactive.pack2(0.05,0.05);
  const radius = 0.04;
  const radius2 = Reactive.mul(radius,0.5);
  const sides = 5;

  // Create the SDF Star
  const sdfStar = Shaders.sdfStar(center,radius,radius2,sides);

  // Create the SDF Mix
  const sdfMix = Shaders.sdfMix(sdfStar,0,0.993);

  // Create the SDF Repeat parameters
  const pivot = Reactive.pack2(0.05,0.05);
  const size = Reactive.pack2(0.09,0.09);

  // Create the SDF Repeat
  const sdfRepeat = Shaders.sdfRepeat(sdfMix,pivot,size);

  // Create the step
  const step = Reactive.step(sdfRepeat,0);

  // Create the gradient
  const gradient = Shaders.gradient({"type" : Shaders.GradientType.HORIZONTAL});

  // Create the first mix paramaters
  const color1 = Reactive.pack4(1,0.57,0,1);
  const color2 = Reactive.pack4(1,0.25,1,1);

  // Create the first mix
  const mix1 = Reactive.mix(color1,color2,gradient);

  // Create the color for the second mix
  const color3 = Reactive.pack4(0,0,0,0);

  // Create the second mix
  const mix2 = Reactive.mix(mix1,color3,step);

  // Define the texture slot of the material to update
  const textureSlot = Shaders.DefaultMaterialTextures.DIFFUSE;

  // Assign the shader signal to the texture slot
  material.setTexture(mix2, {textureSlotName: textureSlot});

// Enable async/await in JS [part 2]

Properties

This module exposes no properties.

Methods

Method	Description
`blend`	blend(src: ShaderSignal \| PointSignal \| Vec4Signal, dst: ShaderSignal \| PointSignal \| Vec4Signal, config: {mode: BlendMode}): ShaderSignal Blends two colors using the specified blending mode. When a color is passed as a `PointSignal`, its alpha value is considered to be 1. If both colors are passed as a `PointSignal` (without the alpha channel specified), the result will also be a `PointSignal`. `src`: either a `PointSignal`, a `Vec4Signal` or a Shader which outputs one of these two types. `dst`: either a `PointSignal`, a `Vec4Signal` or a Shader which outputs one of these two types. returns: a shader which outputs a `Vec4Signal` if either of (or both) `src` or `dst` are of type `Vec4Signal`, or a `PointSignal` if not.
`colorSpaceConvert`	colorSpaceConvert(color: ShaderSignal \| PointSignal \| Vec4Signal, config: {inColorSpace: ColorSpace, outColorSpace: ColorSpace}): ShaderSignal Converts a color from the input color space to the output color space. `color`: either a `PointSignal`, a `Vec4Signal` or a shader which outputs one of these two types. returns: a shader which outputs a `Vec4Signal` if `color` is of `Vec4Signal` type, or a `PointSignal` if not.
`composition`	composition(f: ShaderSignal, g: ShaderSignal \| number \| ScalarSignal \| Vec2Signal \| PointSignal \| Vec4Signal \| VectorSignal \| TransformSignal): ShaderSignal Returns a signal for the shader composition of the two given functions (a texture and a transform for example). `f`: a shader which takes in a value of one type and outputs a different type. For example, `function_f(A): B` `g`: a shader which takes in a value of one type and outputs a different type (for example, `function_g(I): A`), or a signal of `A`. returns: a shader of `function_f(function_g(I)) => A`, if `g` was a shader, or `function_f(signal of A) => B`, if otherwise.
`derivative`	derivative(v: ShaderSignal \| number \| ScalarSignal \| Vec2Signal \| PointSignal \| Vec4Signal \| VectorSignal, config: {derivativeType: DerivativeType}): ShaderSignal Returns a signal for the specified shader derivative of the given signal. `v`: either a `ScalarSignal`, a `Vec2Signal`, a `PointSignal`, a `Vec4Signal`, a `VectorSignal`, or a shader which outputs one of these types. returns: a shader of a derivate type specified by `config`.
`fallback`	fallback(main: ShaderSignal \| number \| ScalarSignal \| Vec2Signal \| PointSignal \| Vec4Signal \| VectorSignal \| TransformSignal, fallback: ShaderSignal \| number \| ScalarSignal \| Vec2Signal \| PointSignal \| Vec4Signal \| VectorSignal \| TransformSignal): ShaderSignal Forwards the `main` input if present, otherwise uses `fallback`. `main`: a signal or shader which outputs a value of signal type. `fallback`: a signal or shader which outputs a value of signal type. returns: `main` if its output is present, or `fallback` if not.
`fragmentStage`	fragmentStage(v: ShaderSignal \| number \| ScalarSignal \| Vec2Signal \| PointSignal \| Vec4Signal \| VectorSignal \| TransformSignal): ShaderSignal Forces the computation of `val` to happen at the fragment stage. `v`: a signal or shader which outputs a value of signal type.
`functionScalar`	functionScalar(): ShaderSignal Returns a signal for the identity function over the specified type. returns: shader `function(ScalarSignal): ScalarSignal`
`functionVec2`	functionVec2(): ShaderSignal Returns a signal for the identity function over the specified type. returns: shader `function(Vec2Signal): Vec2Signal`
`functionVec3`	functionVec3(): ShaderSignal Returns a signal for the identity function over the specified type. returns: shader `function(PointSignal): PointSignal`
`functionVec4`	functionVec4(): ShaderSignal Returns a signal for the identity function over the specified type. returns: shader `function(Vec4Signal): Vec4Signal`
`gradient`	gradient(config: {type: GradientType}): ShaderSignal Returns a signal for the specified gradient. returns: shader `function(Vec2Signal): ScalarSignal` representing a gradient defined by `config`
`renderTargetSize`	renderTargetSize(): Vec2Signal Returns a signal of the current render target's size. returns: shader `function(): Vec2Signal`
`sdfAnnular`	sdfAnnular(sdf: ShaderSignal, width: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the given SDF shape made annular (ring-like) by the specified width. `sdf`: shader `function(Vec2Signal): ScalarSignal` `width`: number, ScalarSignal or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfCircle`	sdfCircle(center: ShaderSignal \| Vec2Signal, radius: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal for a circle SDF shape. `center`: `Vec2Signal` or shader `function(): Vec2Signal` `radius`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfComplement`	sdfComplement(sdf: ShaderSignal): ShaderSignal Returns a signal of the complement of the given SDF shape. `sdf`: shader `function(Vec2Signal): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfDifference`	sdfDifference(sdf1: ShaderSignal, sdf2: ShaderSignal): ShaderSignal Returns a signal of the difference of the two given SDF shapes. `sdf1`: shader `function(Vec2Signal): ScalarSignal` `sdf2`: shader `function(Vec2Signal): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal` which result is the product of substracting result of `sdf2` from result of `sdf1`
`sdfEllipse`	sdfEllipse(center: ShaderSignal \| Vec2Signal, halfSize: ShaderSignal \| Vec2Signal): ShaderSignal Returns a signal for an ellipse SDF shape. `center`: `Vec2Signal` or shader `function(): Vec2Signal` `halfSize`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfFlip`	sdfFlip(sdf: ShaderSignal, offset: ShaderSignal \| Vec2Signal, normal: ShaderSignal \| Vec2Signal): ShaderSignal Returns a signal of the given SDF shape flipped around the plane given by the offset an normal. `sdf`: shader `function(Vec2Signal): ScalarSignal` `offset`: `Vec2Signal` or shader `function(): Vec2Signal` `normal`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfHalfPlane`	sdfHalfPlane(offset: ShaderSignal \| Vec2Signal, normal: ShaderSignal \| Vec2Signal): ShaderSignal Returns a signal for a half-plane SDF shape. `offset`: `Vec2Signal` or shader `function(): Vec2Signal` `normal`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfIntersection`	sdfIntersection(sdf1: ShaderSignal, sdf2: ShaderSignal): ShaderSignal Returns a signal of the intersection of the two given SDF shapes. `sdf1`: shader `function(Vec2Signal): ScalarSignal` `sdf2`: shader `function(Vec2Signal): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfLine`	sdfLine(offset: ShaderSignal \| Vec2Signal, normal: ShaderSignal \| Vec2Signal, halfWidth: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal for a line SDF shape. `offset`: `Vec2Signal` or shader `function(): Vec2Signal` `normal`: `Vec2Signal` or shader `function(): Vec2Signal` `halfWidth`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfMix`	sdfMix(sdf1: ShaderSignal, sdf2: ShaderSignal, alpha: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the linear interpolation of the two given SDF shapes, modulated by alpha. `sdf1`: shader `function(Vec2Signal): ScalarSignal` `sdf2`: shader `function(Vec2Signal): ScalarSignal` `alpha`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfPolygon`	sdfPolygon(center: ShaderSignal \| Vec2Signal, radius: ShaderSignal \| number \| ScalarSignal, numSides: ShaderSignal \| number \| ScalarSignal, config: {sdfVariant: SdfVariant}): ShaderSignal Returns a signal for a polygon SDF shape. `center`: `Vec2Signal` or shader `function(): Vec2Signal` `radius`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` `numSides`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfRectangle`	sdfRectangle(center: ShaderSignal \| Vec2Signal, halfSize: ShaderSignal \| Vec2Signal, config: {sdfVariant: SdfVariant}): ShaderSignal Returns a signal for a rectangle SDF shape. `center`: `Vec2Signal` or shader `function(): Vec2Signal` `halfSize`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfRepeat`	sdfRepeat(sdf: ShaderSignal, pivot: ShaderSignal \| Vec2Signal, size: ShaderSignal \| Vec2Signal): ShaderSignal Returns a signal of the given SDF shape's grid repetition. The shape should be centered on the pivot and fit within the given size. `sdf`: shader `function(Vec2Signal): ScalarSignal` `pivot`: `Vec2Signal` or shader `function(): Vec2Signal` `size`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfRotation`	sdfRotation(sdf: ShaderSignal, pivot: ShaderSignal \| Vec2Signal, angle: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the given SDF shape rotated around the given pivot by the given angle. `sdf`: shader `function(Vec2Signal): ScalarSignal` `pivot`: `Vec2Signal` or shader `function(): Vec2Signal` `angle`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfRotationalRepeat`	sdfRotationalRepeat(sdf: ShaderSignal, pivot: ShaderSignal \| Vec2Signal, radius: ShaderSignal \| number \| ScalarSignal, numTimes: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the given SDF shape's rotational repetition numTimes at the given radius. The shape should be centered on the pivot and fit within the angular sector defined by numTimes at the given radius. `sdf`: shader `function(Vec2Signal): ScalarSignal` `pivot`: `Vec2Signal` or shader `function(): Vec2Signal` `radius`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` `numTimes`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfRound`	sdfRound(sdf: ShaderSignal, radius: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the given SDF shape rounded by the specified radius. `sdf`: shader `function(Vec2Signal): ScalarSignal` `radius`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfScale`	sdfScale(sdf: ShaderSignal, pivot: ShaderSignal \| Vec2Signal, size: ShaderSignal \| Vec2Signal): ShaderSignal Returns a signal of the given SDF shape scaled around the given pivot by the given size. `sdf`: shader `function(Vec2Signal): ScalarSignal` `pivot`: `Vec2Signal` or shader `function(): Vec2Signal` `size`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfShear`	sdfShear(sdf: ShaderSignal, pivot: ShaderSignal \| Vec2Signal, shear: ShaderSignal \| Vec2Signal): ShaderSignal Returns a signal of the given SDF shape scaled around the given pivot by the given shear amount. `sdf`: shader `function(Vec2Signal): ScalarSignal` `pivot`: `Vec2Signal` or shader `function(): Vec2Signal` `shear`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfSmoothDifference`	sdfSmoothDifference(sdf1: ShaderSignal, sdf2: ShaderSignal, k: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the smooth difference of the two given SDF shapes, modulated by K. `sdf1`: shader `function(Vec2Signal): ScalarSignal` `sdf2`: shader `function(Vec2Signal): ScalarSignal` `k`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfSmoothIntersection`	sdfSmoothIntersection(sdf1: ShaderSignal, sdf2: ShaderSignal, k: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the smooth intersection of the two given SDF shapes, modulated by K. `sdf1`: shader `function(Vec2Signal): ScalarSignal` `sdf2`: shader `function(Vec2Signal): ScalarSignal` `k`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfSmoothUnion`	sdfSmoothUnion(sdf1: ShaderSignal, sdf2: ShaderSignal, k: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the smooth union of the two given SDF shapes, modulated by K. `sdf1`: shader `function(Vec2Signal): ScalarSignal` `sdf2`: shader `function(Vec2Signal): ScalarSignal` `k`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfStar`	sdfStar(center: ShaderSignal \| Vec2Signal, radius1: ShaderSignal \| number \| ScalarSignal, radius2: ShaderSignal \| number \| ScalarSignal, numSides: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal for a star SDF shape. `center`: `Vec2Signal` or shader `function(): Vec2Signal` `radius1`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` `radius2`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` `numSides`: `number`, `ScalarSignal` or shader `function(): ScalarSignal`
`sdfTranslation`	sdfTranslation(sdf: ShaderSignal, offset: ShaderSignal \| Vec2Signal): ShaderSignal Returns a signal of the given SDF shape translated by the given offset. `sdf`: shader `function(Vec2Signal): ScalarSignal` `offset`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfTwist`	sdfTwist(sdf: ShaderSignal, pivot: ShaderSignal \| Vec2Signal, twist: ShaderSignal \| number \| ScalarSignal): ShaderSignal Returns a signal of the given SDF shape twisted around the pivot by the given amount. `sdf`: shader `function(Vec2Signal): ScalarSignal` `pivot`: `Vec2Signal` or shader `function(): Vec2Signal` `twist`: `number`, `ScalarSignal` or shader `function(): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`sdfUnion`	sdfUnion(sdf1: ShaderSignal, sdf2: ShaderSignal): ShaderSignal Returns a signal of the union of the two given SDF shapes. `sdf1`: shader `function(Vec2Signal): ScalarSignal` `sdf2`: shader `function(Vec2Signal): ScalarSignal` returns: shader `function(Vec2Signal): ScalarSignal`
`textureSampler`	textureSampler(texture: ShaderSignal, uv: ShaderSignal \| Vec2Signal): ShaderSignal Samples the given texture at the specified uv coordinates. `texture`: shader `function(Vec2Signal): ScalarSignal`, `function(Vec2Signal): Vec2Signal`, `function(Vec2Signal): PointSignal` or `function(Vec2Signal): Vec4Signal` `uv`: `Vec2Signal` or shader `function(): Vec2Signal` returns: shader `function(): ScalarSignal`, `function(): Vec2Signal`, `function(): PointSignal` or `function(): Vec4Signal` depending on underlying `texture` shader return type
`textureTransform`	textureTransform(texture: ShaderSignal, transform: ShaderSignal): ShaderSignal Transforms the given texture with the specified Mat3 transform. `texture`: shader `function(Vec2Signal): ScalarSignal`, `function(Vec2Signal): Vec2Signal`, `function(Vec2Signal): PointSignal` or `function(Vec2Signal): Vec4Signal` `transform`: shader `function(): Matrix3Signal` returns: shader `function(Vec2Signal): ScalarSignal`, `function(Vec2Signal): Vec2Signal`, `function(Vec2Signal): PointSignal` or `function(Vec2Signal): Vec4Signal` depending on underlying `texture` shader return type
`vertexAttribute`	vertexAttribute(config: {variableName: VertexAttribute}): ShaderSignal Returns a signal for the specified vertex attribute depending on the VertexAttribute used. returns: for `VertexAttribute.POSITION` a shader `function(): Vec4Signal` for `VertexAttribute.NORMAL` a shader `function(): PointSignal` for `VertexAttribute.TANGENT` a shader `function(): Vec4Signal` for `VertexAttribute.TEX_COORDS` a shader `function(): Vec2Signal` for `VertexAttribute.COLOR` a shader `function(): Vec4Signal` for `VertexAttribute.BASE_POSITION` a shader `function(): Vec4Signal`
`vertexTransform`	vertexTransform(config: {variableName: BuiltinUniform}): ShaderSignal Returns a signal for the specified vertex transform depending on the BuiltinUniform used. returns: for `BuiltinUniform.MVP_MATRIX` a shader `function(): TransformSignal` for `BuiltinUniform.MV_MATRIX` a shader `function(): TransformSignal` for `BuiltinUniform.M_MATRIX` a shader `function(): TransformSignal` for `BuiltinUniform.V_MATRIX` a shader `function(): TransformSignal` for `BuiltinUniform.P_MATRIX` a shader `function(): TransformSignal` for `BuiltinUniform.VP_MATRIX` a shader `function(): TransformSignal` for `BuiltinUniform.NORMAL_MATRIX` a shader `function(): Matrix3Signal` for `BuiltinUniform.INV_M_MATRIX` a shader `function(): TransformSignal` for `BuiltinUniform.INV_V_MATRIX` a shader `function(): TransformSignal` for `BuiltinUniform.INV_P_MATRIX` a shader `function(): TransformSignal`

Classes

This module exposes no classes.

Enums

Enum	Description
BlendedMaterialTextures	The `BlendedMaterialTextures` enum describes the different texture slots for a flat material.
BlendMode	The `BlendMode` enum describes the blending mode.
BuiltinUniform	The `BuiltinUniform` enum describes the bultin shader uniforms.
ColorSpace	The `ColorSpace` enum describes the color space.
DefaultMaterialTextures	The `DefaultMaterialTextures` enum describes the different texture slots for a default material.
DerivativeType	The `DerivativeType` enum describes the shader derivative type.
FacePaintMaterialTextures	The `FacePaintMaterialTextures` enum describes the different texture slots for a face paint material.
GradientType	The `GradientType` enum describes the type of the shader gradient.
PhysicallyBasedMaterialTextures	The `PhysicallyBasedMaterialTextures` enum describes the different texture slots for a physically based material.
SdfVariant	The `SdfVariant` enum describes the SDF variant.
VertexAttribute	The `VertexAttribute` enum describes the bultin vertex attributes.

ShadersModule

Contents

Contents

Example

Properties

Methods

Classes

Enums