Crate maray

Source

Expand description

§Maray

JIT Ray Tracing using basic math

chess

This image was rendered by Maray from “data/chess.maray”.

To install:

> cargo install --example maray maray

To run:

> maray --cpus 8 --input "data/chess.maray" --output "test.png"

Shorthand version:

> maray -c 8 -i "data/chess.maray" -o "test.png"

§Textures

You can use --textures or -t to specify a list of images.

> maray -c 8 -i "input.maray" -o "output.png" -t "texture0.png" "texture1.png"

Maray sets up a defaul runtime with functions for color channels (RGB) and image width and height.

For the formula to get the id of a function, see the textures module.

When using Maray as a library, you can customize the runtime.

§Using Maray as a library

Maray has a Cargo default feature flag “render” which can be turned off. This is useful when only needing the library to generate content.

§About Maray

Maray is a binary format for ray tracing scenes that uses basic math expressions. It can be used for both 2D and 3D. The renderer uses Just-In-Time compiling (JIT) into WASM.

Maray can also be used as a Rust library to produce content for ray tracing or to perform semantical analysis on math formulas. Through the library, you can also render using Rayon and an interpreter, which is approximately at least 10-20x slower than the JIT renderer.

The binary format serializes maray::Expr using bincode, with the size [u32; 2], so the renderer knows the resolution of the image. The format is designed to reproduce rendering exactly without any additional parameters. To change the size, you need to generate a new file. The floating point precision is f64 for high quality numeric precision.

§Features

Maray contains much less features than other ray tracing software. In Maray, you build stuff using basic math, so you need an external programming language or tool to produce the data. However, besides this restriction, there are no limits on how people produce content. Results are reproduced deterministically on all platforms and the code runs on most hardware. Using basic math helps researchers build tools that work for all content produced in Maray.

Maray can be used as a Rust library:

Produce binary files storing mathematical expressions
Automatic compressor of math formula
Render and export to PNG file
Parallel rendering using Rayon and interpreter
Parallel rendering using WASM and JIT by wasmer
Semantics trait for performing semantical analysis

When using Maray, it is common to inline everything first and use automatic compression to reduce operations.

§Design

Maray has a very limited set of building blocks:

x (X coordinate)
y (Y coordinate)
τ (tau = 2*𝜋)
𝐞 (Euler’s constant)`
ℕ (natural number constants)
- (unary minus)
1/ (reciprocal, unary division)
abs (absolute value)
sqrt (square root)
step (1 if >= 0, 0 otherwise)
sin (sine)
exp (𝐞^)
ln (natural logarithm)
+ (addition)
* (multiplication)
max (maximum)
min (minimum)
app (call external function)

There are no loops or recursion, vectors, matrices built in. To use a texture, see Runtime.

Maray supports variables, for example:

x + a
where
  a = 2 + y

You can perform partial evaluation and automatic compression of a math formula after inlining everything. This optimizes the formula for rendering.

One benefit of Maray is that researchers can perform semantical analysis on expressions and build tools that works with all content produced in Maray.

Modules§

cache: Variable cache.
compressor: Automatic compressor of math expression.
constant: Semantical constant analysis.
grid: Grid.
partial_eval: Semantical partial evaluation analysis.
partial_red: Semantical partial reduction analysis.
sd: Signed distance functions.
semantics: Semantical analysis.
textures: A runtime context for a list of textures.
token: Tokens for decoration.
var_fixer: Fixes variables ids in expression.

Structs§

Context: Stores variables that are reused in expression.
Runtime: Stores context and external functions.

Enums§

Expr: Stores expression of two variables (X and Y).
RenderMethod: Specifies rendering method.
Report: Specifies report settings when rendering.
ReportState: Stores report state.

Functions§

abs: Absolute value.
add: Addition.
app: Call some external function.
chess: Chess pattern.
clamp: Clamp value.
clamp_u8: Clamp value to u8 range.
clamp_unit: Clamp value to unit range.
cos: Cosine.
div: Division.
e: Euler’s constant.
eq: Equal.
exp: Natural exponent.
from_barycentric: Transforms from barycentric coordinates to cartesian.
ge: Greater or equal.
gen: Render using method, generate to file.
gen_to_image: Render using method, generate to file.
gt: Greater than.
half: Half unit.
inside_triangle: Gets expression for inside triangle.
le: Less or equal.
lerp: Linear interpolation.
let_: Let-expression.
ln: Natural logarithm.
lt: Less than.
max: Maximum.
min: Minimum.
mul: Multiplication.
nat: Natural number.
neg: Negative.
open: Open file.
p2_abs: Component-wise absolute of 2D vector.
p2_add: Addition of 2D vectors.
p2_cbez: Cubic Bezier spline in 2D.
p2_circle: Circle in 2D.
p2_div: Component-wise division of 2D vector.
p2_dot: Dot product of 2D vectors.
p2_len: Length of 2D vector.
p2_lerp: Linear interpolation in 2D.
p2_max: Maximum of 2D vector components.
p2_mul: Component-wise multiplication of 2D vectors.
p2_neg: Negative 2D vector.
p2_pos: If cond is greater or equal to zero, then a is returned, otherwise b.
p2_qbez: Quadratic Bezier spline in 2D.
p2_scale: Scale 2D vector.
p2_spiral: Spiral in 2D.
p2_sub: Subtraction of 2D vectors.
p2_subst: Substitutes with offset.
p4_same: Gets 4D point with same components.
p4_xy: Gets x and y component of 4D point.
p4_zw: Gets z and w component of 4D point.
pi: Pi.
pos: If cond is greater or equal to zero, then return a, otherwise b.
quad_pos: Gets position within quad using UV coordinates.
quad_to_tri: Gets triangles of quad.
rad_45: 45 degrees in radians.
rad_90: 90 degrees in radians.
rad_to_unit: Convert from radians to unit interval.
range: Range with exclusive end.
range_incl: Range with inclusive end.
recip: Reciprocal (univary division).
save: Save to file.
set_and: AND of two sets.
set_inv: Invert set.
set_or: OR of two sets.
set_unit_square: Limit set to unit square.
set_xor: XOR of two sets.
sin: Sine.
sqrt: Square root.
square: Square a^2.
step: Step at zero.
step_at: Step at x.
step_pos: Step after zero.
step_pos_at: Step after x.
sub: Subtraction.
tau: Tau.
to_barycentric: Transforms from cartesian coordinates to barycentric.
to_uv: Gets UV coordinates in triangle.
unit_to_rad: Convert from unit interval to radians.
var: Variable, hashing a variable id from name.
var_id: Variable id.
var_range_union: Gets the variable id range union.
x: X.
y: Y.

Type Aliases§

Color: A parametric color in 2 dimensions.
Decor: Used to decorate an expression with extra information.
Point2: A parameteric point in 2 dimensions.
Point3: A parametric point in 3 dimensions.
Point4: A parametric point in 4 dimensions.

Crate marayCopy item path