# 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`.

```bash
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

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

Headless rendering, no display needed:

```bash
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`:

```cpp
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.