Presets: stop the host's own echo dropping them back to Custom

The same bug an external user reported against vertigo as its issue #2, which
all seven plugins carried because the preset machinery was copied between them.
Choosing a factory preset in Resolume did nothing: the dropdown snapped straight
back to Custom.

applyPreset wrote its values into params[] and raised FF_EVENT_FLAG_VALUE so the
host would re-read its sliders. That rests on an assumption FFGL never makes.
The host owns parameter state; it pushes its own values back down whenever it
likes, and nothing obliges it to act on a value event. Resolume does not act on
them -- it carries on restating the values it still believes in, the ones from
before the preset. Those restatements arrive as SetFloatParameter calls carrying
a changed value, so the rule that a covered parameter changing means the
operator has taken over fired on the host's own echo, immediately, every time.

Three things now arrive through that one call while a preset is active and only
the third is a person, so they are told apart by what the value IS rather than
by the fact that it changed: matching the preset is the host agreeing with us,
matching hostValues[] -- the host's own last word, kept separately from what the
plugin renders with -- is the host restating itself, and anything else is an
edit. The first two are ignored rather than written. Ignoring rather than
writing matters for the first as well as the second: a host that quantises hands
back a ROUNDED copy of our own value, and the pre-existing "did a covered
parameter move?" test works to a tighter tolerance than this one and would read
that rounding as an edit.

seedHostValues() fills the record from the defaults on first parameter traffic,
which has to happen before applyPreset can run -- seeding afterwards records the
preset's own values as the host's opening position and the very next restatement
looks like an edit. That mistake was made once while writing this and the test
caught it.

Dropping to Custom is now logged with the parameter and value that caused it.
Diagnosing the original report needed a code read for exactly the reason orrery
issue #6 did: nothing said it had happened.

The harness grows --presets, which drives three hosts -- one that honours value
events, one that ignores them, one that honours them but quantises to 1/1000 --
across every preset, with no GL involved. Against the pre-fix code it fails in
precisely the "ignores" column, which is the shape of the bug as reported.

sweep.py also learns to stop at the About block, as porthole's already had:
those are browser buttons that never touch a pixel, and sweeping them reported
five dead controls and buried anything real.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: stoatworks-labs

AGENTS.md

@@ -313,6 +313,49 @@ still the only thing that measures anything.
 
 ## Factory presets
 
+### The host owns the parameters, and a preset had to learn that
+
+Reported against **vertigo** as its issue #2 and fixed across all seven plugins
+on 2026-08-22: choosing a factory preset in Resolume did nothing and the
+dropdown snapped straight back to `Custom`.
+
+The pattern was copy-based — `applyPreset` writes the values into `params[]` and
+raises `FF_EVENT_FLAG_VALUE` so the host re-reads its sliders — and it rests on
+an assumption FFGL never makes. **The host owns parameter state.** It pushes its
+own values back down whenever it likes, and nothing obliges it to act on a value
+event. Resolume does not: it carries on restating the values it still believes
+in, which are the ones from before the preset. Those restatements arrive as
+`SetFloatParameter` calls carrying a changed value, so the rule "a covered
+parameter changed, therefore the operator has taken over" fired on the host's
+own echo, instantly, every time.
+
+Three things now arrive through that one call while a preset is active, and only
+the third is a person:
+
+| What arrives | How it is recognised | What happens |
+|---|---|---|
+| the preset's own values, from a host that honoured the events | matches the preset | ignored — nothing to write |
+| the values from *before* the preset, from a host that did not | matches `hostValues[]`, the host's own last word | ignored — writing it would undo the preset |
+| a new value from neither | matches neither | written, and the preset falls back to Custom |
+
+`hostValues[]` is the record of what the **host** last sent, which is not what
+the plugin is rendering with, and `seedHostValues()` fills it from the defaults
+on the first parameter traffic — **before `applyPreset` can run**. Seeding it
+afterwards records the preset's own values as the host's opening position, so
+the host's very next restatement looks like an edit; that mistake was made once
+during the fix and the test caught it.
+
+Two tolerances matter and they are not the same number. `kSame` is **1e-3**, a
+host-quantisation allowance rather than a float epsilon — a host that keeps its
+parameters shorter than a float hands back a number *near* ours. The pre-existing
+"did a covered parameter move?" test below still works to 1e-4, which is why a
+value matching the preset is **ignored rather than written**: letting a rounded
+copy of our own value into `params[]` would trip that tighter test.
+
+`octest --presets` drives all three hosts across every preset, with no GL
+involved, and runs in `tools/verify.sh`. Against the pre-fix code it fails in
+exactly the "ignores value events" column.
+
 `source/Presets.h` is one table of named looks in the host-facing 0..1
 parameter space, and it drives **both** builds — the FFGL constructor and the
 OFX describe each read it, so a preset cannot drift between Resolume and

