+![ ](../assets/img/image-scaling/workflow-2.png) ![ ](workflow-2.png)
+
+#### Fitting Mode {#resourceimagescaling-fittingmode}
+
+DALi provides a number of strategies for mapping the pixels of an image onto the target box derived above.
+It provides a `FittingMode` enumeration to the developer to select a mapping or fitting approach.
+These are `SCALE_TO_FILL`, `SHRINK_TO_FIT`, `FIT_WIDTH`, and `FIT_HEIGHT` and their effect is best appreciated visually:
+
+The operation of each of these modes is as follows:
+
+| `FittingMode` | **Operation** |
+| ------------- | ------------- |
+| `SCALE_TO_FILL` | Centers the image on the target box and uniformly scales it so that it matches the target in one dimension and extends outside the target in the other. Chooses the dimension to match that results in the fewest pixels outside the target. Trims away the parts of the image outside the target box so as to match it exactly. This guarentees all of the target area is filled. |
+| `SHRINK_TO_FIT` | Centers the image on the target box and uniformly scales it so that it matches the target in one dimension and fits inside it in the other. This guarentees that all of the source image area is visible. |
+| `FIT_WIDTH` | Centers the image on the target box and uniformly scales it so that it matches the target width without regard for the target height. |
+| `FIT_HEIGHT` | Centers the image on the target box and uniformly scales it so that it matches the target in height without regard for the target width. |
+
+
+![ ](../assets/img/image-scaling/fitting-mode-options.png) ![ ](fitting-mode-options.png)
+
+<sub> **Fitting modes**: *The top row shows the effect of each mode when a tall target rectangle is applied to a square image. The middle row applies a wide target to a square raw image. The bottom row uses a target with the same aspect ratio as the raw image. This example shows that `SCALE_TO_FILL` is the only option for which the dimensions of the fitted image result fill all the area of the target. Others would be letterboxed with borders. `SHRINK_TO_FIT` is always equal to one of `FIT_WIDTH` or `FIT_HEIGHT`: in each case it is the minimum of them. As a special case, where the aspect ratio of raw image and target match, all fitting modes generate an exact match final image and are equivalent to each other.* </sub>
+
+
+Note: The image is scaled to the same aspect and shrunk to fit depending on fitting mode. It is not upscaled. See: [Upscaling](#resourceimagescalingupscaling).
+
+
+
+### Scaling {#resourceimagescaling-scaling}
+
+![ ](../assets/img/image-scaling/workflow-3.png) ![ ](workflow-3.png)
+
+To perform the scaling stage, the source image is scaled to a (factor of) the target image size using the specified Sampling Mode/
+
+The process of scaling an image can be expensive in CPU cycles and add latency to the loading of each resource.
+To allow the developer to trade-off speed against quality for different use cases, DALi provides the `SamplingMode` enum, which can be passed to `ResourceImage::New()`.
+Two of these modes produce bitmaps which differ from the dimensions calculated by the fitting algorithm and so have a memory trade-off as well. The full set of modes is explained below.
+
+| `SamplingMode` | **Operation** |
+| ------------- | --------- |
+| `NEAREST` | Use simple point sampling when scaling. For each pixel in output image, just one pixel is chosen from the input image. This is the fastest, crudest option but suffers the worst from aliasing artifacts so should only be used for fast previews, or where the source image is known to have very low-frequency features. |
+| `LINEAR` | Uses a weighted bilinear filter with a `(2,2)` footprint when scaling. For each output pixel, four input pixels are averaged from the input image. This is a good quality option, equivalent to the GPU's filtering and works well at least down to a `0.5` scaling. |
+| `BOX` | Uses an iterated `(2,2)` box filter to repeatedly halve the image in both dimensions, averaging adjacent pixels until the the result is approximately right for the fitting target rectangle. For each output pixel some number of pixels from the sequence `[4,16,64,256,1024,...]` are averaged from the input image, where the number averaged depends on the degree of scaling requested. This provides a very high quality result and is free from aliasing artifacts because of the iterated averaging. *The resulting bitmap will not exactly match the dimensions calculated by the fitting mode but it will be within a factor of two of it and have the same aspect ratio as it.* |
+| `BOX_THEN_NEAREST` | Applies the `BOX` mode to get within a factor of two of the fitted dimensions, and then finishes off with `NEAREST` to reach the exact dimensions. |
+| `BOX_THEN_LINEAR` | Applies the `BOX` mode to get within a factor of two of the fitted dimensions, and then finishes off with `LINEAR` to reach the exact dimensions. This is the slowest option and of equivalent quality to `BOX`. It is superior to `BOX` in that is uses an average of 62% of the memory and exactly matches the dimensions calculated by fitting. **This is the best mode for most use cases**. |
+| `NO_FILTER` | Disables scaling altogether. In conjunction with `SCALE_TO_FILL` mode this can be useful as the edge trimming of that fitting mode is still applied. An example would be a gallery application, where a database of prescaled thumbnails of approximately the correct size need to be displayed in a regular grid of equal-sized cells, while being loaded at maximum speed. |
+
+
+Here are all the modes applied to scaling-down a `(640,720)` line art and text JPEG image to a `(218, 227)` thumbnail:
+
+| | | |
+| ---- | ---- | --- |
+| ![ ](../assets/img/image-scaling/sampling_modes_no_filter.png) ![ ](sampling_modes_no_filter.png) | ![ ](../assets/img/image-scaling/sampling_modes_nearest.png) ![ ](sampling_modes_nearest.png) | ![ ](../assets/img/image-scaling/sampling_modes_linear.png) ![ ](sampling_modes_linear.png) |
+| **NO_FILTER** | **NEAREST** | **LINEAR** |
+| ![ ](../assets/img/image-scaling/sampling_modes_box.png) ![ ](sampling_modes_box.png) | ![ ](../assets/img/image-scaling/sampling_modes_box_then_nearest.png) ![ ](sampling_modes_box_then_nearest.png) | ![ ](../assets/img/image-scaling/sampling_modes_box_then_linear.png) ![ ](sampling_modes_box_then_linear.png) |
+| **BOX** | **BOX_THEN_NEAREST** | **BOX_THEN_LINEAR** |
+
+These are screenshots, showing how the images are rendered in a DALi demo.
+There is an additional level of GPU bilinear filtering happening at render time.
+The best way to get a feel for the best sampling mode for different image types is to play with the [examples](#resourceimagescaling-samplingmodesdemoexamples).
+
+
+
+### Crop or Add Borders {#resourceimagescaling-croporaddborders}
+
+![ ](../assets/img/image-scaling/workflow-4.png) ![ ](workflow-4.png)
+
+Lastly, the image data will be cropped, or have borders added automatically as necessary.
+This is done to ensure the image correctly fits the aspect of the target window, whilst maintaining the aspect of the source image.
+
+Images that have an alpha channel will be given transparent borders. Otherwise black is used.
+
+
+
+## Using the API (With source code examples) {#resourceimagescaling-apidetails}
+
+This section contains more detail about using the API to setup the desired behaviour.
+
+`ResourceImage` :: New has the following parameters:
+- **path**: Identifier for the image (allows raw image width and height to be retrieved).
+- **requested dimensions**: These are either `(0,0)`, a width, a height, or a (width, height) pair and either directly, or after reading the image raw dimensions and doing some math, define a target rectangle to fit the image to.
+- **fitting mode**: one of four strategies for mapping images onto the target rectangle.
+- **sampling mode** Different quality options for the scaling.
+
+### Code Examples {#resourceimagescaling-targetdimensionsexamples}
+If we have a `(320, 240)` image called "flower.jpg", we use these options in code as below.
+
+**Case 1**: In these two equivalent loads, the target dimensions are not specified, so will be `(320, 240)` so the image will be loaded at its raw dimensions without modification.