Scripting reference 180

From PopcornFX
Jump to: navigation, search

In PopcornFX, particle behavior is controlled by short programs called "scripts". These include the "Spawn scripts", "Evolve scripts" and "Layer Scripts".
The scripts are edited inside the PopcornFX editor with the Script editor

This page is for version v1.8.0 and above
For the latest version of PopcornFX, see: Scripting reference
For previous versions of PopcornFX, see the following pages:


Overview

The popcorn-script syntax borrows most of its concepts from high-level shader languages such as GLSL or HLSL.

Every name/symbol in popcorn-scripts is case-sensitive, and each statement must end with a semicolon.

For the full language reference, see the Scripting language reference page.


Particle-related functions and variables

In the following tables you will find a quick review of most of the things you can use inside a particle-script. Sometimes a link will be provided to a page that contains more details on a specific item.

How to read the tables:

  • The Spawn column tells which of these are available inside a particle Spawn-script.
  • The Evolve column tells which of these are available inside a particle Evolve-script.
  • R means you can read the variable.
  • RW means you can read AND write the variable.


(Note: Some of these will work in versions below 1.8.0)


Particle spawn and evolve scripts

Particle

Spawn Evolve type description
Fields
RW RW all the Particle fields particle fields
  RW float LifeRatio

Life-ratio of the particle, in the [0, 1] range. Does not exist inside Spawn-scripts.

RW RW float Life

Life duration of the particle. virtual particle field, for scripting convenience, maps to 1.0 / InvLife

  R float Age

Age of the particle in seconds

  R float dt

length of the simulation frame in seconds

ParentFields
R   all the Particle fields particle parent-fields
Functions
    void kill(int condition)

kills the particle if 'condition' is not false. Not available in spawn-scripts. To instant-kill inside a spawn-script, use Life = 0;


Spawner

Spawn Evolve type description
R   float spawner.Age

Time in seconds the spawner has been spawning particles. Useful for infinite spawner whose liferatio stays at zero. (Was SpawnerRunningTime before v1.8.0)

R   float spawner.Life

Duration of the spawner, in seconds

R   float spawner.LifeRatio

Life-ratio of the spawner, in the [0, 1] range. (Was SpawnerLifeRatio before v1.8.0)

R   float spawner.EmittedCount

number of particles already emitted by the spawner before it spawned this-one

R   float spawner.SpawnRate

