Using Views: Filter Image

The Mosaic class Views::FilterImage implements a graphical object specialized to display an image with additional filter effects applied on it. This so-called Filter Image view can be used to compose the appearance of a GUI component, in particular to enrich the component by sophisticated filter effects, like blurring, masking, color tinting or shadowing. The following screenshot demonstrates examples of how Filter Image views appear in the canvas area of Composer (and accordingly on the screen in your target device). The example uses the Filter Image to grayscale an image, to blur it, display a shadow of the image and mask it:

The following sections are intended to provide you an introduction and useful tips of how to work with the Filter Image view. For the complete reference please see the documentation of the Views::FilterImage class.

TIP

If all you need is a blurred rectangle, use the Shadow view.

Add new Filter Image view

To add a new Filter Image view just at the design time of a GUI component do following:

First ensure that the Templates window is visible.

In Templates window switch to the folder Views.

In the folder locate the template Filter Image.

Drag & Drop the template into the canvas area of the Composer window:

Eventually name the new added Filter Image view.

Inspect the Filter Image view

As long as the Filter Image view is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below:

This is in so far worth mentioning as all following sections describe diverse features of the Filter Image view by explicitly referring to its corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

Arrange the Filter Image view

Once added, you can freely move the Filter Image view, or you simply grab one of its corners and resize it in this way. You can control the position and the size of the view also by directly modifying its property Bounds. If you want the Filter Image view to appear behind other views you can reorder it explicitly.

Specify the bitmap for the Filter Image view

The content to display within a Filter Image view is determined by its property Bitmap. Usually, you initialize this property with the name of an existing bitmap resource member, which is typical for all immutable assets like icons, screen backgrounds and any other decorations well known already at the design time. With the Inspector Assistant you can conveniently select the right resource when you edit the initialization expression for the property Bitmap.

From technical point of view, you can initialize the property Bitmap with any instance of a class descending from the Mosaic class Resources::Bitmap. In particular, you can use an instance of the Resources::ExternBitmap class if you want to display bitmap contents, you have e.g. received just at the runtime. Or you render the bitmap dynamically into a Graphics::Canvas object and assign it to the Filter Image view. Please note, every new added Filter Image view uses the Resources::DefaultBitmap bitmap resource as place holder to display something on the screen.

IMPORTANT

Unlike all other views, Filter Image view is restricted to single frame bitmaps only. When you assign a multi-frame bitmap to the Filter Image view, the filter operation will be ignored and dedicated error message is reported.

Configure the blur filter

The blur filter is controlled by the property BlurRadius. This value determines the area around a pixel to take in account when calculating the blur effect at the respective position. The larger the specified blur radius, the more intensive the resulting blur effect. Configuring the property with the value 0 (zero) disables the blur effect again:

Please note, Embedded Wizard does not prescribe any concrete method for calculating the blurred values. Depending on the capability of the target system, the Gaussian or Box blur algorithm can be applied. Similarly, the supported blur radius range can differ from target to target. A target system can even be restricted to support only few discrete blur radius values. The value specified in the BlurRadius property is then automatically rounded to the nearest supported value. With the method AdjustBlurRadius() you can query the effective blur radius based on the desired value:

var int32 blurRadius = 50; // Configure the view with the desired blur radius. It is however // not guarantied that the view will really apply 50 pixel radius. FilterImage.BlurRadius = blurRadius; // ... ask the view, which blur radius will be really used. trace "The real blur radius is: ", FilterImage.AdjustBlurRadius( blurRadius );

The blur filter considers pixel lying outside the source image as being transparent. Consequently, the closer the resulting pixel to the view's edge, the more transparent pixel lying beyond the borders are involved in the calculation. The resulting pixel will appear faded-out. By setting the property BlurClampToEdges to the value true, the blur effect will end abruptly at the view's edges ignoring the transparent pixel lying outside its area. Thereupon when the source image is aligned at the edges of the view, its borders don't appear transparent anymore as demonstrated in the figure below:

When using the blur filter configured with BlurClampToEdges = false it may be useful to additionally add a margin around the blurred bitmap content where the bitmap edges can fade-out. Without the margin, the blur effect will be clipped at view's edges. For more details see the section Position the bitmap within the Filter Image view.

CAUTION

Calculating the blur effect can become very CPU intensive if there is no GPU accelerated support for such operation in the target system. From technical point of view, for each resulting pixel the algorithm has to evaluate all surrounding pixel found in the area with size corresponding to the specified blur radius. The larger the blur radius, the more pixel have to be taken in account as consequence.

The blur calculation also requires intermediate image results to be stored temporarily before they can be shown on the screen. These occupy additional RAM according to the size of the blurred area. Thus, if RAM and CPU are scarce resources in your target device, you should use the blur effects with prudence.

Configure the tint filter

The tint filter modifies the colors found in the originally specified image content. It is controlled by the properties TintMode and TintColor where the desired conversion mode and the color to apply during the conversion are configured. The following table provides a short description of the supported tint modes (for more details see Graphics::TintMode):

Tint mode

Description and application cases

None

The tint filter is disabled. The original colors resulting from the source image are used without any further modification.

Grayscale

The original RGB colors resulting from the source image are converted to grayscale values according to their luminance. This mode is thus ideal to simply gray out the image.

TintByOpacity

The opacity information found in the source image is used to modulate the color value specified in the property TintColor producing so a monochrome image. For example, to display a black shadow based on the original source image opacity, configure the property TintColor with the black color #000000FF.

TintByLuminance

The luminance resulting from the RGB components of the source image is used to modulate the RGB components of the color value specified in the property TintColor producing so a monochrome image. For example, configuring TintColor with the value #FFF6C8FF (sepia color) lets the original image appear as an old photography.

The following figure demonstrates the resulting effect depending on selected tint mode and the specified color value:

Besides the both above explained properties, the tint effect can additionally be controlled by the property TintIntensity. It determines the intensity of the tint operation and lies in the floating point range 0.0 .. 1.0. If the value is 1.0, the original image colors are completely replaced by values resulting from the tint filter. In turn, the value equal to 0.0 results in the original colors without any tinting effect. For all other values the colors are interpolated between the original and the color value resulting from the filter effect. The following figure illustrates the effect of the TintIntensity property for a Filter Image view being configured to grayscale the colors of the original image:

Configure the mask filter

The mask filter combines the originally specified image content with the content of an ALPHA8 mask bitmap, so that pixel information found in the mask bitmap is used to modulate the opacity of the corresponding pixel from the original image. As consequence, the Filter Image view displays only those image pixel which are not transparent in the mask bitmap. The following figure illustrates the working principle of the mask filter:

The mask bitmap to use by a Filter Image view is determined by its property MaskBitmap. Usually, you initialize this property with the name of an existing bitmap resource member, which is typical for all immutable assets well known already at the design time. With the Inspector Assistant you can conveniently select the right resource when you edit the initialization expression for the property MaskBitmap.

From technical point of view, you can initialize the property MaskBitmap with any instance of a class descending from the Mosaic class Resources::Bitmap. This includes in particular the both graphics objects Filled Path Bitmap and Stroked Path Bitmap. Using them the mask bitmap can be rendered from vector path data. The mask and so the filter effect can thereupon change dynamically at the runtime.

IMPORTANT

Unlike all other views, Filter Image view is restricted to single frame bitmaps only. When you assign a multi-frame bitmap as mask to the Filter Image view, the filter operation will be ignored and dedicated error message is reported. Also, please ensure that the assigned mask bitmap is stored in the ALPHA8 format (containing the opacity information only) otherwise the filter operation is ignored and an error message is reported.

Per default, mask bitmaps are arranged directly at the top-left corner of the respective Filter Image view. To change this distance you use the property MaskOrigin. The following figure illustrates the resulting effect using here a mask bitmap containing a simple circle with 50 pixel radius. The thin gray borders in the figure indicate the areas of the corresponding Filter Image views. When changing the property MaskOrigin, the mask moves within the view exposing so the corresponding image areas:

If desired, the effect of the mask bitmap can be inverted. Doing this, the Filter Image view will display only those image pixel which are not fully opaque in the mask bitmap. This function is controlled by the property MaskInverted and the following figure demonstrates it. Please note, that pixel lying outside the mask bitmap are considered as transparent. Consequently, when MaskInverted is true, the Filter Image view will expose all image pixel which are found beyond the borders of the mask:

If you intend to combine the mask and the blur filter effects together, note the right order in which the effects are applied. Per default the mask effect is applied after the blur is done. Consequently, the blurred contents appear masked which results in sharp edges according to the shape of the mask. If your application case requires the image content to be masked first and then the resulting masked image being blurred, set the property MaskBeforeBlur to the value true. The following figure illustrates the different results depending on the initialization of the MaskBeforeBlur property:

Combine multiple filter effects together

In order to produce more sophisticated visual effects, the above explained blur, tint and mask filters can be combined together. As inspiration the following table provides an overview of the most typical application cases and the necessary filter configuration:

Desired effect

Blur

Tint

Mask

Description

Shadow

YES

TintByOpacity

NO

The opacity information found in the original image is used to create a monochrome image with desired color. This image is thereupon blurred.

Fade out the background

YES

Grayscale

NO

The color information found in the original image is converted in grayscale resulting in a monochrome image. This image is blurred thereupon.

Blur with rounded corners

YES

None

YES

The original image is blurred and thereupon masked by a bitmap containing a rectangle with rounded corners.

Colorize an area with rounded corners

NO

TintByLuminance

YES

The RGB information found in the original image is replaced by specified color according to the original luminance. This image is thereupon masked by a bitmap containing a rectangle with rounded corners.

The following figure illustrates the resulting effects of the combined filters:

The following example project demonstrates the practical application of the above mentioned filter effects:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 12.00

Please note, when using blur and mask effects simultaneously, the order in which these are applied is significant. The mask can be applied either on the already blurred content or the blur filter is applied on the previously masked image. For more details see the property MaskBeforeBlur explained in the section Configure the mask filter.

Position the bitmap within the Filter Image view

Per default, the specified bitmap is arranged and displayed directly at the top-left corner of the respective Filter Image view. To change this distance you use the property Origin. The following figure illustrates the resulting effect. When changing the property Origin, the bitmap moves within the view. Parts of the bitmap lying eventually outside the view's border are clipped and not visible. The thin borders in the figure indicate the areas of the corresponding Filter Image views:

Moving the bitmap is generally a useful feature if the Filter Image view should display a smaller area of a larger bitmap. Other application case is found in connection with the blur filter when it is essential to completely blur (fade-out) the edges of the bitmap. In this case enlarge the Filter Image view by at least twice the size of the specified blur radius and configure the Origin to correspond to the blur radius. This results in a margin around the bitmap where the blurred bitmap edges can fade-out. If the margin is too small, the blur effect at this edge will be clipped, what can be undesired depending on your application case as shown in the figure below. Again the thin borders in the figure indicate the Filter Image views:

Modulate the resulting opacity of the filter effect

Using the property Opacity you can modulate the opacity of the resulting filter effect, so that it appears semi-transparent even if the original content was opaque. The valid values for the property Opacity are 0 .. 255, whereby the smaller the value the more transparent the resulting image. For example:

Control the visibility of the Filter Image view

The visibility of the Filter Image view is controlled primarily by the property Visible and the content of the assigned bitmap. Also the specified opacity and eventually the color tint effect may affect the resulting appearance of the Filter Image view. In particular, when the Filter Image view is configured to tint the original image with a transparent color, the resulting image is consequently transparent too.

Per default the views appear alpha-blended over the contents lying behind them unless you explicitly disable this mode by setting the property AlphaBlended to the value false. In such case, the image resulting from the filter effect will overwrite the contents in the background. For example:

TIP

In the complete GUI application an individual view is visible on the screen only when all of its superior Owner components are visible too, the view itself does lie within the visible area of the superior components and the view is not covered by other sibling views nor components.