source/OldCathode.cpp

@@ -620,6 +620,8 @@ FFResult OldCathode::SetFloatParameter( unsigned int index, float value )
 	if( index >= PT_COUNT )
 		return FF_FAIL;
 
+	seedHostValues();
+
 	// An About button is a press, not a value to keep: it opens a browser and
 	// nothing about the effect changes.
 	if( index >= PT_ABOUT_FIRST )
@@ -633,6 +635,14 @@ FFResult OldCathode::SetFloatParameter( unsigned int index, float value )
 		return FF_SUCCESS;
 	}
 
+	// The host may be restating a value it still believes in rather than the
+	// operator moving anything. Letting that through would overwrite the
+	// preset's value in params[] AND read as an edit, dropping the dropdown
+	// back to Custom -- which is what made presets look like they could not
+	// be selected at all. See AGENTS.md.
+	if( hostIsRestatingItself( index, value ) )
+		return FF_SUCCESS;
+
 	// A slider moved while a preset is active means the operator has taken
 	// over: the dropdown falls back to Custom. The equality guard matters —
 	// hosts that honour the value events echo the preset's own values straight
@@ -647,6 +657,13 @@ FFResult OldCathode::SetFloatParameter( unsigned int index, float value )
 		{
 			if( id == index )
 			{
+				// Logged, unlike an ordinary parameter change: this one is a
+				// state change an operator can be surprised by, it happens once
+				// rather than per frame, and diagnosing vertigo #2 needed a code
+				// read precisely because nothing said it had happened.
+				diag::info( "preset dropped to Custom: parameter "
+				            + std::to_string( index ) + " moved to "
+				            + std::to_string( value ) );
 				params[ PT_PRESET ] = 0.0f;
 				RaiseParamEvent( PT_PRESET, FF_EVENT_FLAG_VALUE );
 				break;
@@ -657,6 +674,76 @@ FFResult OldCathode::SetFloatParameter( unsigned int index, float value )
 	return FF_SUCCESS;
 }
 
+const unsigned int* OldCathode::PresetParamIDsForTest( int& count )
+{
+	count = oldcathode::presets::kParamCount;
+	return kPresetParamIDs;
+}
+
+float OldCathode::presetValue( int presetIndex, unsigned int id ) const
+{
+	if( presetIndex <= 0 || presetIndex > oldcathode::presets::kCount )
+		return -1.0f;
+
+	const oldcathode::presets::Preset& preset = oldcathode::presets::kPresets[ presetIndex - 1 ];
+	for( int j = 0; j < oldcathode::presets::kParamCount; ++j )
+		if( kPresetParamIDs[ j ] == id )
+			return preset.v[ j ];
+
+	return -1.0f;
+}
+
+void OldCathode::seedHostValues()
+{
+	// Seeded on first parameter traffic rather than in the constructor, so the
+	// whole mechanism stays in one place. It has to happen BEFORE applyPreset
+	// can run: seeding afterwards would record the preset's own values as the
+	// host's opening position, and the host's very next restatement would then
+	// look like an edit -- which is the bug this exists to fix, reintroduced.
+	if( hostValuesSeeded )
+		return;
+
+	for( unsigned int i = 0; i < PT_COUNT; ++i )
+		hostValues[ i ] = params[ i ];
+	hostValuesSeeded = true;
+}
+
+bool OldCathode::hostIsRestatingItself( unsigned int index, float value )
+{
+	const float lastFromHost = hostValues[ index ];
+	hostValues[ index ]      = value;
+
+	const float fromPreset =
+		presetValue( static_cast< int >( std::lround( params[ PT_PRESET ] ) ), index );
+	if( fromPreset < 0.0f )
+		return false;
+
+	// A quantisation allowance rather than a float epsilon. A host that keeps
+	// its parameters shorter than a float -- or round-trips them through a UI,
+	// a MIDI value or a saved composition -- hands back a number near ours
+	// rather than ours, and 1e-4 read that as an edit.
+	constexpr float kSame = 1e-3f;
+
+	if( std::fabs( value - fromPreset ) <= kSame )
+	{
+		// The host agreeing with the preset. Nothing to write -- and writing it
+		// would actively hurt: a host that quantises hands back a ROUNDED copy
+		// of our own value, params[] would take the rounding, and the existing
+		// "did a covered parameter move?" test below works to a tighter
+		// tolerance than this one and would read that rounding as an edit.
+		return true;
+	}
+
+	if( std::fabs( value - lastFromHost ) > kSame )
+		return false;//neither: the operator has taken over
+
+	// Deliberately not logged. A host that pushes its parameters every frame
+	// would put a line here every frame, and a log that scrolls is a log nobody
+	// reads. The event worth recording is the one below, in the fallback to
+	// Custom, which happens once.
+	return true;
+}
+
 void OldCathode::applyPreset( int presetIndex )
 {
 	params[ PT_PRESET ] = static_cast< float >( presetIndex );

source/OldCathode.h

@@ -52,6 +52,11 @@ class OldCathode : public CFFGLPlugin
 	FFResult SetTextParameter( unsigned int index, const char* value ) override;
 	float GetFloatParameter( unsigned int index ) override;
 
+	/// Test hook: the parameter ids a preset covers, in presets::Param
+	/// order. Handed out rather than copied into the harness, so a second
+	/// list cannot go quietly out of step with this one.
+	static const unsigned int* PresetParamIDsForTest( int& count );
+
 	FFResult SetTime( double time ) override;
 
 private:
@@ -125,8 +130,39 @@ class OldCathode : public CFFGLPlugin
 
 	/// Copy a factory preset's values into params[] and raise value events so
 	/// the host re-reads the sliders. `presetIndex` is 1-based; 0 is Custom.
+	/// The active preset's value for `id`, or -1 when no preset is active or
+	/// this one has no opinion about `id`. Preset values are all 0..1, so a
+	/// negative is unambiguous.
+	float presetValue( int presetIndex, unsigned int id ) const;
+
+	/// True when this write is the HOST restating a value it still believes in
+	/// rather than the operator moving anything -- in which case it must not
+	/// reach params[] and must not disturb the preset.
+	bool hostIsRestatingItself( unsigned int index, float value );
+
+	/// Record the defaults as the host's opening position, once, before
+	/// anything has had a chance to move them.
+	void seedHostValues();
+
 	void applyPreset( int presetIndex );
 
+	/// What the HOST last sent for each parameter, which is not the same thing
+	/// as what the plugin is rendering with.
+	///
+	/// FFGL's host owns parameter state. It pushes its own values back down
+	/// whenever it likes, and nothing obliges it to act on the value events
+	/// applyPreset raises -- Resolume does not. So a preset that writes params[]
+	/// and trusts the host to follow is relying on behaviour the specification
+	/// never promised, and when the host instead restates the values it still
+	/// believes in, the rule that a covered parameter changing means the
+	/// operator has taken over fires on the host's own echo and drops straight
+	/// back to Custom. Reported against vertigo as its issue #2; the same
+	/// pattern had been copied into all seven plugins.
+	///
+	/// Keeping the host's own last word separately is what tells the two apart.
+	float hostValues[ PT_COUNT ] = {};
+	bool hostValuesSeeded        = false;
+
 	bool compileShaders();
 	void releaseBuffers();
 

tools/octest/main.cpp

@@ -349,6 +349,7 @@ void usage()
 		"  --flat V          render a uniform field at level V instead of the test card\n"
 		"  --measure         print the mean RGB of the middle of the picture\n"
 		"  --list            print every parameter and its default, then exit\n"
+		"  --presets         every factory preset survives every host behaviour\n"
 		"\n"
 		"  --pipe            read raw RGBA frames from stdin, write them to stdout,\n"
 		"                    so real footage can be put through the chain:\n"
@@ -360,6 +361,145 @@ void usage()
 }
 } // namespace
 
