Skip to main content

qualia_core_db/hypermedia_authoring/
image_composite.rs

1//! Bounded, caller-output image layer composition in encoded RGBA8 space.
2//!
3//! Blend equations follow W3C Compositing and Blending Level 1, section 10.
4//! This is an artistic encoded-sample operator, not colour management.
5
6use super::{source_over, BlendMode, ImageDocument, ImageError, ImageLimits};
7
8/// Validate the complete source, including hidden layers, before writing output.
9/// Returns the exact number of document pixels required in the caller buffer.
10pub fn validate_document(doc: &ImageDocument, limits: ImageLimits) -> Result<usize, ImageError> {
11    let pixels = checked_pixels(doc.width, doc.height, limits)?;
12    let mut visits = pixels;
13    let mut bytes = pixels.checked_mul(4).ok_or(ImageError::Budget)?;
14    for layer in &doc.layers {
15        let layer_pixels = checked_pixels(layer.width, layer.height, limits)?;
16        if layer.pixels.len() != layer_pixels ||
17            layer.mask.as_ref().is_some_and(|mask| mask.len() != layer_pixels)
18        {
19            return Err(ImageError::Storage);
20        }
21        if !layer.opacity.is_finite() || !(0.0..=1.0).contains(&layer.opacity) {
22            return Err(ImageError::Parameters);
23        }
24        visits = visits.checked_add(layer_pixels).ok_or(ImageError::Budget)?;
25        let layer_bytes = layer_pixels.checked_mul(4).ok_or(ImageError::Budget)?;
26        bytes = bytes.checked_add(layer_bytes).ok_or(ImageError::Budget)?;
27        if layer.mask.is_some() {
28            bytes = bytes.checked_add(layer_pixels).ok_or(ImageError::Budget)?;
29        }
30        if visits > limits.max_work || bytes > limits.max_bytes {
31            return Err(ImageError::Budget);
32        }
33    }
34    if visits > limits.max_work || bytes > limits.max_bytes {
35        return Err(ImageError::Budget);
36    }
37    Ok(pixels)
38}
39
40fn checked_pixels(width: u32, height: u32, limits: ImageLimits) -> Result<usize, ImageError> {
41    if width == 0 || height == 0 {
42        return Err(ImageError::Dimensions);
43    }
44    let count = (width as usize).checked_mul(height as usize).ok_or(ImageError::Dimensions)?;
45    if count > limits.max_pixels {
46        return Err(ImageError::Dimensions);
47    }
48    Ok(count)
49}
50
51/// Compose into caller-owned storage. Every refusal occurs before the first write.
52pub fn composite_into(doc: &ImageDocument, out: &mut [[u8; 4]], limits: ImageLimits) -> Result<(), ImageError> {
53    let count = validate_document(doc, limits)?;
54    if out.len() != count {
55        return Err(ImageError::Output);
56    }
57    out.fill([0; 4]);
58    let dst_width = doc.width as usize;
59    for layer in &doc.layers {
60        if !layer.visible { continue; }
61        let x0 = (layer.offset_x as i64).max(0);
62        let y0 = (layer.offset_y as i64).max(0);
63        let x1 = (layer.offset_x as i64 + layer.width as i64).min(doc.width as i64);
64        let y1 = (layer.offset_y as i64 + layer.height as i64).min(doc.height as i64);
65        if x1 <= x0 || y1 <= y0 { continue; }
66        for y in y0..y1 {
67            let local_y = (y - layer.offset_y as i64) as usize;
68            for x in x0..x1 {
69                let local_x = (x - layer.offset_x as i64) as usize;
70                let source_index = local_y * layer.width as usize + local_x;
71                let dest_index = y as usize * dst_width + x as usize;
72                let coverage = layer.opacity * layer.mask.as_ref()
73                    .map_or(1.0, |mask| mask[source_index] as f32 / 255.0);
74                let source = layer.pixels[source_index];
75                let backdrop = out[dest_index];
76                out[dest_index] = if layer.blend_mode == BlendMode::Normal {
77                    // This preserves the established Normal byte rounding, including
78                    // unmasked zero-offset legacy documents.
79                    source_over::rgba(source, backdrop, coverage)
80                } else {
81                    blend_over(source, backdrop, coverage, layer.blend_mode)
82                };
83            }
84        }
85    }
86    Ok(())
87}
88
89fn blend_over(source: [u8; 4], backdrop: [u8; 4], coverage: f32, mode: BlendMode) -> [u8; 4] {
90    let sa = source[3] as f32 / 255.0 * coverage;
91    let ba = backdrop[3] as f32 / 255.0;
92    let alpha = sa + ba * (1.0 - sa);
93    if alpha <= 0.0 { return [0; 4]; }
94    let mut result = [0; 4];
95    for channel in 0..3 {
96        let cs = source[channel] as f32 / 255.0;
97        let cb = backdrop[channel] as f32 / 255.0;
98        // The backdrop-alpha interpolation makes blend modes reduce to the
99        // unmodified source over a transparent backdrop.
100        let blended_source = (1.0 - ba) * cs + ba * blend_channel(cb, cs, mode);
101        let premultiplied = sa * blended_source + ba * (1.0 - sa) * cb;
102        result[channel] = ((premultiplied / alpha) * 255.0).round().clamp(0.0, 255.0) as u8;
103    }
104    result[3] = (alpha * 255.0).round().clamp(0.0, 255.0) as u8;
105    result
106}
107
108fn blend_channel(cb: f32, cs: f32, mode: BlendMode) -> f32 {
109    match mode {
110        BlendMode::Normal => cs,
111        BlendMode::Multiply => cb * cs,
112        BlendMode::Screen => cb + cs - cb * cs,
113        BlendMode::Overlay => hard_light(cs, cb),
114        BlendMode::HardLight => hard_light(cb, cs),
115        BlendMode::SoftLight => {
116            if cs <= 0.5 {
117                cb - (1.0 - 2.0 * cs) * cb * (1.0 - cb)
118            } else {
119                let d = if cb <= 0.25 {
120                    ((16.0 * cb - 12.0) * cb + 4.0) * cb
121                } else {
122                    cb.sqrt()
123                };
124                cb + (2.0 * cs - 1.0) * (d - cb)
125            }
126        }
127        BlendMode::ColorDodge => {
128            if cb <= 0.0 { 0.0 }
129            else if cs >= 1.0 { 1.0 }
130            else { (cb / (1.0 - cs)).min(1.0) }
131        }
132        BlendMode::ColorBurn => {
133            if cb >= 1.0 { 1.0 }
134            else if cs <= 0.0 { 0.0 }
135            else { 1.0 - ((1.0 - cb) / cs).min(1.0) }
136        }
137        BlendMode::Difference => (cb - cs).abs(),
138        BlendMode::Exclusion => cb + cs - 2.0 * cb * cs,
139    }
140}
141
142fn hard_light(cb: f32, cs: f32) -> f32 {
143    if cs <= 0.5 { 2.0 * cb * cs } else { 1.0 - 2.0 * (1.0 - cb) * (1.0 - cs) }
144}