Add an image overlay effect

Lays a single picture from disk over its input: fitted, filled, stretched,
left at its own size or tiled, centred or pinned to the top left corner,
nudged by an offset and mixed in by its opacity.

The file it needs is a new kind of param, Path, so the interface shows a
chooser and the CLI takes a file name, both without knowing an overlay
exists. Projects write it relative to their own folder, as they do a
source, and Image::load can now hand back the alpha channel instead of
flattening it onto white, so a cut-out PNG keeps its cut-out.

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

src/core/effect.cpp

@@ -16,6 +16,7 @@ ParamValues Effect::defaults() const {
                 values[spec.key] = spec.defaultValue != 0.0;
                 break;
             case ParamSpec::Type::Choice:
+            case ParamSpec::Type::Path:
                 values[spec.key] = spec.defaultChoice;
                 break;
         }

src/core/image.cpp

@@ -43,7 +43,7 @@ Image::Image(int width, int height)
       pixels_(static_cast<std::size_t>(std::max(width, 0)) * 3 *
               static_cast<std::size_t>(std::max(height, 0))) {}
 
-Image Image::load(const std::string& path) {
+Image Image::load(const std::string& path, std::vector<std::uint8_t>* alphaOut) {
     GError* error = nullptr;
     PixbufPtr pixbuf = wrap(gdk_pixbuf_new_from_file(path.c_str(), &error));
     if (!pixbuf) throw std::runtime_error(takeError(error));
@@ -59,11 +59,23 @@ Image Image::load(const std::string& path) {
     const guint8* src = gdk_pixbuf_get_pixels(pixbuf.get());
 
     Image image(width, height);
+    if (alphaOut != nullptr) {
+        alphaOut->assign(static_cast<std::size_t>(std::max(width, 0)) *
+                             static_cast<std::size_t>(std::max(height, 0)),
+                         255);
+    }
     for (int y = 0; y < height; ++y) {
         const guint8* in = src + static_cast<std::size_t>(y) * srcStride;
         std::uint8_t* out = image.row(y);
         if (channels == 3) {
             std::memcpy(out, in, static_cast<std::size_t>(width) * 3);
+        } else if (alphaOut != nullptr) {
+            // Kept apart rather than flattened: the caller does the compositing.
+            std::uint8_t* alpha = alphaOut->data() + static_cast<std::size_t>(y) * width;
+            for (int x = 0; x < width; ++x) {
+                for (int c = 0; c < 3; ++c) out[x * 3 + c] = in[x * channels + c];
+                alpha[x] = in[x * channels + 3];
+            }
         } else {
             // Flatten alpha onto white, matching what a viewer would show.
             for (int x = 0; x < width; ++x) {

src/core/image.hpp

@@ -34,7 +34,11 @@ public:
 
     // Decodes via GdkPixbuf (PNG, JPEG, WebP, TIFF, BMP, ...), applying the
     // embedded EXIF orientation. Throws std::runtime_error on failure.
-    static Image load(const std::string& path);
+    // Transparency is flattened onto white, as a viewer would show it, unless
+    // `alphaOut` is given: it then receives one byte per pixel (255 throughout
+    // for a file without an alpha channel) and the colours are left untouched,
+    // which is what an effect compositing the image needs.
+    static Image load(const std::string& path, std::vector<std::uint8_t>* alphaOut = nullptr);
 
     // Encodes by file extension; png is used when the extension is unknown.
     void save(const std::string& path) const;

src/core/params.cpp

@@ -63,6 +63,15 @@ ParamSpec ParamSpec::makeChoice(std::string key, std::string label, std::string
     return spec;
 }
 
+ParamSpec ParamSpec::makePath(std::string key, std::string label, std::string help) {
+    ParamSpec spec;
+    spec.type = Type::Path;
+    spec.key = std::move(key);
+    spec.label = std::move(label);
+    spec.help = std::move(help);
+    return spec;
+}
+
 namespace {
 
 const ParamValue* find(const ParamValues& values, const std::string& key) {
@@ -99,6 +108,11 @@ bool paramBool(const ParamValues& values, const std::string& key, bool fallback)
 
 std::string paramChoice(const ParamValues& values, const std::string& key,
                         const std::string& fallback) {
+    return paramText(values, key, fallback);
+}
+
+std::string paramText(const ParamValues& values, const std::string& key,
+                      const std::string& fallback) {
     if (const auto* value = find(values, key)) {
         if (const auto* v = std::get_if<std::string>(value)) return *v;
     }

src/core/params.hpp

@@ -10,7 +10,7 @@ namespace effector {
 // Declarative description of one effect knob. The GUI turns these into widgets
 // and the CLI turns them into flags, so neither knows about any effect.
 struct ParamSpec {
-    enum class Type { Int, Double, Bool, Choice };
+    enum class Type { Int, Double, Bool, Choice, Path };
 
     Type type = Type::Int;
     std::string key;
@@ -35,6 +35,10 @@ struct ParamSpec {
                               std::string help = {});
     static ParamSpec makeChoice(std::string key, std::string label, std::string defaultChoice,
                                 std::vector<std::string> choices, std::string help = {});
+    // A path to a file on disk, empty by default: a chooser in the interface, a
+    // flag taking any string on the command line, written relative to the
+    // project folder so that a folder still opens after it is moved.
+    static ParamSpec makePath(std::string key, std::string label, std::string help = {});
 };
 
 using ParamValue = std::variant<long, double, bool, std::string>;
@@ -45,5 +49,7 @@ double paramDouble(const ParamValues& values, const std::string& key, double fal
 bool paramBool(const ParamValues& values, const std::string& key, bool fallback);
 std::string paramChoice(const ParamValues& values, const std::string& key,
                         const std::string& fallback);
+std::string paramText(const ParamValues& values, const std::string& key,
+                      const std::string& fallback);
 
 }  // namespace effector

src/core/project.cpp

@@ -348,6 +348,13 @@ std::string projectToJson(const Project& project, const std::string& directory)
                 case ParamSpec::Type::Choice:
                     out << quote(paramChoice(stage.values, spec.key, spec.defaultChoice));
                     break;
+                case ParamSpec::Type::Path: {
+                    // Written relative to the project folder, exactly as the
+                    // sources are, so a folder still opens once it is moved.
+                    const auto path = paramText(stage.values, spec.key, "");
+                    out << quote(path.empty() ? path : relativeTo(path, directory));
+                    break;
+                }
             }
         }
         out << (specs.empty() ? "}" : "\n      }") << "\n    }";
@@ -418,6 +425,12 @@ Project projectFromJson(const std::string& text, const std::string& directory) {
                     case ParamSpec::Type::Double:
                         if (value->kind == Json::Kind::Number) stage.values[spec.key] = value->number;
                         break;
+                    case ParamSpec::Type::Path:
+                        if (value->kind == Json::Kind::String) {
+                            stage.values[spec.key] =
+                                value->text.empty() ? value->text : resolve(value->text, directory);
+                        }
+                        break;
                     case ParamSpec::Type::Choice:
                         for (const auto& choice : spec.choices) {
                             if (value->kind == Json::Kind::String && value->text == choice) {

src/core/registry.cpp

@@ -3,6 +3,7 @@
 #include "effects/blur.hpp"
 #include "effects/grain.hpp"
 #include "effects/monochrome.hpp"
+#include "effects/overlay.hpp"
 #include "effects/scanlines.hpp"
 
 namespace effector {
@@ -14,6 +15,7 @@ const std::vector<EffectPtr>& effects() {
         std::make_shared<BlurEffect>(),
         std::make_shared<GrainEffect>(),
         std::make_shared<MonochromeEffect>(),
+        std::make_shared<OverlayEffect>(),
     };
     return registry;
 }