Using Graphic objects: Filled Path Bitmap
The Filled Path Bitmap object represents an ALPHA8 off-screen bitmap filled with a graphical shape according to provided vector path data. The Filled Path Bitmap object can be used wherever ALPHA8 bitmaps are expected in your application. For example, it can be associated to a Filter Image view and act there as the mask bitmap. When at the runtime the provided path data changes, the content of the Filled Path Bitmap is automatically updated, causing in turn an update in all associated views like the Filter Image view. The path data can be composed of line segments, Bézier curves and elliptical arcs. Several paths can be combined together in order to describe complex shapes.
Please note, Filled Path Bitmap represents the bitmap only. To display its contents on the screen you have to assign the Stroked Path Bitmap object to an image view. If all you want to do is to display the shape, it may be more convenient to use the Filled Path view instead of the here described bitmap object. The bitmap object is convenient only wherever the bitmap itself is needed (e.g. as mask in the Filter Image view).
The following sections are intended to provide you an introduction and useful tips of how to deal with the Filled Path Bitmap. For the complete reference please see the documentation of the Graphics::FillPath class.
Please consider, that each Filled Path Bitmap object reserves memory for an internal bitmap to store the resulting graphical shape inside. The size of the bitmap corresponds to the size configured in the particular Filled Path Bitmap object. Since the bitmap is stored in ALPHA8 format, the bitmap will occupy 1 byte per pixel. For example, a 300x200 pixel large Filled Path Bitmap will occupy ~60 KB RAM. Thus, if RAM is a scarce resource in your target device, you should use the Filled Path Bitmap objects with prudence.
Add new Filled Path Bitmap
To add a new Filled Path Bitmap 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 Resources.
★In the folder locate the template Filled Path Bitmap.
★Drag & Drop the template into the Composer window:
★Eventually name the new added Filled Path Bitmap object.
Inspect the Filled Path Bitmap
As long as the Filled Path Bitmap object is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property FrameSize in the screenshot below:
This is in so far worth mentioning as all following sections describe diverse features of the Filled Path Bitmap 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.
Connect the Filled Path Bitmap to a view
The Filled Path Bitmap stores the rasterized graphical shape in an internal ALPHA8 bitmap. In order to display this bitmap on the screen you have to connect the Filled Path Bitmap object to one of the image views. Accordingly, the view will display the bitmap similarly to how regular static Bitmap resources are displayed.
To connect a Filled Path Bitmap to a view you have to assign this object to the adequate property of the affected view (e.g. to the Bitmap property). With the Inspector Assistant you can conveniently select the right Filled Path Bitmap object when you edit the initialization expression for the property. The following example demonstrates how you assign the Filled Path Bitmap object to the property MaskBitmap of a Filter Image view:
As soon as you have connected the both, the information provided in the Filled Path Bitmap object is used by the view. If desired, you can assign the same object to several views. If during the runtime of the application, the content of the Filled Path Bitmap object changes, all associated views are updated automatically.
Configure the Filled Path Bitmap
Each Filled Path Bitmap manages internally an off-screen ALPHA8 bitmap where the resulting (rasterized) graphical shape is stored. The size (width x height) of this bitmap is configured by using the property FrameSize. Consequently, if you configure the Filled Path Bitmap with the size <200,100>, the bitmap will be able to store 200x100 pixel large graphical shapes. Parts of the graphical shape lying beyond this border are simply clipped.
Since the internally used off-screen bitmap is stored in ALPHA8 format, the bitmap will occupy 1 byte per pixel. For example, a 300x200 pixel large Filled Path Bitmap will occupy ~60 KB RAM. Thus, if RAM is a scarce resource in your target device, you should use the Filled Path Bitmap objects with prudence.
Provide path information for the Filled Path Bitmap object
In order to rasterize a graphical shape in the Filled Path Bitmap object, you have to provide the corresponding path information. You can consider the path as a list of connected straight line segments (so-called edges) describing precisely the outline of the shape intended to be to drawn. Depending on the application case the path may consist of few or even hundreds of edges. In this manner you describe primitive (e.g. triangles) or even complex shapes (e.g. circles, rings, Bézier curves or polygons).
To provide the path information you use a Path Data object. Usually you will add such object to your component, you will implement code to fill this object with your particular path information (the lines, arcs, Bézier curves, etc.) and finally you will assign the so prepared object to the property Path of the affected Filled Path Bitmap object. With the Inspector Assistant you can conveniently select the right object when you edit the initialization expression for the property Path. For example:
As soon as you have connected the both, the information provided in the Path Data object is processed by the Filled Path Bitmap. If desired, you can assign the same Path Data object to several Filled Path Bitmap (or Stroked Path Bitmap) objects. If during the runtime of the application, the content of the Path Data object changes, all associated bitmap objects are updated automatically.
Please note, newly added Filled Path Bitmaps are using the default Path Data object Resources::DefaultPath describing a simple pie segment. In the practice you will always manage your own path objects containing your particular path information. In any case you should avoid to modify the contents of the Resources::DefaultPath object.
In particular cases, when the desired shape is an ellipse, ring, pie segment, circle segment, etc. you can use the more convenient Arc Path Data object. With this object you don't need to implement any code to prepare the path data. Instead, you simply configure the properties of the Arc Path Data object determining so e.g. the desired radiuses of the ellipse, its start and end angles, and so far.
Determine the origin position for the path coordinates
Per default, the coordinates provided in the associated path object are rasterized relative to the top-left corner of the Filled Path Bitmap. This corner corresponds thus to the origin of the path own coordinate system (0,0). By modifying the property Offset you can specify other position within the area of the Filled Path Bitmap where to map the origin of this coordinate system. In other words, changing the property Offset causes the shape to be rasterized at different position within the area of the Filled Path Bitmap.
Let's assume, the associated path object describes a circle with its center lying at the origin of the path own coordinate system (0,0). Depending on how the property Offset is configured, the circle appears at different positions within the Filled Path Bitmap as demonstrated in the following screenshot. For visualization purpose, the black cross indicates the center of the path coordinate system and the thin blue frames are borders of the respective Filled Path Bitmap. Please note, parts of a shape lying outside of the bitmap's area are clipped and not visible:
Originally the positive Y-axis of the path coordinate system points downwards, which corresponds to how other positions or coordinates are treated in Embedded Wizard. By initializing the property FlipY with the value true, the Filled Path Bitmap mirrors vertically the path coordinate system resulting in the Y-axis pointing upwards, which is more natural for mathematical application cases. The shape described by the path appears accordingly mirrored. Furthermore, with this alternation the effect of the property Offset changes, so that it specifies the position where to map the origin of the path coordinate system relative to the bottom-left corner of the bitmap. The following screenshot demonstrates this effect:
Determine the rule how to fill nested path areas
With the property FillRule you specify the algorithm which is used by the Filled Path Bitmap during the rasterization process to determine what area of the provided path should appear filled and what area should remain empty. This is in particular essential in case of a complex path, which intersects itself or a path composed of several nested sub-paths. Following are the possible fill rules:
Fills the path areas alternately depending on the nesting level of the enclosed path segments. An area is considered as filled if the number of path segments between a point lying inside the area and any point outside the entire shape is odd. If the number of path segments is even, the area is not filled.
Fills the path areas depending on the nesting level of the enclosed path segments and their winding direction. An area is considered as filled when counting the path segments between a point lying inside the area and any point outside the entire shape the resulting value is not zero, whereby paths with positive winding direction increment the value while paths with negative winding decrement it. If the counter value is 0 (zero), the area is not filled.
The following figures demonstrate the effect of the both fill rules. Please note the small arrows indicating the winding direction of the particular path segment:
Control the quality of the filled path
The Filled Path Bitmap rasterizes the shape per default with enabled anti-aliasing. This produces the best possible results. If not desired, with the property Quality you can disable this mode. For this purpose initialize Quality with the value false. The following figure demonstrates the results depending on the current setting of the property:
Embedded Wizard own implementation to rasterize vector graphics calculates with 4x anti-aliasing, which means that every pixel is divided in 4 sub-pixel vertically and 4 sub-pixel horizontally. If the vector graphic is rasterized by using target own graphics subsystem (e.g. GPU), the resulting anti-aliasing depends on the implementation of this subsystem. In particular cases (e.g. in case of the WebGL Platform Package) the anti-aliasing can't be deactivated.
Despite the advantages, you should consider, that with enabled anti-aliasing the rasterization operations are more computing intensive. Thus, if your target device is not powerful nor doesn't provide any dedicated graphics hardware to rasterize vector graphics, setting the property Quality to the value false may improve the performance.