---
title: "One Document, the Same Meaning Everywhere"
summary: "I wanted a portable standard for blogging and research papers, with a compiled result that stays lightweight to browse, and with the same meaning in static reading and interactive reading. This post looks at a simple compile workflow and at the first adoption on voidreg.xyz."
url: "https://www.voidreg.xyz/blog/introducing-publisle"
published: "2026-11-19T14:15:00.716713667Z"
updated: "2026-11-19T14:15:00.716723655Z"
category: "Document tooling"
tags: ["typescript", "documents", "markdown", "latex", "jats"]
---
# One Document, the Same Meaning Everywhere
## What I wanted to know

When I was developing my website for blogging, I wanted a standard schematic system for blogging with version control, and to be able to represent the full blog as pure MD with support for customized elements for interactivity. I also wanted a compiled result for lightweight browsing without much client overhead, and to be able to create a searchable database for content on the website.
I struggled to find a solution that solves all the points needed, so I said why not make my own solution to be focused around providing a standard for portability between frameworks and browser-based compilation, with an addon to compile an article as a research paper, with support for bibliography and standard research paper format templates out of the box.
The same document keeps its meaning when you read it as static HTML with no JavaScript, as print or PDF, as Markdown, or as text for an LLM, and when a framework host makes the interactive islands live. Authored fallbacks keep the same semantics when interactivity is not available.
This post looks at a simple compile workflow, and at the first adoption on voidreg.xyz. The [Publisle project page](https://www.voidreg.xyz/projects/publisle) covers the schema, compiler, adapters, and addon split in more detail.
## How the stack is split
The main decision is to keep a portable document model at the center, and compile out from that model instead of tying the article to one framework or one export format. That ensures portability without enforcing strict framework limits that can be expanded later easily.
As per the design decision for flexibility of design, most of the library infrastructure is built as addons over the core library package for decoupled development, with a prime example being `@publisle/cli-research`. The same document can pick up bibliography support, BibTeX and CSL, and export to LaTeX, PDF, and JATS, including standard research paper format templates. Core itself does not pull in TeX, citeproc, or those templates.
```mermaid
flowchart LR
subgraph core ["Core"]
direction TB
schema["@publisle/schema"]
corepkg["@publisle/core"]
markdown["@publisle/markdown"]
compiler["@publisle/adapter-core"]
schema --> corepkg
markdown --> corepkg
corepkg --> compiler
end
subgraph layer ["CLI, adapters, and addons"]
direction TB
cli["@publisle/cli"]
hosts["Svelte, React, Next.js,
Astro, and Vue adapters"]
addon["Addon: @publisle/cli-research"]
end
subgraph out ["Outputs"]
direction TB
html["Static HTML"]
journal["LaTeX, PDF, and JATS"]
end
compiler --> cli
compiler --> hosts
core --> addon
cli --> html
hosts --> html
addon --> journal
```
The Core packages sit in the middle, the CLI and framework adapters compile to static HTML, and `@publisle/cli-research` is an addon for research export.
Schema, markdown, and core feed adapter-core in the Core group. From there the CLI and the Svelte, React, Next.js, Astro, and Vue adapters compile to static HTML, and @publisle/cli-research, built over Core, exports LaTeX, PDF, and JATS.
## One document, step by step
A concrete workflow is the Core quickstart. You write the article in Markdown, publisle validation cli command, then build the article to produce static output and open HTML output index for preview.
Here is a short article.md.
````md article.md
---
title: A portable article
language: en
---
The transform in Equation :ref[eq\:signal] turns samples into a spectrum :cite[shannon1949].
:::equation{label="eq:signal"}
$$
X_k=\sum_{n=0}^{N-1} x_n e^{-2\pi i kn/N}
$$
:::
::::figure{src="/fft-spectrum.svg" variant-dark="/fft-spectrum-dark.svg" label="fig:spectrum" alt="Eight frequency bins with magnitude four at bins two and six"}
:::caption
A signal becomes two clear peaks.
:::
::::
::::diagram{engine="mermaid" label="diagram:flow" alt="Samples go through the DFT to a spectrum."}
```mermaid
flowchart LR A[Samples] --> B[DFT] --> C[Spectrum]
```
:::fallback
Samples go through the DFT to a spectrum.
:::
::::
::::interactive{type="publisle:interactive-schematic" schemaVersion="2" activation="interaction" label="Interactive clocked counter"}
:::title
Clocked counter
:::
:::description
Observe the output on each clock edge.
:::
:::instructions
Press Clock to advance the count and Reset to return it to zero.
:::
:::fallback
The counter starts at zero.
:::
```publisle-payload
{ "source": "./counter.json" }
```
::::
:::bibliography
```json
[{"id":"shannon1949","type":"article-journal","authors":["Shannon, Claude E."],"title":"Communication in the Presence of Noise","issued":"1949","containerTitle":"Proceedings of the IRE","volume":"37","issue":"1","page":"10--21","doi":"10.1109/JRPROC.1949.232969"}]
```
:::
````
```sh
publisle validate article.md
publisle build article.md --out dist/
```
I wanted the compiled result to stay lightweight for the reader. The measured comparison in [Put the work in the build. Keep the reader lean.](https://publisle.xyz/#performance) uses the same math-heavy document through popular publishing tools, with reader delivery measured separately, and static hosts and default documentation themes identified.
| Tool | Math compilation · median | Reader JS | Installed tools |
| :------------------------------------------------------ | :------------------------------------- | :-------- | :-------------- |
| Publisle
Minimal static HTML host, one article | 11.29 ms
HTML · warm process | 0 B | 10.8 MiB |
| MDX
Minimal static HTML host, one article | 46.35 ms
HTML · warm process | 0 B | 13.8 MiB |
| VitePress
Default documentation theme, one article | 60.22 ms
HTML · warm process | 56.8 KiB | 144.2 MiB |
| Docusaurus
Default documentation theme, one article | 42.94 ms
MDX module · warm process | 171.2 KiB | 163.3 MiB |
| Pandoc
Minimal static HTML host, one article | 24.66 ms
HTML · fresh process | 0 B | 157.8 MiB |
MDX and Pandoc can also publish static HTML without reader JavaScript. Docusaurus compilation here produces a module; its default site theme and VitePress include navigation and framework code. JavaScript compilers are warm; Pandoc includes process startup. Prose and large-document results are in the [full report](https://publisle.xyz/docs/guides/performance-comparison/).
## What happens to interactive elements
On the web, a host runtime can make the islands interactive, and the authored fallbacks are already in the page if that runtime is not there. Print and PDF exports do not execute interactive behavior. Diagrams and embeds contribute their accessible text, and schematic islands contribute their authored fallback prose, with that reduction reported in the export diagnostics.
A research paper export can use the same source without pretending the interactive parts still run on paper.
## voidreg.xyz, the first adoption
I built voidreg.xyz as the first adoption of Publisle, an attempt to stress test the architecture and prove its value in a production environment.
The compiled documents are hosted on the site, and I use [the knowledge map](https://www.voidreg.xyz/map) as a searchable view of that set. Each module is a category and each chip is a project, I can filter by name, technology, or category, and choosing a chip lights the projects it relates to, the technologies it shares, and the posts that follow it.
For a static database that agents can read, [llms.txt](https://www.voidreg.xyz/llms.txt) is the site index, [llms-full.txt](https://www.voidreg.xyz/llms-full.txt) is the full text of the published site, and each project has its own index at `/llms/.txt` and full text at `/llms/-full.txt`. Every published post and project also has a clean Markdown version if I add `.md` to its address, or if the page is requested as `text/markdown`. Published posts and projects can also be searched and read over the MCP server at , with no token required for that published read.
## Try it out
If you want to try Publisle, go to [publisle.xyz](https://publisle.xyz/). There is a [playground](https://publisle.xyz/playground/) to edit Markdown and preview a compiled article, and [docs](https://publisle.xyz/docs/) for the standard and the integration guides. To compile locally, install the Core CLI with `npm install -g @publisle/cli`.
## References
* [Publisle project page](https://www.voidreg.xyz/projects/publisle): The project write-up, with the schema and compiler split and the current status.
* [publisle/publisle](https://github.com/publisle/publisle): Source repository for the Publisle document standard and tooling.
* [Publisle website](https://publisle.xyz/): Project site and documentation home.
* [Documentation](https://publisle.xyz/docs/): Guides, standards, and integration docs.
* [Playground](https://publisle.xyz/playground/): In-browser Markdown editor, article preview, and an interactive FFT example.
* [Put the work in the build. Keep the reader lean.](https://publisle.xyz/#performance): Measured compile time, reader JavaScript, and installed tool sizes compared with MDX, VitePress, Docusaurus, and Pandoc.
* [Measured publishing performance](https://publisle.xyz/docs/guides/performance-comparison/): Methodology and the full report, including prose and large-document results.
* [Knowledge map](https://www.voidreg.xyz/map): Searchable map of published projects and posts, filterable by name, technology, or category.
* [llms.txt](https://www.voidreg.xyz/llms.txt): Static site index for agents, with links to Markdown versions of published posts and projects.
* [llms-full.txt](https://www.voidreg.xyz/llms-full.txt): Full text of the published site in one document.
* [Connect an agent](https://www.voidreg.xyz/agents): How to connect over MCP, and the Markdown and llms.txt endpoints.
---
---
title: "Introducing Rotex Through a Million Particles"
summary: "I used a Vulkan particle simulator to test Rotex, my Rust rendering hardware interface. One frame shows what the application controls, what the backend translates, and how a blend setting sent me back to the API design."
url: "https://www.voidreg.xyz/blog/introducing-rotex"
published: "2026-11-14T16:11:02.911073023Z"
updated: "2026-11-14T16:11:08.411824812Z"
category: "Graphics and engines"
tags: ["rust", "graphics", "rhi", "vulkan"]
---
# Introducing Rotex Through a Million Particles
## What I wanted to know

I wanted to know what Rotex would make me give up when I moved a Vulkan particle simulation into its command model. The frame above is that test: two gravity wells, a million particles, and the trails they leave. What follows is the command list that draws it, the type that submits the list, the barrier between the compute write and the draw, and how close the result came to the Vulkan program I started from.
## How the stack is split
Rotex is the rendering hardware interface I am writing in Rust, still pre-1.0. An RHI, in the way this post uses the term, means the application records an explicit list of commands and a backend translates that list into one graphics API. The short public description is on the [project page](https://www.voidreg.xyz/projects/rotex). The split below is the one the crates enforce.
The application owns the frame. In this particle sim that means the buffers, the trail texture, the order of the passes, the frame-ring index, and the choice to draw the live points on top of the tonemap. Scene contents and draw order stay in the application. Resource creation arrives as an explicit batch from the application.
`rotex-types` is the shared vocabulary, including `RhiCommand`, and it imports no GPU API. `rotex-core` \[1] is the adapter in front of one backend: the `GpuBackend` trait, and `GraphicsContext`, which owns that backend and forwards each call. The translators are `rotex-vulkan`, `rotex-wgpu`, `rotex-gl`, and `rotex-d3d12`. A translator may keep handle tables, a pipeline cache, and the submission objects a frame needs, such as command pools and fences. Draw policy stays in the application.
`rotex-graph` is optional. It reads the pass usage the application declares and splices destination-only `Barrier` commands around those passes. `nova_gravity` records its own barriers, including the one that makes the compute output readable as vertices. On Vulkan and D3D12 a barrier is a transition from the last state that backend recorded for the buffer or texture. On wgpu and GL the same command is accepted, and those APIs insert their own memory hazards.
A command the backend does not implement returns `Error::unsupported`. `capabilities()` reports what the running device can do, and that report stays runtime data. The type parameter in the next section is the compile-time half.
```mermaid
flowchart TB
app["Application: buffers, passes, frame index"]
types["rotex-types: the RhiCommand list"]
barriers["rotex-graph: optional barrier splice"]
ctx["GraphicsContext of one bridge"]
hal["Vulkan, wgpu, GL, or D3D12"]
app --> types --> barriers --> ctx --> hal
```
## One concrete backend type
`GraphicsContext` is generic over the concrete bridge, and it stores that bridge by value. Each method forwards to `B`, and the source marks them `#[inline]`. `render` passes the command slice to `backend.execute`. A call on `GraphicsContext` is static dispatch to `VulkanBridge::execute`. The concrete type is what establishes that. Inlining is the compiler's choice.
The examples pin `B` with a type alias. The default is `AppBackend = VulkanBridge` and `AppContext = GraphicsContext`. The `backend-wgpu` feature, and wasm, select `WgpuBridge`. `backend-d3d12` selects `D3d12Bridge`. Switching backends changes that alias and the crate dependency. `graphics_context.render(&commands)` stays written once, and rustc generates it for the bridge the alias names.
Recording stays separate from submission. `CommandEncoder` holds a `Vec` and a `PhantomData B>`. The type parameter is there so a later change can gate encoder methods with `Supports`, the compile-time marker that this backend implements an optional feature. Appending a command only pushes a value onto that `Vec`. `nova_gravity` records with `CommandEncoder::<()>`, `finish` returns the `Vec`, and `AppContext::render` submits it. `Device` is the same kind of wrapper for the device calls: `encoder` returns a `CommandEncoder`, and `submit` forwards that list to `execute`.
`Supports` sits beside `capabilities()`. The Rust type can be `VulkanBridge` while the device still lacks a limit the frame needs, and `capabilities()` is the report from that device.
```mermaid
flowchart LR
alias["AppContext = GraphicsContext of VulkanBridge"]
render["static dispatch"]
exec["VulkanBridge::execute"]
list["Vec of RhiCommand"]
alias --> render --> exec
list --> exec
```
## One frame, step by step
The opening figure is the `direct` path of [`nova_gravity`](https://github.com/rotex-labs/rotex-examples) \[2]. `frame_commands` records the list. Each frame appends `BeginFrame` and `AcquirePresentationTarget`, then the steps in the diagram.
The gravity wells are 32 bytes. The frame copies them from a staging buffer into the device buffer and records a barrier to shader read. The compute pass dispatches over the particle count and writes the other ping-pong buffer. The next barrier makes that buffer readable as vertex data.
The accumulation pass loads the trail texture, draws a fullscreen triangle that fades it, then draws the particles additively into the same texture. The present pass clears the window, tonemaps the trail into it, and draws the live particles on top. That last draw is the `direct` path. The other live mode, `float`, draws those particles into a half-float target and blits that target in their place.
```mermaid
flowchart TB
copy["Copy the 32-byte well set"]
wells["Barrier the well buffer to shader read"]
compute["Compute dispatch into the other particle buffer"]
verts["Barrier that buffer to vertex read"]
fade["Fullscreen fade of the trail"]
add["Additive point draw into the trail"]
tone["Tonemap the trail onto the window"]
live["Draw the live points on top"]
copy --> wells --> compute --> verts --> fade --> add --> tone --> live
```
### The barrier the example records
The frame writes one particle buffer in a compute pass and reads it as vertices in the same frame. Something has to publish that write before the draw. In `nova_gravity` that something is a barrier the example records itself. `rotex-graph` can emit a barrier of the same shape, and for this buffer the destination it emits today is a different state than the one the example asks for.
```mermaid
flowchart LR
compute[Compute write]
barrier[Barrier to VertexShaderRead]
draw[Point draw]
again[Next frame shader read]
compute --> barrier --> draw --> again
```
The compute pass writes `buffer_b` on even frames and `buffer_a` on odd frames. The draw uses whichever one was just written. After `end_compute_pass`, the example appends one command:
```rust
encoder.barrier(
BarrierResource::Buffer(written),
ResourceState::VertexShaderRead,
);
```
The command carries the destination only. The Vulkan backend turns that into a transition from the last state it saw for that buffer. `VertexShaderRead` is the state for a compute write that this frame draws and a later frame reads as a shader resource: the write becomes visible to vertex fetch without waiting for earlier vertex fetches. On this destination the Vulkan recorder does not use the tracked previous state as the source. It waits on the compute shader's write, so the next frame's compute can overlap the draw. wgpu and GL accept the same command and do nothing with it, because those APIs insert their own memory hazards. In the capability flags that is `Emulated` on wgpu and GL, and `Native` on Vulkan and D3D12.
There is a second barrier earlier in the frame, on the 32-byte well buffer, to `ShaderRead`, after the copy from staging. Same shape, different resource.
### What the graph would emit
`rotex-graph` does not create resources and does not read GPU objects. The caller declares each pass and the buffer intents, and `record` splices a destination-only `Barrier` where the desired state differs from the last one. The first declared use of a resource with no initial state emits no barrier.
A graphics pass that declares `AccessType::VertexShaderRead` on `written` is asking for a vertex read of the buffer just written. `record` maps both vertex accesses to the same destination:
```rust
AccessType::VertexRead | AccessType::VertexShaderRead => Some(ResourceState::VertexBuffer),
```
Given a previous state of `ShaderWrite`, the spliced command is a barrier to `VertexBuffer`, not to `VertexShaderRead`.
So the two recordings are the same kind of command and, for this buffer, not the same destination. `nova_gravity` keeps the hand-written `VertexShaderRead` barrier. I have not pointed this frame at `rotex-graph`. The graph is there for a caller who wants the splice, and the state it chooses for a vertex read is `VertexBuffer`.
The same rule is what makes the first use silent. If the well buffer has no initial state, the graph emits nothing the first time a pass declares a read. The example cannot rely on that, because the copy from staging is a real transition into `ShaderRead`, and the example records it.
Presentation acquire and present stay in the backend. The graph does not insert them.
## What portability means here
The particle comparison later in this post is one backend. I ran it on Vulkan, on this Linux machine, with `nova_gravity`. The command list is the same Rust either way. A second backend is a different type alias and a different crate, and I have not measured `cube` or `nova_gravity` on wgpu, D3D12, or GL for this series. The table below is the source, not a demonstrated run.
`cube` is the small proof that the call does not change. `AppBackend` is `VulkanBridge` by default, `WgpuBridge` with `backend-wgpu` or on wasm, and `D3d12Bridge` with `backend-d3d12`. `AppContext` is `GraphicsContext`. The example still calls `graphics_context.render(&commands)`.
```bash
cargo run --example cube --no-default-features --features backend-wgpu
```
That is the selection. It is not a result from this machine.
`capabilities()` is the runtime report: `CoreCaps`, limits, and the optional feature set, from the device that was opened. `StaticCaps` is the compile-time const on the bridge type. A command the backend does not implement returns `Error::unsupported`.
`rotex-emulation` is an optional rewrite the application runs before `execute`. It does not allocate a GPU resource, and the backends do not depend on it. Absent push constants become a `WriteBuffer` into a uniform buffer the caller supplies. Repeated viewport, scissor, pipeline, and buffer binds are dropped. A texture pass can be retargeted when render-to-texture is absent and a fallback target was given. A missing stand-in returns unsupported.
`rotex-conformance` lives outside `rotex-core`. A backend calls `run` from its own tests, on a device it has already created. The checks read `CoreCaps` and submit commands. Where push constants are `Absent`, accepting a `PushConstants` command is a failure. Where compute is `Absent`, accepting a `Dispatch` is a failure. Barriers are checked at the support level the caps report.
These are the `CoreCaps` consts in the backend crates. wgpu's runtime report can promote push constants to `Native` when the device exposes immediates and a non-zero immediate size. The const itself says `Absent`. D3D12's Windows const is the native column. The const compiled on this Linux machine sets every one of these to `Absent`, because there is no D3D12 device here. GL has no compute and no push constants in its const. I have not run the conformance tests as part of this write-up.
| | Vulkan | wgpu const | GL | D3D12, Windows source |
| ----------------- | ------ | ---------- | -------- | --------------------- |
| Compute | Native | Native | Absent | Native |
| Storage buffers | Native | Native | Absent | Native |
| Push constants | Native | Absent | Absent | Native |
| Barriers | Native | Emulated | Emulated | Native |
| Render to texture | Native | Native | Native | Native |
| Readback | Native | Native | Native | Native |
`Emulated` on barriers means the backend accepts the command and the API inserts its own hazards. It does not mean `rotex-emulation` rewrote the list. That rewrite is a separate step, and only if the application runs it.
Portability, as I can stand behind it today, is the command list and the type alias. The fps numbers below are Vulkan on one laptop. A feature marked Native in the table is what the crate's const says, until I have a run to put next to it.
## What the experiment found
Nova \[3] is [xevrion's](https://github.com/xevrion/nova) C++20 Vulkan simulator. I built it with the UI stubbed out and the audio silent, so the window is the particles and nothing else.
The machine is one RTX 4060 Laptop, driver 580.159.04, Fedora on Wayland. The window is 1280×720 with mailbox presentation. Each run discards 10 seconds of warm-up, then measures 60 seconds at 1M particles and 30 seconds at the other counts. Configurations are interleaved. The workload is GPU-bound. The intervals below are Welch \[4] 95% intervals on the run-to-run spread inside that session. They say nothing about another machine or another day.
### The first run was not that close
The headline further down is the re-run: at one million particles, Rotex `direct` averaged 562.6 fps against Nova's 564.9. The first complete run was not that close. Rotex `direct` was 1.6% behind at 1M particles and 3.9% behind at 4M. Two differences caused it. Both are fixed, and the numbers in the re-run are the ones I quote. The old set is archived and is not mixed into those tables.
### The fade was reading destination alpha
The fade pass blends into an RGBA16F trail texture. Nova writes the source alpha with factors one and zero, so the blend never reads the destination alpha. Rotex's `BlendMode::Alpha` uses one and one-minus-source-alpha for the alpha channel. Nothing later reads that alpha. The blend still had to read it and combine it.
I found it with a Vulkan layer, `pipestats` \[5], that asks the driver for `VK_KHR_pipeline_executable_properties` \[6] on every pipeline and logs the blend state the application actually set. The driver-compiled code matched. The fade pipeline differed in one place: the alpha destination factor, zero in Nova and one-minus-source-alpha in Rotex.
An earlier RenderDoc \[7] pass had called the blend state identical. It compared the color factors and missed the alpha factors. That claim was wrong.
Changing only that factor, in three interleaved runs of 16 seconds at 1M particles, moved Rotex from −2.43% to −0.40% against Nova. I added `BlendMode::AlphaColorOnly` to `rotex-types`: color blends with the source alpha, and the alpha channel takes the source alpha, with factors one and zero, so the destination alpha is never read. The Vulkan, wgpu, and D3D12 backends translate it. The D3D12 check on this Linux machine is syntax only. The `nova_gravity` fade pass uses the new mode.
Nsight Graphics 2026.4 \[8], one GPU trace of three frames per app, taken before either fix, showed the same shape. Rotex `direct` had 12% more color-ROP throughput (15.7% of peak against 17.6%), 8% more L2 traffic from the raster unit, and 16% more DRAM read throughput, about 2 MB more per frame. Those three fit an extra destination read on a float target. The trace also showed 17% more registers allocated to 3D shaders, which contradicts the driver statistics, where the register counts per shader were identical. I did not resolve that, and I have not re-traced after the fixes. The Nsight numbers stay pre-fix.
### The point shader was wider than Nova's
After the blend fix, 4M particles was still 1.2% to 1.3% behind. Compute time matched. The remaining render time scaled with the particle count, so it was per particle.
The Rotex point vertex shader passed a `float4` color to the fragment shader. Nova passes a `vec3`. Rotex hashed the particle position. Nova hashes the vertex index. The shader now uses Nova's interface: a `float3` varying, and a brightness hash of the raw vertex index. I changed the varying width and the hash together. I did not separate their effects.
At 4M particles, three interleaved runs of 20 seconds:
| | fps | Render ms |
| ------------------------------- | ------------- | --------- |
| Nova | 162.1 | 5.209 |
| Rotex, blend fix only | 160.0 (−1.3%) | 5.278 |
| Rotex, blend fix and shader fix | 162.7 (+0.4%) | 5.188 |
### What I checked and set aside
Each row is one change, or one inspection, run interleaved against Nova and unmodified Rotex `direct` before either fix: three runs of 30 seconds at 1M, except the Vulkan-version row, which was 15 seconds. The fade blend, which none of these rows touched, dominated the gap. The timed rows showed no change. The queue row is a comparison of what `vkCreateDevice` requested, not a timed run.
| What I suspected | What I did | What happened |
| -------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Slang versus glslang | Nova's own SPIR-V for the point shaders, inside Rotex's pipeline | 552.2 against 551.4 fps, same per-draw GPU times |
| The driver compiled different code | RenderDoc replay with pipeline executable properties | Same sizes: compute 5,888 B, point vertex 1,280 B, point fragment 640 B, composite fragment 1,152 B. Fullscreen vertex 768 B in Nova, 640 B in Rotex |
| A different command stream | One captured frame from each app | Same passes, draws, and vertex counts |
| The draw itself cost more | Four replay timings per app | The accumulation draw varied from 593 to 676 µs inside one app, more than the gap between the apps |
| The well-copy barrier waited on the previous frame | Source stage set to transfer, confirmed in a capture | No change |
| The swapchain pass exit dependency | Removed | No change |
| `TRANSFER_SRC` on the images | Matched Nova | No change |
| Different initial particles | Nova's mt19937 seed | No change |
| Depth and stencil state, and an uncleared trail | Removed the state, cleared on the first frame | No change |
| Device features and queues | Compared `vkCreateDevice` | Same features. Rotex creates one extra queue and does not submit to it |
| Vulkan 1.2 versus 1.0 | Rotex built to request 1.2 | 537.3 against 537.6 fps |
| The window system | Both apps forced onto X11 | Both capped at 165 fps, the display refresh, so the test cannot measure GPU speed |
### The re-run
At one million particles the direct path averaged 562.6 fps against Nova's 564.9.
| Configuration | Mean fps at 1M particles |
| -------------- | ------------------------ |
| Nova | 564.9 |
| Rotex `direct` | 562.6 (0.4% gap) |
GPU time, read from the timestamps rather than from the frame rate, was 1.326 ms per frame for Nova and 1.334 ms for Rotex direct. Both programs are GPU-bound at the same frame rate.
The 0.125 ms CPU figure is a separate measurement, taken before either fix. It is the CPU work of the entire frame, including command recording: 0.125 ms per frame for Rotex direct, 6.9% of one core. Nova's CPU time in that probe was 1.92 ms, more than one core, and I have not explained it. That pair measures the two programs as built. It is not a claim that Rotex is more CPU-efficient than raw Vulkan.
At 1M, five runs, the Welch intervals are narrow because the runs repeat. They are the spread inside one session.
| | Difference | 95% interval |
| -------------------------------- | ---------- | --------------- |
| Rotex direct, mean fps | −0.4% | \[−0.4%, −0.4%] |
| Rotex direct, GPU time | +0.6% | \[+0.5%, +0.6%] |
| Rotex direct, p99 frame time | −1.6% | \[−2.6%, −0.6%] |
| Rotex direct, GPU timestamps off | −0.1% | \[−0.1%, −0.0%] |
Rotex's optional timestamps cost about 0.3% of the frame rate, 562.6 against 564.4. The headline keeps them on, because Nova's timestamps cannot be turned off. p99 is lower for Rotex in these runs. The spikes are the same shape in every configuration: mailbox present returning early.

Each point is the runs at that particle count, drawn against Nova's mean, and the bars are the sample standard deviation. There are five runs at 1M and three at the other counts. At 1M the direct path is 0.4% behind and the float path is 1.2% ahead, and the runs barely spread. At 0.5M, with the slow Nova run included, Rotex direct was 2.0% ahead, and the run-to-run variation was substantial. Nova's own runs at that count spread by about 4%. Excluding that slow run puts Rotex about 0.2% behind. The float path pulls further ahead as the count grows: 3.2% at 2M and 7.0% at 4M.
## The float path does different work
The float path's lead is a different frame, not a faster copy of Nova's. `direct` draws the live points in the same pass as the tonemap, on top of the window. `float` draws those points into a half-float target, then a fullscreen pass adds that target. The live points blend in a different space, and the window pass no longer pays for a million point fragments.


The stills are the same kind of frame. I would not ask anyone to see the blend change in them. The difference shows up in the GPU spans, which each app timestamps about once a second. Only the totals are comparable across the two programs, because Nova reports one render span and Rotex reports a span per draw.
At 1M particles, milliseconds per frame:
| | Nova | Rotex direct | Rotex float |
| -------------------------------- | ----- | ------------ | ----------- |
| Compute, including the well copy | 0.055 | 0.056 | 0.083 |
| Render | 1.271 | 1.278 | 1.223 |
| Total | 1.326 | 1.334 | 1.306 |
Rotex direct, per span: fade 0.049, accumulation points 0.580, composite 0.014, live points 0.632. The live overlay is the expensive draw, a bit more than the trail points.
Rotex float, per span: fade 0.051, accumulation points 0.580, live points into the float target 0.571, composite 0.014, fullscreen add 0.006. The accumulation points cost the same 0.580 ms. The fullscreen add is almost free. The float path's compute span reads 0.03 ms higher than direct's. That span is bounded by the profiler stamps, and I did not find out why it differs. The totals are what I compare.
The simulation is not stationary. Particles gather into the wells, and the draw cost grows. Both apps step in real time, so at a given wall-clock second they hold similar states, and every run measures the same window: 10 seconds in, through 70 seconds at 1M and through 40 seconds at the other counts.
At 4M particles the float path's GPU time is 5.247 ms against Nova's 5.636 ms, −6.9%, and the frame rate is +7.0%. At 4M the float path pushes about 703 million particle-updates-and-draws per second, against Nova's 657 million. I would quote that only with the setup attached: one RTX 4060 Laptop, Linux and Wayland, driver 580, and a frame that does more than Nova's.
## What the programs weigh
The release binary that draws this frame is 2.60 MiB, and the file was already stripped. Its `.text` section is 1.97 MiB. Nova's executable, stripped the same way for the comparison, is 0.81 MiB, with 670 KiB of `.text`. The unstripped Nova file is 970,936 bytes. The executable is only part of what the process maps. `ldd` on the Rotex binary lists libc, libm, and libgcc. Nova additionally maps libstdc++ at 2.52 MiB, the Vulkan loader at 0.54 MiB, and GLFW at 0.35 MiB. Those files come to 4.21 MiB for Nova, against 2.60 MiB for the Rotex binary. The bars are the size of each file on disk.

The shaders in this frame were compiled twice, once with slangc \[9] and once with glslang \[10], and then the driver compiled both results. slangc's SPIR-V for the seven modules is 11,756 bytes. glslang's SPIR-V for the same stages is 15,232 bytes. Nova uses one fullscreen vertex shader for the fade pass and the present pass, so that 1,228 byte module appears on both rows. The fade fragment is the stage where Rotex's SPIR-V is the larger one: 696 bytes against 628.

The driver reported the same executable size for the compute shader, the point vertex shader, the point fragment shader, and the composite fragment: 5,888, 1,280, 640, and 1,152 bytes. The fullscreen vertex shader is 640 bytes in Rotex and 768 in Nova. This is one RenderDoc replay using `VK_KHR_pipeline_executable_properties`, taken while checking the benchmark, so it is a single observation.

tokei \[11] counts 30,007 lines of Rust in the umbrella tree. Comments and blank lines are excluded, and so is `target`. `rotex-vulkan` is the largest crate, at 7,682 lines. The shader group is the cooker, the core, the graph, and the slang frontend, 2,360 lines together. Math is `rotex-color` and `rotex-math`. Window is `rotex-window` and `rotex-winit`. The example crate is 5,165 lines, and 715 of them are `nova_gravity.rs` and `nova_gravity_shared.rs`. Nova's own `src`, with the vendored imgui left out, is 1,729 lines of C++.

The line counts are from 14 Nov 2026, `rotex-dev` at `69534e0` and Nova at `a652a4e`. The Rotex executable is the release file built on 13 Nov. Nova's is the stubbed build from that day.
## What it changed in the API
Matching the trail fade changed the blend vocabulary. `BlendMode::Alpha` blends the alpha channel as well as the color. `BlendMode::AlphaColorOnly` is the mode the fade pass uses now: the color blends with the source alpha, and the alpha channel takes the source alpha. The measurement behind that mode is the fade section above.
## Where to go next
* [Rotex](https://www.voidreg.xyz/projects/rotex) on this site
* [`rotex-examples`](https://github.com/rotex-labs/rotex-examples), including `nova_gravity`
* [`rotex-core`](https://github.com/rotex-labs/rotex-core), the `GraphicsContext` adapter
* [xevrion/nova](https://github.com/xevrion/nova), the simulator this frame is measured against
## Questions left to answer later
These are the measurements I have not made, and the results I have not explained. The numbers above stand without them.
* Nova's CPU time in that probe was 1.92 ms, more than one core. I have not explained it.
* The Nsight trace is from before either fix. The 17% increase in registers allocated to 3D shaders contradicts the identical per-shader register counts, and I have not re-traced after the fixes.
* I changed the point shader's varying width and its hash together. I have not measured those two edits separately.
* On the float path the compute span, including the well copy, reads 0.083 ms against 0.056 ms on the direct path. That span is bounded by the profiler stamps, and I have not found out why it differs.
* I have not measured `GraphicsContext` against a trait object. The 0.125 ms of CPU per frame is a separate pre-fix measurement of the whole frame's CPU work, including command recording.
* This series ran on Vulkan, on this machine. I have not measured `cube` or `nova_gravity` on wgpu, D3D12, or GL. The D3D12 translation of `BlendMode::AlphaColorOnly` was a syntax check. I have not run the conformance tests for this write-up.
* I have not pointed this frame at `rotex-graph`. The graph would barrier the particle buffer to `VertexBuffer`. The example barriers it to `VertexShaderRead`. I have not measured that difference.
* Rotex creates one extra queue at `vkCreateDevice` and does not submit to it. I have not measured a device that skips that queue.
* The Welch intervals are the spread inside one session on one laptop. They say nothing about another machine or another day.
* The line counts are the tree on 14 Nov, at `69534e0`. The Rotex executable is the release file built on 13 Nov. I have not remeasured that file at the counted commit.
## References
1\. rotex-labs. rotex-core. https\://github.com/rotex-labs/rotex-core
2\. rotex-labs. rotex-examples. https\://github.com/rotex-labs/rotex-examples
3\. xevrion. Nova. https\://github.com/xevrion/nova
4\. Welch, B. L. (1947). The generalization of "Student's" problem when several different population variances are involved. Biometrika. vol. 34, no. 1-2, pp. 28-35. https\://doi.org/10.1093/biomet/34.1-2.28
5\. rotex-labs. pipestats, a Vulkan layer at benchmarks/nova/scripts/pipestats in rotex-examples. https\://github.com/rotex-labs/rotex-examples
6\. The Khronos Group. VK_KHR_pipeline_executable_properties. https\://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_pipeline_executable_properties.html
7\. Baldur Karlsson. RenderDoc. https\://renderdoc.org/
8\. NVIDIA. NVIDIA Nsight Graphics. https\://developer.nvidia.com/nsight-graphics
9\. shader-slang. Slang. https\://github.com/shader-slang/slang
10\. The Khronos Group. glslang. https\://github.com/KhronosGroup/glslang
11\. XAMPPRocky. tokei. https\://github.com/XAMPPRocky/tokei