ZSLICEDOCS

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.

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.

Long-lived memory:

DataLifetimeSize
MeshThe whole slice12 bytes for each vertex, 12 bytes for each triangle
Face indexPass 14 bytes for each (triangle, layer) crossing
Outlines and surfacesThe whole slice16 bytes for each outline point
MemosThe slice, or until the next slice of an appThe results of the slow steps of a layer
Layer plans and their G-code textA ring of a few layers for each thread16 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.

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:

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

The C API layer

c_api.zig and the files in c_api/ are a thin layer:

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:

  1. The timer. It calls zs_app_history_commit 400 ms after the last change, with the time. The core has no clock, also in wasm.
  2. The focus. It calls zs_app_history_set_focus with the setting of the editor that has the focus. The edits of one setting are one step while its editor keeps the focus.
  3. 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).