number of particles emitted per spawn metric (per second, per world unit, or per custom metric, depending on the spawner's settings)

R   float spawner.SpawnCount

total number of particles the spawner will emit (if available, otherwise zero)

R   float spawner.BaseSpawnRate

number of particles emitted per spawn metric, before being weighted by the spawn flux and layer script

R   float spawner.BaseSpawnCount

total number of particles the spawner will emit (if available, otherwise zero), before being weighted by the spawn flux and layer script

R   float spawner.FirstSpawnDelay

returns the value of the 'FirstSpawnDelay' property in the parent particle spawner action layer or trail evolver evolver spawner.


Events

Spawn Evolve type description
    all the Particle events particle events
    void EventName.trigger(int condition)

triggers the event based on 'condition'. 'condition' must be 0 or -1, or the result of a compare (ex: MyEvent.trigger(LifeRatio > 0.5); )
Spawns at the current Position particle field, and Velocity oriented if it exists.
Never broadcasts the event to the game engine.

    void EventName.trigger(int condition, float3 position, float3 forwardAxis, float3 upAxis)

Like .trigger(cond), but with explicit position and axis for orientation (instead of Position and Velocity)

    void EventName.broadcast(int condition) Experimental

Like .trigger(cond), except it also forces broadcasting of the event to the game engine, as long as the event's 'Broadcast' property is enabled.

    void EventName.broadcast(int condition, float3 position, float3 forwardAxis, float3 upAxis) Experimental

Like .trigger(cond, pos, fwd, up) but .broadcast.

    void Trigger(int eventId, int condition) Deprecated

triggers the event referenced by 'eventId', which is the zero-based index of the desired event in the event list, based on 'condition'. 'condition' must be 0 or -1, or the result of a compare (ex: Trigger(select(0, 1, Position.y < 0), LifeRatio > 0.5); --> when the LifeRatio goes above 0.5, if the particle is above the plane on y = 0, will trigger the first event, if it's below or on the plane, will trigger the second event in the event-list.)

Layer scripts

See the Layer page for how to create and use layer scripts

Spawner

Layer spawn-scripts not yet available. In 1.8 you can only use layer evolve scripts.

Spawn Evolve type description
  R float Age

Time in seconds the spawner has been spawning particles (at the beginning of the frame)

RW R float Life

Duration of the spawner, in seconds

  R float LifeRatio

Life-ratio of the spawner, in the [0, 1] range (at the beginning of the frame)

  R float EmittedCount

number of particles already emitted by the spawner (at the beginning of the frame)

  RW float Flux

Base value each frame is 1.0, you can write to this to weight the spawn rate by a custom value. Setting it to 2.0 will make the spawner emit twice as many particles as its base value.

  R float SpawnRate

number of particles emitted per spawn metric (per second, per world unit, or per custom metric, depending on the spawner's settings)

  R float SpawnCount

total number of particles the spawner will emit (if available, otherwise zero)

RW R float BaseSpawnRate

number of particles emitted per spawn metric, before being weighted by any spawn flux

RW R float BaseSpawnCount

total number of particles the spawner will emit (if available, otherwise zero), before being weighted by any spawn flux

RW R float FirstSpawnDelay

returns the value of the 'FirstSpawnDelay' property in the parent particle spawner action layer.

R R float3 Position

Position of the layer at the end of the current frame.

R R float3 PrevPosition

Position of the layer at the beginning of the current frame.

R R float3 Orientation

Orientation of the layer at the end of the current frame. (represented as euler angles in radians)

R R float3 PrevOrientation

Orientation of the layer at the beginning of the current frame. (represented as euler angles in radians)

RW RW float3 PositionOffset

Position offset of the layer at the end of the current frame. Defaults to zero

RW RW float3 PrevPositionOffset

Position offset of the layer at the beginning of the current frame. Defaults to zero

RW RW float3 OrientationOffset

Orientation offset of the layer at the end of the current frame. Defaults to zero. (represented as euler angles in radians)

RW RW float3 PrevOrientationOffset

Orientation offset of the layer at the beginning of the current frame. Defaults to zero. (represented as euler angles in radians)


Common to particle and layer scripts

Attributes

Spawn Evolve type description
R R all the particle attributes


Samplers

Attribute-samplers cannot currently be accessed during evolve. If you do try to access them, you will instead get the values of the original sampler, as defined in the effect, NOT the actual sampler overridden by the game.

Spawn Evolve type description
R ~ all the Particle samplers particle samplers
curve sampler Curve sampler
  ~ float# SamplerName.sample(float cursor)

Samples the curve sampler curve at x=cursor. Return type is a float vector whose dimension matches the curve dimension. a 1D curve will return a float, 3D curve will return a float3, etc...

  ~ float# SamplerName.integrate(float cursorStart, float cursorEnd)

Computes the integral of the curve sampler curve between x0=cursorStart and x1=cursorEnd. Return type is a float vector whose dimension matches the curve dimension. Each xyzw element of the result will contain the integral of each of the separate curve components.

double-curve sampler Double-curve sampler
  ~ float# SamplerName.sample(float cursor, float ratio)

Samples the double-curve sampler double-curve at x=cursor, and interpolates between the results from each curve using ratio which should be in the [0,1] range.

shape sampler Shape sampler
  ~ int3 SamplerName.sampleParametricCoords()

Samples a random location identifier on the shape sampler shape. The resulting parametric coordinate then be passed to the other sampling functions.

  ~ float3 SamplerName.samplePosition([ int3 pCoords ])

Samples a position on the shape sampler shape. Accepts an optional parametric coordinate. If no pCoord is provided, will sample a random location.

  ~ float3 SamplerName.sampleNormal([ int3 pCoords ])

Samples a normal on the shape sampler shape. Accepts an optional parametric coordinate. If no pCoord is provided, will sample a random location.

  ~ float4 SamplerName.sampleTangent([ int3 pCoords ])

Samples a tangent on the shape sampler shape. Accepts an optional parametric coordinate. If no pCoord is provided, will sample a random location. Sampled tangent contains a sign-flip in its 'w' component to take into account tangent-basis mirroring.

  ~ float2 SamplerName.sampleTexcoord([ int3 pCoords ])

Samples a texture-coordinate on the shape sampler shape. Accepts an optional parametric coordinate. If no pCoord is provided, will sample a random location. additional functions sampleTexcoord0 to sampleTexcoord9 are declared, to sample different explicit UV streams.

  ~ float4 SamplerName.sampleColor([ int3 pCoords ])

Samples a color on the shape sampler shape. Accepts an optional parametric coordinate. If no pCoord is provided, will sample a random location. additional functions sampleColor0 to sampleColor9 are declared, to sample different explicit Color streams.

  ~ float3 SamplerName.sampleVelocity([ int3 pCoords ])

Samples the instantaneous surface-velocity of the shape sampler shape. Accepts an optional parametric coordinate. If no pCoord is provided, will sample a random location.

  ~ float SamplerName.surface()

Returns the surface of the shape sampler shape.

  ~ float SamplerName.volume()

Returns the volume of the shape sampler shape.

  ~ float SamplerName.radius()

Returns the radius of the shape sampler shape if it's a sphere, complexEllipsoid, capsule, cone, or cylinder. If not, returns zero.

  ~ float SamplerName.innerRadius()

Returns the innerRadius of the shape sampler shape if it's a sphere, complexEllipsoid, capsule, or cylinder. If not, returns zero.

  ~ float SamplerName.height()

Returns the height of the shape sampler shape if it's a capsule, cone, or cylinder. If not, returns zero.

  ~ int SamplerName.triangleCount()

Returns the triangle-count of the shape sampler shape if it's a mesh. If not, returns zero.

  ~ float3 SamplerName.meshScale()

Returns the mesh-scale of the shape sampler shape if it's a mesh. If not, returns zero.

  ~ float3 SamplerName.boxDim()

Returns the dimensions of the shape sampler shape if it's a box. If not, returns zero.

  ~ int SamplerName.type()

Returns the type of the shape sampler shape. Can be any of the following:

  1. shapeType.Box
  2. shapeType.Sphere
  3. shapeType.ComplexEllipsoid
  4. shapeType.Cylinder
  5. shapeType.Capsule
  6. shapeType.Cone
  7. shapeType.Plane
  8. shapeType.Mesh
  9. shapeType.Spline
  10. shapeType.Collection
  11. shapeType.Sweep

  ~ float3 SamplerName.position()

Returns the position of the shape sampler shape.

  ~ int3 SamplerName.buildParametricCoordsMesh(int triangleId, float2 barycentricCoordinates)

Allows to manually build parametric coordinates on a shape sampler mesh shape.

  ~ int3 SamplerName.buildParametricCoordsBox(float3 normalizedPos)

Allows to manually build parametric coordinates on a shape sampler box shape. Declared when sampling dimensionality is set to 'Volume'

  ~ int3 SamplerName.buildParametricCoordsBox(int faceId, float2 uv)

Allows to manually build parametric coordinates on a shape sampler box shape. Declared when sampling dimensionality is set to 'Surface'.
'faceId' can be one of the following values: [-3, -2, -1, 1, 2, 3]. -1 and 1 map the -X and +X faces, respectively. -2, 2 map the -Y, +Y faces, and -3, 3 map the -Z, +Z faces.
'uv' is a float2 UV coordinate on the selected face. it's in the [0,1] range.

  ~ int3 SamplerName.buildParametricCoordsSphere(float2 polarAngles, float radius)

Allows to manually build parametric coordinates on a shape sampler sphere shape.

  ~ int3 SamplerName.buildParametricCoordsCone(float height, float angle [, float radius])

Allows to manually build parametric coordinates on a shape sampler cone shape. Radius only available when sampling dimensionality is set to 'Volume'

  ~ int3 SamplerName.buildParametricCoordsCapsule(float height, float angle, float radius)

Allows to manually build parametric coordinates on a shape sampler capsule shape.

  ~ int3 SamplerName.buildParametricCoordsCylinder(float height, float angle, float radius)

Allows to manually build parametric coordinates on a shape sampler cylinder shape.

  ~ float SamplerName.sampleDistanceField(float3 position)

Samples the distance-field of the shape sampler shape at the specified location.

  ~ int SamplerName.contains(float3 position)

returns true if the shape sampler shape contains the specified position, false otherwise.

  ~ float4 SamplerName.intersect(float3 rayStart, float3 rayDirection, float rayLength)

raytraces the shape sampler shape with the specified ray. returns the hit normal and intersection distance packed in a float4.

  ~ float4 SamplerName.project(float3 position)

Computes the projection of the specified position on the shape sampler shape. returns the projected position and projection distance packed in a float4.

  ~ int3 SamplerName.projectParametricCoords(float3 position)

Computes the projection of the specified position on the shape sampler shape. returns the parametric coordinate of the projected location.

  ~ float3 SamplerName.axisUp()

Returns the up axis of the shape sampler shape.

  ~ float3 SamplerName.axisSide()

Returns the side axis of the shape sampler shape.

  ~ float3 SamplerName.axisForward()

Returns the forward axis of the shape sampler shape.

texture sampler Texture sampler
  ~ float# SamplerName.sample(float2 uv [, int filterMode [, int wrapMode]])

Samples a texel on the texture sampler texture at the specified UV coordinates. the optional 'filterMode' can be one of the following:

  1. textureFilter.Default
  2. textureFilter.Point
  3. textureFilter.Linear

The optional 'addrMode' can be one of the following:

  1. textureAddr.Default
  2. textureAddr.Clamp
  3. textureAddr.Wrap

  ~ float# SamplerName.sample(float subRectId, float2 uv [, int filterMode [, int wrapMode]])

Samples a texel on the texture sampler texture atlas at the specified sub-rect and UV coordinates.

  ~ float2 SamplerName.sampleDensity(float2 uv [, int filterMode [, int wrapMode]])

Builds a new UV from the input UV so that the final UV distribution matches the density of the texture sampler texture.

  ~ float2 SamplerName.sampleDensity(float subRectId, float2 uv [, int filterMode [, int wrapMode]])

Does not work properly in v1.8.0! will be fixed in v1.9.0 only. Avoid using this until the v1.9.0 release.
Builds a new UV from the input UV so that the final UV distribution matches the density of the texture sampler texture atlas at the specified sub-rect.

turbulence sampler Turbulence sampler
  ~ float3 SamplerName.sample(float3 position)

Samples the default field turbulence sampler turbulence at the specified location. (by default, samples the curl, so it's basically curl-noise)/font>

  ~ float3 SamplerName.sampleCurl(float3 position)

Samples the curl of the turbulence sampler turbulence noise-field at the specified location./font>

  ~ float3 SamplerName.samplePotential(float3 position)

Samples the potential of the turbulence sampler turbulence noise-field at the specified location./font>

audio sampler Audio sampler
  ~ float SamplerName.sample(float cursor [, int sampleFilter])

Samples the spectrum sampler spectrum at the specified cursor, which is in the [0,1] range, 0 meaning full-bass and 1 meaning full-treble. sampleFilter can be one of the following:

  1. spectrumFilter.Point
  2. spectrumFilter.Linear
  3. spectrumFilter.Cubic

  ~ float SamplerName.sample(float cursor, float convolution [, int sampleFilter [, int convolutionFilter]])

Samples the spectrum sampler spectrum at the specified cursor, which is in the [0,1] range, 0 meaning full-bass and 1 meaning full-treble. The convolution parameters is in the [0,1] range and allows to smooth the sampled spectrum. The convolutionFilter accepts the same values as the sampleFilter, and tells how to interpolate between the various spectrum 'mipmaps' used by the convolution level.

text sampler Text sampler
  ~ int SamplerName.charCode(int charId)

Samples the text sampler text at the specified character position, and returns the ASCII code of the sampled character.

  ~ int SamplerName.charCode(int2 lineAndCharId)

Samples the text sampler text at the specified line and character position, and returns the ASCII code of the sampled character.

  ~ int SamplerName.charCount(int lineId)

Returns the number of characters at the specified line of the text sampler text.

  ~ int SamplerName.charCount()

Returns the number of characters in the whole text sampler text.

  ~ int SamplerName.lineCount()

Returns the number of lines in the whole text sampler text.


Scene

Spawn Evolve type description
Variables
R R float scene.Time

global date of the current particle medium collection, in seconds. (Was CurrentDate before v1.8.0)

R R int scene.surfaceType.*

All surface types configured in the project-settings 'Scene' panel

R R int scene.collisionFilter.*

All collision filters configured in the project-settings 'Scene' panel

Functions
    float3 scene.axisUp()

constant: up axis (based on the Axis-System).

    float3 scene.axisSide()

constant: side axis (based on the Axis-System).

    float3 scene.axisForward()

constant: forward axis (based on the Axis-System).

    float3 scene.isRight()

v1.8.2 constant: true (0xFFFFFFFF) if the Axis-System is right handed, or false (0x0) if left handed.
Example: Axis = cross(Velocity, scene.axisUp()) * iif(scene.isRight(), 1, -1);

    float3 scene.isRightSign()

v1.8.2 constant: 1.0 if the Axis-System is right handed, -1.0 if left handed.
Example: Axis = cross(Velocity, scene.axisUp()) * scene.isRightSign();

    float4 scene.intersect(float3 rayStart, float3 rayDirection, float rayLength [, int collisionFilter])

issues a scene intersection query, returns the intersection normal in xyz, and intersection distance in w.
The optional 'collisionFilter' parameter must be one of the collision filters you configured in the project-settings 'Scene' panel
ex: scene.collisionFilter.StaticGeom, scene.collisionFilter.ConvexHulls, etc...

    int4 scene.intersectExt(float3 rayStart, float3 rayDirection, float rayLength [, int collisionFilter]) Experimental

issues an extended scene intersection query, returns an int4 containing the packed intersection normal, intersection distance, and surface type.
Use the 'unpack' functions below to extract each one of them.
The optional 'collisionFilter' parameter must be one of the collision filters you configured in the project-settings 'Scene' panel
ex: scene.collisionFilter.StaticGeom, scene.collisionFilter.ConvexHulls, etc...

    float3 scene.unpackNormal(int4 packedISecResult) Experimental

takes a packed intersection result returned by scene.intersectExt(), extracts and returns the float3 intersection normal it contains.
Equivalent to scene.intersect(...).xyz

    float scene.unpackSceneDist(int4 packedISecResult) Experimental

takes a packed intersection result returned by scene.intersectExt(), extracts and returns the float intersection distance it contains.
Equivalent to scene.intersect(...).w

    int scene.unpackSceneSurface(int4 packedISecResult) Experimental

takes a packed intersection result returned by scene.intersectExt(), extracts and returns the int surface-type it contains.
The returned surface-type can be tested against one of the surface-types you configured in the project-settings 'Scene' panel
ex: scene.surfaceType.Grass, scene.surfaceType.Rock, etc...


Spatial layers

Spawn Evolve type description
    all the Spatial layer Spatial layers
Global queries
    int spatialLayers.LayerName.neighborCount(float3 center, float radius) Experimental

Returns the number of particles inside the query volume.

Field queries
    fieldType spatialLayers.LayerName.FieldName.closest(float3 center, float radius) Experimental

Returns the value of 'FieldName' of the closest particle inside the query volume.

    float# spatialLayers.LayerName.FieldName.sum(float3 center, float radius) Experimental

Returns the sum of 'FieldName' of all particles inside the query volume.

    float# spatialLayers.LayerName.FieldName.sumKernel(float3 center, float radius, samplerCurve1D kernelSampler) Experimental

Returns the sum of 'FieldName' of all particles inside the query volume, and uses the custom kernel (1D curve sampler curve sampler) to weight each value based on its distance to the query center.

    float# spatialLayers.LayerName.FieldName.average(float3 center, float radius) Experimental

Returns the average value of 'FieldName' of all particles inside the query volume.

    float# spatialLayers.LayerName.FieldName.averageKernel(float3 center, float radius, samplerCurve1D kernelSampler) Experimental

Returns the average value of 'FieldName' of all particles inside the query volume, and uses the custom kernel (1D curve sampler curve sampler) to weight each value based on its distance to the query center.



Language builtins

Constants

Name Value
pi $ \pi $ ~= 3.14159265359
phi $ \varphi $ ~= 1.61803398875
infinity $ +\infty $


Math functions

Function Plot Notation float int Description Input range $ \longrightarrow $ output range
rand(x,y)
Y N random function, returns a random value 'r' such that x <= r < y $ [-\infty, +\infty] \longrightarrow [x, y[ $
dot(u,v)
$ \vec{u} \cdot \vec{v} $ Y N vector dot-product $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
cross(u,v)
$ \vec{u} \times \vec{v} $ Y N 3D vector cross-product $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
mirror(v,n)
ScriptFunc Abs.png $ \vec{v} - 2*\vec{n} * (\vec{v} \cdot \vec{n}) $ Y N reflects (mirrors) the float3 vector 'v' on the plane defined by the float3 normal 'n'. $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
abs(x)
ScriptFunc Abs.png $ \begin{align} | x | \end{align} $ Y Y absolute value $ [-\infty, +\infty] \longrightarrow [0, +\infty] $
sign(x)
ScriptFunc Sign.png $ \begin{align} \frac{x}{| x |}\end{align} $ Y Y sign function, returns -1 when x <= -0, and +1 when x >= +0 $ [-\infty, +\infty] \longrightarrow [-1], [+1] $
ceil(x)
ScriptFunc Ceil.png $ \lceil x \rceil $ Y N/A ceiling rounding: rounds to the closest integer value >= x $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
floor(x)
ScriptFunc Floor 0.png $ \lfloor x \rfloor $ Y N/A floor rounding: rounds to the closest integer value <= x $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
frac(x) ScriptFunc Frac.png $ x % 1 $ Y N/A extracts the fractional part of 'x' $ [-\infty, +\infty] \longrightarrow [0, +1[ $
wavesq(x)
ScriptFunc WaveSquare.png Y N/A square wave function $ [-\infty, +\infty] \longrightarrow [-1, +1] $
wavetri(x)
ScriptFunc WaveTri.png Y N/A triangular wave function $ [-\infty, +\infty] \longrightarrow [0, +1] $
wavesaw(x)
ScriptFunc WaveSaw.png $ x - \lfloor x \rfloor $ Y N/A sawtooth wave function $ [-\infty, +\infty] \longrightarrow [0, +1] $
saturate(x)
ScriptFunc Saturate.png Y N/A clamps 'x' in the [0, 1] range $ [-\infty, +\infty] \longrightarrow [0, +1] $
step(x,y)
ScriptFunc Step.png $ \begin{align} x >= y\end{align} $ Y N step function. evaluates to 0 if x < y, and evaluates to 1 if x >= y $ [-\infty, +\infty] \longrightarrow [0, +1] $
discretize(x,y)
ScriptFunc Discretize.png Y N discretization function, snaps 'x' to the nearest step, given a step size 'y' $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
min(x,y)
ScriptFunc Min.png $ \begin{align} min(x, y) \end{align} $ Y Y minimization function: if x < y, returns x, otherwise, returns y $ [-\infty, +\infty] \longrightarrow [-\infty, y] $
max(x,y)
ScriptFunc Max.png $ \begin{align} max(x, y) \end{align} $ Y Y maximization function: if x > y, returns x, otherwise, returns y $ [-\infty, +\infty] \longrightarrow [y, +\infty] $
clamp(x,a,b)
ScriptFunc Clamp.png $ \begin{align} clamp(x, a, b) \end{align} $ Y N v1.8.0 clamp function: if x < a, returns a, otherwise, if x > b, returns b, otherwise, returns x $ [-\infty, +\infty] \longrightarrow [a, b] $
sqrt(x)

fast_sqrt(x)

ScriptFunc Sqrt.png $ \sqrt{x} $ Y N
  • square-root
  • faster square-root, lower precision
$ [0, +\infty] \longrightarrow [0, +\infty] $
rsqrt(x)

fast_rsqrt(x)

ScriptFunc RSqrt.png $ \frac{1}{\sqrt{x}} $ Y N/A
  • reverse square-root
  • faster reverse square-root, lower precision
$ [0, +\infty] \longrightarrow [0, +\infty] $
length(v)

fast_length(v)

$ \left\| v \right\| $ Y N/A
  • vector length
  • faster vector length, lower precision
$ [-\infty, +\infty] \longrightarrow [0, +\infty] $
normalize(v)

fast_normalize(v)

$ \vec{v} \cdot \frac{1}{ \left\| v \right\| } $ Y N/A
  • vector normalization
  • faster vector normalization, lower precision
$ [-\infty, +\infty] \longrightarrow [-1, +1] $
exp(x)

fast_exp(x)

ScriptFunc Exp.png $ \begin{align} e^x \end{align} $ Y N
  • natural exponential
  • faster natural exponential, lower precision
$ [-\infty, +\infty] \longrightarrow [0, +\infty] $
exp2(x)

fast_exp2(x)

ScriptFunc Exp2.png $ \begin{align} 2^x \end{align} $ Y N
  • base-2 exponential
  • faster base-2 exponential, lower precision
$ [-\infty, +\infty] \longrightarrow [0, +\infty] $
pow(x,y)

fast_pow(x,y)

ScriptFunc Pow.png $ \begin{align} x^y \end{align} $ Y N
  • power function
  • faster power function, lower precision
$ {[0, +\infty], [-\infty, +\infty]} \longrightarrow [-\infty, +\infty] $
log(x)

fast_log(x)

ScriptFunc Ln.png $ \ln \!\left( x \right) $ Y N
  • natural logarithm
  • faster natural logarithm, lower precision
$ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
log2(x)

fast_log2(x)

ScriptFunc Log2.png $ \log_2 \!\left( x \right) $ Y N
  • base-2 logarithm
  • faster base-2 logarithm, lower precision
$ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
rcp(x)

fast_rcp(x)

ScriptFunc Rcp.png $ \frac{1}{x} $ Y N/A
  • inverse
  • faster inverse, lower precision
$ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
sin(x)

fast_sin(x)

ScriptFunc Sin.png $ \begin{align} \sin x \end{align} $ Y N/A
  • sine
  • faster sine, lower precision
$ [-\infty, +\infty] \longrightarrow [-1, +1] $
cos(x)

fast_cos(x)

ScriptFunc Cos.png $ \begin{align} \cos x \end{align} $ Y N/A
  • cosine
  • faster cosine, lower precision
$ [-\infty, +\infty] \longrightarrow [-1, +1] $
sincos(x)

fast_sincos(x)

ScriptFunc SinCos.png $ \begin{align} \sin x \end{align} $ $ \begin{align} \cos x \end{align} $ Y N/A

Warning: could be subject to change.

  • sine/cosine. takes a float value, returns a float2 containing the sine in 'x', and the cosine in 'y'
  • faster sine/cosine, lower precision
$ [-\infty, +\infty] \longrightarrow [-1, +1] $
tan(x)

fast_tan(x)

ScriptFunc Tan.png $ \begin{align} \tan x \end{align} $ Y N/A
  • tangent
  • faster tangent, lower precision
$ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $
asin(x)

fast_asin(x)

ScriptFunc ASin.png $ \begin{align} \arcsin x \end{align} $ Y N/A
  • arc-sine : returns the inverse of the sin() function : asin(sin(x)) = x
  • fast arc-sine, lower precision
$ [-1, +1] \longrightarrow [-\pi, +\pi] $
acos(x)

fast_acos(x)

ScriptFunc ACos.png $ \begin{align} \arccos x \end{align} $ Y N/A
  • arc-cosine : returns the inverse of the cos() function : acos(cos(x)) = x
  • faster arc-cosine, lower precision
$ [-1, +1] \longrightarrow [-\pi, +\pi] $
atan(x)

fast_atan(x)

ScriptFunc ATan.png $ \begin{align} \arctan x \end{align} $ Y N/A
  • arc-tangent : returns the inverse of the tan() function : atan(tan(x)) = x
  • faster arc-tangent, lower precision
$ [-\infty, +\infty] \longrightarrow [-\pi, +\pi] $
atan2(x,y)

fast_atan2(x,y)

ScriptFunc ATan.png $ \begin{align} \arctan \!\left( x,y \right) \end{align} $ Y N/A
  • signed arc-tangent like tan(), but uses the sign of 'y' to determine which quadrant the angle lies on
  • faster signed arc-tangent, lower precision
$ [-\infty, +\infty] \longrightarrow [-\pi, +\pi] $


Functions

Function float int Description
vrand()
Y N random function, returns a random float3 vector 'v' on the unit sphere (ie: a random normal vector uniformly distributed on the sphere's surface)
select(a,b,c) Y Y
returns 'a' or 'b' depending on the value of 'c'

'c' should be the boolean result of a compare operation, or function returning a true / false result. ex: select(float3(0), float3(1,2,3), x <= y); will return float3(1,2,3) if x <= y, otherwise it will return float3(0).

logic:

if (c is true)
  return b;
else
  return a;
iif(c,a,b) Y Y
iif: Inline IF
returns 'a' or 'b' depending on the value of 'c'. Like 'select', but reversed, syntactically closer to the syntax of an 'if/else' block.

'c' should be the boolean result of a compare operation, or function returning a true / false result. ex: iif(x <= y, float3(1,2,3), float3(0)); will return float3(1,2,3) if x <= y, otherwise it will return float3(0).

logic:

if (c is true)
  return a;
else
  return b;
lerp(a,b,t) Y N
lineary blends between 'a' and 'b' based on the value of 't'

't' is an interpolation factor in the $ [0, 1] $ range. when 't' equals 0, 'a' is returned, when 't' equals 1, 'b' is returned. values in between return values between 'a' and 'b'.
ex: lerp(float3(0), float3(1,2,3), 0.5); will return float3(0.5, 1, 1.5).

logic:

return a + t * (b - a);

equivalent to:

return a * (1-t) + b * t;
within(x,lower,upper) Y N
returns 1.0f if 'x' is within the [lower, upper] range, returns 0.0f otherwise.

all the function's arguments can be either scalars, or vectors. if some arguments are vectors, they must have the same dimension. The return value will be a vector as large as the largest input vector.
IE: you cannot call within(float2, float3, float4), but you can call within(float, float, float4) or within(float3, float, float3)


ex:
within(0.5, -1.2, 3.0); will return 1.0f.
within(float3(-2,0,2.5), -1.2, 3.0); will return float3(0.0, 1.0, 1.0).
within(1.5, -1.0, float4(0,1,2,3)); will return float4(0.0, 0.0, 1.0, 1.0).

remap(value, newMin, newMax)

remap(value, oldMin, oldMax, newMin, newMax)

Y Y
v1.8.0

remaps 'value' from the [oldMin, oldMax] range to the [newMin, newMax] range.
all the function's arguments can be either scalars, or vectors. if some arguments are vectors, they must have the same dimension. The return value will be a vector as large as the largest input vector.
IE: you cannot call remap(float2, float3, float4), but you can call remap(float, float, float4) or remap(float3, float, float3)
the version that has no 'oldMin' and 'oldMax' assumes the original range is [0,1]


ex:
remap(0.5, 1.0, 3.0); will return 2.0f.
remap(0.5, 0, 0.5, 1.0, 3.0); will return 3.0f.

all(c) N Y
returns true if ALL elements of vector 'c' are non-zero / not 'false'

'c' can be a boolean result of a compare operator, or any vector. ex:
all(float3(0) < float3(1,2,3)); will return true. all(float3(0) < float3(1,-2,3)); will return false.

logic:

foreach (element e in c)
  if (e == 0)
    return false;
return true;
any(c) N Y
returns true if ANY element of vector 'c' are non-zero / not 'false'

'c' can be a boolean result of a compare operator, or any vector. ex:
any(float3(0) > float3(1,2,3)); will return false. any(float3(0) > float3(1,-2,3)); will return true.

logic:

foreach (element e in c)
  if (e != 0)
    return true;
return false;
rotate(v, axis, angle) Y N
returns the vector 'v' rotated around 'axis' by 'angle'.

'v' and 'axis' are float3 vectors, 'angle' is the angle in radians (can be negative).
ex:
rotate(float3(1,0,0), float3(0,1,0), pi); will return float3(-1,0,0) (rotates float3(1,0,0) along the 'y' axis float3(0,1,0) by 180 degrees ('pi' radians), leading to the opposite vector float3(-1,0,0). rotate(float3(1,0,0), float3(0,1,0), pi/2); will return float3(0,0,1).

safe_normalize(v)

safe_normalize(v, vz)
safe_normalize(v, vz, epsilon)

safe_fast_normalize(v)
safe_fast_normalize(v, vz)
safe_fast_normalize(v, vz, epsilon)

Y N/A
v1.5.5+ / v1.6.0

Normalizes the input 'v' vector and returns the resulting unit-vector. Unlike the 'normalize' and 'safe_normalize' builtins, these safe versions check for null vectors.
This will prevent normalizing a null vector and getting an Infinity or NaN vector in return.
Works on any vector dimensions.
ex:
safe_normalize(vector3); returns normalize(vector3), but if length(vector3) < 1.0e-8, returns float3(0,0,0).
safe_normalize(vector3, float3(0,1,0)); returns normalize(vector3), but if length(vector3) < 1.0e-8, returns float3(0,1,0).
safe_normalize(vector3, float3(0,1,0), 1.0e-6); returns normalize(vector3), but if length(vector3) < 1.0e-6, returns float3(0,1,0).

safe_normalize(vector3)

is equivalent to:

select(normalize(vector3), float3(0), length(vector3) < 1.0e-8);

logic:

if (length(v) < epsilon)
  return vz;
else
  return normalize(v);
noise(t)

fast_noise(t)

Y N/A
v1.6.0

evaluates a coherent noise field. 't' can be a float, float2, float3, or float4 cursor. All functions return a single float value in the [-1,1] range.
noise() computes a high quality simplex-noise.
fast_noise() computes a slightly lower quality, but faster, noise.

ex:
noise(LifeRatio); will sample a 1D noise
noise(uv * 100); will sample a 2D noise
noise(Position); will sample a 3D noise
noise(float4(Position, scene.Time)); will sample a 4D noise

float3suf(side, up, forward)

float3suf(...)

Y N
v1.8.2

Takes the side, up, and forward components and permutes/swizzles them based on the current Axis-System.

example:

 float3suf(0, 18, 0);
  • Y-Up axis-system: float3(0, 18, 0);
  • Z-Up axis-system: float3(0, 0, 18);

example:

 float3 vec = float3(1, 2, 3);
 res = float3suf(vec);
  • Y-Up axis-system: res = vec; (no changes)
  • Z-Up axis-system: res = vec.xzy; (so: float3(1, 3, 2))


Axis-System helpers list

Here is quick list of Axis-System dependent function to help create Axis-System independent effects.