v0.1.0

The first release of Holofoil: a trading card's holographic foil as an FFGL effect for Resolume Arena and Avenue, SW Holofoil (HF01). The clip is the print, the foil is under it, and the card tips under a lamp.

The one idea. Holographic foil is aluminium embossed with ridges about a micron apart, which makes it a diffraction grating, and a grating sends each wavelength off at its own angle. So the colour at each pixel isn't a drawn gradient: it follows from where the lamp is, where your eye is and which way the ridges run. The grating equation gives the wavelength, order by order, and the CIE 1931 colour matching functions turn the light into RGB. How deep the ridges are decides how much light goes into the colours rather than the silver mirror (the thin-grating J₀² law), and a bigger lamp or a rougher foil smears the colours together, as it does in your hand.

The finishes. Foil Area puts the foil in the Art Window (the holo), Around Art (the reverse holo), over the Whole Card, under Bright Ink or Dark Ink (keyed on the print's luminance in linear light, the way cold-foil and etched cards are printed), or where the clip is opaque (Clip Alpha). Pattern is what's pressed into it: Rainbow (one plain grating), Crosshatch, Cosmos (discs), Cracked Ice (shards) and Sparkle (glitter). In the cell patterns every cell is its own small grating with its own direction and pitch, so the cells catch the lamp one by one. Motion tips, swings or circles the card, or holds it still and takes the lamp round it, free or locked to Resolume's beats or bars.

Controls: Finish (Foil Area, Pattern); Card (Tilt X, Tilt Y, Motion, Motion Depth, Motion Rate, Motion Sync, Viewer Distance); Lamp (Lamp X, Lamp Y, Lamp Distance, Lamp Size, Lamp Length, Lamp Brightness); Foil (Pitch, Grating Angle, Groove Depth, Pattern Scale, Facet Tilt, Roughness); Print (Ink, Base); Area (Window X, Window Y, Window Width, Window Height, Corner, Softness, Threshold); Output (Mix). The defaults are a holo: a plain rainbow grating in the art window, the card tipping 12° each way every 5 seconds under a strip light.

Downloads: a universal macOS build (Apple silicon and Intel) as a .dmg or .zip, and a Windows x64 installer (-setup.exe) or .zip. Every archive carries ATTRIBUTIONS.md. The macOS build is Developer ID-signed and notarised minutes after publication; if macOS refuses a download, it's from before that, so download it again. The Windows build isn't signed, so SmartScreen warns once. The installer is per user and needs no administrator password: it puts Holofoil.dll in Documents\Resolume Arena\Extra Effects (Avenue's, if only Avenue is there) and its README, notices and uninstaller in a Holofoil folder beside it. Quit Resolume first.

What is measured (offline, by tools/verify.sh on an Apple Silicon Mac under macOS 26, driving the plugin's own class in a headless GL context, at 630×882 and 320×180 and again on Apple's software renderer). The harness's reference never shares the plugin's shortcuts: it sums the light wavelength by wavelength, in double, in a card frame built from rotation matrices, without the plugin's colour table.

• The optics. Each pixel's light against that per-wavelength sum is worst 1.8e-3 of the brightest, over five scenes (bound 1e-2); its dominant wavelength against d·|s·g|/m is worst 0.83 of its bound. With no groove the highlight sits at the mirror point to 0.001 px. The mirror's colour matches J₀² to 5.7e-6. Roughness matches a wider, dimmer lamp to 3.0e-7.
• The print and the area. The holo plus the reverse holo, and Bright Ink plus Dark Ink, sum to the clip plus the whole card's foil, to 3.7e-7. Window coverage matches an exact per-pixel integral to 1.5e-5. Mix 0 and every pixel outside the area give back the clip bit for bit, and alpha never moves.
• The checks can fail. Seventeen deliberately wrong models each fail their check, and 29 one-character mutants of the shipped GLSL and C++ are all caught. All 31 controls change the picture. The bundle is universal, and oxbow reads SW Holofoil / HF01 / effect and renders 120 frames through it.

On Windows it has been in Resolume. The fleet's Arena gate ran this release workflow's own Windows build in Arena 7.27.1 on win-lab (software rendering, no GPU), twice: the DLL loads, registers as HF01 (an effect) and appears in Arena's list, all 37 parameters (Arena's Opacity and the plugin's 36) match their names, order, types, ranges and defaults, it renders, and Arena's log stays clean: 9 passed, 0 failed, 1 skipped. Against a still, all 28 of the controls that can act on one changed the picture. Motion Depth, Motion Rate and Motion Sync only set how the card moves over time, which a still can't show; hftest --motion and --clock check them offline. The installer was tried there too: it installs into Extra Effects, Arena lists the effect from that copy, and the uninstaller takes everything away again.

What isn't verified, or is a limit. It's never been loaded into Resolume on macOS, and nobody has held it up beside a real foil card: the measurements show the plugin does what the optics say, not that the optics are the right ones for a given card. Pitches and groove depths are typical values for embossed holograms, not measured from any card. Patterns are point-sampled, so a crosshatch at its natural scale aliases below 720p; raise Pattern Scale there. The light is one lamp with no room round it, so a mostly-mirror foil shows nothing away from the lamp's reflection. Nobody has watched Motion Sync follow Arena's transport, run it on a GPU other than one Mac's, or measured the frame rate at 4K inside Resolume.

Cost, GPU time on an Apple Silicon Mac: at the defaults 0.21 ms a frame at 1080p and 0.52 ms at 4K; Cosmos over the whole card, the dearest pattern, 0.28 and 1.13 ms. Automating Groove Depth rebuilds the colour table every frame and adds about half a millisecond. Nothing was timed inside Resolume.

Not done. No presets, no browser demo and no OpenFX port.

• User guide: https://stoatworks-labs.com/software/holofoil/guide/
• Project page: https://stoatworks-labs.com/software/holofoil/