Add ResizeImagePolicy.cover - #194665

This PR adds ResizeImagePolicy.cover. With this policy, ResizeImage decodes the image at the smallest size that covers the width x height box and keeps the aspect ratio of the image, like BoxFit.cover.

Problem

There is no resize policy that matches BoxFit.cover. A caller that paints with BoxFit.cover and does not know the aspect ratio of the image before the decode has two options:

• Use ResizeImagePolicy.fit, or set only one of cacheWidth and cacheHeight. For many aspect ratios, the decoded image is smaller than the box, so it is blurry when it is painted.
• Do not resize. The image is decoded at full size, which uses much more memory than necessary.

Change

• Add ResizeImagePolicy.cover. It requires both width and height (assert in the ResizeImage constructor).
• The aspect ratio comes from the intrinsic size that the decoder gives to getTargetSize, so the caller does not need to know the image size.
• The size calculation uses integer math and rounds up. The decoded image always covers the box, and a box that matches the aspect ratio of the image does not get an extra pixel. (With a double scale, a 3000x3000 image in a 448x256 box decodes at 449x449.)
• The image is not scaled up unless allowUpscaling is true. This is the same as the fit policy.
• Update the ResizeImagePolicy and ResizeImage docs.

Decoded sizes for a 640x360 box (physical pixels), with synthetic images:

cover is the only option that fills the box in all cases without a full-size decode. On a macOS host, a 4032x3024 JPEG decodes in approximately 102 ms with no resize (48.77 MB) and approximately 46 ms with cover into a 200x200 box (267x200, 0.21 MB), median of 25 runs.

Compatibility

This adds a value to a public enum. Code outside the framework that has a switch on ResizeImagePolicy with no default gets a compile-time error (non-exhaustive switch). In this repository (packages/ and dev/), only ResizeImage itself switches on ResizeImagePolicy.

Tests

Added tests in test/painting/image_provider_resize_image_test.dart for the cover policy: square, portrait, and landscape images in square, wide, and tall boxes, round-up of the other side, no extra pixel when the scale is exact, no upscaling by default, upscaling with allowUpscaling: true, and the assert when width or height is null.

Fixes #61987

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant in-code documentation (doc comments with ///).
• If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in flutter/website (or verified none is needed).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.