EddyScript¶
EddyScript is a programming language with a similar syntax to Python. It is used in various parts of Eddy. Anything written in this language is compiled to native GPU code and run on hardware.
An example of this language in use can be found by opening any of the shaders Eddy ships with. They are all written in this language.
While there are many similarities to Python, it is definitely not Python. It is important that you understand how types are handled and how functions need to be declared.
Here is a list of Python features which do not have equivalents yet in EddyScript:
import
statementstuples
user defined classes/objects
strings
dictionaries
generators
context managers
nested functions
exceptions
list comprehensions
function
*args
and**kwargs
function named arguments
function optional arguments
The language is still evolving and future versions will most likely gain support for some of these features.
Types¶
Basic Types¶
Type
Description
Int
,int
32-bit signed integer
Int8
,int8
8-bit signed integer
Int16
,int16
16-bit signed integer
Int64
,int64
64-bit signed integer
Float
,float
single precision float
Bool
,bool
boolean type representing True/False
None
void. Default function return type.
Vector types¶
Type
Description
Int2
Array of 2 Int types
Int3
Array of 3 Int types
Int4
Array of 4 Int types
Float2
Array of 2 Float types
Float3
Array of 3 Float types
Float4
Array of 4 Float types
These types can be treated as normal lists like in this example:
def example(foo=Float3, bar=Float2): return foo[0] + bar[1]Here’s an example showing how you can pass a list of integers to a function accepting one of these types.
def add_float3(a=Int3, b=Int3): return a+b def example(): return add_float3([1,1,1], [1,1,1])Note
You will get a compile error if your list can’t be matched up with a corresponding vector type.
Matrix types¶
Type
Description
Float3x3
Array of 3 Float3 types
Float3x4
Array of 3 Float4 types
Float4x4
Array of 4 Float4 types
Functions¶
Defining Functions¶
A function which does not require any arguments and has no return is defined like this:
def useless_function(): pass
Currently, all code must be written inside functions. Nothing is allowed at global scope apart from function definitions.
foo = 5 # ERROR, this is in global scope def example(): bar = 5 # OK
Return Type Rules¶
When a function does not include a return statement, the compiler automatically assumes the return type is
None
.def example_no_return_specified(): pass # No return specified, compiler will assume 'return None' def example_return_specified(): return None
A function which has multiple
return
statements must ensure that all of them return the same type.def multiple_return_example_BAD(): a = 5 if a < 5: return 1.0 return [1.0, 2.0] # BAD, this does not match the type returned above which is a Float. def multiple_return_example_GOOD(): a = 5 if a < 5: return 1.0 return 0.0 # OK, both returns in this function are of the type Float
If you have a return statement other than
None
and it is inside a conditional block, you must also be sure to provide a final return statement.# This will not compile def single_return_example_BAD(): a = 5 if a < 5: return 1.0 # Function return is determined to be Float # The compiler automatically adds 'return None' # return None # BAD, 'None' is incompatible with 'Float' # This is OK def single_return_example_BAD(): a = 5 if a < 5: return None # The compiler automatically adds 'return None' # return None # OK, since the return earlier is also of type 'None'
Function Arguments¶
All function arguments require a type assignment or a literal which the type can be derived from. You specify the type in a similar way that you would mark an argument as optional in python.
# Function accepts two float arguments def add_fn(a=Float, b=Float): return a + b # Function accepts one float argument and one integer argument def add_fn(a=1.0, b=10): # Using literals to define the types return a + b # Function accepts one float argument and one integer argument def add_fn(a=Float, b=Int): # This is identical to the function defined above. return a + b
Calling functions¶
Named arguments and optional arguments are not supported. You must always provide all arguments to a function in the order in which they are defined.
def add_fn(a=1.0, b=1.0): return a + b def bad_example(): return add_fn() # ERROR, you must provide add_fn with two arguments def bad_example2(): return add_fn(5.0, b=10.0) # ERROR, named arguments are not supported def good_example(): return add_fn(5.0, 10.0) # OK
Built-in Functions¶
Math¶
Function
Description
abs (Int) → Int
Computes the absolute value of an integer number. The behavior is undefined if the result cannot be represented by the return type.
abs (Float) → Float
Computes the absolute value of a floating point value arg.
mod (Float) → Float
Computes the floating-point remainder of the division operation x/y.
fma (x: Float, y: Float, z: Float) → Float
Computes (x*y) + z as if to infinite precision and rounded only once to fit the result type.
min (a: Int, b: Int) → Int
Returns the smaller of a and b.
min (a: Float, b: Float) → Float
Returns the smaller of a and b.
max (a: Int, b: Int) → Int
Returns the larger of a and b.
max (a: Float, b: Float) → Float
Returns the larger of a and b.
dim (x: Float, y: Float) → Float
Returns the positive difference between x and y, that is, if x>y, returns x-y, otherwise (if x≤y), returns +0.
exp (arg: Float) → Float
Computes e (Euler’s number, 2.7182818…) raised to the given power arg.
exp2 (n: Float) → Float
Computes 2 raised to the given power n.
expm1 (Float) → Float
Computes the e (Euler’s number, 2.7182818) raised to the given power arg, minus 1.0. This function is more accurate than the expression std::exp(arg)-1.0 if arg is close to zero.
log (arg: Float) → Float
Computes the natural (base e) logarithm of arg.
log10 (arg: Float) → Float
Computes the common (base-10) logarithm of arg.
log2 (arg: Float) → Float
Computes the binary (base-2) logarithm of arg.
log1p (arg: Float) → Float
Computes the natural (base e) logarithm of 1+arg. This function is more precise than the expression std::log(1+arg) if arg is close to zero.
pow (base: Float, exp: Float) → Float
Computes the value of base raised to the power exp.
sqrt (arg: Float) → Float
Computes the square root of arg.
cbrt (arg: Float) → Float
Computes the cubic root of arg.
hypot (x: Float, y: Float) → Float
Computes the square root of the sum of the squares of x and y, without undue overflow or underflow at intermediate stages of the computation.
sin (arg: Float) → Float
Computes the sine of arg (measured in radians).
cos (arg: Float) → Float
Computes the cosine of arg (measured in radians).
tan (arg: Float) → Float
Computes the tangent of arg (measured in radians).
asin (arg: Float) → Float
Computes the principal value of the arc sine of arg.
acos (arg: Float) → Float
Computes the principal value of the arc cosine of arg.
atan (arg: Float) → Float
Computes the principal value of the arc tangent of arg.
atan2 (x: Float, y: Float) → Float
Computes the arc tangent of y/x using the signs of arguments to determine the correct quadrant.
sinh (arg: Float) → Float
Computes the hyperbolic sine of arg.
cosh (arg: Float) → Float
Computes the hyperbolic cosine of arg.
tanh (arg: Float) → Float
Computes the hyperbolic tangent of arg.
asinh (arg: Float) → Float
Computes the inverse hyperbolic sine of arg.
acosh (arg: Float) → Float
Computes the inverse hyperbolic cosine of arg.
atanh (arg: Float) → Float
Computes the inverse hyperbolic tangent of arg.
erf (arg: Float) → Float
Computes the error function of arg.
erfc (arg: Float) → Float
Computes the complementary error function of arg, that is 1.0-erf(arg), but without loss of precision for large arg.
tgamma (arg: Float) → Float
Computes the gamma function of arg.
lgamma (arg: Float) → Float
Computes the natural logarithm of the absolute value of the gamma function of arg.
ceil (arg: Float) → Float
Computes the smallest integer value not less than arg.
floor (arg: Float) → Float
Computes the largest integer value not greater than arg.
trunc (arg: Float) → Float
Computes the nearest integer not greater in magnitude than arg.
round (arg: Float) → Float
Computes the nearest integer value to arg (in floating-point format), rounding halfway cases away from zero, regardless of the current rounding mode.
nearbyint (arg: Float) → Float
Rounds the floating-point argument arg to an integer value (in floating-point format), using the current rounding mode.
rint (arg: Float) → Float
Rounds the floating-point argument arg to an integer value (in floating-point format), using the current rounding mode.
make_float3 (x: Int) → Float3
Returns a Float3 where all three components are set to x.
make_float3 (x: Float) → Float3
Returns a Float3 where all three components are set to x.
make_float3 (arg: Float4) → Float3
Returns a Float3 where all three components are set to the first three components of the passed in Float4.
min (a: Float3, b: Float3) → Float3
Returns a Float3 where each component is the smaller of the same compoent from from a and b.
max (a: Float3, b: Float3) → Float3
Returns a Float3 where each component is the larger of the same compoent from from a and b.
min_comp (v: Float3) → Float
Returns the smallest component of v.
max_comp (v: Float3) → Float
Returns the largest component of v.
dot (a: Float3, b: Float3) → Float
Returns the dot product of the given vectors a and b.
cross (a: Float3, b: Float3) → Float3
Returns a vector which represents the cross product of a and b.
length (v: Float3) → Float
Computes the length of the given vector v.
length2 (v: Float3) → Float
Computes the squared length of the given vector v.
dot (a: Float4, b: Float4) → Float
Returns the dot product of the given vectors a and b.
normalized (v: Float3) → Float3
Returns the normalized version of the vector v.
exp (Float3) → Float3
Returns a vector where each component is e (Euler’s number, 2.7182818) raised to the power of the same component from v.
lerp (a: Float, b: Float, t: Float) → Float
Returns a linearly interpolated value between a and b where t is the interpolation value.
lerp (a: Float3, b: Float3, t: Float3) → Float3
Returns a vector where each component is linearly interpolated from a and b using t as the interpolation value.
sign (arg: Float) → Float
Returns -1 if the arg is negative and 1.0 is the arg is positive.
is_positive (arg: Float) → Bool
Returns true if the arg is more than or equal to 0.0.
floor (v: Float3) → Float3
Returns a vector where each component is the floor of each component of the input vector v.
mul3x3 (m: Float3x4, v: Float3) → Float3
Compute a new vector by multiplying v by upper 3x3 submatrix of m, ignoring translation.
mul (m: Float3x4, v: Float3) → Float3
Compute a new vector by multiplying v by the matrix m. The last row of the matrix is implicitly (0,0,0,1)
mul (m: Float3x4, v: Float4) → Float4
Compute a new vector which is the full 4x4 matrix multiply of v and m.
Random Numbers¶
Function
Description
rngFloat (seed: Int, min: Float, max: Float) → Float
Returns a random Float value between min and max.
rngInt (seed: Int, min: Int, max: Int) → Int
Returns a random Int value between min and max.