understory_imaging

[waywardmonkeys]

Add understory_imaging imaging IR crate

This PR adds understory_imaging, a backend‑agnostic imaging IR that sits between the presentation/display layer and concrete render backends (Vello CPU/Hybrid/Classic, Skia, etc.).

The crate defines:

• Opaque resource handles: PathId, ImageId, PaintId, PictureId, FilterId with PathDesc, ImageDesc,
  PaintDesc, PictureDesc descriptors, managed via a ResourceBackend trait. IDs are small, stable handles reused
  across frames and recordings for the lifetime of each resource.
• Imaging operations: StateOp (transform, paint, stroke, clip, blend, opacity, groups) and DrawOp (fill/
  stroke path/rect, draw image/picture), combined into ImagingOp as a POD‑friendly IR suitable for recording
  and caching.
• Backend interface: an ImagingBackend trait that extends ResourceBackend with state/draw entry points and a
  basic recording API (begin_record/end_record), plus helpers record_ops and record_picture to capture short
  sequences as reusable recordings or pictures.
• Recordings model: RecordedOps wraps an Arc<[ImagingOp]> plus optional backend‑specific acceleration and
  transform metadata (valid_under: TransformClass, original_ctm). Recordings are explicitly environment‑bound:
  all referenced resource IDs must exist and remain compatible when replayed.
• Transform classification: TransformClass and transform_diff_class provide a conservative way to decide when
  cached/recorded content can be safely reused under a new transform (distinguishing exact, translate‑only, and
  general affine differences).

The crate is no_std and currently targets the needs of early Vello/Skia backends. The overall goals, architecture, and future directions are documented in docs/issue_understory_imaging.md; the crate‑level docs give a condensed overview and a minimal usage sketch for backend implementors.

[tomcur]

Indeed! ClipShape::RoundedRect is already in

[no-materials]

I wonder if opacity needs to be reset (back to 1.0) to avoid leaking state across display-list entries...the conditional SetOpacity only fires when opacity != 1, so an image can drop opacity and nothing bumps it back, leaving later ops dimmer than intended.

[tomcur]

Should "failing loudly" be an explicit panic? Handling the format wrong would likely cause panics further down the road.

[tomcur]

We may want an operation that says whether clipping is to be anti-aliased or not, for backends that make a distinction (like Skia), or we may want to say that backends should use the highest-quality clipping available.

[tomcur]

Skia supports rounded rectangle clips, so I think this can be something like the following.

Suggested change

	let rect = sk::Rect::new(x0, y0, x1, y1);
	let mut path = sk::Path::new();
	path.add_round_rect(rect, (radius_x, radius_y), None);
	self.canvas.save();
	self.canvas.clip_path(&path, None, true);
	self.clip_depth = self.clip_depth.saturating_add(1);
	let rect = sk::Rect::new(x0, y0, x1, y1);
	let rrect = sk::RRect::new_rect_xy(&rect, radius_x, radius_y);
	self.canvas.save();
	self.canvas.clip_rrect(&rrect, None, true);
	self.clip_depth = self.clip_depth.saturating_add(1);