blend_image(3)

💅 blend_image(3) — the Arcan Lua API one, bestie

Okay so this is blend_image, straight out of the Arcan Lua API, and it's literally the glow-up button for your images ✨

---

🌸 NAME 🌸

blend_image — change image opacity, periodt. That's the whole job. 🫶

---

🎀 SYNOPSIS 🎀

nil
blend_image( VID or VIDtbl, opacity, time, interp )

---

🦋 DESCRIPTION 🦋

So here's the tea: blend_image changes the opacity of the VID(s) you picked — either instantly (that's the default, no waiting around 💅) or, if you pass the optional time argument, as a lil' animation. And heads up: time has to be a non-negative integer, no cap.

It's flexible too, which is the way I like it: it takes either a single VID or a whole group of VIDs bundled up in a table. And when it's a table, the iteration follows the behavior of pairs() — iykyk. 🔥

And interp? That's your easing vibe check. Set it to one of these constants:

• INTERP_LINEAR
• INTERP_SINE
• INTERP_EXPIN
• INTERP_EXPOUT
• INTERP_EXPINOUT
• INTERP_SMOOTHSTEP

Pick your fighter, bestie 🌈

---

⭐ NOTES ⭐

1. VIDs with an opacity other than 0.0 (hidden) and 1.0 (opaque, visible) will be blended. Like, that's the whole point, bestie 🎀
2. Values outside the allowed range will be clamped. The function said "not today" to your nonsense 🙈
3. The blend behavior is dictated by the default global blendfunc value (src_alpha, 1-src_alpha) and can be overridden with force_image_blend(mode). Iconic override behavior 👑

---

✨ EXAMPLE ✨

The good path, the slay path 💖

function blend_image0()
      a = fill_surface(128, 128, 255, 0, 0);
      b = fill_surface(128, 128, 0, 255, 0);
      move_image(b, 64, 64);
      show_image({a,b});
      blend_image(b, 0.5, 100);
end

---

💀 MISUSE 💀

Not me showing you exactly how to break it 😭 Here's the first cursed one — negative opacity and negative time, absolutely unhinged behavior:

function blend_image0()
      a = fill_surface(128, 128, 255, 0, 0);
      b = fill_surface(128, 128, 0, 255, 0);
      move_image(b, 64, 64);
      show_image({a,b});
      blend_image(b, -0.5, -100);
end

Second one: passing "a" as the VID. A string. Bestie. That's not a VID. That's a string. 🫠

function blend_image1()
      a = fill_surface(128, 128, 255, 0, 0);
      b = fill_surface(128, 128, 0, 255, 0);
      move_image(b, 64, 64);
      show_image({a,b});
      blend_image("a", 0.5, 100);
end

Third one is a full-on chaos salad — a table of {-1, "a", true, 5.0} as the VIDs, true as the opacity, "error" as the time. It's giving "I woke up and chose violence" 💀💀💀

function blend_image2()
      a = fill_surface(128, 128, 255, 0, 0);
      b = fill_surface(128, 128, 0, 255, 0);
      move_image(b, 64, 64);
      show_image({a,b});
      blend_image({-1, "a", true, 5.0}, true, "error");
end

Do NOT do these. They're here so you can recognize the red flags, not so you can copy them. 🚩

---

👀 SEE ALSO 👀

• image_force_blend(3) — the override bestie you met in note 3 🫶

---

Okay that's the whole page, mwah 💋 This gem comes from the image manual, dated October 2026 — go forth and blend responsibly, my love 🌸🦋💖