Files
texturecraft/crates/core/src/blend.rs
T
bflatastic 056a089551 Viewport: show the baked normal map
The viewport's normal texture held only the painted Normal channel, so
a baked normal map changed the export but not the view. Display tiles
now re-orient the painted normal onto the baked one, as export does
(core::blend::rnm, now public).

Fixes #54.
2026-11-02 06:11:11 +07:00

443 lines
15 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Per-channel blend modes and their CPU reference math (straight values, linear space).
//!
//! `a` is the value below (the stack so far), `b` the layer's value. The compositor mixes the
//! result back over `a` by `coverage × opacity × mask`.
use serde::{Deserialize, Serialize};
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
pub enum BlendMode {
#[default]
Normal,
Passthrough,
Disable,
Replace,
Multiply,
Divide,
InverseDivide,
Darken,
Lighten,
LinearDodge,
Subtract,
InverseSubtract,
Difference,
Exclusion,
SignedAddition,
Overlay,
Screen,
LinearBurn,
ColorBurn,
ColorDodge,
SoftLight,
HardLight,
VividLight,
LinearLight,
PinLight,
Tint,
Saturation,
Color,
Value,
NormalMapCombine,
NormalMapDetail,
NormalMapInverseDetail,
}
impl BlendMode {
/// Every mode in menu order; `None` entries are the separators between menu groups.
pub const MENU: [Option<BlendMode>; 39] = [
Some(BlendMode::Normal),
Some(BlendMode::Passthrough),
Some(BlendMode::Disable),
Some(BlendMode::Replace),
None,
Some(BlendMode::Multiply),
Some(BlendMode::Divide),
Some(BlendMode::InverseDivide),
Some(BlendMode::Darken),
Some(BlendMode::Lighten),
None,
Some(BlendMode::LinearDodge),
Some(BlendMode::Subtract),
Some(BlendMode::InverseSubtract),
Some(BlendMode::Difference),
Some(BlendMode::Exclusion),
Some(BlendMode::SignedAddition),
None,
Some(BlendMode::Overlay),
Some(BlendMode::Screen),
Some(BlendMode::LinearBurn),
Some(BlendMode::ColorBurn),
Some(BlendMode::ColorDodge),
None,
Some(BlendMode::SoftLight),
Some(BlendMode::HardLight),
Some(BlendMode::VividLight),
Some(BlendMode::LinearLight),
Some(BlendMode::PinLight),
None,
Some(BlendMode::Tint),
Some(BlendMode::Saturation),
Some(BlendMode::Color),
Some(BlendMode::Value),
None,
Some(BlendMode::NormalMapCombine),
Some(BlendMode::NormalMapDetail),
Some(BlendMode::NormalMapInverseDetail),
None,
];
pub fn all() -> impl Iterator<Item = BlendMode> {
BlendMode::MENU.into_iter().flatten()
}
pub fn label(self) -> &'static str {
match self {
BlendMode::Normal => "Normal",
BlendMode::Passthrough => "Passthrough",
BlendMode::Disable => "Disable",
BlendMode::Replace => "Replace",
BlendMode::Multiply => "Multiply",
BlendMode::Divide => "Divide",
BlendMode::InverseDivide => "Inverse divide",
BlendMode::Darken => "Darken (Min)",
BlendMode::Lighten => "Lighten (Max)",
BlendMode::LinearDodge => "Linear dodge (Add)",
BlendMode::Subtract => "Subtract",
BlendMode::InverseSubtract => "Inverse Subtract",
BlendMode::Difference => "Difference",
BlendMode::Exclusion => "Exclusion",
BlendMode::SignedAddition => "Signed addition (AddSub)",
BlendMode::Overlay => "Overlay",
BlendMode::Screen => "Screen",
BlendMode::LinearBurn => "Linear burn",
BlendMode::ColorBurn => "Color burn",
BlendMode::ColorDodge => "Color dodge",
BlendMode::SoftLight => "Soft light",
BlendMode::HardLight => "Hard light",
BlendMode::VividLight => "Vivid light",
BlendMode::LinearLight => "Linear light",
BlendMode::PinLight => "Pin light",
BlendMode::Tint => "Tint",
BlendMode::Saturation => "Saturation",
BlendMode::Color => "Color",
BlendMode::Value => "Value",
BlendMode::NormalMapCombine => "Normal map combine",
BlendMode::NormalMapDetail => "Normal map detail",
BlendMode::NormalMapInverseDetail => "Normal map inverse detail",
}
}
/// Four-letter abbreviation shown in the compact layer row ("Norm", "Mult", …).
pub fn short(self) -> &'static str {
match self {
BlendMode::Normal => "Norm",
BlendMode::Passthrough => "Pass",
BlendMode::Disable => "Dis",
BlendMode::Replace => "Repl",
BlendMode::Multiply => "Mult",
BlendMode::Divide => "Div",
BlendMode::InverseDivide => "IDiv",
BlendMode::Darken => "Dark",
BlendMode::Lighten => "Ligh",
BlendMode::LinearDodge => "Add",
BlendMode::Subtract => "Sub",
BlendMode::InverseSubtract => "ISub",
BlendMode::Difference => "Diff",
BlendMode::Exclusion => "Excl",
BlendMode::SignedAddition => "AdSb",
BlendMode::Overlay => "Over",
BlendMode::Screen => "Scrn",
BlendMode::LinearBurn => "LBrn",
BlendMode::ColorBurn => "CBrn",
BlendMode::ColorDodge => "CDdg",
BlendMode::SoftLight => "SftL",
BlendMode::HardLight => "HrdL",
BlendMode::VividLight => "VivL",
BlendMode::LinearLight => "LinL",
BlendMode::PinLight => "PinL",
BlendMode::Tint => "Tint",
BlendMode::Saturation => "Sat",
BlendMode::Color => "Colr",
BlendMode::Value => "Val",
BlendMode::NormalMapCombine => "NmCb",
BlendMode::NormalMapDetail => "NmDt",
BlendMode::NormalMapInverseDetail => "NmID",
}
}
/// Parse a label, short label or variant name (case-insensitive; punctuation ignored).
pub fn parse(s: &str) -> Option<BlendMode> {
let norm = |x: &str| x.to_ascii_lowercase().replace([' ', '_', '-', '(', ')'], "");
let want = norm(s);
BlendMode::all().find(|m| norm(m.label()) == want || norm(m.short()) == want || norm(&format!("{m:?}")) == want)
}
/// Modes that need all three components at once.
pub fn is_non_separable(self) -> bool {
matches!(
self,
BlendMode::Tint
| BlendMode::Saturation
| BlendMode::Color
| BlendMode::Value
| BlendMode::NormalMapCombine
| BlendMode::NormalMapDetail
| BlendMode::NormalMapInverseDetail
)
}
}
fn color_burn(a: f32, b: f32) -> f32 {
if a >= 1.0 {
1.0
} else if b <= 0.0 {
0.0
} else {
1.0 - ((1.0 - a) / b).min(1.0)
}
}
fn color_dodge(a: f32, b: f32) -> f32 {
if a <= 0.0 {
0.0
} else if b >= 1.0 {
1.0
} else {
(a / (1.0 - b)).min(1.0)
}
}
fn soft_light(a: f32, b: f32) -> f32 {
let (a, b) = (a.clamp(0.0, 1.0), b.clamp(0.0, 1.0));
if b <= 0.5 {
return a - (1.0 - 2.0 * b) * a * (1.0 - a);
}
let d = if a <= 0.25 { ((16.0 * a - 12.0) * a + 4.0) * a } else { a.sqrt() };
a + (2.0 * b - 1.0) * (d - a)
}
fn overlay(a: f32, b: f32) -> f32 {
if a < 0.5 { 2.0 * a * b } else { 1.0 - 2.0 * (1.0 - a) * (1.0 - b) }
}
/// One component of a separable blend. Non-separable modes fall back to `Normal`.
pub fn blend1(mode: BlendMode, a: f32, b: f32) -> f32 {
match mode {
BlendMode::Normal | BlendMode::Passthrough | BlendMode::Replace => b,
BlendMode::Disable => a,
BlendMode::Multiply => a * b,
BlendMode::Divide => a / b.max(1e-6),
BlendMode::InverseDivide => b / a.max(1e-6),
BlendMode::Darken => a.min(b),
BlendMode::Lighten => a.max(b),
BlendMode::LinearDodge => a + b,
BlendMode::Subtract => a - b,
BlendMode::InverseSubtract => b - a,
BlendMode::Difference => (a - b).abs(),
BlendMode::Exclusion => a + b - 2.0 * a * b,
BlendMode::SignedAddition | BlendMode::LinearLight => a + 2.0 * b - 1.0,
BlendMode::Overlay => overlay(a, b),
BlendMode::Screen => 1.0 - (1.0 - a) * (1.0 - b),
BlendMode::LinearBurn => a + b - 1.0,
BlendMode::ColorBurn => color_burn(a, b),
BlendMode::ColorDodge => color_dodge(a, b),
BlendMode::SoftLight => soft_light(a, b),
BlendMode::HardLight => overlay(b, a),
BlendMode::VividLight => {
if b < 0.5 {
color_burn(a, 2.0 * b)
} else {
color_dodge(a, 2.0 * (b - 0.5))
}
}
BlendMode::PinLight => {
if b < 0.5 {
a.min(2.0 * b)
} else {
a.max(2.0 * b - 1.0)
}
}
BlendMode::Tint
| BlendMode::Saturation
| BlendMode::Color
| BlendMode::Value
| BlendMode::NormalMapCombine
| BlendMode::NormalMapDetail
| BlendMode::NormalMapInverseDetail => b,
}
}
/// Luminance of a color (the W3C non-separable blend weights).
pub fn lum(c: [f32; 3]) -> f32 {
0.3 * c[0] + 0.59 * c[1] + 0.11 * c[2]
}
fn clip_color(c: [f32; 3]) -> [f32; 3] {
let l = lum(c);
let n = c[0].min(c[1]).min(c[2]);
let x = c[0].max(c[1]).max(c[2]);
let mut out = c;
if n < 0.0 && l - n > 1e-6 {
out = out.map(|v| l + (v - l) * l / (l - n));
}
if x > 1.0 && x - l > 1e-6 {
out = out.map(|v| l + (v - l) * (1.0 - l) / (x - l));
}
out
}
fn set_lum(c: [f32; 3], l: f32) -> [f32; 3] {
let d = l - lum(c);
clip_color(c.map(|v| v + d))
}
fn sat(c: [f32; 3]) -> f32 {
c[0].max(c[1]).max(c[2]) - c[0].min(c[1]).min(c[2])
}
fn set_sat(c: [f32; 3], s: f32) -> [f32; 3] {
let mx = c[0].max(c[1]).max(c[2]);
let mn = c[0].min(c[1]).min(c[2]);
if mx - mn <= 1e-6 {
return [0.0; 3];
}
c.map(|v| (v - mn) * s / (mx - mn))
}
fn unpack(n: [f32; 3]) -> [f32; 3] {
n.map(|v| v * 2.0 - 1.0)
}
fn pack(n: [f32; 3]) -> [f32; 3] {
let len = (n[0] * n[0] + n[1] * n[1] + n[2] * n[2]).sqrt().max(1e-6);
n.map(|v| v / len * 0.5 + 0.5)
}
/// Reoriented normal mapping (Barré-Brisebois & Hill): `detail` re-oriented onto `base` (both
/// packed into 0..1, as is the result).
pub fn rnm(base: [f32; 3], detail: [f32; 3]) -> [f32; 3] {
let t = unpack(base);
let t = [t[0], t[1], t[2] + 1.0];
let u = unpack(detail);
let u = [-u[0], -u[1], u[2]];
let d = t[0] * u[0] + t[1] * u[1] + t[2] * u[2];
pack([t[0] * d - u[0] * t[2], t[1] * d - u[1] * t[2], t[2] * d - u[2] * t[2]])
}
/// A three-component blend, including the non-separable modes.
pub fn blend3(mode: BlendMode, a: [f32; 3], b: [f32; 3]) -> [f32; 3] {
match mode {
BlendMode::Color => set_lum(b, lum(a)),
BlendMode::Saturation => set_lum(set_sat(a, sat(b)), lum(a)),
BlendMode::Value => {
let va = a[0].max(a[1]).max(a[2]);
let vb = b[0].max(b[1]).max(b[2]);
if va <= 1e-6 { [vb; 3] } else { a.map(|v| v * vb / va) }
}
BlendMode::Tint => {
let l = lum(a);
b.map(|v| v * l)
}
BlendMode::NormalMapCombine => {
let (na, nb) = (unpack(a), unpack(b));
pack([na[0] + nb[0], na[1] + nb[1], na[2] * nb[2]])
}
BlendMode::NormalMapDetail => rnm(a, b),
BlendMode::NormalMapInverseDetail => rnm(b, a),
_ => [blend1(mode, a[0], b[0]), blend1(mode, a[1], b[1]), blend1(mode, a[2], b[2])],
}
}
/// Mix `blended` over `a` by weight `w` (coverage × opacity × mask).
pub fn mix3(a: [f32; 3], blended: [f32; 3], w: f32) -> [f32; 3] {
[a[0] + (blended[0] - a[0]) * w, a[1] + (blended[1] - a[1]) * w, a[2] + (blended[2] - a[2]) * w]
}
#[cfg(test)]
mod tests {
use super::*;
const AS: [f32; 4] = [0.0, 0.25, 0.5, 1.0];
const BS: [f32; 4] = [0.0, 0.3, 0.7, 1.0];
fn close(a: f32, b: f32) -> bool {
(a - b).abs() < 1e-5
}
#[test]
fn separable_modes_match_hand_computed_values() {
for a in AS {
for b in BS {
assert!(close(blend1(BlendMode::Normal, a, b), b));
assert!(close(blend1(BlendMode::Disable, a, b), a));
assert!(close(blend1(BlendMode::Multiply, a, b), a * b));
assert!(close(blend1(BlendMode::Screen, a, b), 1.0 - (1.0 - a) * (1.0 - b)));
assert!(close(blend1(BlendMode::LinearDodge, a, b), a + b));
assert!(close(blend1(BlendMode::Subtract, a, b), a - b));
assert!(close(blend1(BlendMode::Darken, a, b), a.min(b)));
assert!(close(blend1(BlendMode::Lighten, a, b), a.max(b)));
assert!(close(blend1(BlendMode::Difference, a, b), (a - b).abs()));
assert!(close(blend1(BlendMode::Exclusion, a, b), a + b - 2.0 * a * b));
}
}
assert!(close(blend1(BlendMode::Overlay, 0.25, 0.3), 2.0 * 0.25 * 0.3));
assert!(close(blend1(BlendMode::Overlay, 0.5, 0.7), 1.0 - 2.0 * 0.5 * 0.3));
assert!(close(blend1(BlendMode::HardLight, 0.7, 0.25), 2.0 * 0.25 * 0.7));
}
#[test]
fn soft_light_matches_w3c() {
assert!(close(blend1(BlendMode::SoftLight, 0.25, 0.3), 0.25 - 0.4 * 0.25 * 0.75));
let d = ((16.0 * 0.25 - 12.0) * 0.25 + 4.0) * 0.25;
assert!(close(blend1(BlendMode::SoftLight, 0.25, 0.7), 0.25 + 0.4 * (d - 0.25)));
assert!(close(blend1(BlendMode::SoftLight, 0.5, 0.7), 0.5 + 0.4 * (0.5f32.sqrt() - 0.5)));
}
#[test]
fn burns_and_dodges_handle_edges() {
assert!(close(blend1(BlendMode::ColorBurn, 1.0, 0.0), 1.0));
assert!(close(blend1(BlendMode::ColorBurn, 0.5, 0.0), 0.0));
assert!(close(blend1(BlendMode::ColorDodge, 0.0, 1.0), 0.0));
assert!(close(blend1(BlendMode::ColorDodge, 0.5, 1.0), 1.0));
assert!(close(blend1(BlendMode::ColorDodge, 0.25, 0.5), 0.5));
for m in BlendMode::all() {
for a in AS {
for b in BS {
assert!(blend1(m, a, b).is_finite(), "{m:?} {a} {b}");
assert!(blend3(m, [a; 3], [b; 3]).iter().all(|v| v.is_finite()), "{m:?}");
}
}
}
}
#[test]
fn color_keeps_lower_luminance() {
let a = [0.2, 0.4, 0.6];
let out = blend3(BlendMode::Color, a, [1.0, 0.0, 0.0]);
assert!(close(lum(out), lum(a)));
}
#[test]
fn flat_normal_detail_is_identity() {
let flat = [0.5, 0.5, 1.0];
let n = pack([0.3, -0.2, 0.9]);
for m in [BlendMode::NormalMapDetail, BlendMode::NormalMapCombine] {
let out = blend3(m, n, flat);
for i in 0..3 {
assert!((out[i] - n[i]).abs() < 1e-4, "{m:?} {out:?} {n:?}");
}
}
}
#[test]
fn menu_lists_each_mode_once_and_parse_round_trips() {
let all: Vec<_> = BlendMode::all().collect();
assert_eq!(all.len(), 32);
for m in &all {
assert_eq!(all.iter().filter(|x| *x == m).count(), 1);
assert_eq!(BlendMode::parse(m.label()), Some(*m));
assert_eq!(BlendMode::parse(&format!("{m:?}")), Some(*m));
}
}
}