Scripting reference 170

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.7.0 and below
For the latest version of PopcornFX, see: Scripting reference


Overview

The popcorn-script syntax borrows most of its concepts from a mix between C++ and 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.


Values exposed to scripts

Wether the script is a spawn or evolve script, different global constants will be accessible:

Spawn script

type name access mode description
float CurrentDate read global date of the current particle medium collection, in seconds
float SpawnerLifeRatio read life ratio of the spawner, in the [0, 1] range
float SpawnerRunningTime read time in seconds the spawner has been spawning particles. Useful for infinite spawner whose liferatio stays at zero
read all the particle attributes
read / write all the particle fields
float Life read / write Life duration of the particle. virtual particle field, for scripting convenience, maps to 1.0 / InvLife

Evolve script

type name access mode description
float CurrentDate read global date of the current particle medium collection, in seconds
float dt read length of the current evolve step in seconds
float Age read age of the particle in seconds
read 1.5.5 all the particle attributes
read / write all the particle fields
float Life read / write Life duration of the particle. virtual particle field, for scripting convenience, maps to 1.0 / InvLife


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] $
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).

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