# Dimentra3D Renderer: Design and Improvement Roadmap

**Status:** design and implementation guide; a narrow CPU preview exists, but
the renderer is not a general or GPU/mobile-native implementation.
**Audience:** assistants and contributors building Dimentra3D's mathematical
3D pipeline and mobile preview.
**Related documents:** [`ASSISTANT-ROADMAP.md`](ASSISTANT-ROADMAP.md),
[`SPEC.md`](SPEC.md), and the existing
[Polygon Studio modeling guide](../geometry-math/MODELING.md).

## Goal

Connect Dimentra3D's own scene declarations to a renderer through defined,
typed semantics. A user should be able to write a supported Dimentra3D scene,
receive accurate source diagnostics, inspect the resulting geometry/material
data, and see a repeatable preview on a desktop browser and Android device.

The renderer should extend the project's mathematical work—not merely display
an unrelated hard-coded model, screenshot, or third-party viewer. A first
prototype now lowers the `scene.dimentra` icosphere subset to a versioned
in-memory Scene IR and calls the existing CPU rasterizer. At the same time, it
must be honest about scope: a working low-poly preview is not a production path
tracer, a native compiler, RTX, or evidence of better performance than another
renderer.

## What exists today

The repository already has a useful **independent CPU reference renderer** in
`workshop/geometry-math/mesh-render.js`. It consumes a validated triangular
mesh and projected vertex positions, then rasterizes triangles into a bounded
pixel buffer. It includes a depth buffer, visible face IDs, interpolated UVs,
mathematical diffuse/specular lighting, roughness/metallic response, emissive
terms, optional normal/roughness/emissive maps, tone mapping, wire overlay,
fog and bounded glow.

Its neighboring components provide reusable foundations:

- `math.js`: vector, triangle and topology operations.
- `mesh-tools.js`: bounded mesh validation, UV generation, material/map
  handling, OBJ parsing and mesh operations.
- `studio-model.js`: revision-checked scene state and bounded edits.
- `studio.js`, `studio.html`, `studio.css`: the browser editor and viewport.
- `mesh.test.cjs` and the geometry-math test suites: geometric/material
  correctness fixtures.

`dimentra3d-render.js` is now a narrow Dimentra3D CPU-preview adapter: it
parses/checks a source file, lowers the supported icosphere/material/light/
camera subset, fits an orthographic camera and invokes the shared rasterizer.
`android-preview.html` exposes that path locally, and
`android/` contains an isolated WebView APK prototype plus a Gradle-free build
script. This is not a general compiler or production renderer. The original
`playground.html` still only parses/displays the AST. The Polygon Studio
camera/projection and interaction model belong to the Studio and must be
inspected before reuse; do not assume its UI state is already language
semantics.

The current CPU preview is deliberately bounded: Studio renders at
approximately 500x320 before scaling for display, and `mesh-render.js`
validates a maximum 640x480 output. `mesh-tools.js` limits meshes to 512
vertices and 1024 triangles and limits local maps to 128x128. These are useful
prototype budgets, not requirements that every future target must inherit.
They must not be increased without profiling memory and frame time on actual
mobile hardware.

## Desired pipeline

The renderer must consume validated typed scene data, not parse source text
or guess what an expression means:

```text
 .dimentra source
       |
 parser + name/type/reference checking
       |
 typed Dimentra3D Scene IR
       |
 bounded geometry generation + transforms
       |
 renderer-neutral frame/scene data
       |
 +-----+----------------------+
 |                            |
 CPU reference rasterizer   mobile GPU backend (later)
 |                            |
 pixel buffer + tests       device surface
       |
 desktop/browser + Android preview
```

Keep the CPU reference path. It is the deterministic oracle for checking
geometry and shading changes, even if a GPU path is later faster. A GPU
backend must consume the same scene semantics and pass equivalent geometry,
depth/order, color-space and material tests within declared tolerances.

## Renderer rules

