Add more documentation on asset management

Author: krisgiesing

assets-and-images.md

@@ -0,0 +1,115 @@
+---
+layout: page
+title: Assets and Images
+permalink: /assets-and-images/
+---
+
+Flutter applications include both code and assets (sometimes called resources).
+Assets can include static data, configuration files, or anything else an
+application needs to function; in particular, assets include icons and other
+images displayed in the UI.
+
+## Specifying assets
+
+The flutter build process uses the `flutter.yaml` file to identify assets
+required by an application, as shown in the [Tutorial](/tutorial/). There are
+two sections that specify assets: the general `assets` section and the
+`material-design-icons` section, which includes any
+[Material Design icons](https://design.google.com/icons/) the application uses.
+Both kinds of assets are included in the Flutter application's _asset bundle_,
+which is a special archive that Flutter applications can read from at runtime.
+
+### Asset variants
+
+The build process supports the notion of asset variants: different versions of
+an asset that might be displayed in different contexts. When an asset's path is
+specified in the `assets` section of `flutter.yaml`, the build process looks for
+any files with the same name in subdirectories next to the main asset. Such
+files are then included in the asset bundle along with the main asset.
+
+The key use of asset variants is in choosing resolution appropriate images; see
+below. In the future, this mechanism may be extended to include variants for
+different locales or regions, reading directions, etc.
+
+## Working with assets
+
+Your application can access its assets through the
+[AssetBundle](http://docs.flutter.io/flutter/services/AssetBundle-class.html)
+interface. The two main methods on an asset bundle allow you to load a string
+or an image out of the bundle, given a logical key.  The logical key maps to
+the path to the asset specified in the `flutter.yaml` file at build time. The
+application's asset bundle is accessible through the
+[DefaultAssetBundle](http://docs.flutter.io/flutter/widgets/DefaultAssetBundle-class.html)
+widget.
+
+As a shortcut, the
+[AssetImage](http://docs.flutter.io/flutter/widgets/AssetImage-class.html)
+widget provides a simple way to display an image in the UI.  Images may also be
+specified as the background of a
+[BoxDecoration](http://docs.flutter.io/flutter/painting/BoxDecoration-class.html).
+
+## Resolution awareness
+
+Flutter can load resolution-appropriate images for the current device
+pixel ratio.
+
+[AssetImage](http://docs.flutter.io/flutter/widgets/AssetImage-class.html)
+understands how to map a logical requested asset onto one that most
+closely matches the current device pixel ratio. In order for this mapping to
+work, assets should be arranged according to a particular directory structure:
+
+    .../image.png
+    .../Mx/image.png
+    .../Nx/image.png
+    ...etc.
+
+Where M and N are numeric identifiers that correspond to the nominal resolution
+of the images contained within. The main asset is assumed to correspond to a
+resolution of 1.0. For example, consider the following asset layout for an
+image named `my_icon.png`:
+
+    .../my_icon.png
+    .../2.0x/my_icon.png
+    .../3.0x/my_icon.png
+
+On devices with a device pixel ratio of 1.8, the asset `.../2.0x/my_icon.png`
+would be chosen. For a device pixel ratio of 2.7, the asset
+`.../3.0x/my_icon.png` would be chosen.
+
+If the width and height of the rendered image are not specified, the nominal
+resolution is used to scale the asset so that it will occupy the same amount
+of screen space as the main asset would have, just with a higher resolution.
+That is, if `.../my_icon.png` is 72px by 72px, then `.../3.0x/my_icon.png`
+should be 216px by 216px; but they both will render into 72px by 72px
+(in logical pixels) if width and height are not specified.
+
+The way this works is through an object called
+[AssetVendor](http://docs.flutter.io/flutter/widgets/AssetVendor-class.html)
+established at the top of the build tree. AssetVendor replaces the default asset
+bundle, so anything using the default asset bundle will inherit resolution
+awareness when loading images.  (If you work with some of the lower level
+classes, like
+[ImageResource](http://docs.flutter.io/flutter/services/ImageResource-class.html)
+or
+[ImageCache](http://docs.flutter.io/flutter/services/ImageCache-class.html),
+you'll also notice parameters related to scale.)
+
+Some caveats:
+
+* If you're not using
+  [MaterialApp](http://docs.flutter.io/flutter/material/MaterialApp-class.html)
+  in your application, and you want to use resolution awareness, you'll need to
+  establish your own AssetVendor in your build logic. (This may change, please see
+  [this issue](https://github.com/flutter/flutter/issues/1346).)
+* If you want establish a your own
+  [MediaQuery](http://docs.flutter.io/flutter/widgets/MediaQuery-class.html) or
+  [DefaultAssetBundle](http://docs.flutter.io/flutter/widgets/DefaultAssetBundle-class.html)
+  below the root of the widget hierarchy, the root-level AssetVendor won't be
+  aware of the change.  If you want resolution awareness with the new MediaQuery
+  or DefaultAssetBundle you specify, you'll need to create an AssetVendor at
+  that point in the tree as well.
+
+You can see an example
+([examples/widgets.dart](https://github.com/flutter/flutter/tree/master/examples/widgets))
+from the flutter repo.
+Run `flutter start -t resolution_awareness.dart` to see it in action.

index.md

@@ -33,7 +33,7 @@ to install Flutter and run your first app on Android and iOS.
  - [Animations in Flutter](animations)
  - [Architecture diagram](https://docs.google.com/presentation/d/1cw7A4HbvM_Abv320rVgPVGiUP2msVs7tfGbkgdrTy0I/edit?usp=sharing)
  - [Upgrading Flutter](upgrading)
- - [Resolution-aware images](/resolution-aware-images)
+ - [Assets and images](assets-and-images)
 
 ## See also