+//---------------------------------------------------------------------------
+/// Prove a factory preset survives whatever the host does next.
+///
+/// FFGL's host owns parameter state and is free to push it back down at any
+/// time, and nothing in the specification obliges it to act on the value
+/// events a plugin raises when it changes a parameter itself. So there are
+/// three hosts to survive, and the plugin cannot tell which one it is talking
+/// to:
+///
+///   - one that honours the events and hands the new values straight back;
+///   - one that ignores them and carries on restating the values it still
+///     believes in, which are the ones from before the preset;
+///   - one that honours them but keeps its parameters shorter than a float, so
+///     what comes back is near the preset rather than equal to it.
+///
+/// All three arrive as SetFloatParameter calls carrying a changed value, which
+/// is why "the value changed, so the operator must have taken over" is the
+/// wrong test. Resolume is the second kind, and against the unfixed code this
+/// fails in exactly that column -- reported as vertigo issue #2.
+///
+/// No GL here: this is the parameter plumbing, not the picture.
+//---------------------------------------------------------------------------
+int runPresetTest()
+{
+	using namespace oldcathode::presets;
+
+	int coveredCount            = 0;
+	const unsigned int* covered = OldCathode::PresetParamIDsForTest( coveredCount );
+
+	enum class Host
+	{
+		Honours,
+		Ignores,
+		Quantises
+	};
+	struct HostCase
+	{
+		Host kind;
+		const char* name;
+	};
+	const HostCase hosts[] = {
+		{ Host::Honours, "honours value events" },
+		{ Host::Ignores, "ignores value events" },
+		{ Host::Quantises, "honours, 1/1000 steps" },
+	};
+
+	int failures = 0;
+
+	for( const HostCase& host : hosts )
+	{
+		for( int preset = 1; preset <= kCount; ++preset )
+		{
+			OldCathode plugin;
+
+			int presetIndex = -1;
+			for( unsigned int i = 0; i < plugin.GetNumParams(); ++i )
+			{
+				const char* declared = plugin.GetParamName( i );
+				if( declared != nullptr && std::strcmp( declared, "Preset" ) == 0 )
+				{
+					presetIndex = int( i );
+					break;
+				}
+			}
+			if( presetIndex < 0 )
+			{
+				std::fprintf( stderr, "presets: no parameter is called \"Preset\"\n" );
+				return 1;
+			}
+
+			// What the host thinks the sliders say before the operator reaches
+			// for the dropdown.
+			std::vector< float > hostOwn;
+			for( int j = 0; j < coveredCount; ++j )
+				hostOwn.push_back( plugin.GetFloatParameter( covered[ j ] ) );
+
+			// The operator picks a preset.
+			plugin.SetFloatParameter( unsigned( presetIndex ), float( preset ) );
+
+			// And now the host says its piece.
+			for( int j = 0; j < coveredCount; ++j )
+			{
+				float back = 0.0f;
+				switch( host.kind )
+				{
+				case Host::Honours:
+					back = plugin.GetFloatParameter( covered[ j ] );
+					break;
+				case Host::Ignores:
+					back = hostOwn[ size_t( j ) ];
+					break;
+				case Host::Quantises:
+					back = std::round( plugin.GetFloatParameter( covered[ j ] ) * 1000.0f ) / 1000.0f;
+					break;
+				}
+				plugin.SetFloatParameter( covered[ j ], back );
+			}
+
+			const int still = int( std::lround( plugin.GetFloatParameter( unsigned( presetIndex ) ) ) );
+			bool ok         = still == preset;
+
+			// Still selected is not enough -- it has to be what renders.
+			for( int j = 0; j < coveredCount; ++j )
+			{
+				const float want = kPresets[ preset - 1 ].v[ j ];
+				const float got  = plugin.GetFloatParameter( covered[ j ] );
+				ok               = ok && std::fabs( got - want ) <= 1e-4f;
+			}
+
+			if( !ok )
+			{
+				std::printf( "presets %-22s %-22s FAILED (shows %d)\n",
+				             host.name, kPresets[ preset - 1 ].name, still );
+				++failures;
+				continue;
+			}
+
+			// An operator turning a covered knob must still drop to Custom -- a
+			// preset that cannot be left is no better than one that will not
+			// stick. Move it somewhere neither the preset nor the host named.
+			const float moved = kPresets[ preset - 1 ].v[ 0 ] > 0.5f ? 0.123f : 0.877f;
+			plugin.SetFloatParameter( covered[ 0 ], moved );
+			const int after = int( std::lround( plugin.GetFloatParameter( unsigned( presetIndex ) ) ) );
+			if( after != 0 )
+			{
+				std::printf( "presets %-22s %-22s FAILED (an edit left it on %d)\n",
+				             host.name, kPresets[ preset - 1 ].name, after );
+				++failures;
+				continue;
+			}
+
+			std::printf( "presets %-22s %-22s ok\n", host.name, kPresets[ preset - 1 ].name );
+		}
+	}
+
+	std::printf( "%s\n", failures == 0 ? "presets: all ok" : "presets: FAILURES" );
+	return failures == 0 ? 0 : 1;
+}
+
 int main( int argc, char** argv )
 {
 	std::string outputPath = "/tmp/oldcathode.png";
@@ -400,6 +540,8 @@ int main( int argc, char** argv )
 			fps = std::strtod( next().c_str(), nullptr );
 		else if( arg == "--flat" )
 			flatLevel = std::strtof( next().c_str(), nullptr );
+		else if( arg == "--presets" )
+			return runPresetTest();
 		else if( arg == "--list" )
 			listOnly = true;
 		else if( arg == "--set" )

tools/sweep.py

@@ -72,6 +72,11 @@ def diff(a, b):
 names = subprocess.run(["./build/octest", "--list"], capture_output=True, text=True).stdout
 params = [' '.join(l.split()[1:-1]) for l in names.strip().splitlines()]
 
+# The About block is a text field and browser buttons, declared last. They
+# never touch a pixel, so sweeping them only buries a real dead control.
+if "About" in params:
+    params = params[:params.index("About")]
+
 # Options are discrete; sweep them across their real element range.
 DISCRETE = {"System": (0, 1), "Source": (0, 3), "Mask Pattern": (1, 4), "Interlace": (0, 1)}