amenui
en·中 github ↗ v0.0.1
01docs 02components 03lab 04works
en·中github ↗
×

docs / concepts / design / 1.18 3d docs / concepts / design /

1.18 3D

03.34

A 3D object is one more thing on the page (a fourth instance kind, MESH): it is drawn in the rect layout gives it, in the current material, loosens, morphs and can be pressed; it is not a separate engine. Code: src/mesh.rs (no GPU: matrices, generated meshes, a glTF subset, scene description, picking), src/mesh.wgsl (the mesh pass and its resolve) and the renderer's prepare_meshes.

Description. el::scene3d(Scene3d) (100% wide and 240 tall by default) and el::mesh(MeshId) (one mesh, default camera and light). Scene3d { items: Vec<MeshInstances>, camera, light, spec: Mesh3d, picture }: MeshInstances { mesh, transforms: Vec<Mat4>, paint, id } is several copies of one mesh in one draw call (two thousand low-poly instances are one page on the website); one camera (Camera: perspective fov or orthographic height, yaw, pitch and distance about target, near, far); one directional light (Light { dir, ambient }). Meshes live in mesh::Library: the built-in cube, UV sphere, icosahedron (0–3 subdivisions), torus, cylinder, cone and plane have fixed ids, and Ui::add_mesh adds others (generated in code, or read with mesh::load_gltf behind the gltf feature: positions, normals, indices, node transforms; no skinning, materials or textures). A mesh is a triangle list, each triangle using its face normal by default; when Mesh::normals gives each corner its own normal the surface is smooth and only creases are edges (Mesh::creased(angle) decides by the angle between neighbouring faces: smooth below it, creased above). More generated primitives: extrude (a closed 2D outline extruded along z, both faces as triangle fans, side walls smoothed by crease), extrude_bored (the same with a round hole), tube (washers, bushings), gear (a spur gear: tooth count, pitch radius, thickness, hole; the tooth flank rises steeply from the root and curves to the tip circle like an involute, with tooth thickness half the circular pitch at the pitch circle), block (a box with every edge creased) and rod (a cylinder with smooth sides and creased ends). Mesh3d adds tones (2: flat lit and shadow tones, with the terminator at terminator) and outline (ink lines on silhouettes and creases, in logical px); flat-shading normals and shading are interpolated in the fragment. Colour is a Paint (tone, accent, hue), using theme colours like shapes do.

The mesh pass. Each scene3d element has a set of off-screen images the size of its device rect × Mesh3d.resolution_scale (0.5 by default, 0.25–1), with 24-bit depth and three RGBA8 targets drawn at once (multiple render targets work on WebGL2 without blending): shading (ambient + Lambert, flat), tone, accent and hue; view-space normal xy and 16-bit linear depth; the instance index (+ 1, 16 bits) and normal z. Unchanged elements (same Scene3d::fingerprint and size) are not redrawn.

The resolve. Three small full-screen passes: mask (covered pixels are silhouette; a covered pixel whose right or lower neighbour is a different instance, whose depth jumps more than edge_depth (relative depth, 0.04 by default) or whose normals differ by more than edge_normal (15° by default) is an edge, one pixel wide), then h and v (an exact Euclidean distance: the nearest inside / outside horizontally, combined vertically over ±R rows, R = SPREAD / device length per pixel + 1). The result is two signed distances, one for the silhouette only and one for silhouette plus creases, and a projected normal code (1 facing the viewer, 2–9 one eighth of a half turn of direction each). In the G-buffer stage a MESH instance reads distance bilinearly and colour by nearest: coverage comes from the silhouette distance (so the outline is smooth), near.r is the silhouette-plus-creases distance, the coverage buffer uses the shape encoding (r = shade × tone × (1 − accent), g = shade × accent, the b code hue × 0.15 + 0.07: a shape, recognisable as a mesh), and near.g holds the normal code (1–9 / 255, below every picture marking). So every material draws 3D without extra code: creases are outlines in the SDF, carvr carves along them, near draws their iso-lines. ambient keeps the darkest face off the page background. With Scene3d.picture = Some(slot) it is drawn as a picture (the marks of §1.6.1, with its own ground).

ASCII by normal: in a mesh's cells, the charr material sets character density by shading; on creases (|sd| < 0.75 P) it draws strokes along the crease, and on faces turned sideways strokes across the slope (| / - \, the nearest of four families, one stroke max(1, 0.14P) wide), in the proportion ascii_normal_weight (charr's 4th parameter, 1 by default).

Marks by depth (Look::marks: Marks { depth_scale, depth_dim }, both 0 by default, also in presets): the mesh pass multiplies shading by 1 − depth_dim × far and tone by 1 − depth_scale × far, far being where this instance's view-space depth lies between the scene's nearest and farthest (Scene3d::depth_range: each instance's center plus and minus its bounding radius); materials that size and space marks by ink (dottr, halftonr, charr, picture marks) therefore draw smaller and fainter far away. This is not a second route that changes cell size by depth: the cells are still the one screen-wide grid (§1.6.1); what changes is the ink in them. The 3D page's mechanism can use 0.45 and 0.35. check item 17 (formerly item 19): with both at 0 it is byte-identical to off; turned on, more than 500 pixels far away darken and fewer than a tenth of that many brighten.

Interaction. Picking happens on the CPU: the same transforms and camera cast a ray from the pointer (bounding-sphere culling, then Möller–Trumbore), so headless, WebGL2 (where readback is asynchronous) and native all behave the same, synchronously. El::on_pick(|Pick| ..): Pick::Hover(Option<MeshHit>) when the pointer moves to another instance (or leaves), Pick::Press(..) on press, with MeshHit { object, instance }, through the existing hit-test path. El::on_wheel gets the wheel before scrolling does. widgets::orbit is the camera control: dragging orbits (computed from the angles at the press, per_px degrees per pixel), the wheel dollies (dolly), the arrow keys turn once focused (step_deg, Shift × 4); on release it takes the velocity of the last 0.1 s and decelerates by the exact integral of v e^(−friction t) (like the fling in §1.8.2), stopping below stop; the application calls Orbit::step in on_tick and wants frames with on_wake while moving(). The camera is state; the component never moves by itself.

Loosening. 3D elements are decoration by default (Response::Loosen, not legible), even when draggable: fronts and hover bursts loosen them through the same field (the burst is added to meshes in the G-buffer stage's own_loose), and the scope rules (§1.15) apply as usual; the lens, as §1.15 says, touches only those the pointer is not operating.

Acceptance. tests/mesh.rs (two thousand copies are one group in one draw; hover and press carry the instance index and the hovered instance is drawn alone in the accent; dragging orbits and coasts to a stop with no frames wanted after; the wheel and the arrow keys; fronts loosen meshes); unit tests in mesh.rs (primitives are closed and face outward, the camera, picking the nearest, surface sampling, glTF); check item 14: drawing again after turning 0° and drawing with a new renderer are byte-identical; at resolutions 0.5 and 1 each row of a still silhouette is one run (convex objects), and under near every edge projected on the CPU has an outline drawn on it (control: none with a threshold above every angle). Samples samples <dir> mesh: the same object in every material at rest and loosened 0.7, plus four mark sets drawing it as a picture.