PExpr#

PearExpression is a single line, math like, functional language. It is, by design, easy to transpile to other languages like artic, like in the case of the Ignis rendering framework. It has no support for control flow, like if or while, and statements in general. For more complex shading networks multiple expressions can be chained with textures and function calls.

Some examples for the PExpr language:

sin(uv.x) * uv.xyxy + color(0.2, 0.4, 0.1, 0)
/* or */
fract(P.x) * perlin(N.yx)

A very similar language is SeExpr by Walt Disney Animation Studios. SeExpr is more complex and industry proven, however, more difficult to transpile to other languages. Nevertheless, both languages are easy to learn and to tinkle around.

An expression can be defined in many places where a number, vector or color can be given as a parameter to a light, texture, bsdf, medium, etc…

An example for a PExpr used inside a BSDF definition:

{
    // ...
    "bsdfs": [
        // ...
        { "name":"NAME", "type":"diffuse", "reflectance":"some_tex.r * perlin(uv.yx * abs(sin(uv.x * 10 * Pi))) * some_other_tex(uv.yx)" }
        // ...
    ]
    // ...
}

A direct connection to a texture is just a simple use-case of a PExpr expression. Keep in mind that throughout the use of textures and expressions cycles are prohibited at all times.

Types#

PExpr is strongly typed. Only a single implicit cast from int to num is available.

All available types are:

bool Boolean with true and false states.
int Signed integer.
num Floating point number.
vec2 Two-dimensional vector.
vec3 Three-dimensional vector.
vec4 Four-dimensional vector. Is used also as a color.
str String.

Vectorized types like vec2, vec3 and vec4 can be cast or extended to each other by the access/swizzle operation like:

vec3(1,2,3).zyxx /* Return type is vec4 (same as color) with values (3,2,1,1) */

Variables#

Some special variables given are available as vec2:

uv The current texture coordinates.
prim_coords Primitive specific coordinates if surface, else zero vector.

some as vec3:

uvw The current texture coordinates given as triplet.
V World ray direction facing from a surface or any other source outwards.
Rd Same as V.
Ro World ray origin.
P World position if bsdf or medium, else zero vector.
Np Normalized position if bsdf or medium, else zero vector.
N World shading normal if bsdf, else zero vector.
Ng World geometry normal if bsdf, else zero vector.
Nx World shading tangent if bsdf, else zero vector.
Ny World shading bitangent if bsdf, else zero vector.

few as int:

entity_id Contains the id of the current entity or -1 if not on a surface.
Ix Contains the current pixel x index or 0 if not available.
Iy Contains the current pixel y index or 0 if not available.

and a few as bool:

frontside true if normal and ray orientation is front facing. This will be always true if the point is not lying on a surface.

Predefined constants of type num are:

Pi The famous pi constant.
E The famous euler constant.
Eps The float epsilon defined by the system.
NumMax The maximum number a float can represent by the system.
NumMin The minimum number a float can represent by the system.
Inf Infinity float constant.

All textures defined in the scene representation are also available as variables of type vec4. These texture variables use the variable uv as their texture coordinate implicitly. The above defined special variable and constant names have precedence over texture names and parameters as explained below.

Scene Parameters#

Defining scene-wide parameters inside the "parameters" section in the scene description allows the convenient usage of user input in the viewer and the cli. All defined parameters are available as variables inside a PExpr expression. Parameters can be defined as follow:

{
    // ...
    "parameters": [
        // ...
        { "name":"NAME1", "type":"number", "value":42 },
        { "name":"NAME2", "type":"vector", "value":[1,0,0] },
        { "name":"NAME3", "type":"color",  "value":[1,0,1] }
        // ...
    ]
    // ...
}

Currently only the types number for num, vector for vec3 and color for vec4 are available. The given value can not be a PExpr!

Note

Defining color with alpha is currently not supported. Use an array of three numbers to define color.

The above defined parameters have precedence over texture names, but not the already defined special variables and constants in the previous section.

