I'm not sure I understand what extreme aspect ratio is concretely and why are we doing something special in that case and what happens if we just followed the 3 instead of 2.

So if we used 3 instead of 2 in this "extreme" case, then the shape would still look noticeably flat on the edges instead of rounded like with the search bar on native iOS.

Here too. Don't use subjective words. Quantify and explain why those numbers are important.

I'm still confused about these various usages of concave vs convex. Isn't the shape always convex? When does it become concave? Or are you describing the path drawing glitch caused by this specific implementation of the bezier curve when it clips?

I now realize that a lozenge isn't actually convex. But yah a lozenge doesn't correctly describe the shape that the curves make when they clip as the shape in reality is more like |X| with a lozenge in middle. Which is a convex shape.

I think we're mixing a bunch of things.

If we're talking about these shapes assuming we produce protruding rendering artifacts when the shapes clip, then:

• If it doesn't clip, it's a simple non-intersecting polygon that is convex
• If it does clip, it is a non-simple self-intersecting polygon (which by definition is neither convex nor concave).
  We shouldn't do this since the fact that we produce rendering artifacts is an implementation detail that we use bezier curves and has nothing to do with superellipses themselves.

If we're talking about these shapes assuming we don't render protruding artifacts (e.g. we end up producing a lozenge), then:

• If it doesn't clip (n>2), it's a simple non-intersecting polygon that is convex.
• If it does clip (n<2), then it is still a simple non-intersecting polygon that is convex

How is this number derived?

By visual approximation and comparison with the native Cupertino search bar rounded rect.

Then it should be in Cupertino.

Why is this needed? Do we think apple is doing this?

This is to make a more rounded, stadium-esque shape at a small width or height. And yah, I believe apple does this for their search bar.

Same here, then this in-between-superellipse-and-stadium-ness should be in cupertino.

Skia team had a discussion about this "squircles" about 1.5 years ago. It seems that Skia wanted to add something like bool SkPath::asSuperellipse(SkRect*, int* exp); but it's not there yet.

From my own CPU path rasterization experience, cubics are more expensive than quadratics. Although it's unlikely to be a bottleneck for the whole app, it might be safer to just use quadratics as I heard that you can either use a single cubic or 2 quadratics to approximate the squircle.

CC Skia's GPU guru @bsalomon @csmartdalton here for comments about cubics vs. quadratics performance on GPU.

Of course, it would be better if Skia just added bool SkPath::asSuperellipse(SkRect*, int* exp); API so it can freely change the most performant implementation without Flutter modifying the source code. Not sure if the benefit is worth the maintenance cost (CC @reed-at-google ).

The shapes are not yet linked as this PR needs to land before the shape images can be generated. Tho you should be able to see the shapes at this link: https://github.com/flutter/assets-for-api-docs/pull/55/files

Same here. If quadratics can be used, I think they're usually more preferred than cubics from Skia's perspective. My anecdotal experience also told me that cubics are more prone to bugs and rendering artifacts than quadratics since Skia has to handle many more edge cases for cubics than quadratics. Skia's major clients such as Chrome and Anroid probably use much more quadratics than cubics which makes quadratics better tested. @reed-at-google : please correct me if my impression were wrong.

cubic paths are definitely present in our framework. If they're prone to bugs or rendering artifacts, we should make a concerted effort to remove them from our codebase and remove the API until ready.

Oh, cubics definitely passes Skia's quality control which means that it's fast and correct probably 99.99% of the time. It's just that quadratics are even faster and more reliable. So if it's easy to use quadratics instead cubics, we'll prefer quadratics.

This is already implied in the previous sentence. I would just remove this.

This still reads like too much math in the sentence. Just "Therefore, with 2 corners per side, the height or width needs to be minimally ~1.5 * 2 = ~3 times the length of the radius to accommodate the smooth corner transitions."

"... needed to render this rectangle before reducing the radius."

Otherwise, it might sound like we can't render this rectangle at all.

I'm asking what's the motivation for doing something special for smaller sizes and not have one single set of rules. The users will be wondering too after reading this paragraph.

Each field's doc must be able to stand on its own. Mention here too the fact that the value you put in isn't always what actually gets drawn.

Then it should be in Cupertino.

Same here, then this in-between-superellipse-and-stadium-ness should be in cupertino.

I think this was copy pasted but doesn't fit in the flow of the paragraphs here. Make sure this doc reads right.

Don't change the value of incoming function parameters. Make new variables.