Internals
Architecture
Read How a slicer works first. It explains the stages. This document explains how the code is organized.
Modules
src/
root.zig The public Zig API. It exports the modules and the main types.
main.zig The command line tool.
c_api.zig The C API of the slicer (zslice.h), the status codes, and
the wasm exports. c_api/app.zig and c_api/view.zig have the
app API and the 3D view API (zslice-app.h).
Stages, in pipeline order:
mesh.zig Mesh, Builder (vertex weld), STL load and write, test shapes.
slicer.zig Layer table, face index, mesh -> layer outline.
layer.zig Layer plan: walls, skin, infill, path order.
arachne.zig Arachne walls with a variable line width (a port of
CuraEngine): arachne/beading.zig, skeletal.zig,
extrusion.zig, walls.zig.
slope.zig Slope smoothing: beads in the steps of sloped tops.
support.zig Support areas under overhangs (grid support).
tree_support.zig Tree support: branches that join on the way down.
lightning.zig Lightning infill: branches under the tops, grown from the
top layer down.
gcode.zig Emitter: layer plans -> G-code, statistics.
gcode_vars.zig The variables of the start and end G-code: the names
of zslice, Cura, PrusaSlicer, OrcaSlicer, and Bambu
Studio, and their expression syntax.
engine.zig Job: runs all stages with threads, and reuses the work
of an older job.
Tools that the stages use:
geom.zig Point, Paths (flat polygon store), area, simplify.
clip.zig Polygon booleans.
clip_open.zig Clip open polylines to a region.
offset.zig Polygon offset.
voronoi.zig Voronoi diagram of points and segments (a port of
boost::polygon), with voronoi_predicates.zig and
voronoi_ctypes.zig.
infill.zig Scanline line fill, and the other infill patterns.
flow.zig The shape and the volume of a bead.
motion.zig Motion planner: the time of each move with acceleration.
settings.zig Settings, Resolved (derived values), Feature.
settings_meta.zig The section and the help text of each setting (made by
tools/settings_doc.py).
parallel.zig Parallel for loop, and a signal that threads wait on.
scratch.zig A pool of arenas for work memory.
svg.zig SVG picture of a layer plan.
Models, plates, and profiles:
plate.zig The parts on the bed, their places, and the arrangement.
orient.zig The orientation of a part with the least support.
islands.zig Shapes that start in the air.
threemf.zig 3MF load and save. zipfile.zig: the zip container.
profile.zig Profiles in TOML files. toml.zig: the parser.
import_cura.zig Import of Cura profile stacks.
cura_compare.zig The zslice settings next to the settings of a Cura
stack.
The app core (see docs/app/README.md):
app.zig The state of the app: the plates, the settings, the
overrides, the support marks, and the slice worker.
app/toolpaths.zig The paths of a slice for the previews, and the pick.
app/inspect.zig The values of one path and the reasons for them.
app/feature_settings.zig The settings that change each feature.
app/setting_effect.zig What a setting changes in the preview.
app/setting_info.zig The description of each setting for a panel.
app/history.zig The undo list of each app (the steps, the amend of
one edit, undo, redo, goto, truncate), and the changes
of a step in words.
app/plate_set.zig The plate set: one app for each plate, the
active plate, the status of each, the order of the
slices, project loads, and the sync of a view.
app/licenses.zig The licenses for a Licenses screen.
render/view.zig The 3D view: the scene, the camera, the beads.
render/plates.zig The other plates of a set in the view, and the
light beads of a slice for a far camera.
render/vk.zig The Vulkan backend of the 3D view.
render/web.zig The web backend: the frame data for WebGL2.
The dependencies go one way: stages use tools, and later stages use earlier stages. No tool uses a stage, with two exceptions: svg.zig reads a layer plan (it is an output, like gcode.zig), and a test in offset.zig uses slicer.zig to make a real input. The app core uses the stages and the tools. No stage or tool uses the app core.
Data flow
STL bytes
-> Mesh (mesh.zig)
-> []Layer, FaceIndex (slicer.zig)
-> []Paths (one outline for each layer) pass 1, parallel
-> top and bottom surfaces of each layer parallel
-> LayerPlan (a ring of a few layers) pass 2, parallel
-> G-code text, Stats (gcode.zig) in layer order
Conventions
These rules hold everywhere. Code that breaks one of them makes wrong output in a later stage, not an error.
- Units. 2D coordinates are
i64micrometers (geom.Point). Settings aref64millimeters. Convert withgeom.fromMmandgeom.toMm. Mesh vertices aref32millimeters. - Orientation. A closed polygon has the material on its left. Outer boundaries are counterclockwise and holes are clockwise. Each boolean and offset result follows this rule. Code that makes polygons from other sources must give them the same orientation, or pass them through
clip.unionAllwith.non_zero. - Closed polygons. A closed polygon does not repeat its first point at the end. The edge from the last point to the first point is implicit.
- Exact predicates. Tests on points (left of, on, crossing) use the integer functions
geom.cross3andgeom.dot3, in i128. Floating point is only for constructions (a new point), and the result is rounded to the grid.
Data types
geom.Paths
A set of paths in two flat arrays: points (all points, one path after the other) and ends (the end index of each path). One set has two allocations, not one for each path. get(i) returns the points of path i as a slice.
Build a set with append(gpa, points), or point by point with appendPoint and endPath.
layer.LayerPlan
The paths of one layer, in print order. It has its own arena: deinit frees all of it in one step. paths.items[i] has the feature and the closed flag of points.get(i).
settings.Settings and settings.Resolved
Settings has the values that the user sets. Resolved comes from Settings.resolve(): it has the derived values (the line width when it is 0, the skin layer count from the thickness, the filament area) and the speed function. Code after the engine start uses Resolved, so that each derived value has one definition.
A layer with overrides has its own Resolved (Job.resolvedAt). Settings for some layers lists the settings that can change per layer, and the code that reads them.
Memory model
zslice uses arenas for temporary memory. An arena frees all its memory in one step, so the code needs no free for each temporary array.
- Each boolean, offset, fill, and plan takes an arena for its intermediate data from the pool in
scratch.zig, and gives it back at the end. The arena keeps its memory (up to 16 MB) for the next call, so a slice does not get new pages from the operating system for each call. The engine frees the memory of the pool at the end of a slice. The result of a call goes in the allocator of the caller. layer.planputs the plan in its own arena (it lives until the G-code is written).slicer.sliceAtuses a pool arena for the segments and chains of a layer.- The memo of each layer (
layer.Memo) has its own arena with the results of the slow steps (offsets, skin, fill regions) by their inputs. An app keeps the memos for the next slice (Job.initReuse). A one-shot slice frees each memo after the plan of its layer (Job.keep_memos).
Long-lived memory:
| Data | Lifetime | Size |
|---|---|---|
| Mesh | The whole slice | 12 bytes for each vertex, 12 bytes for each triangle |
| Face index | Pass 1 | 4 bytes for each (triangle, layer) crossing |
| Outlines and surfaces | The whole slice | 16 bytes for each outline point |
| Memos | The slice, or until the next slice of an app | The results of the slow steps of a layer |
| Layer plans and their G-code text | A ring of a few layers for each thread | 16 bytes for each path point |
Threads
parallel.forEach(threads, n, ctx, func) runs func(ctx, i) for each i on a set of threads. Each thread takes the next i from one atomic counter.
- Pass 1 writes
outlines[i]from thread i. Each slot has one writer. - The face index of pass 1 is made in blocks of faces on all threads. Each block counts its faces in each layer, and a prefix sum gives each block its part of each layer, so the faces of a layer stay in face order.
- Pass 2 is a pipeline (
engine.Pipeline). A thread plans layer i into slot i mod (ring size) of a ring. The same thread then does the work of the emitter that does not depend on the layers before (gcode.prepare): the combing ways of the travels and the lengths of the moves. The calling thread makes a dry run of the emitter for each planned layer, in layer order: it finds the emitter state at the start of the layer and formats no numbers. It uses a prepared way or length only if the nozzle is at the point that it was found from. Then any thread writes the G-code text of the layer with a copy of that state, and the calling thread writes the texts out in layer order. A thread that waits sleeps on aparallel.Signal. - A cancel stops pass 2 between the steps of a layer plan (
layer.Context.cancel). The pipeline drops a plan that stopped early. The memos get only complete results, so the next slice can use them.
The work of each item depends only on its index and on data that does not change during the pass. Thus the output is the same for each thread count. A test checks this (engine.zig).
On wasm, parallel.has_threads is false and the loop runs on the calling thread.
Speed in WebAssembly
The wasm module runs the same code as the native build. Some code that is fast on x86-64 is slow in wasm. Keep these rules in the hot loops:
- No 128-bit product. Wasm has no instruction for a 64 x 64 -> 128 bit product, so each one is a call of a library function (
__multi3). Usegeom.mulSubandgeom.mulAdd(andgeom.cross3,geom.dot3,Point.dist, which use them): in wasm they use 64-bit products when the factors are small.clip.zighas its own 64-bit forms for coordinates in range (Arith). - No float
@min,@max, or@round. Wasm has other rules for NaN and for a half than C, so each of these is a call of a library function. Usegeom.fmin,geom.fmax, andgeom.round. - No division for an index. A band, a slab, or a grid cell has a width that is a power of two, so its number is a shift (
clip.Grid,clip.SlabIndex,geom.EdgeIndex,infill.Boundary). A walk around a polygon steps with a comparison, and not with a modulo. - No copy with a length that is known only when the code runs. It is a call into the host (
memory.copy). Copy a fixed count of bytes (seegcode.Line.addDigits), or a struct. - Small functions for the hot loops, and pointers to the items. The compiler of the host keeps the values of a small loop in registers. In a very large function (after much inlining) it keeps them on the stack. A copy of a 48-byte struct from an array costs six loads and stores. See
clip.testCells. - Threads: sync the memory size. V8 keeps the size of the shared memory in each instance. A thread must do a
memory.growof 0 pages before it uses memory that another thread added (wasm_heap.sync). Without it, amemory.fillormemory.copycan trap, and the slice then waits for the thread with no end.
Measure each change in wasm and native, on one thread and on all threads, and check that the G-code is the same. web/app/README.md tells what helps the first slice of a visit.
Error handling
- Allocation errors go up to the caller as
error.OutOfMemory. - Bad input (a broken STL file, bad settings) returns an error from
Mesh.fromStlorSettings.resolve. - Bad geometry is not an error. A mesh with holes or overlaps gives the best output that the code can make: open chains are closed or removed, and overlaps are joined by a union.
The C API layer
c_api.zig and the files in c_api/ are a thin layer:
- Each exported function checks its pointers, calls the Zig API, and changes the Zig error to a status code.
CSettingshasSettingsand an arena for the string values, becauseSettings.setdoes not copy strings.CallbackWriteris astd.Io.Writerthat sends its buffer to the C callback.- The wasm build compiles the same file for
wasm32-freestanding. - Each function that changes the state of an app notes the change for its undo list (
notedinc_api/app.zig): the name of one setting, or "more", and a flag for a change of the plate. The Zig functions ofAppdo not note changes. A Zig shell that calls them directly callsApp.undo.noteitself.
The undo list
The undo list is in the core (src/app/history.zig), one list for each app. The GTK shell and the web app had a copy each; now they call zs_app_history_*. A shell keeps only three things:
- The timer. It calls
zs_app_history_commit400 ms after the last change, with the time. The core has no clock, also in wasm. - The focus. It calls
zs_app_history_set_focuswith the setting of the editor that has the focus. The edits of one setting are one step while its editor keeps the focus. - The UI: the history list, the timeline, and the undo and redo keys. After an undo, it updates its editors from the bits of
enum zs_history_restored, saves the groups that changed, and slices again.
A step keeps the texts of the three groups (zs_app_state_write), the quality profile, the plate as a 3MF file (steps with the same plate share one file), and the facts of the state. The text of a step comes from the diff of its facts and the facts of the step before. A plate set has one app for each plate, so each plate has its own undo list. The plates themselves are not in an undo list: a removal of a plate cannot be undone.
The plate set
The plate set is in the core (src/app/plate_set.zig, zs_set_*). A zs_set owns one zs_app for each plate. The shells had a copy each (the web worker had the list of plates, and the GTK app had the PlateSlot swap in one app); now they call zs_set_*, and the zs_app_* calls on the app of the active plate (zs_set_app).
- The status of a plate comes from the state of its app and two marks of the set: wanted (a slice waits) and cannot (a resin plate).
zs_set_plate_infogives it with the id (new for each plate), the bed, the name, the printer key, the part count, and the message of a load. - The order: a change (
zs_set_changed) marks a plate wanted. The active plate slices first, then the other wanted plates in order, one at a time. A held change (zs_set_changed_held) waits forzs_set_release, so a drag slices once at the end. - Two modes. Native (
zs_set_new): the core starts each slice on its threads. A change of the active plate starts its slice at once and stops a background slice; that plate slices again later. A slice thread never waits for the lock of the set: it marks the work as pending, and the holder of the lock starts the next slice. wasm (zs_set_new_web): a slice runs on the calling thread, and the worker callszs_set_stepfrom a timer, so the messages of the page come between the slices. - Projects:
zs_set_project_loadloads all plates of a printdeck.yml, one app for each plate. A plate with no Cura stack gets its parts (for the footprints) and the status cannot. - The view:
zs_set_view_syncgives a view the beds, the clears where another plate came to a place (by id), the flags, the footprints, and the beads of the other plates with a new slice. The set keeps the scene bytes of the last slice of each plate, so a plate that slices again shows its old beads. The web app slices in a worker and draws on the page:zs_set_sync_writewrites the same sync as bytes, andzs_view_sync_readapplies it to the view of the page. - The shells keep the UI: the plate bar, the labels, the keys, the framing of the camera, and the question before a removal.