Wipe user guide

Wipe is a 1970s vision mixer’s pattern generator, as an FFGL mixer for Resolume Arena and Avenue and as an OpenFX transition for DaVinci Resolve, Vegas, Nuke and Natron (see OpenFX). In Resolume it wipes this layer in over the layer below, and as a transition it wipes the next clip in over the last.

Either way, it makes every wipe the way the hardware did. There’s no stored picture of a shape, just a few waveforms (a horizontal ramp, a vertical ramp and their parabolas) compared against the fader. Soft edges, borders, the wobble of the modulator and the way a circle’s edge is softer near its middle all come from what that comparator does.

The repo’s two test cards through the plugin: a Circle at Opacity 0.42 with a soft edge, a gold border and the modulator on. Rendered by the offline harness rather than captured from Resolume.

Before you rely on this: released at v0.2.0, which adds the OpenFX build (a transition for DaVinci Resolve, Vegas, Nuke and Natron), and still early days. The pattern generator is measured, not just asserted. An offline harness drives the plugin itself with two inputs at two different sizes. A hard edge lands on its column with 0 pixels wrong. A soft edge’s position integrates to 0.0000 px of where the fader puts it. In Area law every pattern’s revealed area is within 0.33 px of the fader. A circle’s soft edge widens towards its centre exactly as the parabola predicts (41.855 px measured, 41.855 predicted). The modulator’s sine comes back at 16.0000 px of 16. All 21 controls the harness can sweep change the picture. It has never been loaded into Resolume on macOS. On Windows, a build of v0.1.0 loads in Resolume Arena 7.27.1, is offered as a layer’s Blend Mode, is driven by the layer’s opacity fader and hides only Aspect Comp, as designed. That was on software rendering, and nobody has captured a picture of it inside Resolume, so it hasn’t been shown to render correctly there yet. The rest of what it assumes about how Resolume treats a mixer was measured on Genlock, the fleet’s first mixer. Try it on a spare layer first, and please tell me about anything that misbehaves.

This codebase was created with AI assistance, directed and reviewed by a human author.

Installing

Download the build for your platform. For macOS there’s a universal .dmg or .zip (Apple silicon and Intel), Developer ID-signed and notarised so the bundle just loads, and for Windows an x64 installer or .zip. Each of these has one mixer in it, SW Wipe (the wipe-ofx- zips are the OpenFX build; see OpenFX). Put it in Resolume’s FFGL folder, then restart Resolume:

macOS    ~/Documents/Resolume Arena/Extra Effects/
Windows  %USERPROFILE%\Documents\Resolume Arena\Extra Effects\

Avenue uses the same layout in its own folder. Yes, it’s Extra Effects, even though this is a mixer: Resolume has one FFGL plugin folder, and sources, effects and mixers all load from it. There’s no Extra Mixers.

A mixer doesn’t appear in the effects browser. In Resolume it appears in a layer’s Blend Mode list, beside Resolume’s own blend modes (the same list Resolume uses for transitions). Choose SW Wipe as the blend mode of the upper layer.

The Windows builds aren’t code-signed. Plugin files aren’t gated the way .exe files are, so Resolume loads them as normal; only the installer trips SmartScreen, once: More info → Run anyway.

It is a mixer, not an effect

An effect gets one picture. A mixer gets two, and Wipe needs both:

To patch it, put one clip on a layer and the clip you want to wipe in on the layer above it. Then set the upper layer’s Blend Mode to SW Wipe. Give it only one picture and the plugin won’t draw anything.

The two layers don’t have to be the same size. Each input is read at its own resolution, and every distance below is in pixels of the output picture.

Start here

The layer’s opacity fader is the wipe. Wipe’s fader is a parameter called Opacity, and Resolume drives a mixer parameter of that name from the layer’s own opacity fader. So once SW Wipe is the upper layer’s blend mode, pull that layer’s opacity down and the layer below is wiped in; push it up and this layer is wiped back in. At 0 you see only the layer below, at 1 only this layer, and in between the wipe.

The defaults are a plain hard Horizontal wipe: at half way this layer fills the left half and the layer below the right half, and as the fader rises the edge travels to the right. Then, in this order:

1. Pattern. Try Box and Circle, which open from the centre, and Clock, which sweeps round from twelve.
2. Softness. Give the edge 16 pixels or so. On a Circle, notice the edge is softer when the circle is small than when it’s large. That’s not a bug.
3. Border Width, and the border colour. A second edge in a solid colour.
4. Mod Amount. The edge starts to wobble, and the wobble travels.

Pattern

