imaging_model: introduce initial clip-focused model types by waywardmonkeys · Pull Request #165 · linebender/peniko

waywardmonkeys · 2026-02-11T17:26:02Z

Introduce a first draft of the imaging_model crate with clip-focused model types. The goal is to establish a small, explicit core model that we can evolve as we define the imaging model and move our renderers to using it.

waywardmonkeys · 2026-02-11T17:27:46Z

imaging_model/src/clip.rs

+
+    /// Conservative axis-aligned bounds of this geometry.
+    ///
+    /// Returns `None` if the geometry bounds are non-finite.


Is this a reasonable guarantee to make?

I think I understand the point of making these return values options, it forces the client to consider the non-finite case, where in the current world there is substantial risk of nan values flowing through to consumers where they will more likely than not wreak havoc. I'm not sure I love it though, it feels like it adds nontrivial ceremony.

waywardmonkeys · 2026-02-11T17:29:18Z

imaging_model/src/clip.rs

+        return None;
+    }
+
+    // Conservative outset to account for width, caps, and miter joins.


Is the fact that this isn't accurate a reason to not do it? Should we drop Clip::bounds because of this? But we do call it out in the doc comment. But maybe we should call the function conservative_bounds instead?

I think it's ok, and having fast reasonably-accurate bounds is a useful feature. In practice, I think it will be very unlikely people will specify a miter limit greater than the default 4.0.

waywardmonkeys · 2026-02-11T17:30:28Z

imaging_model/src/clip.rs

