Merge outside PR #476: fix(xfl): read shape hints written as morphHintsList (M8)

# Conflicts:
#	CHANGELOG.md
This commit is contained in:
Tanish Manku committed 2026-11-19 14:42:00 -07:00
commit 2ac002c364
6 files changed
+171 -8

No files matched your search

+4
View File
@@ -5,6 +5,10 @@
* **Double-click the Hand tool to fit the stage in the window** (#457, M8). A single click
still selects the Hand tool without changing the view.
* **Fixed: shape hints were lost when opening Animate files.** Animate saves a shape tween's
hints as `morphHintsList`, which the XFL and `.fla` importer didn't read, so tweens came in
without them. They now come across with their letters and points.
* **Themes of your own** (#340, ADR 0117, M8): a theme is a small JSON file that names colours
for the interface's roles, kept in `themes` in the settings folder (`data/themes` in a
portable copy).
+14 -8
View File
@@ -772,7 +772,7 @@ impl<'a> Builder<'a> {
}
// Shape hints sit on both keyframes of a shape tween; they are paired up below.
let shape_hints = craft_xfl::shape_hints::ShapeHints::new(f);
if !shape_hints.is_empty() {
if !shape_hints.is_empty() || crate::morph_hints::list(f).next().is_some() {
raw_hints.insert(start, self.raw_hints(f));
}
// Frame scripts are kept verbatim (ADR 0013 tier 1); those in the subset run.
@@ -899,20 +899,26 @@ impl<'a> Builder<'a> {
/// hint; it gives its point on this keyframe as `x`/`y` (or `startPoint="x, y"`, or
/// `startX`/`startY`), and may carry its end point too (`endPoint`, or `endX`/`endY`);
/// otherwise the end comes from the same hint on the next keyframe. Points are in pixels.
/// The order is `index` (or a letter `name`), else the order in the file.
/// The order is `index` (or a letter `name`), else the order in the file. Without
/// `shapeHints`, Animate's own `morphHintsList` is read (`morph_hints`).
fn raw_hints(&mut self, frame: &X) -> Vec<RawHint> {
const MAX_LISTED: usize = anicraft_doc::MAX_SHAPE_HINTS * 4;
let hints = craft_xfl::shape_hints::ShapeHints::new(frame);
let to_vec = |point: Option<craft_xfl::shape_hints::Point>| {
point.map(|point| Vec2::new(point.x, point.y)).filter(|point| point.x.abs() < 1e6 && point.y.abs() < 1e6)
let to_vec = |point: Option<craft_xfl::shape_hints::Point>| point.map(|point| Vec2::new(point.x, point.y));
let listed: Vec<(Option<usize>, Option<Vec2>, Option<Vec2>)> = if hints.is_empty() {
crate::morph_hints::list(frame).take(MAX_LISTED).map(|hint| (None, hint.start, hint.end)).collect()
} else {
hints.iter().take(MAX_LISTED).map(|hint| (hint.index(), to_vec(hint.start_point()), to_vec(hint.end_point()))).collect()
};
let in_range = |point: Option<Vec2>| point.filter(|point| point.x.abs() < 1e6 && point.y.abs() < 1e6);
let mut out: Vec<RawHint> = Vec::new();
for (n, hint) in hints.iter().enumerate().take(anicraft_doc::MAX_SHAPE_HINTS * 4) {
let order = hint.index().unwrap_or(n);
let Some(here) = to_vec(hint.start_point()) else {
for (n, (index, here, end)) in listed.into_iter().enumerate() {
let order = index.unwrap_or(n);
let Some(here) = in_range(here) else {
self.report.skip("shape hints without a position");
continue;
};
out.push(RawHint { order, here, end: to_vec(hint.end_point()) });
out.push(RawHint { order, here, end: in_range(end) });
}
out.sort_by_key(|h| h.order);
if out.len() > anicraft_doc::MAX_SHAPE_HINTS {
+1
View File
@@ -9,6 +9,7 @@
pub mod edges;
mod end_record;
pub mod import;
mod morph_hints;
pub mod text;
pub mod video;
/// The shared XML reader (`anicraft-xml`), under its old path.
+108
View File
@@ -0,0 +1,108 @@
//! Shape hints as Animate saves them (ADR 0023).
//!
//! Animate writes a shape tween's hints as a `<morphHintsList>` on the keyframe that starts the
//! tween, one `<MorphHint startPoint="x, y" endPoint="x, y" key="…"/>` per hint in letter order
//! (`a` first), each record carrying its point on both keyframes. Learned by observing files
//! Animate saved; no Animate code involved.
//!
//! Each coordinate is decimal or `#` hex fixed point (signed 24.8, as in `edges`), in units of
//! 256 twips: `#FFFFFB.FB, #0.84` is (-1029, 132) twips, a vertex of the start shape. `key` is
//! 0 in every file seen and is not read; nor is the `<morphHintsList>` inside a frame's
//! `<MorphShape>`, which was empty in every file seen.
//!
//! craft-xfl's `shape_hints` reads only the `<shapeHints>` spelling; this belongs there.
use crate::xml::Element as X;
use anicraft_geom::Vec2;
/// One native unit is 256 twips.
const TWIPS_PER_UNIT: f32 = 256.0;
const TWIPS_PER_PIXEL: f32 = 20.0;
/// One `<MorphHint>`: its points in pixels on the start and end keyframes, each `None` when
/// missing or malformed.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct MorphHint {
pub start: Option<Vec2>,
pub end: Option<Vec2>,
}
/// The hints a frame lists in `<morphHintsList>`, in file order (any child counts as a hint).
pub(crate) fn list(frame: &X) -> impl Iterator<Item = MorphHint> + '_ {
frame.list("morphHintsList").iter().map(|h| MorphHint { start: point(h, "startPoint"), end: point(h, "endPoint") })
}
/// A `"x, y"` attribute in pixels.
fn point(hint: &X, name: &str) -> Option<Vec2> {
let mut parts = hint.attr(name)?.split([',', ' ']).filter(|p| !p.trim().is_empty());
let (x, y) = (number(parts.next()?)?, number(parts.next()?)?);
parts.next().is_none().then(|| Vec2::new(x * TWIPS_PER_UNIT / TWIPS_PER_PIXEL, y * TWIPS_PER_UNIT / TWIPS_PER_PIXEL))
}
/// A decimal number, or `#` hex fixed point: up to eight whole digits (two's complement once
/// shifted into 24.8) and up to two fraction digits (a single one is the high nibble).
fn number(s: &str) -> Option<f32> {
let s = s.trim();
let value = match s.strip_prefix('#') {
Some(hex) => {
let (whole, frac) = hex.split_once('.').unwrap_or((hex, ""));
let digits = |d: &str| d.bytes().all(|b| b.is_ascii_hexdigit());
if !digits(whole) || !digits(frac) || whole.len() > 8 || frac.len() > 2 || (whole.is_empty() && frac.is_empty()) {
return None;
}
let whole = if whole.is_empty() { 0 } else { u32::from_str_radix(whole, 16).ok()? };
let frac = if frac.is_empty() { 0 } else { u32::from_str_radix(frac, 16).ok()? << if frac.len() == 1 { 4 } else { 0 } };
(whole.wrapping_shl(8) | frac) as i32 as f32 / 256.0
}
None => s.parse::<f32>().ok()?,
};
value.is_finite().then_some(value)
}
#[cfg(test)]
mod tests {
use super::*;
fn frame(xml: &str) -> X {
crate::xml::parse(xml.as_bytes()).unwrap()
}
#[test]
fn reads_hex_and_decimal_points_in_units_of_256_twips() {
let f = frame(
r##"<DOMFrame><morphHintsList>
<MorphHint startPoint="#FFFFFB.FB, #0.84" endPoint="#FFFFFC.3B, -0.0078125" key="0"/>
<MorphHint startPoint="#29.D4, 4.76953125" endPoint="#28.A, #5" key="0"/>
</morphHintsList></DOMFrame>"##,
);
let hints: Vec<_> = list(&f).collect();
assert_eq!(hints.len(), 2);
// (-1029, 132) twips; (-965, -2) twips.
assert_eq!(hints[0].start, Some(Vec2::new(-1029.0 / 20.0, 132.0 / 20.0)));
assert_eq!(hints[0].end, Some(Vec2::new(-965.0 / 20.0, -2.0 / 20.0)));
// (10708, 1221) twips; a single fraction digit is the high nibble: #28.A is 0x28A0.
assert_eq!(hints[1].start, Some(Vec2::new(10708.0 / 20.0, 1221.0 / 20.0)));
assert_eq!(hints[1].end, Some(Vec2::new(10400.0 / 20.0, 1280.0 / 20.0)));
}
#[test]
fn malformed_points_are_none_never_a_panic() {
let bad = [
"", ",", "1", "1,", "1, 2, 3", "#", "#.", "#G, 0", "#1.234, 0", "#123456789, 0", "nan, 0", "inf, 1", "1e40, 0", "#-1, 0",
"#+1, 0", "🙂, 1", "#FFFFFFFF.FF, #80000000",
];
for s in bad {
let f = frame(&format!(r#"<DOMFrame><morphHintsList><MorphHint startPoint="{s}"/></morphHintsList></DOMFrame>"#));
let hint = list(&f).next().unwrap();
assert_eq!(hint.end, None, "{s:?}");
// The two largest hex values still decode, to finite numbers.
if s.starts_with("#FFFFFFFF") {
assert!(hint.start.is_some_and(|p| p.x.is_finite() && p.y.is_finite()));
} else {
assert_eq!(hint.start, None, "{s:?}");
}
}
assert_eq!(list(&frame("<DOMFrame/>")).count(), 0);
assert_eq!(list(&frame("<DOMFrame><morphHintsList/></DOMFrame>")).count(), 0);
}
}
+38
View File
@@ -434,6 +434,44 @@ fn shape_hints_come_across_in_either_form() {
}
}
#[test]
fn shape_hints_come_across_as_animate_writes_them() {
// `morphHintsList` on the start keyframe, both points per record, in units of 256 twips:
// (0, 0) and (300, 50) px, the end as hex fixed point and decimal. The list inside
// `MorphShape` is not the artist's and is left alone.
let hint = r##"<MorphHint startPoint="0, #0" endPoint="#17.70, 3.90625" key="0"/>"##;
let doc = hinted_doc(&format!("<MorphShape><morphHintsList>{hint}{hint}</morphHintsList></MorphShape><morphHintsList>{hint}</morphHintsList>"), "");
let (d, report) = import(&HashMap::from([("DOMDocument.xml", doc)])).unwrap();
assert!(report.skipped.keys().all(|s| !s.contains("hint")), "{:?}", report.skipped);
let l = &d.timeline(0).layers[0];
let k = &l.keyframes[0];
assert_eq!(k.hints.len(), 1);
assert!(k.hints[0].start.distance(anicraft_geom::Vec2::new(0.0, 0.0)) < 1e-3, "{:?}", k.hints[0]);
assert!(k.hints[0].end.distance(anicraft_geom::Vec2::new(300.0, 50.0)) < 1e-3, "{:?}", k.hints[0]);
assert!(anicraft_doc::placed_on(&k.elements, k.hints[0].start).is_some());
assert!(anicraft_doc::placed_on(&l.keyframes[1].elements, k.hints[0].end).is_some());
// Either spelling gives the same hints.
let native = hinted_doc(r#"<shapeHints><ShapeHint startPoint="0, 0" endPoint="300, 50"/></shapeHints>"#, "");
let (n, _) = import(&HashMap::from([("DOMDocument.xml", native)])).unwrap();
assert_eq!(n.timeline(0).layers[0].keyframes[0].hints, k.hints);
}
#[test]
fn odd_morph_hints_are_reported_not_fatal() {
let many: String = (0..30).map(|_| r##"<MorphHint startPoint="0, 0" endPoint="#F.A0, 0"/>"##).collect();
let odd = r##"<MorphHint/><MorphHint startPoint="#zz, 1"/><MorphHint startPoint="1e39, 0"/><MorphHint startPoint="#7FFFFFFF.FF, #80000000" endPoint="#F.A0, 0"/>"##;
let doc = hinted_doc(&format!("<morphHintsList>{odd}{many}<Other startPoint=\"0, 0\"/></morphHintsList>"), "");
let (d, report) = import(&HashMap::from([("DOMDocument.xml", doc)])).unwrap();
assert_eq!(d.timeline(0).layers[0].keyframes[0].hints.len(), 26);
assert!(report.skipped.contains_key("shape hints past z"), "{:?}", report.skipped);
assert!(report.skipped.contains_key("shape hints without a position"));
// No end point, and no hints on the end keyframe to take one from.
let doc = hinted_doc(r#"<morphHintsList><MorphHint startPoint="0, 0" endPoint="0"/></morphHintsList>"#, "");
let (d, report) = import(&HashMap::from([("DOMDocument.xml", doc)])).unwrap();
assert!(d.timeline(0).layers[0].keyframes[0].hints.is_empty());
assert!(report.skipped.contains_key("shape hints missing on the end keyframe"));
}
#[test]
fn odd_shape_hints_are_reported_not_fatal() {
let many: String = (0..30).map(|i| format!(r#"<ShapeHint index="{i}" startPoint="0, 0" endPoint="200, 0"/>"#)).collect();
+6
View File
@@ -77,6 +77,12 @@ literature on polygon and Bézier blending. Nothing was copied.
the next keyframe's `shapeHints`. Points within 2 px of an edge snap onto it. Hints past
`z`, without a position or without an end are reported, never fatal. If real files turn out
to use another layout, only this reader changes.
*Update (2026-11-18):* files Animate saves use another layout, a `<morphHintsList>` on the
tween's start keyframe with one `<MorphHint startPoint="x, y" endPoint="x, y" key="0"/>` per
hint in letter order; coordinates are decimal or `#` hex fixed point in units of 256 twips
(observed: they land exactly on the shapes' edge vertices). The importer reads that list
when a frame has no `shapeHints` (`crates/xfl/src/morph_hints.rs`); both map to the same
hints.
## Consequences