640 lines
13 KiB
Plaintext
640 lines
13 KiB
Plaintext
# System library
|
|
|
|
haku comes with a set of built-in functions, called the _system library._
|
|
This is a reference for these functions.
|
|
|
|
## Preamble: how to read this reference
|
|
|
|
Each function comes with a _signature description_.
|
|
These descriptions read like this:
|
|
|
|
```haku
|
|
stroke
|
|
thickness : number
|
|
color : rgba
|
|
position : vec
|
|
-> scribble
|
|
```
|
|
|
|
The first element is always the function's name - in this case `stroke`.
|
|
Following this are `argumentName : argumentType` pairs, which describe the arguments that need to be passed to the function.
|
|
The last element is always the type of data this function produces.
|
|
|
|
Function names which are made up of symbols instead of letters are _operators_.
|
|
Operators may have one or two arguments, where one argument corresponds to a prefix form `-x`, and two arguments correspond to an infix form `x - y`.
|
|
Note that this documentation lists a unary and binary operator of the same spelling as _two separate functions_, not overloads of a single function.
|
|
|
|
The argument name usually does not matter when calling the function - it is only used for documentation purposes.
|
|
The one exception is arguments called `...`, which signify that zero or more arguments can be passed to the function at that position.
|
|
(Currently there are no functions that accept any number of arguments, though.)
|
|
|
|
The argument _type_ however is important.
|
|
If you try to use a function with the wrong type of value as its argument, it will fail with an error.
|
|
For example, consider a brush where we pass a number as `stroke`'s `color` and `position` arguments.
|
|
|
|
```haku
|
|
stroke 1 1 1
|
|
```
|
|
|
|
This brush will fail to render, since `stroke` expects an `rgba` as its 2nd argument.
|
|
|
|
With that said, there are several types of values in haku that can be passed into, and returned by functions.
|
|
|
|
- `_` - special type used to signify that any value may be passed into the function.
|
|
- `()` - also known as _nil_, means _no value._
|
|
- `boolean` - either `False` or `True`. Indicates truth or falsehood, used in `if` conditions.
|
|
- `number` - a real number, with 32 bits of precision.
|
|
- `vec` - a 4-dimensional vector, composed of four `number`s.
|
|
- `rgba` - an RGBA color, composed of four `number`s.
|
|
- `\a -> r` - a function taking in the parameter `a` and returning `r`, as returned by `\x -> x` literals.
|
|
- `list t` - a list of values, where each value is of the type `t`.
|
|
- `shape` - a mathematical shape.
|
|
|
|
- `shapeLike` - anything that can be turned into a `shape` using `toShape`.
|
|
|
|
- `scribble` - something that can be drawn on the wall.
|
|
|
|
Additionally, the syntax `a | b` may be used to signify that one of the listed types is accepted or returned.
|
|
|
|
|
|
## Math
|
|
|
|
```haku
|
|
-
|
|
a : number
|
|
-> number
|
|
```
|
|
|
|
`-`, when used in its unary form `-x`, returns the number `x` with the opposite sign.
|
|
|
|
```haku
|
|
+
|
|
a : number
|
|
b : number
|
|
-> number
|
|
```
|
|
|
|
`+` adds two numbers together.
|
|
|
|
```haku
|
|
-
|
|
a : number
|
|
b : number
|
|
-> number
|
|
```
|
|
|
|
`-`, when used in its binary form `x - y`, subtracts two numbers from one another.
|
|
|
|
```haku
|
|
*
|
|
a : number
|
|
b : number
|
|
-> number
|
|
```
|
|
|
|
`*` multiplies two numbers together.
|
|
|
|
```haku
|
|
/
|
|
a : number
|
|
b : number
|
|
-> number
|
|
```
|
|
|
|
`/` divides a number by another number.
|
|
|
|
```haku
|
|
floor
|
|
x : number
|
|
-> number
|
|
|
|
ceil
|
|
x : number
|
|
-> number
|
|
|
|
round
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`floor`, `ceil`, and `round` are rounding functions.
|
|
Each of them rounds a little differently:
|
|
|
|
- `floor` rounds towards -∞.
|
|
- `ceil` rounds towards +∞.
|
|
- `round` rounds half towards +∞.
|
|
|
|
```haku
|
|
abs
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`abs` returns the absolute value of the given number.
|
|
|
|
If `x` is less than zero, returns `-x`.
|
|
Otherwise returns `x`.
|
|
|
|
```haku
|
|
mod
|
|
x : number
|
|
y : number
|
|
-> number
|
|
```
|
|
|
|
`mod` is the modulo operation.
|
|
|
|
It returns the remainder of dividing `x` by `y`.
|
|
haku uses the Euclidean definition, which means the remainder returned by `mod` is _always non-negative_.
|
|
|
|
```haku
|
|
pow
|
|
base : number
|
|
exponent : number
|
|
-> number
|
|
```
|
|
|
|
`pow` raises `base` to the given `exponent`.
|
|
|
|
```haku
|
|
sqrt
|
|
x : number
|
|
-> number
|
|
|
|
cbrt
|
|
x : nunber
|
|
-> number
|
|
```
|
|
|
|
`sqrt` returns the square root of the given number.
|
|
|
|
`cbrt` returns the cubic root of the given number.
|
|
|
|
Other roots may be obtained using `pow x (1 / base)`.
|
|
|
|
```haku
|
|
exp
|
|
x : number
|
|
-> number
|
|
|
|
ln
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
In the following functions, `e` is the base of the natural logarithm (approximately `2.7128`.)
|
|
The `e` constant (Euler's number) is currently not exposed to haku source code; you have to define it yourself.
|
|
|
|
`exp` is the exponential function `pow e x`.
|
|
|
|
`ln` is the natural logarithm (logarithm base `e` of `x`.)
|
|
|
|
```haku
|
|
expMinus1
|
|
x : number
|
|
-> number
|
|
|
|
ln1Plus
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`expMinus1` is `pow e x - 1`, but accurate even when `x` is close to zero.
|
|
|
|
`ln1Plus` is `ln (1 + x)`, but more accurate than if the operations are performed separately.
|
|
|
|
```haku
|
|
exp2
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`exp2` is the exponential function `pow 2 x`.
|
|
|
|
```haku
|
|
log2
|
|
x : number
|
|
-> number
|
|
|
|
log10
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`log2` is the logarithm base `2` of `x`.
|
|
|
|
`log10` is the logarithm base `10` of `x`.
|
|
|
|
```haku
|
|
hypot
|
|
x : number
|
|
y : number
|
|
-> number
|
|
```
|
|
|
|
`hypot` is the hypotenuse of the Pythagorean triangle with right angle-adjacent sides `x` and `y`.
|
|
|
|
```haku
|
|
sin
|
|
x : number
|
|
-> number
|
|
|
|
cos
|
|
x : number
|
|
-> number
|
|
|
|
tan
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`sin`, `cos`, and `tan` are the [trigonometric functions][] sine, cosine, and tangent.
|
|
Their argument `x` is counted in radians.
|
|
|
|
[trigonometric functions]: https://wikipedia.org/Trigonometric_functions
|
|
|
|
```haku
|
|
asin
|
|
x : number
|
|
-> number
|
|
|
|
acos
|
|
x : number
|
|
-> number
|
|
|
|
atan
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`asin`, `acos`, and `atan` are the [inverse trigonometric functions][] arc sine, arc cosine, and arc tangent.
|
|
Their argument `x` is counted in radians.
|
|
|
|
[inverse trigonometric functions]: https://wikipedia.org/Inverse_trigonometric_functions
|
|
|
|
```haku
|
|
atan2
|
|
y : number
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`atan2` is the angle between the positive X axis and a line that passes through `(0, 0)` and `(x, y)`.
|
|
|
|
Note the reverse argument order---`y` comes first, due to `atan2` being a convenience function over `atan (y / x)` that is defined for all arguments.
|
|
|
|
```haku
|
|
sinh
|
|
x : number
|
|
-> number
|
|
|
|
cosh
|
|
x : number
|
|
-> number
|
|
|
|
tanh
|
|
x : number
|
|
-> number
|
|
|
|
asinh
|
|
x : number
|
|
-> number
|
|
|
|
acosh
|
|
x : number
|
|
-> number
|
|
|
|
atanh
|
|
x : number
|
|
-> number
|
|
```
|
|
|
|
`sinh`, `cosh`, `tanh`, `asinh`, `acosh`, and `atanh`, are the six [hyperbolic functions][].
|
|
|
|
[hyperbolic functions]: https://en.wikipedia.org/wiki/Hyperbolic_functions
|
|
|
|
|
|
## Logic
|
|
|
|
The following functions are used to compare values and work with `boolean`s.
|
|
|
|
```haku
|
|
!
|
|
a : _
|
|
-> boolean
|
|
```
|
|
|
|
If `b` is `()` or `False`, `not` returns `true`.
|
|
Otherwise it returns `False`.
|
|
|
|
```haku
|
|
==
|
|
a : _
|
|
b : _
|
|
-> boolean
|
|
|
|
!=
|
|
a : _
|
|
b : _
|
|
-> boolean
|
|
```
|
|
|
|
`==` returns `True` if `a` and `b` are equal.
|
|
Whether two values are considered equal depends on their type:
|
|
|
|
- If the type of the two values differs, `False` is returned.
|
|
- If the two values are `number`s:
|
|
|
|
- If any of the values are `NaN`, `False` is returned.
|
|
- Otherwise `True` is returned if the two numbers have the exact same bit representation.
|
|
|
|
- If the two values are `vec`s, `True` is returned if each of their `number` components is equal to each other using the rules above.
|
|
- Likewise with `rgba`s.
|
|
- All other types of values use _reference_ equality - `True` is returned only if `a` and `b` are located in the same place in memory.
|
|
This more or less means that the values are considered equal if they are produced by the same call to a system function, in time.
|
|
|
|
`!=` returns `!(a == b)`.
|
|
|
|
```haku
|
|
<
|
|
a : _
|
|
b : _
|
|
-> boolean
|
|
|
|
<=
|
|
a : _
|
|
b : _
|
|
-> boolean
|
|
|
|
>
|
|
a : _
|
|
b : _
|
|
-> boolean
|
|
|
|
>=
|
|
a : _
|
|
b : _
|
|
-> boolean
|
|
```
|
|
|
|
`<` returns `True` if `a` is less than `b`, and `<=` returns `True` if `a` is less than _or_ equal to `b`.
|
|
|
|
Order is only well-defined for numbers.
|
|
Other types may assume an arbitrary but consistent ordering - `()` may be less than `True`, or it may not be less than `True`, but this will not change between executions of the program.
|
|
|
|
`a > b` is the same as `b < a`.
|
|
`a >= b` is the same as `b <= a`.
|
|
|
|
---
|
|
|
|
Note that `and` and `or` are currently missing from this list, but are reserved keywords.
|
|
You can implement them using regular functions as a replacement.
|
|
|
|
```haku
|
|
boolAnd = \a, b ->
|
|
if (a)
|
|
if (b) True
|
|
else False
|
|
else False
|
|
|
|
boolOr = \a, b ->
|
|
if (a)
|
|
True
|
|
else
|
|
if (b) True
|
|
else False
|
|
```
|
|
|
|
|
|
## Vectors
|
|
|
|
```haku
|
|
vec
|
|
x : number
|
|
-> vec
|
|
|
|
vec
|
|
x : number
|
|
y : number
|
|
-> vec
|
|
|
|
vec
|
|
x : number
|
|
y : number
|
|
z : number
|
|
-> vec
|
|
|
|
vec
|
|
x : number
|
|
y : number
|
|
z : number
|
|
w : number
|
|
-> vec
|
|
```
|
|
|
|
Creates a new `vec` from one to four number values.
|
|
|
|
A `vec` always has four dimensions.
|
|
If any of the arguments are omitted, its corresponding dimension is initialized to zero.
|
|
|
|
```haku
|
|
vecX
|
|
v : vec
|
|
-> number
|
|
|
|
vecY
|
|
v : vec
|
|
-> number
|
|
|
|
vecZ
|
|
v : vec
|
|
-> number
|
|
|
|
vecW
|
|
v : vec
|
|
-> number
|
|
```
|
|
|
|
`vecX`, `vecY`, `vecZ`, and `vecW` extract the individual components of a `vec`.
|
|
|
|
---
|
|
|
|
Note that mathematical operations are currently not defined for vectors.
|
|
You may define your own vector operations like so:
|
|
|
|
```haku
|
|
-- Vector addition
|
|
addv = \a, b ->
|
|
vec (vecX a + vecX b) (vecY a + vecY b) (vecZ a + vecZ b) (vecW a + vecW b)
|
|
|
|
-- Likewise for subtraction, multiplication, and division.
|
|
```
|
|
|
|
Note that haku-defined vector operations like these are more costly the more components they operate on.
|
|
Therefore, it's recommended to only define them for two dimensions, unless you really need more.
|
|
|
|
```haku
|
|
addv2 = \a, b ->
|
|
vec (vecX a + vecX b) (vecY a + vecY b)
|
|
```
|
|
|
|
## Colors
|
|
|
|
```haku
|
|
rgba
|
|
r : number
|
|
g : number
|
|
b : number
|
|
a : number
|
|
-> rgba
|
|
```
|
|
|
|
Creates a new `rgba` with the given color channels.
|
|
Note that unlike `vec`, all color channels have to be provided to form an `rgba`.
|
|
|
|
```haku
|
|
rgbaR
|
|
color : rgba
|
|
-> number
|
|
|
|
rgbaG
|
|
color : rgba
|
|
-> number
|
|
|
|
rgbaB
|
|
color : rgba
|
|
-> number
|
|
|
|
rgbaA
|
|
color : rgba
|
|
-> number
|
|
```
|
|
|
|
`rgbaR`, `rgbaG`, `rgbaB`, `rgbaA` extract color channels out of an `rgba`.
|
|
|
|
---
|
|
|
|
haku uses RGBA values in a normalized `0` to `1` range rather than `0` to `255`, which may be unfamiliar if you're coming from other image editing software.
|
|
This is because it's easier to do math on normalized colors.
|
|
For example, consider multiplicatively blending two colors.
|
|
|
|
```haku
|
|
-- This is how you can multiply two colors together.
|
|
mulRgba = \a, b ->
|
|
rgba (rgbaR a * rgbaR b) (rgbaG a * rgbaG b) (rgbaB a * rgbaB b) (rgbaA a * rgbaA b)
|
|
```
|
|
|
|
If haku represented colors using an 8-bit `0` to `255` range instead, to multiply two colors together, you would have to divide them by `255` to get them back into the correct range.
|
|
|
|
```haku
|
|
-- NOTE: This example does NOT work correctly.
|
|
mulRgba = \a, b ->
|
|
let red = (rgbaR a * rgbaR b) / 255
|
|
let green = (rgbaG a * rgbaG b) / 255
|
|
let blue = (rgbaB a * rgbaB b) / 255
|
|
let alpha = (rgbaA a * rgbaA b) / 255
|
|
rgba red green blue alpha
|
|
```
|
|
|
|
Note that haku does not clamp colors to the `0` to `1` range.
|
|
It is perfectly valid to have a color that is out of range or even `NaN`, but when drawing scribbles:
|
|
|
|
- `∞` is clamped back to `1`.
|
|
- `-∞` is clamped back to `0`.
|
|
- any scribble with a `NaN` color is ignored.
|
|
|
|
Note that just like vectors, arithmetic operations on colors are currently not defined.
|
|
|
|
Before scribbles are drawn to the wall, colors are converted to 8-bit integers for more efficient rasterization and storage.
|
|
This means some loss of precision will happen, which may cause issues with brushes like this one:
|
|
|
|
```haku
|
|
stroke 128 #00000004 (vec 0 0)
|
|
```
|
|
|
|
If you try to to use this brush to fill up a single spot with black, you will notice that despite all the math suggesting so, the color will end up gray instead.
|
|
|
|
|
|
## Shapes
|
|
|
|
```haku
|
|
toShape
|
|
value : _
|
|
-> () | shape
|
|
```
|
|
|
|
Converts the given value to a shape.
|
|
|
|
- For `shape`, clones the shape that was passed in.
|
|
- For `vec`, returns a point `shape`.
|
|
- For anything else, returns `()`.
|
|
|
|
```haku
|
|
line
|
|
start : vec
|
|
end : vec
|
|
-> shape
|
|
```
|
|
|
|
Creates a line segment shape with the provided `start` and `end` points.
|
|
|
|
```haku
|
|
rect
|
|
position : vec
|
|
size : vec
|
|
-> shape
|
|
|
|
rect
|
|
x : number
|
|
y : number
|
|
width : number
|
|
height : number
|
|
-> shape
|
|
```
|
|
|
|
Creates a rectangle shape with its top-left corner at `position`, with a given `size` stretching from the top-left corner.
|
|
|
|
The alternative 4-argument version takes in the rectangle's X/Y coordinates, width, and height as separate arguments instead of aggregating them into a `vec`.
|
|
|
|
```haku
|
|
circle
|
|
center : vec
|
|
radius : number
|
|
-> shape
|
|
|
|
circle
|
|
x : number
|
|
y : number
|
|
radius : number
|
|
-> shape
|
|
```
|
|
|
|
Creates a circle shape, with its center at `center`, with the provided radius.
|
|
|
|
The alternative 3-argument version takes in the circle's center X/Y coordinates as separate arguments instead of aggregating them into a `vec`.
|
|
|
|
## Scribbles
|
|
|
|
```haku
|
|
stroke
|
|
thickness : number
|
|
color : rgba
|
|
shape : shapeLike
|
|
-> scribble
|
|
```
|
|
|
|
Creates a stroke scribble, which outlines the provided shape with a stroke of the given thickness and color.
|
|
|
|
Point shapes are drawn as squares, and `line` shapes have square caps at the line's endpoints.
|
|
|
|
```haku
|
|
fill
|
|
color : rgba
|
|
shape : shapeLike
|
|
-> scribble
|
|
```
|
|
|
|
Creates a fill scribble, which fills in the entire area of the provided shape with a solid color.
|
|
|
|
Since this requires the shape to have a surface area, this does not do anything when point and `line` shapes are passed in.
|