Add API for discovering assets #118410

andrewkolos · 2023-01-12T20:51:26Z

Supersedes #116621. This PR is largely the same.

Overview

This change introduces a public API for inspecting what assets are available within a Flutter app. Currently, there is no officially-supported way to do this, and some apps--needing this ability--depend on undocumented behavior internal to Flutter.

Example use case

The google_fonts package, when loading a font, first checks if the font is already available in the app. If it is not available, it will load it from fonts.google.com. Code.

Other known use cases:

Preemptively searching for available shaders and then warming them up via a call over a MethodChannel.
Dynamically listing assets (and maybe loading) all assets that match some criterion (e.g. are within some arbitrry directory).
Tests.

Context

Terminology

The asset manifest. The framework, when performing it's first asset load, has to load a file called the asset manifest, which contains information about assets available to the app (e.g. where to find higher-resolution variants of images). This is a JSON file that is created at build time by the tool. It is meant for framework-internal use--but some Flutter apps, including ones internal to Google, read the file directly.

Why make this change now

#117233 introduced a new, binary-formatted, version of the asset manifest that enables faster first-time asset resolution. Before updating the framework to use the new asset manifest and deprecating the older JSON manifest¹, we should take this opportunity to add this new API.

Design

We add a new class, AssetManifest, that is responsible for loading and parsing the asset manifest file contents from an AssetBundle. AssetManifest exposes two methods, one for listing all assets and one for listing the variants of a particular asset.

AssetBundle also gets a new method, loadStructuredBinaryData, to enable loading data from a binary asset. This new method is similar to the existing loadStructuredData, which is used for loading the JSON asset manifest.

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
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 documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
All existing and new tests are passing.

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

Normally, it might be fair to perform such a breaking change--without a deprecation cycle--because the asset manifest is not a publicly documented/supported concept. However, it's possible that some users, when consulting with Flutter maintainers, were told about the file and that they could use it to accomplish the asset-related behavior they were looking for. As a result, it would be unfair to break the older behavior without a full deprecation cycle. ↩

…t-api-2

packages/flutter/lib/src/services/asset_bundle.dart

packages/flutter/lib/src/services/asset_manifest.dart

jonahwilliams · 2023-01-19T18:05:57Z

packages/flutter/lib/src/services/asset_manifest.dart

+  });
+
+  /// The device pixel ratio that the asset is most ideal for, if any.
+  final double? targetDevicePixelRatio;


This would be null for any asset not in a 1x/2x subfolder right?

I would consider linking to the website assets page too.

This would be null for any asset not in a 1x/2x subfolder right?

Yup, exactly. I chose to be passive and not doc comment that specifically--just in case things change in the future. A link to the doc site seems like a good idea, though.

Not documenting how an API behaves is not a reasonable defense for changing the API in the future. If we need to change the behavior, we have criteria on the wiki for determining whether or not it qualifies as a breaking change.

Please document the behavior

If by "API" you are referring to how the ratio is derived from the file path, then I see your point. I made the doc string more informative and added a docsite link.

packages/flutter/lib/src/services/asset_manifest.dart

