Skip to content

armgit / vork

Public Imported from GitHub
0

Headless 3D and VFX engine for agents. Research preview.

Correct Mac requirements, help scope and benchmark rerun claims

Ravi Parikh683f96139118
diff --git a/README.md b/README.md
index 5b74e77..b499349 100644
--- a/README.md
+++ b/README.md
@@ -138,8 +138,12 @@ initial impulse and limited secondary spray.
## Give it to an agent
Start with `vork help`. The getting-started help is about **2,500 tokens**,
-including a complete first scene. The full help is about **19,400 tokens**.
-Those are help-text counts, not a claim that every advanced API fits on one page.
+including a complete first scene. Root, topic and command help total about
+**19,500 tokens**; detailed field lookups add more. These are release 0.1.0
+counts with the o200k_base tokenizer, not a measure of the whole API. The aggregate
+concatenates `vork help`, each listed topic except `field` with `--all`, and `--help` for
+render/std/setup/help. `vork help field material.inputs` includes another 38
+lookup-only records (about 1,800 tokens).
Use the [prompt above](#paste-this-to-your-agent) to start.
@@ -169,6 +173,8 @@ vork help programs --all
Scene content and render quality are separate. Use `std/previs` to iterate,
`std/draft` for scene-ray lighting at 4 samples,
`std/final` for the default delivery profile, and `std/path` for path transport.
+Final approximates indirect lighting and can darken interiors, including glossy
+bounces. More samples do not restore omitted transport; try path and inspect.
Draft and final use 4 and 8 samples with bundled OIDN denoising by default; use `--set denoise=false` to turn it
off. `--set samples=N` overrides the profile budget (1..4096); more samples means cleaner and slower.
Without a fast GPU denoiser (NVIDIA or Apple GPU), draft and final say so and use 16 and 32 samples undenoised;
@@ -247,7 +253,7 @@ Different quality and timing boundaries still apply.
These 1080p still timings were measured in an earlier freeze, not on that
build. Adaptive sampling up to 4,096, threshold 0.01, minimum 64; stopping
-implementations differ. vork is slower in all three named cases.
+implementations differ. vork is slower in both cases below.
| Scene input | Cycles (s) | vork path (s) | Comparison |
|---|---:|---:|---|
@@ -292,7 +298,9 @@ The [bird inputs](benchmarks/birds/README.md) include the compute programs and
all three cameras. These `std/draft` movies use four samples and OIDN at
1080p24; each number is the median of three full commands. The first full movie
is included in that three-command median, after a separate 320×180 still warmup.
-Setup and warmup are excluded from the movie times below.
+Setup and warmup are excluded from the movie times below. For skim, setup +
+warmup + the movie median total 506.781 seconds (8.45 minutes); asset preparation
+and transfers are additional.
| Camera input | Frames | vork movie (s) | Setup (s) | Warmup (s) | EEVEE 16-sample projection (s), both retained runs |
|---|---:|---:|---:|---:|---:|
@@ -318,9 +326,15 @@ python3 benchmarks/run.py --vork vork --out /tmp/vork-benchmark
python3 integrations/blender/benchmark.py --blender blender --out /tmp/blender-benchmark
```
-These recipes use the current shipped profiles and their own documented timing
-boundaries; they are not the exact harness behind the numbers above. Compare results only with
-recorded builds, settings and cache state. See [the method](benchmarks/README.md).
+The vork runner measures undenoised B-scene variants, not the denoised final8
+tables above. It omits draft and does not set the recorded seed 11. The bird
+runner uses previs/final with a full-resolution warmup, not the recorded draft4
+workflow. The final8/draft4 tables use build `81ae2b075`; preview and path results
+come from earlier freezes, as noted beside those tables.
+
+The Blender helper currently fails during camera preparation on Blender 5.2.1.
+Independent reproduction of the comparisons is not working. The commands above
+are supplied for inspection; see [the method](benchmarks/README.md).
## Research-preview limits
@@ -352,9 +366,9 @@ Binary packages are available from [GitHub Releases](https://github.com/voyager-
once a release is published. Keep the entire install folder together: Slang, OIDN,
libraries, examples, SDKs and licence texts are runtime companions to the binary.
-- **Linux:** x64, glibc 2.35+ (Ubuntu 22.04+), a recent NVIDIA GPU and its hardware-ray-tracing Vulkan driver.
+- **Linux:** x64, glibc 2.35+ and libstdc++ with `GLIBCXX_3.4.30` (Ubuntu 22.04+), a recent NVIDIA GPU and its hardware-ray-tracing Vulkan driver.
- **Windows:** x64 Windows 10/11, a recent NVIDIA GPU and its hardware-ray-tracing Vulkan driver.
-- **Mac:** Apple Silicon with Metal. Intel Macs are unsupported. H.264 uses system VideoToolbox.
+- **Mac:** Apple Silicon with Metal, macOS 26 for the bundled Slang toolchain. Older macOS versions are unqualified. Intel Macs are unsupported. H.264 uses system VideoToolbox.
### Linux
@@ -370,6 +384,10 @@ vork --version
vork help
```
+These dependency commands are for Ubuntu with sudo. In a root container, omit
+`sudo`; without administrator access, arrange for the dependencies to be installed.
+The installer itself runs in your user account without root.
+
The installer verifies SHA256SUMS, installs under `$HOME/.local/lib/vork`, links
`$HOME/.local/bin/vork`, runs `vork setup`, and adds the PATH line to your shell's
startup files, including the one login shells read. The `export` above covers the
@@ -377,9 +395,29 @@ current shell, and any shell that reads no startup file, such as plain `bash -c`
`VORK_NO_MODIFY_PATH=1` or a custom `PREFIX` leaves startup files alone. Linux MP4 needs ffmpeg even when NVENC encodes frames, because ffmpeg
muxes the stream. Native NVENC is attempted on NVIDIA; otherwise encoding uses a
readback fallback. Older GPUs and software Vulkan adapters are unsupported.
+A100, H100, H200, B200 and B300 lack the required hardware ray tracing; recency
+alone does not make a NVIDIA GPU suitable. Containers also need working NVIDIA
+Vulkan driver discovery; passing through a GPU alone may not be sufficient.
### Mac
+The released 0.1.0 archive has these Mach-O `LC_BUILD_VERSION` minimums:
+
+| Binary | macOS minimum |
+|---|---:|
+| `vork` | 11.0 |
+| `slang/bin/slangc` | 26.0 |
+| `slang/lib/libslang-compiler.0.2026.20.dylib` | 26.0 |
+| `slang/lib/libslang-glsl-module-2026.20.dylib` | 26.0 |
+| `oidn/lib/libOpenImageDenoise.2.5.1.dylib` | 11.0 |
+| `oidn/lib/libOpenImageDenoise_core.2.5.1.dylib` | 11.0 |
+| `oidn/lib/libOpenImageDenoise_device_cpu.2.5.1.dylib` | 11.0 |
+| `oidn/lib/libOpenImageDenoise_device_metal.2.5.1.dylib` | 11.0 |
+| `oidn/lib/libtbb.12.19.dylib` | 11.0 |
+
+These are archive load-command targets, not tests on older macOS versions.
+A successful `vork --version` does not test Slang; new authored programs need it.
+
In Terminal:
```sh
@@ -414,6 +452,10 @@ vork --version
vork help
```
+These dependency commands are for Ubuntu with sudo. In a root container, omit
+`sudo`; without administrator access, arrange for the dependencies to be installed.
+The installer itself runs in your user account without root.
+
The installer verifies SHA256SUMS, installs under `%LOCALAPPDATA%\Programs\vork`,
runs `vork setup`, and adds that folder to your user PATH so new windows find `vork`;
the `$env:Path` line above covers the current one. `VORK_NO_MODIFY_PATH=1` or a custom
@@ -432,7 +474,7 @@ Add that folder to your user PATH, open a new PowerShell window, and run
with no output until `Shader setup completed`; that isn't a hang. Keep all bundled
runtime companions beside the executable.
-`install.sh` downloads the release from GitHub; to install an archive you already
+The separately downloadable `install.sh` downloads the release from GitHub; to install an archive you already
have without downloading again, use the manual steps below.
### Manual archive install (Linux or Mac)
diff --git a/benchmarks/README.md b/benchmarks/README.md
index f07ff7b..d851dd6 100644
--- a/benchmarks/README.md
+++ b/benchmarks/README.md
@@ -19,7 +19,12 @@ python3 benchmarks/fetch.py
python3 benchmarks/run.py --vork vork --out /tmp/vork-benchmark
```
-The runner measures the **current shipped profiles**. It records setup, a separate per-scene warmup, five warm process
+The runner resolves named profiles but forces `denoise=false`. By default it
+selects only B scenes and previs/final/path, omits draft, and does not set seed 11.
+It does not reproduce the historical denoised final8 tables or their C/D scenes.
+Those measurements use build `81ae2b075` and the settings listed with each table.
+
+It records setup, a separate per-scene warmup, five warm process
times, commands, exit codes, diagnostics and PNGs. Setup uses the existing cache;
this is not a cold-cache benchmark. Use a new `VORK_CACHE_DIR` to measure first use
and record that choice. `--resolution 320x180 --repetitions 1` is a smoke run only.
@@ -27,6 +32,12 @@ and record that choice. `--resolution 320x180 --repetitions 1` is a smoke run on
separately from final/path. No timings are projections. Inspect every image and
report failures, hardware, driver, build, cache state and quality differences.
+**Known failure:** the helper fails during camera preparation on Blender 5.2.1:
+its Track To axis enum is invalid, and Python exceptions do not stop preparation
+reliably. The historical comparisons cannot currently be reproduced with it.
+Repair and validation across scenes are pending. The commands below describe
+the intended workflow.
+
To create and time Blender inputs, use the separately licensed
[Blender benchmark helper](../integrations/blender/benchmark.py). It imports the
same scene assets and copies the camera and lights from these scene files. Its
diff --git a/benchmarks/birds/README.md b/benchmarks/birds/README.md
index c09702d..111332f 100644
--- a/benchmarks/birds/README.md
+++ b/benchmarks/birds/README.md
@@ -23,7 +23,9 @@ needed. `--shot dive` and `--shot reveal` run the other later cameras. Results,
images, video, simulation checkpoints, exact commands, exit codes, wall times,
version and scene hashes stay in the output folder. Asset downloads and setup
are timed separately. Each profile gets a separate warmup and full measured movie.
-The current shipped `std/previs` and `std/final` profiles are used; `std/draft` remains available, with four samples and OIDN denoising.
+The runner selects `std/previs` and `std/final` and warms up at full resolution.
+It does not reproduce the historical draft4 + OIDN movies, which used a 320×180
+still warmup. Those timings use build `81ae2b075`, seed 11 and the table settings.
The Blender adapters live in [the separately licensed integration](../../integrations/blender/).
They bake actual simulation checkpoints before timing and hand the completed flock
diff --git a/docs/help/build.md b/docs/help/build.md
index 47972e5..9bd6d8d 100644
--- a/docs/help/build.md
+++ b/docs/help/build.md
@@ -8,6 +8,9 @@ pinned Intel Mac or Linux ARM archive.
## Prerequisites
+The pinned Slang 2026.20 macOS binaries target macOS 26. Older macOS versions
+have not been qualified with this toolchain.
+
On macOS, install Apple's command line tools, then install Homebrew from
https://brew.sh if it is not already available:
@@ -97,7 +100,8 @@ see README.md (Install). The compiled help and scene JSON are identical on every
## Runtime dependencies
-Video output needs FFmpeg and ffprobe on PATH.
+Linux/Windows video output and video decoding/fallbacks need FFmpeg on PATH;
+video inputs also need ffprobe. Native Mac H.264 output uses VideoToolbox.
Install the pinned denoiser with `python scripts/install-oidn DESTINATION`.
Set VORK_OIDN to its lib/libOpenImageDenoise.so.2 on Linux,
lib/libOpenImageDenoise.2.dylib on macOS, or bin/OpenImageDenoise.dll on Windows.
diff --git a/docs/help/errors.md b/docs/help/errors.md
index b0e2eac..3a2c612 100644
--- a/docs/help/errors.md
+++ b/docs/help/errors.md
@@ -1,2 +1,3 @@
ERRORS: exit codes: 0 success; 2 usage; 3 invalid scene or program;
4 device, GPU memory, encoder or setup; 5 filesystem IO.
+Known issue in 0.1.0: truncating help through a pipe may panic with exit 101.
diff --git a/docs/help/limits.md b/docs/help/limits.md
index 121b4d2..f2ab991 100644
--- a/docs/help/limits.md
+++ b/docs/help/limits.md
@@ -2,7 +2,9 @@ LIMITS
Supported GPUs: Apple Silicon Metal and recent NVIDIA Vulkan with hardware ray
tracing and storage buffer arrays. AMD, Intel and CPU/software rendering are
unsupported. Run vork setup to check the adapter. Windows x64 ships install.ps1;
-macOS and Linux ship install.sh. See README.md (Install) for binary setup.
+macOS and Linux provide install.sh as a separate release asset.
+The 0.1.0 bundled Slang toolchain targets macOS 26; older macOS is unqualified.
+See README.md (Mac) for each companion binary's deployment target. See README.md (Install) for binary setup.
Participating media (fog, smoke and volumes) are absent from this release's API.
Legacy medium bindings are ignored with a warning; surface subsurface scattering