1. **The language is authoritative.** Resolve Dimentra3D mesh, material, light
   and scene references before rendering. Do not hard-code a scene because the
   parser currently leaves an argument as text.
2. **No silent approximations.** If the renderer supports only point lights,
   flat normals or one mesh generator, diagnose unsupported declarations or
   label the fallback in the UI. Never silently omit a mesh/light/material.
3. **Bound work before allocation.** Validate source bytes, declaration
   counts, generator parameters, vertices, indices, texture dimensions,
   framebuffer dimensions and shader work before allocating large buffers.
4. **Separate parsing, geometry and drawing.** The renderer accepts a typed
   scene object. It does not call the parser per frame, reinterpret strings,
   load arbitrary paths, or access the network.
5. **Keep color/math explicit.** Document color space, units, coordinate
   handedness, matrix layout, winding, normal transforms, clipping and depth
   convention. Convert sampled sRGB colors to linear light before lighting and
   convert to display color once at output.
6. **Keep user actions reversible and local.** A mobile preview may change
   camera/material controls in memory. It does not write arbitrary files,
   execute effects, or modify system settings.
7. **Preserve correctness at reduced quality.** Mobile quality tiers may lower
   resolution or disable optional glow/fog. They must not change source
   semantics, corrupt depth, silently alter material values, or produce
   unbounded frame work.

## Step-by-step renderer work

### 1. Close the language-to-scene gap

First define a small, explicit Dimentra3D-renderable subset. Suggested first
slice:

- `mesh` declarations for cube and icosphere generators with typed, bounded
  parameters;
- `material` values for base color, roughness, metallic, emission and optional
  clearcoat, within documented ranges;
- `light` declarations with a supported type, color, intensity and direction
  or position;
- `scene` camera and object placements with 3D transforms;
- no external image paths, shader code execution, effects, animation, skinning
  or implicit asset loading in the first renderer.

The exact source grammar and supported generators must be confirmed against
`SPEC.md`, `dimentra3d.js` and tests. The example currently declares
`icosphere(radius: ..., subdivisions: ...)` and materials/lights/scenes. The
experimental scene adapter lowers only this supported subset to validated
geometry. Other parsed generator names do not yet produce renderer-ready
geometry; never treat a parsed mesh name by itself as a generated mesh.

Implement a Dimentra3D scene-lowering module that:

- accepts the parsed and checked AST, never raw unchecked text;
- parses generator arguments into typed numbers using a real expression
  grammar once that exists (until then, accept only narrowly specified
  numeric literals and reject other expressions);
- creates validated vertices/triangles through reusable geometry helpers or
  dedicated generators;
- applies object transforms with a stated transform order and correct normal
  handling;
- resolves every material and light identifier;
- returns an explicit scene IR with a schema/version identifier;
- reports unsupported declarations as located errors rather than skipping
  them.

Keep the IR in memory initially. Persisted scene artifacts create format
compatibility obligations and should only be introduced with a schema version,
size limits and validation.

### 2. Establish geometric correctness

For each generator, add unit tests for:

- parameter lower/upper bounds and rejection of NaN/infinity;
- vertex and triangle counts;
- finite coordinates and declared radius/size bounds;
- index range, triangle area, winding and normals;
- manifold/orientation properties where promised;
- deterministic geometry for the same source and version.

For transforms, test translation, rotation, nonuniform scaling and negative
scale/reflection. Normals require inverse-transpose handling under
nonuniform scale; reflected geometry must have consistent winding or explicit
back-face behavior. Test camera projection, near/far clipping, viewport
boundaries and degenerate triangles separately from shading.

Use the existing topology/math tests where their contract matches. Add
Dimentra3D-specific fixtures for language diagnostics and IR shape; don't
couple language tests to CSS, DOM state or screenshot timing.

### 3. Make the current CPU renderer a reference backend

Create a renderer adapter with a narrow interface such as:

```text
render(sceneIR, camera, quality) -> { width, height, pixels, depth, diagnostics }
```