Aspect Comp: whether the generator corrects for the picture’s shape. On, the default, a Circle is round and a Box is square on screen. Off, the pattern is drawn in the unit square and stretched to the picture, so on a 16:9 composition a circle is an ellipse and a box is a rectangle, which is what an uncompensated generator actually drew.

In Resolume this control is missing, on purpose. Resolume Arena doesn’t show a mixer’s first parameter at all (measured on Genlock, whose first control vanished from the panel). So Wipe puts Aspect Comp first, because its default is the right setting if it can never be changed: in Resolume, circles are always round and the ellipse can’t be reached. In Arena 7.27.1 on Windows, Wipe’s panel shows every control except Aspect Comp, so this works as intended.

Pattern: the shape of the wipe. The default is Horizontal.

Whatever the pattern, the fader’s range covers the picture: at 1 the last corner has been reached, and at 0 nothing has started.

Reverse: runs the pattern the other way. It mirrors the waveform rather than swapping the two pictures, so a reversed Box closes: B comes in from the edges and a shrinking rectangle of A is left in the middle. A reversed Horizontal comes in from the right, a reversed Vertical from the top, and a reversed Clock sweeps anticlockwise from twelve.

Flip-Flop: reverses the pattern on alternate transitions. A transition is the fader arriving at one end from the other. With Flip-Flop on, the direction flips each time one completes, so on the way back the wipe doesn’t run backwards: each new picture arrives the same way as the last. Whether that’s “from the centre” or “from the edges” depends on which end the fader was resting at first. If it’s the wrong one, toggle Reverse. The first arrival at an end after the plugin is created doesn’t count, and turning Flip-Flop off clears it.

Fader

Opacity: the fader. 0 is all A, the layer below; 1 is all B, this layer. The default is 0.5, but in Resolume this is driven by the layer’s opacity fader, and the Opacity slider in the mixer’s own panel is overridden: moving it or automating it does nothing. Use the layer’s fader. (Measured on Genlock and on Wipe in Arena 7.27.1 on Windows. Whether a layer transition or the autopilot also moves it hasn’t been tried.)

At exactly 0 and exactly 1 the output is the untouched picture, bit for bit: no soft edge, border or wobble can leak into an end stop.

Law: how the fader’s position becomes the size of the wipe.

• Edge, the default, is what the hardware did: the comparator’s level moves in a straight line with the fader. On a Horizontal wipe that’s the same as the revealed area, but on the shapes that grow from the centre it isn’t: at half way an edge-law Box has revealed about 44% of a 16:9 picture.
• Area chooses the level so the area of B on screen is exactly the fader, for every pattern, soft edge included. At half way, half the picture is B, whatever the shape. The level is solved on the CPU each time something changes; see Performance.

Edge

All four sizes here are output pixels, measured on the Horizontal wipe, from 0 to 64. On a Horizontal wipe 16 pixels is 16 pixels. Every other pattern converts the same number through its own waveform, and then its edge follows the waveform’s slope. So a Box’s sides match the Horizontal wipe, but a Circle’s edge is softer when the circle is small and sharper when it is large, because the parabola is flatter near its centre. The harness measures that: at Softness 16 the circle’s edge is 41.9 pixels wide at a radius of 82 and 14.3 at a radius of 233.

Because the unit is a pixel, the same setting is half the share of the picture on a 4K composition that it is at 1080p.

Softness: the width of the soft edge between A and B, from 0 to 64 pixels. The default is 0, a hard cut. The edge is a straight ramp, so its 10–90% width is 0.8 of the setting.

Border Width: a band of solid colour at the edge, from 0 to 64 pixels. The default is 0, which is no border at all. It sits on the A side of the edge, the side the wipe is heading into.

Border Softness: the softness of the border’s outer edge, from 0 to 64 pixels. The default is 0. It only does anything once Border Width is above 0.

Border colour: the colour of the border. The host sees it as three parameters, Border Red, Border Green and Border Blue, and can show them as one swatch. The default is white. The border is painted opaque, whatever the alpha of the two pictures.

On the Matrix pattern there is no edge to measure, so Softness and the border act on the order the cells switch in: a soft matrix fades each cell over a short stretch of the fader instead of switching it, and a border paints the next few cells due to switch in the border colour.

Positioner

Centre X and Centre Y: where the pattern is centred, from 0 to 1 across and up the picture. The default is the middle. 0, 0 is the bottom-left corner. It moves Box, Diamond, Circle and Clock. The Horizontal and Vertical wipes and the Matrix ignore it, as the hardware’s did: on a plain ramp a positioner only slides an edge the fader already slides.

