Documentation

How Fragsplainer Works

A guide for readers exploring these shaders, and authors looking to write their own.

For the Reader

A Fragsplainer is a three-panel machine designed to pull apart a complex shader and show you how it works from the inside out.

The Render Panel

On the left is the live output. It’s not a video; it’s code running on your GPU. You can interact with it directly by clicking and dragging, or by using the widgets in the text.

The Prose Panel

In the middle is the explanation. Look for highlighted terms and interactive sliders. Nudging a slider in the text updates the math in the renderer instantly.

The Code Panel

On the right is the source code. As you read the prose, the code panel scrolls to the relevant lines, and live uniform values update as you drag sliders. Hovering over functions or variables shows their definitions.

For the Author

Adding a new explainer to Fragsplainer means creating a single "Shader Package" folder. No custom wiring required.

src/content/shaders/[my-shader]/
  index.mdx        # Metadata & Prose
  image.glsl       # Main Fragment Shader
  common.glsl      # (Optional) Shared helpers
  bufferA.glsl     # (Optional) Multipass buffers

1. The Frontmatter

Define your uniforms and pass graph in the YAML header of your index.mdx. This creates the "shared brain" that connects your prose to your code.

2. Annotating GLSL

Use // @region [name] and // @end markers in your GLSL files. This allows your prose to target specific chunks of code for highlighting and scrolling.

3. Using Components

Import the components you need at the top of your MDX, then use them inline with the prose (a component alone on its own line is parsed as a block and splits the paragraph):

<Slider client:visible u="myUniform" /> — an inline slider bound to a uniform. Its live value also updates in the code panel.
<Toggle client:visible u="myBool" /> — a switch bound to a bool uniform.
<Lens client:visible sym="armSpin">arm</Lens> — highlights every matching token in the source on hover.
<Disclosure client:visible title="..." code="image#setup"> — a collapsible section that focuses a code region.
<Term client:visible id="uv">uv</Term> — a glossary term with a hover definition.
<Pass client:visible name="bufferA" subtitle="..." /> — a section header that switches the code panel's active tab.