The exact interface can follow repository conventions. Its important
properties are:

- only validated IR reaches the rasterizer;
- bounds are validated before allocating color/depth buffers;
- output dimensions are explicit and capped;
- renderer quality settings are explicit and cannot change scene semantics;
- errors surface to the UI; invalid input never displays a stale "successful"
  frame as if it were current.

The prototype adapts `mesh-render.js` rather than rewriting the rasterizer.
It implements orthographic scene projection, bounded icosphere generation,
multi-object depth composition and a small set of mapped material/light
properties in `dimentra3d-render.js`. Reuse its depth/pixel buffers for
deterministic fixtures. Further generators, full transforms, perspective
clipping, richer light semantics and coverage remain future work; do not
silently broaden the supported subset.

Use stable fixtures: overlapping triangles for depth, known normals for
lighting direction, known material values for color, a back-facing/degenerate
triangle, and a multi-object Dimentra3D scene. Assert dimensions, selected
pixel samples or image hashes/tolerance using the project's established
image-test conventions. Avoid tests that pass merely because a canvas exists.

### 4. Connect the browser playground

The playground should show distinct stages:

1. **Parse/check:** report Dimentra3D diagnostics, source line/column and
   unsupported features.
2. **Preview:** only run after successful checks and scene lowering; show the
   rendered output and the exact supported subset/quality tier.
3. **Inspect:** expose resolved meshes/materials/lights, triangle/vertex
   counts, camera and draw diagnostics to help validate mathematical results.

Keep the existing source display safe: render source/diagnostics as text, not
HTML. Preview must be opt-in, local, bounded and deterministic. Add tests for
valid preview, invalid source, unsupported features, empty scenes, render
errors and stale-frame clearing. Include a reset-to-example control if user
editing is supported.

The first acceptance scene should be derived from
`examples/scene.dimentra`; it should not be a separate hard-coded scene that
only resembles the example.

### 5. Android prototype

The current low-risk Android prototype reuses the browser's
JavaScript parser and CPU reference renderer inside a local-only Android
WebView. This avoids a second Kotlin parser with subtly different Dimentra3D
semantics and makes the prototype's supported subset visible. It is a
software-rendered preview, not a native/GPU performance claim.

If that route is chosen:

- package only the self-contained Dimentra3D parser, scene-lowering code,
  required geometry/math/renderer files, page assets and bundled examples;
- disable network access, mixed content, popups, arbitrary navigation,
  universal file-URL access and JavaScript-to-native bridges;
- only load the fixed packaged asset page; do not expose Android APIs to page
  content;
- configure WebView debugging off in release builds and keep `file://` access
  no broader than required for packaged assets;
- cap render size and rate, avoid rendering in the background, and release
  resources when the activity pauses;
- provide touch camera controls and a readable source/diagnostic view without
  allowing arbitrary Android file selection in the first prototype;
- verify behavior at the repository's Android minimum API and on a real
  device/emulator, including rotation, pause/resume, malformed source and
  low-memory behavior.

A separate standalone prototype app avoids coupling the renderer to the
existing N8128 console-library workflow. The new custom `android/build.ps1`
assembles a debug APK with `aapt2`, `javac`, `d8`, `jar`, `zipalign` and
`apksigner` without Gradle; it still requires a JDK and Android SDK. The
current development environment does not have those tools, so an APK/device
run has not yet been verified. If the preview is ever added to N8128, keep its
launcher/trampoline and emulator launch path unchanged and add a separate
internal activity. Do not touch the emulator's native renderer or route
Dimentra3D scenes into it.

Once the CPU path is correct and measured on representative Android hardware,
consider a native GLES/Vulkan/WebGPU backend. That is a separate project
decision: native integration brings shader compilation, surface lifecycle,
device capability, synchronization and memory-management requirements. Keep
the same scene IR and correctness fixtures across backends.

### 6. Mobile quality and performance