Rotation: turns the pattern clockwise, from 0 to 360 degrees. The default is 0. It turns every pattern except the Matrix, so a rotated Horizontal wipe is an angled wipe.

Aspect: the pattern’s own width against its height, from 0.25 to 4 on a geometric scale. The middle of the slider (the default) is 1. Towards the top the pattern gets narrower, so a Box becomes a tall rectangle; towards the bottom it gets wider. It doesn’t affect the Matrix, and on a Horizontal or Vertical wipe it only changes anything once the wipe is rotated.

Modulation

The modulator adds a sine wave to the waveform, which makes the edge wobble. The wobble runs down the picture on every pattern except Vertical, where it runs across.

Mod Amount: how far the wobble pushes the edge, from 0 to 64 pixels, measured the same way as Softness. The default is 0, which is off.

Mod Frequency: how many waves fit in the picture, from 0.5 to 32 on a geometric scale. The default is about 2.6.

Mod Speed: how fast the wobble travels along the edge, from 0 to 4 cycles a second. The default is a quarter of the way along, 1 cycle a second. At 0 it stands still. It runs on Resolume’s clock, which Arena sends to a mixer every frame (measured on Genlock).

Multiple H and Multiple V: run the waveforms 1 to 8 times over, so the pattern repeats in cells. The default is 1 of each. Multiple V counts copies up the picture. Multiple H counts copies across one picture height’s worth of width whenever Aspect Comp is on (the default, and the only setting Resolume can reach), because the horizontal ramp is scaled for the picture’s shape before it wraps: that keeps the cells square, so on a 16:9 picture Multiple H of 4 gives about seven copies across. With Aspect Comp off it’s exactly N across, and a circle’s cells are stretched with the picture. A Horizontal wipe uses Multiple H only and a Vertical wipe Multiple V only; a Box, Diamond or Circle is repeated in a grid, each copy opening in its own cell; a Clock with Multiple H of N sweeps N sectors at once; the Matrix multiplies its 32 × 18 grid by both.

How it works: a waveform and a comparator

A vision mixer of the 1970s didn’t store its wipes. It ran a few analogue waveform generators at line and field rate: a horizontal ramp, a vertical ramp, and the two parabolas. It combined them in a small matrix, adding them or taking the larger, and compared the result against the level set by the fader. Where the waveform was below the level you saw B; above it, A.

Wipe does the same for every pixel, and everything else follows from that:

• Softness is the comparator’s gain. A low-gain comparator doesn’t switch cleanly, and the width of its soft edge on screen depends on how steep the waveform is there. That’s why a circle’s edge is softer near its middle.
• The border is a second comparator, set a little above the first. The border is where the two disagree, so its width follows the waveform’s slope too.
• The modulator is a sine added to the waveform, which is how the wobble control on a real generator worked.
• A circle is an ellipse unless the generator compensates for the picture’s aspect. Real ones had to, and Aspect Comp is that correction.

The fader’s two ends are special-cased: at 0 and 1 the plugin fetches one picture and does nothing else.

Performance

It’s one pass with two texture reads. The worst figures from the offline harness on an Apple M4 Max, on the Matrix pattern with softness, a border and the modulator all on (the most work per pixel), were:

At this size the measurement itself costs about as much as the work, so take the ceiling, not the average.

Area law adds a calculation on the CPU, on the frames where the fader or a setting has changed. It’s under 0.06 ms for any single pattern, but it grows with the Multiples: about 2.8 ms for a Box at Multiple 8 × 8 and 7.8 ms for a Circle on a quiet machine, and up to 16.9 ms for the Circle on a busy one. If a moving fader stutters with both Multiples high, use Edge law.

No timing has been taken inside Resolume.

If it looks wrong

Only one of the two pictures shows. The fader is at an end. In Resolume the fader is the layer’s opacity, not the Opacity slider in the mixer’s panel.

Moving the Opacity slider does nothing. That’s Resolume overriding it with the layer’s opacity fader. Use the layer’s fader.

A control does nothing. Some controls only act on some patterns: the positioner on Box, Diamond, Circle and Clock; Border Softness and the border colour only with a Border Width; Mod Frequency and Mod Speed only with a Mod Amount.

The mixer does nothing at all. That’s what a shader that fails to compile looks like. The plugin writes a small log:

macOS    ~/Library/Logs/wipe/wipe.YYYY-MM-DD.log
Windows  %LOCALAPPDATA%\wipe\logs\wipe.YYYY-MM-DD.log

It records when an instance is created, the host’s name and version and the file it was loaded from, the GL vendor, renderer and version when it is put on a layer, and an error line if the shader failed to compile.

