[Breaking Change Proposal] CustomPaint can't set raster cache hints with null painters

[Yuqian Li]

If your app does not use CustomPaint, you can stop reading now.

Summary

In the proposal (https://github.com/flutter/flutter/pull/49771), if one builds a CustomPaint widget with null painter and null foregroundPainter, then the assertion would trigger if isComplex or willChange is set to true.

Justification

Our old API doc on CustomPaint seems to suggest that one can use CustomPaint to affect the raster cache behaviors by setting isComplex and willChange flags even if painter and foregroundPainter are null. The fact is that CustomPaint is completely optimized away if both painters are null, and those flags are ignored.

To reduce confusions, we'll update the API doc and add this assertion so people won't misuse CustomPaint and have a false expectation on the performance implications.

Related issues

https://github.com/flutter/flutter/issues/49700

How to migrate

If you're using CustomPaint and the assertion triggers, simply remove the CustomPaint widget that triggers the assertion. It shouldn't have any visual or performance difference.

If you have any questions, please feel free to contact me and I'm very happy to help.

Thanks,

Yuqian