+    Fill {
+        /// Transform applied to the clip shape.
+        ///
+        /// This does not affect subsequent draws; it only affects how the clip shape is interpreted.


At some point, we should identify the semantics of this transform: coordinate space, when it is applied, etc.

Indeed. It might be worth looking at the 1982 Warnock and Wyatt paper, as they are quite precise about this, and in many ways, that work is closer to the modern imaging model work than the PS/Cairo/HTML5 evolution; in particular, geometry for clip/fill/stroke is an object passed to the drawing method rather than belonging to graphics state.

The "subsequent draws" language is not great as normative documentation, as it implies a temporal sequencing. I think a more precise way of saying this is that the transform is applied to the clip geometry but not to the content affected by the clip.

Introduce a first draft of the `imaging_model` crate with clip-focused model types. The goal is to establish a small, explicit core model that we can evolve as we define the imaging model and move our renderers to using it.

AustinMReppert · 2026-02-16T03:48:48Z

What was the selection criteria for these clip geometries? Are you planning to add other shapes like polygons, circles, ellipses, text, etc. in the future?

waywardmonkeys · 2026-02-16T05:02:46Z

What was the selection criteria for these clip geometries? Are you planning to add other shapes like polygons, circles, ellipses, text, etc. in the future?

These are ones that we've commonly talked about having fast paths for due to how common they are in actual usage.

There could be some others in the future, especially if we saw an opportunity to have a fast path for them.

(Clipping to text would be more likely to use clipping to a path or stroke, not something dedicated. That's already supported in this model.)

raphlinus

I'm inclined to approve this (modulo the comments) but I have some concerns about the direction.

I don't feel I yet 100% understand the scope of the imaging_model crate. It seems like it can potentially abstract over some of the rendering functionality. I'm wondering whether SkPicture like functionality is envisioned as ultimately being in scope.

From what I can see, one of the biggest potential benefits is the ability to abstract over imaging operations that are actually provisioned by a system compositor (for example, in CALayer by creating a CAShapeLayer for the Bézier path and then setting that as the mask of the layer to be clipped). From that perspective, I expect the scope to include operations provided by a rich compositor, which includes opacity and blending, filter effects, and perhaps a bit more (but probably not everything in Core Animation, the particle effects stuff).

I'm going to reserve judgment for now about taking a dependency on imaging_model from Vello; I can be convinced but I'm also seeing some risks.

raphlinus · 2026-02-17T02:29:08Z

imaging_model/src/clip.rs

+        /// Transform applied to the clip shape.
+        ///
+        /// This does not affect subsequent draws; it only affects how the clip shape is interpreted.
+        transform: Affine,


It's not obvious to me why the transform belongs in the clip geometry object, it feels to me it belongs either in the graphics state or as an argument to the clip method.

raphlinus · 2026-02-17T02:42:16Z

imaging_model/src/clip.rs

+    Fill {
+        /// Transform applied to the clip shape.
+        ///
+        /// This does not affect subsequent draws; it only affects how the clip shape is interpreted.


Indeed. It might be worth looking at the 1982 Warnock and Wyatt paper, as they are quite precise about this, and in many ways, that work is closer to the modern imaging model work than the PS/Cairo/HTML5 evolution; in particular, geometry for clip/fill/stroke is an object passed to the drawing method rather than belonging to graphics state.

The "subsequent draws" language is not great as normative documentation, as it implies a temporal sequencing. I think a more precise way of saying this is that the transform is applied to the clip geometry but not to the content affected by the clip.

raphlinus · 2026-02-17T02:53:23Z

imaging_model/src/clip.rs

+    }
+
+    // Conservative outset to account for width, caps, and miter joins.
+    let outset = 0.5 * stroke.width.abs() * stroke.miter_limit.abs().max(1.0);


You only need to account for the miter limit when the the stroke's join is Join::Miter.

Also, I'm not sure whether the .abs().max(1.0) belongs here, or should be treated as validation. According to W3C spec, values less than 1 are invalid. We don't (currently) document that in kurbo, but arguably should.

raphlinus · 2026-02-17T02:56:42Z

imaging_model/src/clip.rs

+
+    /// Conservative axis-aligned bounds of this geometry.
+    ///
+    /// Returns `None` if the geometry bounds are non-finite.


I think I understand the point of making these return values options, it forces the client to consider the non-finite case, where in the current world there is substantial risk of nan values flowing through to consumers where they will more likely than not wreak havoc. I'm not sure I love it though, it feels like it adds nontrivial ceremony.

raphlinus · 2026-02-17T02:56:58Z

imaging_model/src/clip.rs

+    Stroke {
+        /// Transform applied to the clip shape.
+        ///
+        /// This does not affect subsequent draws; it only affects how the clip shape is interpreted.


Here's a question for you: is the transform applied to the geometry before stroking, or after? I believe the right answer is the latter, but it needs to be clear.

raphlinus · 2026-02-17T03:27:56Z

imaging_model/src/clip.rs

+        fill_rule: Fill,
+    },
+    /// Clip to the filled outline of a stroked shape.
+    Stroke {


This raises some questions. In some use cases, for example drawing to HTML5 canvas or making SVG output, implementing this requires path-to-path stroke expansion, which increases binary size. And, as far as I can tell, the capability isn't required by any existing 2D content, so it's not 100% clear to me what the motivation is for including it.

raphlinus · 2026-02-17T03:31:57Z

imaging_model/src/clip.rs

+        return None;
+    }
+
+    // Conservative outset to account for width, caps, and miter joins.


I think it's ok, and having fast reasonably-accurate bounds is a useful feature. In practice, I think it will be very unlikely people will specify a miter limit greater than the default 4.0.

waywardmonkeys requested a review from raphlinus February 11, 2026 17:26

waywardmonkeys commented Feb 11, 2026

View reviewed changes

waywardmonkeys force-pushed the initial-imaging_model branch from 313bb12 to aed02d7 Compare February 11, 2026 17:34

imaging_model: introduce initial clip-focused model types

593ac1b

Introduce a first draft of the `imaging_model` crate with clip-focused model types. The goal is to establish a small, explicit core model that we can evolve as we define the imaging model and move our renderers to using it.

waywardmonkeys force-pushed the initial-imaging_model branch from aed02d7 to 593ac1b Compare February 12, 2026 02:37

raphlinus reviewed Feb 17, 2026

View reviewed changes

Comments

Conversation

waywardmonkeys commented Feb 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AustinMReppert commented Feb 16, 2026

Uh oh!

waywardmonkeys commented Feb 16, 2026

Uh oh!

raphlinus left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants