Here we have a large, square image that we want to set as the wallpaper on a tall and narrow phone screen.
We want to fill the screen without distorting the image or having black borders, and wasting as few pixels from the source image as possible.
-
DALi provides the concept of a `FittingMode` to specify how a source image is mapped into a target rectangle, and the one we need here is `FittingMode::SCALE_TO_FILL` as it guarantees to cover all of the pixels of the target dimensions specified.
In this case, `SCALE_TO_FILL` will perform this sequence of operations:
- 
+
We can pass the stage dimensions to the `ResourceImage` creator function as the desired rectangle and ask it to map the image to the screen as shown here:
Dali::FittingMode::SCALE_TO_FILL,
Dali::SamplingMode::BOX_THEN_LINEAR );
~~~
-~~~{.js}
-// JavaScript
-// First get stage dimensions into stageX and stageY ...
-var image = new dali.ResourceImage( {
- url: "gallery-large-12.jpg",
- width: stageX,
- height: stageY,
- fittingMode: "SCALE_TO_FILL",
- samplingMode: "BOX_THEN_LINEAR"
-});
-~~~
## Workflow {#resourceimagescaling-workflow}
- 
+
The workflow for achieving the final scaled image is (in order):
### Determine Target Dimensions {#resourceimagescaling-targetdimensions}
- 
+
An application has several options for specifying the target rectangle for the image to be fitted to.
The application may request dimensions through `ResourceImage::New()`:
- `Width AND Height both specified` The requested dimensions pass straight through to become the target for fitting.
- 
+
The result of this process is an `(x, y)` target size to fit the image in the next step.
### Target Image Dimensions {#resourceimagescaling-targetimagedimensions}
- 
+
#### Fitting Mode {#resourceimagescaling-fittingmode}
| `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. |
- 
+
<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>
### Scaling {#resourceimagescaling-scaling}
- 
+
To perform the scaling stage, the source image is scaled to a (factor of) the target image size using the specified Sampling Mode/
| | | |
| ---- | ---- | --- |
-|   |   |   |
+|  |  |  |
| **NO_FILTER** | **NEAREST** | **LINEAR** |
-|   |   |   |
+|  |  |  |
| **BOX** | **BOX_THEN_NEAREST** | **BOX_THEN_LINEAR** |
These are screenshots, showing how the images are rendered in a DALi demo.
### Crop or Add Borders {#resourceimagescaling-croporaddborders}
- 
+
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.
ResourceImage image1 = ResourceImage::New( "flower.png" );
ResourceImage image2 = ResourceImage::New( "flower.png", ImageDimensions( 0, 0 ) );
~~~
-~~~{.js}
-// JavaScript
-var image1 = new dali.ResourceImage( { url:"flower.png" } );
-var image2 = new dali.ResourceImage( { url:"flower.png", width:0, height:0 } );
-~~~
**Case 2**: In these loads, the target dimensions will be `(160, 120)` as the zero dimension is derived from the aspect ratio of the raw image.
ResourceImage image1 = ResourceImage::New( "flower.png", ImageDimensions( 160, 0 ) );
ResourceImage image2 = ResourceImage::New( "flower.png", ImageDimensions( 0, 120 ) );
~~~
-~~~{.js}
-// JavaScript
-var image1 = new dali.ResourceImage( { url:"flower.png", width:160, height:0 } );
-var image2 = new dali.ResourceImage( { url:"flower.png", width:0, height:120 } );
-~~~
**Case 3**: In this load, the target dimensions will be `(111, 233)`.
// C++
ResourceImage image = ResourceImage::New( "flower.png", ImageDimensions( 111, 233 ) );
~~~
-~~~{.js}
-// JavaScript
-var image = new dali.ResourceImage( { url:"flower.png", width:111, height:233 } );
-~~~
### Fitting an image's dimensions to the target box {#resourceimagescaling-codeexamplesfittingmodes}
ResourceImage image = ResourceImage::New( "flower.png", ImageDimensions( 32, 24 ) );
// Image will be loaded at (32, 24), regardless of fitting mode.
~~~
-~~~{.js}
-// JavaScript
-// Image on 'disk' is 320x240.
-var image = new dali.ResourceImage( { url:"flower.png", width:32, height:24});
-// Image will be loaded at (32, 24), regardless of fitting mode.
-~~~
### Passing a Zero Dimension {#resourceimagescalingzerodimensions}
// FIT_HEIGHT:
ResourceImage image = ResourceImage::New("flower.png", ImageDimensions(0, y));
~~~
-~~~{.js}
-// JavaScript
-// FIT_WIDTH:
-var image = new dali.ResourceImage( {
- url: "flower.png",
- width: x,
- height: 0
-});
-// FIT_HEIGHT:
-var image = new dali.ResourceImage( {
- url: "flower.png",
- width: 0,
- height: y
-});
-~~~
Note:
- If both values are specified as 0, both dimensions are taken from the source image.
ResourceImage image4 = ResourceImage::New( "flower.png",
ImageDimensions( 240, 240 ), FittingMode::SCALE_TO_FILL, SamplingMode::BOX_THEN_LINEAR );
~~~
-~~~{.js}
-// JavaScript
-var image1 = new dali.ResourceImage( {
- url:"flower.png", width:240, height:240,
- fittingMode:"SCALE_TO_FILL", samplingMode:"NEAREST"
-} );
-
-var image2 = new dali.ResourceImage( {
- url:"flower.png", width:240, height:240,
- fittingMode:"SCALE_TO_FILL", samplingMode:"NO_FILTER"
-} );
-
-var image3 = new dali.ResourceImage( {
- url:"flower.png", width:240, height:240,
- fittingMode:"SCALE_TO_FILL", samplingMode:"BOX"
-} );
-
-var image4 = new dali.ResourceImage( {
- url:"flower.png", width:240, height:240,
- fittingMode:"SCALE_TO_FILL", samplingMode:"BOX_THEN_LINEAR"
-} );
-~~~
There is also a specific demo to show all of the fitting and scaling modes.
which lives in the demo project at `examples/image-scaling-and-filtering`.
- 
+
Touch the arrows in the top corners to changes image.
Drag the resize handle in the corner of the image to change the requested size and trigger an immediate image reload.
A second specific demo shows the effect of a filter mode on a single image loaded into various requested rectangles side by side.
It can be found under `examples/image-scaling-irregular-grid`.
- 
+
Touch the button at top-left to change image.
The button at top-right changes sampling mode.
-@class _Guide_Resource_Image_Scaling
*/
projects / platform / core / uifw / dali-toolkit.git / blobdiff