Scripting reference 2000
You are on a PopcornFX v2.0 page.
The following references applies to v2.0 only, not v1.x
This page is for version v2.0.0 and above
This page is deprecated, please use the online documentation on the official PopcornFX website: https://www.popcornfx.com/docs/popcornfx-v2/scripting-reference/
For the latest version of PopcornFX, see: Scripting reference
For previous versions of PopcornFX, see the following pages:
- Scripting reference (v1.13.0)
- Scripting reference (v1.12.0)
- Scripting reference (v1.11.0)
- Scripting reference (v1.10.0 and below)
Contents
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 language syntax reference, see the Scripting language reference page.
In the following tables you will find an extensive list of 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:
Optional parameters are written inside brackets.
For example:
SamplerName.remapDensity(float2 uv [, int filterMode [, int wrapMode]])
Means you have three ways to call the 'remapDensity' function:
MySampler.remapDensity(uv); MySampler.remapDensity(uv, textureFilter.Point); MySampler.remapDensity(uv, textureFilter.Point, textureFilter.Clamp);
Whereas:
spatialLayers.LayerName.FieldName.sumKernel(float3 center, float radius, samplerCurve1D kernelSampler)
Means there is only a single way to call the 'sumKernel' function:
spatialLayers.MyLayer.MyField.sumKernel(center, radius, MyCurve);
Particle scripts
Self
v2.0.0.a0 The 'self' namespace contains all particle-related functions and variables.
type | description |
---|---|
float |
self.LifeRatio v2.0.0.a1 Life-ratio of the particle, in the [0, 1] range. |
void |
self.kill( int condition ) v2.0.0.a1 kills the particle if 'condition' is not |
Samplers
These are all the functions and properties exposed by particle samplers:
type | description | ||
---|---|---|---|
all the ![]() | |||
![]() | |||
float# |
SamplerName.sample( float cursor ) Samples the | ||
float# |
SamplerName.sampleCDF( float cursor ) Treats the | ||
float# |
SamplerName.derive( float cursor ) Computes the derivative of the | ||
float# |
SamplerName.integrate( float cursorStart, float cursorEnd ) Computes the integral of the | ||
![]() | |||
float# |
SamplerName.sample( float cursor, float ratio ) Samples the | ||
int3 |
SamplerName.samplePCoords() Samples a random location identifier on the | ||
int3 |
SamplerName.sampleSurfacePCoordsFromUV( [ float2 uv ] ) Only available for 'Mesh' shapesSamples a location identifier on the | ||
float3 |
SamplerName.samplePosition( [ int3 pCoords ] ) Samples a position on the | ||
float3 |
SamplerName.sampleNormal( [ int3 pCoords ] ) Samples a normal on the | ||
float4 |
SamplerName.sampleTangent( [ int3 pCoords ] ) Only available for 'Mesh' shapesSamples a tangent on the | ||
float2 |
SamplerName.sampleTexcoord( [ int3 pCoords ] ) Only available for 'Mesh' shapesSamples a texture-coordinate on the | ||
float4 |
SamplerName.sampleColor( [ int3 pCoords ] ) Only available for 'Mesh' shapesSamples a color on the | ||
float3 |
SamplerName.sampleVelocity( [ int3 pCoords ] ) Samples the instantaneous surface-velocity of the | ||
float |
SamplerName.surface() Returns the surface of the | ||
float |
SamplerName.volume() Returns the volume of the | ||
float |
SamplerName.radius() Returns the radius of the | ||
float |
SamplerName.innerRadius() Returns the innerRadius of the | ||
float |
SamplerName.height() Returns the height of the | ||
int |
SamplerName.vertexCount() Returns the vertex-count of the | ||
int |
SamplerName.triangleCount() Returns the triangle-count of the | ||
int |
SamplerName.tetraCount() Returns the tetrahedron-count of the | ||
float3 |
SamplerName.meshScale() Returns the mesh-scale of the | ||
float3 |
SamplerName.boxDim() Returns the dimensions of the | ||
int |
SamplerName.type() Returns the type of the
| ||
float3 |
SamplerName.position() Returns the position of the | ||
float3 |
SamplerName.axisUp() Returns the up axis of the | ||
float3 |
SamplerName.axisSide() Returns the side axis of the | ||
float3 |
SamplerName.axisForward() Returns the forward axis of the | ||
float |
SamplerName.sampleDistanceField( float3 position ) Samples the distance-field of the | ||
int |
SamplerName.contains( float3 position ) returns | ||
float4 |
SamplerName.intersect( float3 rayStart, float3 rayDirection, float rayLength ) raytraces the | ||
int4 |
SamplerName.intersectPCoords( float3 rayStart, float3 rayDirection, float rayLength ) raytraces the | ||
float4 |
SamplerName.project( float3 position ) Computes the projection of the specified position on the | ||
int3 |
SamplerName.projectPCoords( float3 position ) Computes the projection of the specified position on the | ||
![]() | |||
float# |
SamplerName.sample( float2 uv [, int filterMode [, int wrapMode]] ) Samples a texel on the
The optional 'addrMode' can be one of the following:
| ||
float# |
SamplerName.sample( float subRectId, float2 uv [, int filterMode [, int wrapMode]] ) Samples a texel on the | ||
float2 |
SamplerName.remapDensity( float2 uv [, int filterMode [, int wrapMode]] ) This is the old 'sampleDensity' in versions anterior to v1.9.0 | ||
float2 |
SamplerName.remapDensity( float subRectId, float2 uv [, int filterMode [, int wrapMode]] ) This is the old 'sampleDensity' in versions anterior to v1.9.0 | ||
float2 |
SamplerName.sampleDensity( [int filterMode [, int wrapMode]] ) Builds a random UV coordinate so that the UV distribution matches the density of the | ||
float2 |
SamplerName.sampleDensity( float subRectId [, int filterMode [, int wrapMode]] ) Builds a random UV coordinate so that the UV distribution matches the density of the | ||
float2 |
SamplerName.dimensions() Returns a float2 containing the texture texel dimensions (can be just an abstract aspect ratio if the sampler is an attribute sampler overriden by the game engine and is a procedural "infinite" texture rather than a physical texture). | ||
int |
SamplerName.atlasRectCount() Returns the number of sub-rectangles in the texture atlas. Returns zero if there's no atlas. | ||
![]() | |||
float3 |
SamplerName.sample( float3 position ) Samples the default field | ||
![]() | |||
float |
SamplerName.sample( float cursor [, int sampleFilter] ) Samples the
| ||
float |
SamplerName.sample( float cursor, float convolution [, int sampleFilter [, int convolutionFilter]] ) Samples the | ||
![]() | |||
int |
SamplerName.charCode( int charId ) Samples the | ||
int |
SamplerName.charCode( int2 lineAndCharId ) Samples the | ||
int2 |
SamplerName.charLineId( int charId ) Returns an int2 vector containing the 0-based line index of the specified character in 'x' and the 0-based character index relative to the start of the line in 'y'. 'charId' is the global character index in the [0, totalCharCount] range | ||
int |
SamplerName.charOffset( int lineId, int charId ) Returns the horizontal distance between charId and the beginning of the line in displayable units, where '1.0' is the average glyph size. Takes kerning into account if a kerning file has been provided in the | ||
int |
SamplerName.lineOffset( int lineId ) Returns the vertical distance between lineId and the beginning of the text in displayable units, where '1.0' is the average glyph size. Defaults to 3.0 if no metrics file has been provided in the | ||
int |
SamplerName.charCount( int lineId ) Returns the number of characters at the specified line of the | ||
int |
SamplerName.charCount() Returns the number of characters in the whole | ||
int |
SamplerName.lineCount() Returns the number of lines in the whole |
Shape
The "shape" namespace gives access to shape-related functions that do not need an actual shape to work.
type | description | ||
---|---|---|---|
![]() | |||
int3 |
shape.buildPCoordsMesh( int vertexId ) Allows to manually build parametric coordinates on a | ||
int3 |
shape.buildPCoordsMesh( int triangleId, float2 barycentricCoordinates ) Allows to manually build parametric coordinates on a | ||
int3 |
shape.buildPCoordsMesh( int tetraId, float3 barycentricCoordinates ) Allows to manually build parametric coordinates on a | ||
int3 |
shape.buildPCoordsBox( int faceId, float2 uv ) Allows to manually build parametric coordinates on a | ||
int3 |
shape.buildPCoordsBox( float3 normalizedPos ) Allows to manually build parametric coordinates on a | ||
int3 |
shape.buildPCoordsSphere( float2 polarAngles, float radius ) Allows to manually build parametric coordinates on a | ||
int3 |
shape.buildPCoordsCone( float height, float angle [, float radius] ) Allows to manually build parametric coordinates on a | ||
int3 |
shape.buildPCoordsCapsule( float height, float angle, float radius ) Allows to manually build parametric coordinates on a | ||
int3 |
shape.buildPCoordsCylinder( float height, float angle, float radius ) Allows to manually build parametric coordinates on a |
Effect
v2.0.0.a1 The 'effect' namespace contains all effect-related functions and variables.
Scene
The "scene" namespace gives access to scene-wide functions such as raycast queries, time, and axis-system.
type | description | ||
---|---|---|---|
Variables | |||
float |
scene.Time global date of the current particle medium collection, in seconds. (Was | ||
float |
scene.surfaceType.* All surface types configured in the project-settings 'Scene' panel | ||
float |
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). | ||
int |
scene.isRight() constant: | ||
float |
scene.isRightSign() constant: | ||
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. | ||
int4 |
scene.intersectExt( float3 rayStart, float3 rayDirection, float rayLength [, int collisionFilter] ) issues an extended scene intersection query, returns an int4 containing the packed intersection normal, intersection distance, and surface type. | ||
float3 |
scene.unpackNormal( int4 packedISecResult ) takes a packed intersection result returned by | ||
float |
scene.unpackDist( int4 packedISecResult ) takes a packed intersection result returned by | ||
int |
scene.unpackSurfaceType( int4 packedISecResult ) takes a packed intersection result returned by |
View
The "view" namespace gives access to camera-related functions such as projection or distance functions.
type | description | ||
---|---|---|---|
Functions | |||
int |
view.count() returns the number of active cameras/views. | ||
float |
view.distance( float3 position [, int camIndex] ) returns the distance between 'position' and the camera whose ID is 'camIndex'. | ||
int |
view.closest( float3 position [, int n] ) returns the index of the cam closest to 'position'. | ||
float3 |
view.position( [int camIndex = 0] ) returns the position of the cam whose ID is 'camIndex'. If 'camIndex' is not specified, uses the first camera. | ||
float3 |
view.axisSide( [int camIndex = 0] ) returns the side axis of the cam whose ID is 'camIndex'. If 'camIndex' is not specified, uses the first camera. | ||
float3 |
view.axisUp( [int camIndex = 0] ) returns the up axis of the cam whose ID is 'camIndex'. If 'camIndex' is not specified, uses the first camera. | ||
float3 |
view.axisForward( [int camIndex = 0] ) returns the forward axis of the cam whose ID is 'camIndex'. If 'camIndex' is not specified, uses the first camera. | ||
float3 |
view.direction( [int camIndex = 0] ) returns the view vector of the cam whose ID is 'camIndex'. If 'camIndex' is not specified, uses the first camera. | ||
float3 |
view.project( float3 worldPos [, int camIndex = 0] ) projects the input worldspace coordinate into the clip-space of the cam whose ID is 'camIndex'. If 'camIndex' is not specified, uses the first camera. | ||
float3 |
view.unproject( float3 clipPos [, int camIndex = 0] ) unprojects to worldspace the input clipspace coordinate of the cam whose ID is 'camIndex'. If 'camIndex' is not specified, uses the first camera. | ||
float3 |
view.unprojectedAxis( float2 clipPos [, int camIndex = 0] ) returns the normalized axis of the ray that goes from the camera origin through the camera plane at coordinates specified in 'clipPos'. If 'camIndex' is not specified, uses the first camera. | ||
int2 |
view.resolution( [int camIndex = 0] ) returns the resolution of the view in pixels. If 'camIndex' is not specified, uses the first camera. ex: | ||
float |
view.aspect( [int camIndex = 0] ) returns the aspect-ratio of the view. If 'camIndex' is not specified, uses the first camera. | ||
float |
view.fovHorizontal( [int camIndex = 0] ) returns the horizontal fov of the view, in radians. If 'camIndex' is not specified, uses the first camera. | ||
float |
view.fovVertical( [int camIndex = 0] ) returns the vertical fov of the view, in radians. If 'camIndex' is not specified, uses the first camera. | ||
float |
view.fov( [int camIndex = 0] ) returns the fov of the view, in radians. If 'camIndex' is not specified, uses the first camera. |
Spatial layers
The "spatialLayers" namespace gives access to all spatial layers visible by the effect.
type | description | ||
---|---|---|---|
all the ![]() | |||
Global queries | |||
int |
spatialLayers.LayerName.neighborCount( float3 center, float radius ) Returns the number of particles inside the query volume. | ||
Field queries | |||
fieldType |
spatialLayers.LayerName.FieldName.closest( float3 center, float radius ) Returns the value of 'FieldName' of the closest particle inside the query volume. | ||
fieldType |
spatialLayers.LayerName.FieldName.closest( float3 center, float radius, int n [, int cacheSize] ) Returns the value of 'FieldName' of the n-closest particle inside the query volume. 'n' is 0-based, so calling the query with '0' for 'n' will return closest value, calling with '3' will return the 4th closest, etc... | ||
fieldType |
spatialLayers.LayerName.FieldName.closest2( float3 center, float radiusMin, float radiusMax ) Returns the value of 'FieldName' of the closest particle inside the hollowed query volume. setting 'radiusMin' to zero is equivalent to calling | ||
float# |
spatialLayers.LayerName.FieldName.sum( float3 center, float radius ) Returns the sum of 'FieldName' of all particles inside the query volume. | ||
float# |
spatialLayers.LayerName.FieldName.sumKernel( float3 center, float radius, samplerCurve1D kernelSampler ) Returns the sum of 'FieldName' of all particles inside the query volume, and uses the custom kernel (1D | ||
float# |
spatialLayers.LayerName.FieldName.average( float3 center, float radius ) Returns the average value of 'FieldName' of all particles inside the query volume. | ||
float# |
spatialLayers.LayerName.FieldName.averageKernel( float3 center, float radius, samplerCurve1D kernelSampler ) Returns the average value of 'FieldName' of all particles inside the query volume, and uses the custom kernel (1D |
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] $ | |
reflect(v,n) |
![]() |
$ \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) |
![]() |
$ \begin{align} | x | \end{align} $ | Y | Y | absolute value | $ [-\infty, +\infty] \longrightarrow [0, +\infty] $ |
sign(x) |
![]() |
$ \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) |
![]() |
$ \lceil x \rceil $ | Y | N/A | ceiling rounding: rounds to the closest integer value >= x | $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $ |
floor(x) |
![]() |
$ \lfloor x \rfloor $ | Y | N/A | floor rounding: rounds to the closest integer value <= x | $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $ |
frac(x)
|
![]() |
$ x % 1 $ | Y | N/A | extracts the fractional part of 'x' | $ [-\infty, +\infty] \longrightarrow [0, +1[ $
|
wavesq(x) |
![]() |
Y | N/A | square wave function | $ [-\infty, +\infty] \longrightarrow [-1, +1] $ | |
wavetri(x) |
![]() |
Y | N/A | triangular wave function | $ [-\infty, +\infty] \longrightarrow [0, +1] $ | |
wavesaw(x) |
![]() |
$ x - \lfloor x \rfloor $ | Y | N/A | sawtooth wave function | $ [-\infty, +\infty] \longrightarrow [0, +1] $ |
saturate(x) |
![]() |
Y | N/A | clamps 'x' in the [0, 1] range | $ [-\infty, +\infty] \longrightarrow [0, +1] $ | |
step(x,y) |
![]() |
$ \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] $
|
linearstep(a,b,x) |
![]() |
$ \begin{align} t=\frac{x-a}{b-a} \end{align} $ | Y | N | linearstep function. linearly evaluates between 0 to 1 the position of x between a and b. | $ [-\infty, +\infty] \longrightarrow [0, +1] $ |
smoothstep(a,b,x) |
![]() |
$ \begin{align} 3t^2 - 2t^3 \end{align} $ | Y | N | smoothstep function. smoothly evaluates between 0 to 1 the position of x between a and b. | $ [-\infty, +\infty] \longrightarrow [0, +1] $ |
discretize(x,y) |
![]() |
Y | N | discretization function, snaps 'x' to the nearest step, given a step size 'y' | $ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $ | |
min(x,y) |
![]() |
$ \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) |
![]() |
$ \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) |
![]() |
$ \begin{align} clamp(x, a, b) \end{align} $ | Y | N | clamp function: if x < a, returns a, otherwise, if x > b, returns b, otherwise, returns x | $ [-\infty, +\infty] \longrightarrow [a, b] $ |
sqrt(x)
|
![]() |
$ \sqrt{x} $ | Y | N |
|
$ [0, +\infty] \longrightarrow [0, +\infty] $ |
rsqrt(x)
|
![]() |
$ \frac{1}{\sqrt{x}} $ | Y | N/A |
|
$ [0, +\infty] \longrightarrow [0, +\infty] $ |
cbrt(x)
|
![]() |
$ \sqrt[3]{x} $ | Y | N |
|
$ [0, +\infty] \longrightarrow [0, +\infty] $ |
length(v)
|
$ \left\| v \right\| $ | Y | N/A |
|
$ [-\infty, +\infty] \longrightarrow [0, +\infty] $ | |
normalize(v)
|
$ \vec{v} \cdot \frac{1}{ \left\| v \right\| } $ | Y | N/A |
|
$ [-\infty, +\infty] \longrightarrow [-1, +1] $ | |
exp(x)
|
![]() |
$ \begin{align} e^x \end{align} $ | Y | N |
|
$ [-\infty, +\infty] \longrightarrow [0, +\infty] $ |
exp2(x)
|
![]() |
$ \begin{align} 2^x \end{align} $ | Y | N |
|
$ [-\infty, +\infty] \longrightarrow [0, +\infty] $ |
pow(x,y)
|
![]() |
$ \begin{align} x^y \end{align} $ | Y | N |
|
$ {[0, +\infty], [-\infty, +\infty]} \longrightarrow [-\infty, +\infty] $ |
log(x)
|
![]() |
$ \ln \!\left( x \right) $ | Y | N |
|
$ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $ |
log2(x)
|
![]() |
$ \log_2 \!\left( x \right) $ | Y | N |
|
$ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $ |
rcp(x)
|
![]() |
$ \frac{1}{x} $ | Y | N/A |
|
$ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $ |
sin(x)
|
![]() |
$ \begin{align} \sin x \end{align} $ | Y | N/A |
|
$ [-\infty, +\infty] \longrightarrow [-1, +1] $ |
cos(x)
|
![]() |
$ \begin{align} \cos x \end{align} $ | Y | N/A |
|
$ [-\infty, +\infty] \longrightarrow [-1, +1] $ |
tan(x)
|
![]() |
$ \begin{align} \tan x \end{align} $ | Y | N/A |
|
$ [-\infty, +\infty] \longrightarrow [-\infty, +\infty] $ |
asin(x)
|
![]() |
$ \begin{align} \sin^{-1} x \end{align} $ | Y | N/A |
|
$ [-1, +1] \longrightarrow [-\pi, +\pi] $ |
acos(x)
|
![]() |
$ \begin{align} \cos^{-1} x \end{align} $ | Y | N/A |
|
$ [-1, +1] \longrightarrow [-\pi, +\pi] $ |
atan(x)
|
![]() |
$ \begin{align} \tan^{-1} x \end{align} $ | Y | N/A |
|
$ [-\infty, +\infty] \longrightarrow [-\pi, +\pi] $ |
atan2(x,y)
|
![]() |
$ \begin{align} \tan^{-1} \!\left( x,y \right) \end{align} $ | Y | N/A |
|
$ [-\infty, +\infty] \longrightarrow [-\pi, +\pi] $ |
Functions
Function | float | int | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
vrand() vrand(inner, outer) vrand(inner, outer, probabilityCurve) |
Y | N | random function, stands for "vector-rand", returns a random float3 vector 'v' uniformly distributed on the unit sphere surface.
Very useful to generate nicely distributed random normals, random 3D offsets, or other unit vectors to give a bit of randomization to particle velocities, etc..
| ||||||||||||||||
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 logic: if (c is true) return b; else return a; | ||||||||||||||||
iif(c,a,b) |
Y | Y | iif : Inline IFreturns '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 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'. logic: return a + t * (b - a); equivalent to: return a * (1-t) + b * t; | ||||||||||||||||
smoothlerp(a,b,t) |
Y | N | smoothly 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'. logic: return lerp(a, b, smoothstep(0, 1, t)); equivalent to: return lerp(a, b, 3*t*t - 2*t*t*t); | ||||||||||||||||
randsel(a,b) randsel(a,b,k) |
Y | Y | randomly returns 'a' or 'b'.
the two-argument version of 'randsel' has equal probability to return 'a' or 'b', and calling logic: return select(a, b, rand(0,1) < k); | ||||||||||||||||
randsign() randsign(k) |
Y | Y | randomly returns '-1.0' or '1.0'.
' logic: return select(-1.0, 1.0, rand(0,1) < k); | ||||||||||||||||
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.
| ||||||||||||||||
remap(value, newMin, newMax) remap(value, oldMin, oldMax, newMin, newMax) |
Y | Y | 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.
| ||||||||||||||||
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: 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: 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). | ||||||||||||||||
deg2rad(angle) rad2deg(angle) |
Y | N |
| ||||||||||||||||
linear2srgb(c) srgb2linear(c) fast.linear2srgb(c) fast.srgb2linear(c) |
Y | N |
The 'fast' versions use an approximation (the absolute precision is under 0.001, and ), whereas the non-fast versions use the real sRGB piecewise-curve conversion. | ||||||||||||||||
rgb2hsv(c) hsv2rgb(c) |
Y | N |
The converters support HDR values. For the HSV color-space, the H-value (hue) is wrapped from 0 to 1 (1 means 360°), the S-value (saturation) is clipped from 0 to 1 and the V-value (intensity) is positive. | ||||||||||||||||
bias(x, e) |
Y | N |
| ||||||||||||||||
safe_normalize(v) safe_normalize(v, vz) safe_normalize(v, vz, epsilon) fast.safe_normalize(v) fast.safe_normalize(v, vz) fast.safe_normalize(v, vz, epsilon) |
Y | N/A | 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. 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 | evaluates a coherent noise field. 't' can be a float, float2, float3, or float4 cursor. All functions return a single float value in the ex: | ||||||||||||||||
float3suf(side, up, forward) float3suf(...) float3sfu(side, forward, up) float3sfu(...) |
Y | N | Takes the side, up, and forward components and permutes/swizzles them based on the current Axis-System. example: float3suf(0, 18, 0);
example: float3 vec = float3(1, 2, 3); res = float3suf(vec);
See #Axis-System helpers. | ||||||||||||||||
isfinite(v) isinf(v) isnan(v) |
Y | N | Useful to detect infinite or invalid values.
isfinite(42); --> true isfinite(1.0/0.0);--> false isfinite(0.0/0.0);--> false
isinf(42); --> false isinf(1.0/0.0); --> true isinf(0.0/0.0); --> false
isnan(42); --> false isnan(1.0/0.0); --> false isnan(0.0/0.0); --> true This function can be used to check the return values of some functions that return infinite values as a way to report en empty result. For example, spatial queries: float3 p = spatialLayers.MyLayer.Position.closest(Position); Position = select(Position, p, all(isfinite(p))); | ||||||||||||||||
blackbody(t) fast.blackbody(t) |
Y | N | returns the normalized RGB chromaticity color of the emission spectrum of a blackbody at the specified temperature The input value should be a temperature in degrees kelvin. For example, 800 will give a red color, 3000 will give an orange/yellow color, 5000/6000 will give a white color, and higher temperatures will give a blue color. RGB colors returned are in linear space, not in sRGB space. The 'fast' version uses a different algorithm (a polynomial fit on the final RGB curves) than the regular version (which uses a polynomial fit of the chromaticity-space planckian locus), is roughly twice faster, but much less precise (although it's probably fine for most applications). Here's the RGB comparison between the regular and fast versions:
| ||||||||||||||||
asfloat(v) |
Y | Y | reinterprets the input as a float. If given a float, does nothing. If given an int, will reinterpret its bits as if it was a float. asfloat(0x3F800000); --> 1.0 asfloat(42.0); --> 42.0 asfloat(int4(0x40490FDB, 0, 0xC0200000, -1071644672)) --> float4(3.141593, 0, -2.5, -2.5) | ||||||||||||||||
asint(v) |
Y | Y | reinterprets the input as an int. If given an int, does nothing. If given a float, will reinterpret its bits as if it was an int. asint(1.0); --> 0x3F800000 asint(42); --> 42 asint(float4(3.141593, 0, -2.5, -2.5)) --> int4(0x40490FDB, 0, 0xC0200000, 0xC0200000) |
Axis-System helpers
Here is quick list of Axis-System dependent function to help create Axis-System independent effects.
- Vector swizzling/shuffling
s u f
(side, up, forward), works same way asx y z
, but changes depending on the current axis system:- Y-Up system
.s => .x
.u => .y
.f => .z
- Z-Up system
.s => .x
.u => .z
.f => .y
- Y-Up system
Examples:
float3 vec = ...; float3 vec_plus_42_up = vec + scene.axisUp() * 42; float3 vec_plus_42_up = vec + float3suf(0, 42, 0); float3 vec_plus_42_up = vec + float3sfu(0, 0, 42); float3 vec_plus_42_up = float3suf(vec.s, vec.u + 42, vec.f); float3 vec_plus_42_up = float3sfu(vec.sf, vec.u + 42);
All those vec_plus_42_up
gives the same vector for a given Axis System: vec
offset by 42.0 on the Up axis (so it adds 42 to Y when Y-Up, or 42 to Z when Z-Up)