* 7d3b762 Fix: Added `margin` parameter for `MaterialBanner` class (flutter/flutter#119005) * 40bd82e Roll Plugins from 1e5efd144f93 to e9406bc209a2 (4 revisions) (flutter/flutter#119249) * 07522b7 Roll Flutter Engine from 8f1e5dc1b124 to 04f22beebb42 (5 revisions) (flutter/flutter#119218) * 459c1b7 Marks Mac complex_layout_scroll_perf_macos__timeline_summary to be unflaky (flutter/flutter#119157) * 2b8f2d0 Add API for discovering assets (flutter/flutter#118410) * a04ab71 Revert "Add API for discovering assets (#118410)" (flutter/flutter#119273) * 1da487d Roll Flutter Engine from 04f22beebb42 to 93901260098e (12 revisions) (flutter/flutter#119279) * 1b779b6 Roll Flutter Engine from 93901260098e to be0125bd5716 (2 revisions) (flutter/flutter#119283) * 42bd5f2 Download platform-agnostic Flutter Web SDK in the flutter_tool (flutter/flutter#118654) * d52b6b9 Roll Flutter Engine from be0125bd5716 to d17004dd96d7 (2 revisions) (flutter/flutter#119287) * 4aed487 Roll Flutter Engine from d17004dd96d7 to a63d98feb608 (3 revisions) (flutter/flutter#119299) * 05fc29f Rename DeviceGestureSettings.fromWindow to DeviceGestureSettings.fromView (flutter/flutter#119291) * 86ab01d Revert "Add --serve-observatory flag to run, attach, and test (#118402)" (flutter/flutter#119302) * 8d03af3 Roll Flutter Engine from a63d98feb608 to 79c958fc7e9b (3 revisions) (flutter/flutter#119306) * 27f8ebd ade610ec8 [fuchsia] Migrate to new RealmBuilder API (flutter/engine#39175) (flutter/flutter#119310)

* a0f7c8c 6f806491e [web] use a render target instead of a new surface for Picture.toImage (flutter/engine#38573) (flutter/flutter#119143) * e85547b Roll Plugins from 11361d0 to 8bab180 (28 revisions) (flutter/flutter#119115) * 81052a7 Add usage event to track when a iOS network device is used (flutter/flutter#118915) * cd34fa6 24aa324b8 Roll Skia from da5034f9d117 to c4b171fe5668 (1 revision) (flutter/engine#39127) (flutter/flutter#119159) * 6cd4fa4 Add --serve-observatory flag to run, attach, and test (flutter/flutter#118402) * 48cd95d 1e5efd1 [various] Enable use_build_context_synchronously (#6585) (flutter/flutter#119162) * b907acd Add the cupertino system colors mint, cyan, and brown (flutter/flutter#118971) * c6fa5d9 c54580138 Only build analyze_snapshot on Linux host (flutter/engine#39129) (flutter/flutter#119164) * f34ce86 7b72038ef Roll Fuchsia Linux SDK from E9m-Gk382PkB7_Nbp... to pGX7tanT1okL8XCg-... (flutter/engine#39130) (flutter/flutter#119169) * 0dd63d3 Export View (flutter/flutter#117475) * 1fd71de Remove superfluous words from comments (flutter/flutter#119055) * cef9cc7 2e7d6fa7b Remove unnecessary null checks (flutter/engine#39113) (flutter/flutter#119174) * 3be330a 30c02e4c8 [Impeller] Make text glyph offsets respect the current transform (flutter/engine#39119) (flutter/flutter#119179) * a45727d Add MediaQuery to View (flutter/flutter#118004) * 02a9c15 Fix lexer issue where select/plural/other/underscores cannot be in identifier names. (flutter/flutter#119190) * 766e4d2 Remove single-view assumption from material library (flutter/flutter#117486) * dcd3679 Roll Flutter Engine from 30c02e4c8b01 to 44362c90fcec (2 revisions) (flutter/flutter#119185) * 9037e3f roll packages (flutter/flutter#119192) * e0e88da Roll Flutter Engine from 44362c90fcec to 308ce918f67f (2 revisions) (flutter/flutter#119201) * 202e902 Roll Flutter Engine from 308ce918f67f to 8f1e5dc1b124 (4 revisions) (flutter/flutter#119208) * b319938 Add more flexible image API (flutter/flutter#118966) * fc02701 Marks Mac run_debug_test_macos to be unflaky (flutter/flutter#117470) * c9affdb Move windows-x64-flutter.zip to windows-x64-debug location. (flutter/flutter#119177) * 7d3b762 Fix: Added `margin` parameter for `MaterialBanner` class (flutter/flutter#119005) * 40bd82e Roll Plugins from 1e5efd1 to e9406bc (4 revisions) (flutter/flutter#119249) * 07522b7 Roll Flutter Engine from 8f1e5dc1b124 to 04f22beebb42 (5 revisions) (flutter/flutter#119218) * 459c1b7 Marks Mac complex_layout_scroll_perf_macos__timeline_summary to be unflaky (flutter/flutter#119157) * 2b8f2d0 Add API for discovering assets (flutter/flutter#118410) * a04ab71 Revert "Add API for discovering assets (#118410)" (flutter/flutter#119273) * 1da487d Roll Flutter Engine from 04f22beebb42 to 93901260098e (12 revisions) (flutter/flutter#119279) * 1b779b6 Roll Flutter Engine from 93901260098e to be0125bd5716 (2 revisions) (flutter/flutter#119283) * 42bd5f2 Download platform-agnostic Flutter Web SDK in the flutter_tool (flutter/flutter#118654) * d52b6b9 Roll Flutter Engine from be0125bd5716 to d17004dd96d7 (2 revisions) (flutter/flutter#119287) * 4aed487 Roll Flutter Engine from d17004dd96d7 to a63d98feb608 (3 revisions) (flutter/flutter#119299) * 05fc29f Rename DeviceGestureSettings.fromWindow to DeviceGestureSettings.fromView (flutter/flutter#119291) * 86ab01d Revert "Add --serve-observatory flag to run, attach, and test (#118402)" (flutter/flutter#119302) * 8d03af3 Roll Flutter Engine from a63d98feb608 to 79c958fc7e9b (3 revisions) (flutter/flutter#119306) * 27f8ebd ade610ec8 [fuchsia] Migrate to new RealmBuilder API (flutter/engine#39175) (flutter/flutter#119310) * c31856b Roll Plugins from e9406bc to ff84c44 (2 revisions) (flutter/flutter#119335) * d939863 Roll Flutter Engine from ade610ec88b5 to 621e13cc9be3 (3 revisions) (flutter/flutter#119344) * 0b57596 Run "flutter update-packages --force-upgrade" (flutter/flutter#119340) * 0417f66 Fix nullability of TableRow.children (flutter/flutter#119285) * fc3e824 Roll Flutter Engine from 621e13cc9be3 to 189a69d9918d (3 revisions) (flutter/flutter#119347) * ad1a44d Add `requestFocusOnTap` to `DropdownMenu` (flutter/flutter#117504) * 4dbb573 [flutter_tools] remove usage of remap samplers arg (flutter/flutter#119346) * b2f2bf3 Marks Linux run_release_test_linux to be unflaky (flutter/flutter#119156) * 3f95bef Roll Flutter Engine from 189a69d9918d to b32fc7fef208 (3 revisions) (flutter/flutter#119358) * 2e8bebd Remove single window assumption from macrobenchmark (flutter/flutter#119368) * ab2232a Roll Flutter Engine from b32fc7fef208 to 8567d96993ed (5 revisions) (flutter/flutter#119369) * e9ca9cc Remove references to dart:ui's window singelton (flutter/flutter#119296) * da3d4bd Roll Flutter Engine from 8567d96993ed to 225ae87334a5 (2 revisions) (flutter/flutter#119376) * 018c1f8 e2e089ebb Use arm64 engine variant on simulators in iOS unit tests (flutter/engine#39213) (flutter/flutter#119387) * e349bdc 19651cb1d Roll Dart SDK from 2cd9b7ac95e8 to 135f4c51c9ff (3 revisions) (flutter/engine#39214) (flutter/flutter#119389) * 95345b5 77bee011d Roll Dart SDK from 2cd9b7ac95e8 to 135f4c51c9ff (3 revisions) (flutter/engine#39217) (flutter/flutter#119394) * de43ec9 Roll Flutter Engine from 77bee011dabf to 3394b84cc5d7 (3 revisions) (flutter/flutter#119405) * f8d4de4 3dd0fc13f Roll Fuchsia Linux SDK from 6c2H32X3EXOGlWIgb... to TiK_fVODtUaKOgxRf... (flutter/engine#39224) (flutter/flutter#119408) * 7856411 7c5c6c9c9 Roll Skia from 0b75650caf2a to 7df7a83f733d (13 revisions) (flutter/engine#39225) (flutter/flutter#119413) * 75680ae 649362168 Roll Dart SDK from f9583e13e214 to 52dc94238144 (1 revision) (flutter/engine#39227) (flutter/flutter#119416)

andrewkolos added 3 commits January 12, 2023 12:00

add asset manifest bin loading and asset manifest api

fd5a0cc

Merge branch 'master' into add-asset-manifest-api-2

c70d5cb

use new api for image resolution

2828bf4

flutter-dashboard bot added framework flutter/packages/flutter repository. See also f: labels. c: contributor-productivity Team-specific productivity, code health, technical debt. labels Jan 12, 2023

andrewkolos added the tool Affects the "flutter" command-line tool. See also t: labels. label Jan 12, 2023

andrewkolos added 6 commits January 12, 2023 13:14

remove upfront smc data casting

aa86d59

fix typecasting issue

82859e6

remove unused import

ce8cd3e

fix tests

5e3b9cd

lints

4ccf193

lints

668315d

andrewkolos force-pushed the add-asset-manifest-api-2 branch from 327cbee to 668315d Compare January 13, 2023 08:33

andrewkolos added 5 commits January 13, 2023 00:33

fix import

542de1e

Merge remote-tracking branch 'upstream/master' into add-asset-manifes…

62a659c

…t-api-2

revert image resolution changes

21e2ad0

Update image_resolution_test.dart

7eb05aa

Update decode_and_parse_asset_manifest.dart

29d4f98

andrewkolos changed the title ~~speedup first asset load~~ Add AssetManifest API Jan 13, 2023

Merge remote-tracking branch 'upstream/master' into add-asset-manifes…

9e27218

…t-api-2

andrewkolos mentioned this pull request Jan 19, 2023

[tracking] Speed up asset manifest loading and parsing #117228

Closed

make targetDevicePixelRatio optional

d20b729

This was referenced Jan 19, 2023

Add API for discovering assets #116621

Closed

Speed up first asset load by using the binary-formatted asset manifest for image resolution #118782

Merged

andrewkolos requested a review from jonahwilliams January 19, 2023 17:14

andrewkolos marked this pull request as ready for review January 19, 2023 17:14

andrewkolos changed the title ~~Add AssetManifest API~~ Add API for discovering assets Jan 19, 2023

jonahwilliams reviewed Jan 19, 2023

View reviewed changes

packages/flutter/lib/src/services/asset_manifest.dart Outdated Show resolved Hide resolved

jonahwilliams reviewed Jan 19, 2023

View reviewed changes

packages/flutter/lib/src/services/asset_manifest.dart Outdated Show resolved Hide resolved

This was referenced Jan 27, 2023

Roll Flutter from c9affdba9dcd to 27f8ebdaed70 (15 revisions) flutter/packages#3098

Merged

Roll Flutter from a815ee634202 to 27f8ebdaed70 (38 revisions) flutter/plugins#7037

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/plugins that referenced this pull request Jan 27, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

6ed23ba

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jan 27, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

0c78ce2

engine-flutter-autoroll mentioned this pull request Jan 27, 2023

Roll Flutter from a815ee634202 to c31856bc4859 (39 revisions) flutter/plugins#7039

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/plugins that referenced this pull request Jan 27, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

170e80d

engine-flutter-autoroll mentioned this pull request Jan 27, 2023

Roll Flutter from a815ee634202 to d939863a2638 (40 revisions) flutter/plugins#7040

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/plugins that referenced this pull request Jan 27, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

beee108

engine-flutter-autoroll mentioned this pull request Jan 27, 2023

Roll Flutter from a815ee634202 to 0417f6621eaa (42 revisions) flutter/plugins#7041

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/plugins that referenced this pull request Jan 27, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

4987ead

engine-flutter-autoroll mentioned this pull request Jan 27, 2023

Roll Flutter from a815ee634202 to fc3e8243cab5 (43 revisions) flutter/plugins#7042

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/plugins that referenced this pull request Jan 27, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

5ddd12a

engine-flutter-autoroll mentioned this pull request Jan 27, 2023

Roll Flutter from a815ee634202 to ad1a44d0a702 (44 revisions) flutter/plugins#7044

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/plugins that referenced this pull request Jan 27, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

001cf0a

engine-flutter-autoroll mentioned this pull request Jan 28, 2023

Roll Flutter from a815ee634202 to 75680ae99e85 (58 revisions) flutter/plugins#7047

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/plugins that referenced this pull request Jan 28, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

ce4b36a

engine-flutter-autoroll mentioned this pull request Jan 28, 2023

Roll Flutter from a815ee634202 to 75680ae99e85 (58 revisions) flutter/plugins#7048

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/plugins that referenced this pull request Jan 28, 2023

2b8f2d0 Add API for discovering assets (flutter/flutter#118410)

56e0ede

andrewkolos mentioned this pull request Jan 30, 2023

bump google_fonts from ^3.0.1 to ^4.0.1 flutter/gallery#876

Merged

8 tasks

andrewkolos deleted the add-asset-manifest-api-2 branch April 21, 2023 19:53

andrewkolos mentioned this pull request Jun 6, 2023

[tool] the load_and_parse_large_asset_manifest benchmark doesn't use the intended example asset manifest #128303

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add API for discovering assets #118410

Add API for discovering assets #118410

Uh oh!

andrewkolos commented Jan 12, 2023 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jonahwilliams Jan 19, 2023

Uh oh!

andrewkolos Jan 20, 2023

Uh oh!

jonahwilliams Jan 23, 2023

Uh oh!

andrewkolos Jan 23, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Add API for discovering assets #118410

Add API for discovering assets #118410

Uh oh!

Conversation

andrewkolos commented Jan 12, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Example use case

Context

Terminology

Why make this change now

Design

Pre-launch Checklist

Footnotes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jonahwilliams Jan 19, 2023

Choose a reason for hiding this comment

Uh oh!

andrewkolos Jan 20, 2023

Choose a reason for hiding this comment

Uh oh!

jonahwilliams Jan 23, 2023

Choose a reason for hiding this comment

Uh oh!

andrewkolos Jan 23, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andrewkolos commented Jan 12, 2023 •

edited

Loading