Property names starting with an _ are considered read-only and can not be changed within the viewer. You may have to press F4 to open up the property view in igview.

The command line options --Pi, --Pn, --Pv and --Pc allow setting the parameters to a different value at the start of the rendering. Using the command line parameters allow changing internal and read-only flagged parameters as well.

Functions#

abs(num) -> num
abs(vec2) -> vec2
abs(vec3) -> vec3
abs(vec4) -> vec4
abs(int) -> int
acos(num) -> num
acos(vec2) -> vec2
acos(vec3) -> vec3
acos(vec4) -> vec4
angle(vec2, vec2) -> num
angle(vec3, vec3) -> num
angle(vec4, vec4) -> num
asin(num) -> num
asin(vec2) -> vec2
asin(vec3) -> vec3
asin(vec4) -> vec4
atan(num) -> num
atan(vec2) -> vec2
atan(vec3) -> vec3
atan(vec4) -> vec4
atan2(num, num) -> num
atan2(vec2, vec2) -> vec2
atan2(vec3, vec3) -> vec3
atan2(vec4, vec4) -> vec4
avg(vec2) -> num
avg(vec3) -> num
avg(vec4) -> num
blackbody(num) -> vec4
bump(vec3, vec3, vec3, num, num, num) -> vec3
cbrt(num) -> num
cbrt(vec2) -> vec2
cbrt(vec3) -> vec3
cbrt(vec4) -> vec4
ccellnoise(num) -> vec4
ccellnoise(num, num) -> vec4
ccellnoise(vec2) -> vec4
ccellnoise(vec2, num) -> vec4
ccellnoise(vec3) -> vec4
ccellnoise(vec3, num) -> vec4
ceil(num) -> num
ceil(vec2) -> vec2
ceil(vec3) -> vec3
ceil(vec4) -> vec4
cellnoise(num) -> num
cellnoise(num, num) -> num
cellnoise(vec2) -> num
cellnoise(vec2, num) -> num
cellnoise(vec3) -> num
cellnoise(vec3, num) -> num
cfbm(vec2) -> vec4
cfbm(vec2, num) -> vec4
cfbm(vec2, num, int, num, num) -> vec4
cfbm(vec3) -> vec4
cfbm(vec3, num) -> vec4
cfbm(vec3, num, int, num, num) -> vec4
check_ray_flag(str) -> bool
checkerboard(vec2) -> int
checkerboard(vec3) -> int
clamp(num, num, num) -> num
clamp(vec2, vec2, vec2) -> vec2
clamp(vec3, vec3, vec3) -> vec3
clamp(vec4, vec4, vec4) -> vec4
clamp(int, int, int) -> int
cnoise(num) -> vec4
cnoise(num, num) -> vec4
cnoise(vec2) -> vec4
cnoise(vec2, num) -> vec4
cnoise(vec3) -> vec4
cnoise(vec3, num) -> vec4
color(num, num, num, num) -> vec4
color(num, num, num) -> vec4
color(num) -> vec4
cos(num) -> num
cos(vec2) -> vec2
cos(vec3) -> vec3
cos(vec4) -> vec4
cperlin(vec2) -> vec4
cperlin(vec2, num) -> vec4
cpnoise(num) -> vec4
cpnoise(num, num) -> vec4
cpnoise(vec2) -> vec4
cpnoise(vec2, num) -> vec4
cpnoise(vec3) -> vec4
cpnoise(vec3, num) -> vec4
cross(vec3, vec3) -> vec3
cvoronoi(num) -> vec4
cvoronoi(num, num) -> vec4
cvoronoi(num, num, num, str) -> vec4
cvoronoi(vec2) -> vec4
cvoronoi(vec2, num) -> vec4
cvoronoi(vec2, num, num, str, str) -> vec4
cvoronoi(vec2, num, num, str, str, num) -> vec4
cvoronoi(vec3) -> vec4
cvoronoi(vec3, num) -> vec4
cvoronoi(vec3, num, num, str, str) -> vec4
cvoronoi(vec3, num, num, str, str, num) -> vec4
deg(num) -> num
deg(vec2) -> vec2
deg(vec3) -> vec3
deg(vec4) -> vec4
dist(vec2, vec2) -> num
dist(vec3, vec3) -> num
dist(vec4, vec4) -> num
dot(vec2, vec2) -> num
dot(vec3, vec3) -> num
dot(vec4, vec4) -> num
ensure_valid_reflection(vec3, vec3, vec3) -> vec3
exp(num) -> num
exp(vec2) -> vec2
exp(vec3) -> vec3
exp(vec4) -> vec4
exp2(num) -> num
exp2(vec2) -> vec2
exp2(vec3) -> vec3
exp2(vec4) -> vec4
fbm(vec2) -> num
fbm(vec2, num) -> num
fbm(vec2, num, int, num, num) -> num
fbm(vec3) -> num
fbm(vec3, num) -> num
fbm(vec3, num, int, num, num) -> num
floor(num) -> num
floor(vec2) -> vec2
floor(vec3) -> vec3
floor(vec4) -> vec4
fmod(num, num) -> num
fmod(vec2, vec2) -> vec2
fmod(vec3, vec3) -> vec3
fmod(vec4, vec4) -> vec4
fract(num) -> num
fract(vec2) -> vec2
fract(vec3) -> vec3
fract(vec4) -> vec4
fresnel_conductor(num, num, num) -> num
fresnel_dielectric(num, num) -> num
gabor(vec2) -> num
gabor(vec2, num) -> num
gabor(vec2, num, int, num, num, num) -> num
hash(num) -> num
hsltorgb(vec4) -> vec4
hsvtorgb(vec4) -> vec4
int(num) -> int
length(vec2) -> num
length(vec3) -> num
length(vec4) -> num
log(num) -> num
log(vec2) -> vec2
log(vec3) -> vec3
log(vec4) -> vec4
log10(num) -> num
log10(vec2) -> vec2
log10(vec3) -> vec3
log10(vec4) -> vec4
log2(num) -> num
log2(vec2) -> vec2
log2(vec3) -> vec3
log2(vec4) -> vec4
lookup(str, bool, num, vec2, ...) -> num
luminance(vec4) -> num
max(num, num) -> num
max(vec2, vec2) -> vec2
max(vec3, vec3) -> vec3
max(vec4, vec4) -> vec4
max(int, int) -> int
min(num, num) -> num
min(vec2, vec2) -> vec2
min(vec3, vec3) -> vec3
min(vec4, vec4) -> vec4
min(int, int) -> int
mix(num, num, num) -> num
mix(vec2, vec2, num) -> vec2
mix(vec3, vec3, num) -> vec3
mix(vec4, vec4, num) -> vec4
mix_burn(vec4, vec4, num) -> vec4
mix_color(vec4, vec4, num) -> vec4
mix_dodge(vec4, vec4, num) -> vec4
mix_hue(vec4, vec4, num) -> vec4
mix_linear(vec4, vec4, num) -> vec4
mix_overlay(vec4, vec4, num) -> vec4
mix_saturation(vec4, vec4, num) -> vec4
mix_screen(vec4, vec4, num) -> vec4
mix_soft(vec4, vec4, num) -> vec4
mix_value(vec4, vec4, num) -> vec4
noise(num) -> num
noise(num, num) -> num
noise(vec2) -> num
noise(vec2, num) -> num
noise(vec3) -> num
noise(vec3, num) -> num
norm(vec2) -> vec2
norm(vec3) -> vec3
norm(vec4) -> vec4
num(int) -> num
perlin(vec2) -> num
perlin(vec2, num) -> num
pingpong(num, num) -> num
pingpong(vec2, vec2) -> vec2
pingpong(vec3, vec3) -> vec3
pingpong(vec4, vec4) -> vec4
pnoise(num) -> num
pnoise(num, num) -> num
pnoise(vec2) -> num
pnoise(vec2, num) -> num
pnoise(vec3) -> num
pnoise(vec3, num) -> num
pow(num, num) -> num
pow(vec2, vec2) -> vec2
pow(vec3, vec3) -> vec3
pow(vec4, vec4) -> vec4
rad(num) -> num
rad(vec2) -> vec2
rad(vec3) -> vec3
rad(vec4) -> vec4
reflect(vec3, vec3) -> vec3
rgbtohsl(vec4) -> vec4
rgbtohsv(vec4) -> vec4
rgbtoxyz(vec4) -> vec4
rotate_axis(vec3, num, vec3) -> vec3
rotate_euler(vec3, vec3) -> vec3
rotate_euler_inverse(vec3, vec3) -> vec3
round(num) -> num
round(vec2) -> vec2
round(vec3) -> vec3
round(vec4) -> vec4
select(bool, bool, bool) -> bool
select(bool, int, int) -> int
select(bool, num, num) -> num
select(bool, vec2, vec2) -> vec2
select(bool, vec3, vec3) -> vec3
select(bool, vec4, vec4) -> vec4
select(bool, str, str) -> str
sign(num) -> num
sign(vec2) -> vec2
sign(vec3) -> vec3
sign(vec4) -> vec4
sign(int) -> int
signbit(int) -> bool
signbit(num) -> bool
sin(num) -> num
sin(vec2) -> vec2
sin(vec3) -> vec3
sin(vec4) -> vec4
smax(num, num, num) -> num
smax(vec2, vec2, vec2) -> vec2
smax(vec3, vec3, vec3) -> vec3
smax(vec4, vec4, vec4) -> vec4
smin(num, num, num) -> num
smin(vec2, vec2, vec2) -> vec2
smin(vec3, vec3, vec3) -> vec3
smin(vec4, vec4, vec4) -> vec4
smootherstep(num) -> num
smoothstep(num) -> num
snap(num, num) -> num
snap(vec2, vec2) -> vec2
snap(vec3, vec3) -> vec3
snap(vec4, vec4) -> vec4
snoise(num) -> num
snoise(num, num) -> num
snoise(vec2) -> num
snoise(vec2, num) -> num
snoise(vec3) -> num
snoise(vec3, num) -> num
sperlin(vec2) -> num
sperlin(vec2, num) -> num
sqrt(num) -> num
sqrt(vec2) -> vec2
sqrt(vec3) -> vec3
sqrt(vec4) -> vec4
sum(vec2) -> num
sum(vec3) -> num
sum(vec4) -> num
tan(num) -> num
tan(vec2) -> vec2
tan(vec3) -> vec3
tan(vec4) -> vec4
transform_direction(vec3, str, str) -> vec3
transform_normal(vec3, str, str) -> vec3
transform_point(vec3, str, str) -> vec3
trunc(num) -> num
trunc(vec2) -> vec2
trunc(vec3) -> vec3
trunc(vec4) -> vec4
vec2(num, num) -> vec2
vec2(num) -> vec2
vec3(num, num, num) -> vec3
vec3(num) -> vec3
vec4(num, num, num, num) -> vec4
vec4(num) -> vec4
voronoi(num) -> num
voronoi(num, num) -> num
voronoi(num, num, num, str) -> num
voronoi(vec2) -> num
voronoi(vec2, num) -> num
voronoi(vec2, num, num, str, str) -> num
voronoi(vec2, num, num, str, str, num) -> num
voronoi(vec3) -> num
voronoi(vec3, num) -> num
voronoi(vec3, num, num, str, str) -> num
voronoi(vec3, num, num, str, str, num) -> num
wrap(num, num, num) -> num
wrap(vec2, vec2, vec2) -> vec2
wrap(vec3, vec3, vec3) -> vec3
wrap(vec4, vec4, vec4) -> vec4
xyztorgb(vec4) -> vec4

All textures defined in the scene representation are also available as functions with signature TEXTURE(vec2) -> vec4, with TEXTURE being the texture name. The above defined function names have precedence over texture names, if the signature matches.