Boxshot scripting engine supports some common math functions as well as some built-in types to simplify the scene scripting. Use the links below to navigate the topic:

Colors

Boxshot actively uses colors to tint images, so the scripting engine supports them well. Here are some examples on how to create a color object:

var orange = color("#FF8000");
var red = color(1, 0, 0);
var magenta = color(255, 0, 255, 255);

Please note that if all the color components are less or equal to 1, Boxshot converts them to floating point numbers, so if you need (1, 1, 1) from the range 0..255, please use the string form instead:

var almostBlack = color("#010101");

Accessing color components

You can access color components this way:

var c = color(10, 20, 30, 40);
print("r = %1, g = %2, b = %3, a = %4", c.r, c.g, c.b, c.a);

Please note that even if you may create color from string or bytes, internally color values are kept in floats in range 0..1, so all the components math should be done in floats. The code above doesn’t print 10, 20, 30 and 40, it prints floats instead. Here’s how to assign values:

var c = color(0, 0, 0, 0);
c.r = 1;
c.g = 0.5;
c.b = 0;
c.a = 1;
print(c);

Assigning colors

In javascript assignment means copying the reference, not the value, so the following code may surprise you:

var c1 = color(1, 1, 1, 1);
var c2 = c1; // c2 is now a reference to c1
c2.r = 0; // changing c2 changes c1, as well
print("c1 = %1, c2 = %2", c1, c2);

The code above prints two similar colors. To make c2 a copy of c1, not a reference, use the clone() method:

var c1 = color(1, 1, 1, 1);
var c2 = c1.clone(); // c2 is now a copy of c1, not a reference
c2.r = 0; // changing c2 doesn't change c1 now
print("c1 = %1, c2 = %2", c1, c2);

Color math

You can do some math with colors if necessary. Javascript language doesn’t allow overriding operators for custom classes, so there are some methods:

var c1 = color(0.5, 0.5, 0.5);
var c2 = c1.mul(2); // multiply all the components by 2
print("c1 = %1, c2 = %2", c1, c2);

var c3 = c2.div(2); // divide by 2
print("c3 = %1", c3);

You can add or subtract two colors:

var c1 = color(0.1, 0.1, 0.1, 0.1);
var c2 = color(0.3, 0.3, 0.3, 0.3);
var cAdd = c1.add(c2);
var cSub = c2.sub(c1);
print("add = %1, sub = %2", cAdd, cSub);

Please note that both mul(), div(), add() and sub() methods clamp resulting values to 0..1 range to prevent overflows. The same is done at the construction time, so color(300, 300, 300, 300) is the same as color(255, 255, 255, 255). Finally, here’s how to compare colors:

var c1 = color(255, 255, 255, 255);
var c2 = color(1, 1, 1, 1);
print(c1.equals(c2));

Vector class

Vectors work pretty much the same way as colors above. Here’s how to create a vector object:

var a = vec3(1, 2, 3);
var b = vec3(1); // means vec3(1, 1, 1)

Accessing vector components

Exactly as with colors you may access vector’s component directly:

var a = vec3(1, 2, 3);
print("x = %1, y = %2, z = %3", a.x, a.y, a.z);

You may also edit vector’s value by modifying its components:

var a = vec3(0);
a.x = 1;
a.y = 2;
a.z = 3;
print(a);

Assigning vectors

Similar to colors, assigning vectors means assigning references, use clone() to copy values:

var a = vec3(1, 2, 3);
var b = a;
var c = a.clone();
a.x = 10;
print("a = %1, b = %2, c = %3", a, b, c);

Vector math

You can add, subtract, multiply vectors and do some other math functions, as well:

var a = vec3(1, 1, 1);
var b = vec3(3, 3, 3);
var c = a.add(b);
var d = b.sub(a);
print("add = %1, sub = %2", c, d);

Multiplication and division by number:

var a = vec3(1, 1, 1);
var b = a.mul(2);
var c = a.div(2);
print("mul = %1, div = %2", b, c);

Multiplication by vector:

var a = vec3(1, 2, 3);
var b = vec3(4, 5, 6);

var c = a.dot(b);
var d = a.cross(b);

print("dot = %1, cross = %2", c, d);

You may also get a vector’s length or normalize it this way:

var a = vec3(1, 2, 3);
var len1 = a.length;
var b = a.normalized();
var c = a.clone();
var len2 = c.normalize();

Please note the difference between normalize() and normalized() as the first modifies vector, while the second one doesn’t. The first function also returns the old vector’s length.

Math functions

Here is the list of built-in math functions you may use in scripts:

  • abs(x)
  • acos(x)
  • asin(x)
  • atan(x)
  • atan2(y, x)
  • ceil(x)
  • cos(x)
  • exp(x)
  • floor(x)
  • log(x)
  • max([value1 [, value2 [, …]]])
  • min([value1 [, value2 [, …]]])
  • pow(x, y)
  • random()
  • round(x)
  • sin(x)
  • sqrt(x)
  • tan(x)

All the functions should be called with the Math prefix, like this:

var s = Math.sin(1);
var r = Math.random();

There are some useful constants like:

  • PI
  • E
  • LN10
  • LN2
  • LOG2E
  • LOG10E
  • SQRT1_2
  • SQRT2

Please note that trigonometric functions like sin() or cos() works in radians, not degrees, so you probably need to convert your value first:

var deg = 90;
var rad = 90 * Math.PI / 180;
var cos90 = Math.cos(rad);
print(cos90);

Custom functions

You may write your own cutom function if you like. For example, the code above needs to convert degrees to radians, you may simplify this:

function deg2rad(d)
{
    return d * Math.PI / 180;
}

print(Math.cos(deg2rad(90)));

Custom functions may process built-in objects. The function below converts color to grayscale:

function grayscale(c)
{
    var gray = (c.r + c.g + c.b) / 3;
    return color(gray, gray, gray, c.a);
}

print(grayscale(color(1, 0, 0)));