Measure the actual target device. Record manufacturer/model, Android version,
GPU/driver, WebView version, resolution, source/scene, quality settings,
warm-up, frame count and whether timing includes parsing or only rendering.
Report median and tail frame time, peak/steady memory and dropped frames.

Profile and address bottlenecks in this order:

1. avoid parsing/lowering every animation frame; cache scene IR and geometry
   by source/version;
2. avoid repeated allocations; reuse bounded pixel/depth buffers where
   lifecycle-safe;
3. make renderer resolution/frame rate adaptive with explicit quality labels;
4. skip unchanged frames and pause work when the screen is not visible;
5. measure optional glow/blur, texture sampling and overdraw separately;
6. consider vectorized or GPU rendering only when profiling identifies a
   bottleneck and reference tests can validate the result.

Do not optimize based on desktop timing alone. Do not benchmark while logging,
debugging or running another GPU-heavy app unless that condition is explicitly
part of the test. Compare identical scenes and correctness tolerance.

## Acceptance gates

### Language and scene gate

- The documented example parses and resolves.
- Every rendered source construct has tested semantics.
- Unknown generators, invalid numbers/references, unsupported material/light
  features and resource-limit violations return located errors.
- Dimentra3D scene IR contains no unresolved names or source-expression
  strings where numeric values are required.

### Renderer gate

- Geometry and transform invariants pass.
- CPU reference output is deterministic for fixed input/options.
- Depth, projection, material color and light direction fixtures pass.
- Invalid scenes do not allocate beyond limits or leave a stale success frame.
- Renderer documentation states coordinate system, camera, light and color
  conventions and lists unsupported effects.

### Android gate

- A reproducible APK build is documented and succeeds with the stated Android
  toolchain.
- App opens a packaged Dimentra3D example offline and shows it through the
  same language-to-IR pipeline.
- Parse/check errors are visible; no unsupported operation is silently
  skipped.
- The preview survives rotation and pause/resume without leaks/crashes.
- No internet, external navigation, arbitrary host bridge or system action is
  required.
- Device/GPU/OS and limitations are reported; no performance claim is made
  without repeatable benchmarks.

## Validation commands

Keep existing checks running while adding targeted tests for scene lowering,
projection, raster output and Android behavior. At minimum, the shared
language/geometry checks are:

```powershell
node --test workshop\dimentra3d\dimentra3d.test.cjs
node --test workshop\geometry-math\test.cjs workshop\geometry-math\studio.test.cjs workshop\geometry-math\mesh.test.cjs
node tools\agent-workbench.cjs run dimentra3d
node tools\agent-workbench.cjs run geometry
```

Document the Android build command only after verifying it in the chosen
project/environment. A successful source compilation is not proof that the
APK installs, launches or renders on a device. Report unavailable SDK,
Gradle, JDK, emulator or device checks explicitly; never substitute a
successful parser test for an Android build.

## Next implementation brief

The first vertical slice now exists in experimental form. The recommended
next renderer task is to verify the Android build on a provisioned SDK/device
and then expand the scene subset only with tests:

1. Audit `SPEC.md`, the parser's actual AST, `examples/scene.dimentra`,
   `mesh-render.js`, `mesh-tools.js`, Studio projection logic and Android
   project boundaries.
2. Audit and improve correctness for icosphere generation, transformed
   normals, camera bounds, per-light color/intensity and cross-object depth.
3. Add a visible Dimentra3D preview to the original browser playground, using
   the same parser/lowering/CPU renderer rather than a separate hard-coded
   scene.
4. Build and install the isolated Android APK on an emulator and physical
   device; test pause/resume, rotation, low-memory behavior and touch controls.
5. Add another generator or camera mode only when its typed parameters,
   geometry/clip behavior, budget and reference fixtures are defined.

Keep this first slice small. Do not add a GPU backend, unrestricted shader
execution, image-path loading, effects, mobile OS integration or speed claims
until the relevant acceptance gate is met.
