effector/README.md

Effector

An image effects app: a GTK4 interface and a headless CLI over a set of pluggable effects. Effects are self-contained classes that declare their own parameters; the interface builds its widgets and the CLI builds its flags from those declarations, so a new effect needs no UI or CLI code.

Build

Requirements: a C++20 compiler (GCC 13+), CMake 3.20+, gtkmm-4.0 and gdk-pixbuf-2.0 development packages. On Arch: gcc cmake ninja gtkmm-4.0.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

The binary lands at build/effector; cmake --install build --prefix ~/.local installs it to ~/.local/bin.

Run

build/effector                  # GTK interface
build/effector --list-effects
build/effector --help

Headless rendering, no display needed:

build/effector -o out.png -s 1920x1080 \
    --strip-height 8 --jitter 4 --seed 42 photo1.jpg photo2.png

Any option can also be passed when launching the interface; it becomes the starting state (images, canvas size, effect settings, seed).

Effects

scanlines

Fills the canvas top to bottom with horizontal strips cut at random positions from the source images. Strips are taken at native scale, cropped at a random horizontal offset, and tiled when the source is narrower than the canvas.

Parameter	Flag	Meaning
strip_height	--strip-height	Height in pixels of each extracted line
jitter	--jitter	Random ± variation of that height (0 = uniform)
keep_order	--keep-order	Cycle the images in order instead of picking randomly

The seed makes a result reproducible: same sources, settings and seed give the same image, on any machine — the generator (src/core/rng.hpp) is a hand-rolled xoshiro256** rather than <random>, whose distributions are not portable. Recreate draws a new seed.

Layout

src/core/      image buffer and IO, param specs, effect base, registry, rng, thread helper
src/effects/   one file per effect
src/cli/       argument parsing (flags generated from the registry)
src/gui/       gtkmm 4 interface
tests/         core checks, run by ctest
python-reference/  the original Python prototype, kept for reference only

effector_core is a GUI-free static library that links only gdk-pixbuf, so headless rendering never touches GTK or a display. The GTK front end links on top of it.

Adding an effect

1. Create src/effects/myeffect.{hpp,cpp} with a subclass of Effect:

class MyEffect : public Effect {
    std::string name() const override { return "myeffect"; }
    std::string title() const override { return "My Effect"; }
    std::string description() const override { return "..."; }

    const std::vector<ParamSpec>& params() const override {
        static const std::vector<ParamSpec> specs = {
            ParamSpec::makeInt("amount", "Amount", 4, 1, 64, "How much."),
        };
        return specs;
    }

    Image render(const std::vector<Image>& sources, int width, int height, Rng& rng,
                 const ParamValues& values) const override {
        const long amount = paramInt(values, "amount", 4);
        ...  // return a width x height RGB image
    }
};

2. Add it to _EFFECT_CLASSES-style list in src/core/registry.cpp and to the source list in CMakeLists.txt.

Widgets and flags follow from params() automatically. Draw everything random from the Rng you are handed so results stay reproducible, and use parallelFor (src/core/parallel.hpp) for the pixel work.

Performance notes

The render loop first draws the whole strip plan from the seeded generator, then copies the pixels in parallel across the hardware threads; each row is a memcpy, and horizontal tiling doubles the filled span per pass. Source images are decoded in parallel too, which is what dominates a headless run.

A 7680×4320 canvas at --strip-height 2 from three multi-megapixel JPEGs renders in ~35 ms, against ~73 ms for the Python prototype; the interface reports the render time of the current preview in its status line.