OpenFX: Resolve, Vegas, Nuke and Natron

The OpenFX build is the same wipe as a transition. It’s called Wipe, in the Stoatworks group. Every control in this guide is there under the same name and with the same range and default, except the ones listed below.

Installing. Download the wipe-ofx- zip for your platform (macOS universal, Windows x64 or Linux x86_64; released from v0.2.0 on) and copy Wipe.ofx.bundle into the system OpenFX folder, then restart the host:

macOS    /Library/OFX/Plugins/
Windows  C:\Program Files\Common Files\OFX\Plugins\
Linux    /usr/OFX/Plugins/

Using it. Put it between two clips as a transition. The clip before the cut is SourceFrom and plays the part of A, the layer below; the clip after it is SourceTo and plays B. The host drives the Transition control from 0 to 1 across the transition, which is this build’s Opacity: at 0 you see only the outgoing clip, at 1 only the incoming one, and in between the wipe. At exactly 0 and 1 the clip is passed through untouched.

In a host without transitions (Nuke, Natron, or Resolve’s Fusion page), Wipe is an effect with two inputs, SourceFrom and SourceTo. Wire both, and keyframe Transition from 0 to 1 yourself.

What’s different:

• There’s no Flip-Flop. It works by remembering the previous transition, and each transition in a timeline is separate. Use Reverse on the transitions you want to run the other way. Reverse mirrors the pattern, so a Box closes instead of opening; it isn’t the same as a host’s own option to run a transition backwards.
• The wobble follows the timeline. Mod Speed moves the modulator by the time of the frame, so scrubbing shows it where playback will, and a render is the same every time. Resolve’s Fusion page reports the frame rate on the effect but not on its clips; Mod Speed reads the effect’s, and assumes 24 fps only where a host reports none.
• Sizes in pixels are full-resolution pixels. A proxy or half-resolution preview draws them half as wide, so it looks the same. On an anamorphic format, Aspect Comp keeps a circle round as displayed.
• The border colour is one colour control, not three.
• Aspect Comp can be changed. Only Resolume hides it.
• Area law is worked out for every frame. It costs a few milliseconds at most, for a Circle with both Multiples at 8.

It renders on the CPU, on every core the host gives it: 2.8 to 6.4 ms a frame at 1080p on an Apple M4 Max with eight threads, and 7.8 ms for a Circle with both Multiples at 8 in Area law.

Where it’s been tried. The OpenFX build has been checked against the Resolume build pixel for pixel, and rendered through a test host’s transition, where it matches to within one level in 255. In DaVinci Resolve 21.1 it works as an Edit-page transition, the right way round. It hasn’t been tried yet in Resolve’s Fusion page, Vegas, Nuke or Natron. If the wipe runs the wrong way round in your host (it starts on the incoming clip), please tell me.

Known limits

• Aspect Comp is hidden in Resolume. Arena doesn’t show a mixer’s first parameter, so Wipe puts Aspect Comp there on purpose. In Resolume it’s always on: circles are round and the ellipse can’t be chosen. Checked with Wipe in Arena 7.27.1 on Windows.
• The fader is the layer’s opacity. In Resolume the mixer’s own Opacity slider is overridden by the layer’s opacity fader, so it can’t be set or automated separately. Whether a layer transition or the autopilot moves it hasn’t been tried on any mixer.
• Never loaded into Resolume on macOS. In Resolume on Windows it has run only on software rendering, and its picture there hasn’t been captured. No graphics card but the Mac it was built on has run it.
• Sizes are in pixels, so a 4K edge is half the share of the picture of a 1080p one.
• Area law with the modulator on gives the area of the wipe without the wobble.
• Premultiplied alpha is assumed for both pictures, and the border is opaque.
• No Size control, and no presets.
• The OpenFX build has been tried only in DaVinci Resolve’s Edit page. See OpenFX. It has no Flip-Flop, on purpose, and in a host that reports no frame rate Mod Speed assumes 24 fps (Resolve’s Fusion page reports one on the effect, and Wipe reads it).
• There is a browser demo at wipe-demo.stoatworks-labs.com. It’s a port to a web page rather than the plugin: the shaders run in WebGL2 and any CPU half is rewritten in JavaScript. The page lists what it doesn’t reproduce.

About

The last group, About, carries a credit line (name, version, licence and maker) and buttons that open this user guide, the project page, the source on GitHub and the support page in your browser.

Reporting something

github.com/stoatworks-labs/wipe/issues. A screenshot, your Resolume version, the pattern and Law, the composition’s resolution, and the day’s log are usually enough for me to go on.