General Concepts

• 9-patch image
• Dynamic List
• Integration of Monotype
• Text engine: Shaping
• Monotype's Spark Engine
• Colored Glyph Support
• Integration of CGI Player
• Input Handling
• Touch Input Handling
• Focus Management
• GestureDetector
• Warping
• Introduction
• Configuration
• Default Adjustments
• Enabling Warping
• Warping Sequence
• Warping Library API
• Warping Candera API
• RenderTarget Alpha Blending

9-patch image

Description

The 4-slice scaling technique has been around in desktop graphics software for some years already and is well known to users of Flash and Illustrator. It's a brilliant technique for scaling images by dividing them using 5 slices into sections that have a fixed size (the corners) and sections that are flexible (the edges and the center). There are many names in use for this technique: 9-slice-sprite, 9-slice-scaling, 9-patch-bitmap.

The following image shows the 9 patches areas of an image using different colors:

The basic rules are that the corners will not scale at all, the edges will only scale in their respective direction and the center will scale in all directions.

The green area usually is the content area and the other 8 areas are the border areas. It will be clear why the center area is named content area when we show a few example applications of 9-patch images.

Examples

The images are very often used as background in controls like buttons for example. The big advantage is the low amount of memory needed. It is only necessary to store a small minimum version of the image and it can be reused in many different sizes without losing too much of its quality.

9-patch is mainly used for controls, if you have a text field or a button you can basically stretch it infinitely, but you want certain areas to not stretch like the borders so that in the visual sense it will look much better.

In a layouter (Overlay, Grid…), the 9-patch images will still have the same rules even if the Size properties of the layouter are changed. Using layouters to control the size of a node/control 9-patch images are very often the best way to adapt nodes/controls dynamically to the required space, which is then, adapted to the 9-patch-image as expected.

For BitmapNode sample of the 9-patch click here.

Configuration and special properties

Because not all images are suitable for use as 9-patch-images SceneComposer allows the user to classify an imported bitmap as 9-patch-images using the bitmap properties. To configure the 9-patch, when a bitmap is selected from the Solution Explorer, in the Properties window, in Bitmap section, Bitmap Layout property must be set to NinePatch. If an image is a classified 9-patch-image, 4 additional properties are available. These properties define where the slices are going through the bitmap. For every slice the distance in pixel from the border has to be specified resulting in:

When using an image as a nine-patch image you should disable bilinear filtering (within the BitmapBrushBlend effect for example) by setting the bitmaps filter property to NearestFilter. This is necessary to have sharp borders between the 9 patches.

When using 9-patch-images on a BitmapNode or inside a control changing the size of the node or control will stretch the image as described above. The scale property of a node/control will be applied as an additional step AFTER adapting the image to the size of the node/control!

Scale properties X and Y will scale the whole image and don’t have unscaled areas. 9-patch does not work with the Scale properties, but with the Size properties X and Y. To scale an image with the 9-patch rules, in the node Properties window, in Layout section, changing the values X and Y from Size property will stretch the image according to 9-patch.

If the Size properties X or Y is smaller than the sum of the borders (9-patch Stretchable Area: Left, Top, Right and Bottom), then the borders themselves will also start scaling down.

Dynamic List

Overview and characteristics

Create a list in a binding source (all samples are included in cgi_studio_player)

Create the List view binding to the list data model

Create the binding source for the list item

Create the List item view binding to the list item data model

After defining the List item structure, set up the Bindings in Scene Composer.

1. First, Nodes for the List item are required. Drag a Stack Layout node from the Node 2D section of the Toolbox to the Scene Tree and rename it "Item_1".
   
   
   
   
   
2. Next, drag a Text Value Control and a Slider Control onto that stack node. In addition, change the "Format Text" property of Text Value to “Item %05d”.
   

• In the Scene Editor, the text "Item" should be followed by the number that binds to the UInt64 data binding item you just added.
  
  
  
  
  
• Add a little margin to the top, bottom, left and right of the Slider Control.
  
  
  
  
  
• Bind the Value property of the Text Value Control to /SampleListEntry/UInt64Value.
  
  
  
  
  
• In addition, bind the Value property of the Slider control to /SampleListEntry/FloatValue.
  
  
  
  
  
• This completes the binding settings for this item.
  
  
• After selecting the List control in the Scene Tree, select [ Clone ] from the context menu.
  
  
• When the [ Clone Item ] dialog box appears, select the [ Multiple Clone ] tab, enter “6” for the "Number of Copies", and perform the clone.
  

• A scroll bar will appear because the seventh item is outside the visible area due to the size setting set earlier.
  
  
  
  This completes the scene configuration. You can now generate the assets.
  

Handling the List model code

bool DynamicListComponent::OnMessage(const Courier::Message & msg)
    {
        bool rc = false;
        switch (msg.GetId()) {
        case Courier::StartupMsg::ID:
            (*mSampleBindingSource).mVariantValue = FeatStd::Variant(10.0F);
            LoadSampleListFragmentMissingItems(0, 30);
            (*mSampleBindingSource).mSampleList.UpdateListItemCount(SAMPLE_LIST_SIZE);
            mSampleBindingSource.MarkItemModified(ItemKey::SampleBindingSource::SampleListItem);
            mSampleBindingSource.SendUpdate(true);
            break;

case UpdateModelMsg::ID: {

                case Courier::ListRequestType::NewFragment:
                    switch (request.ItemKey()) {
                    case ItemKey::SampleBindingSource::SampleListItem:
                        LoadSampleListFragmentMissingItems(request.NewIndex(), request.OldIndex());
                        break;
                    }
                    break;

        case Courier::ListRequestType::ChangeDataItem:
            switch (request.ItemKey()) {
            case ItemKey::SampleBindingSource::SampleListItem:
                switch (request.InnerItemKey()) {
                case ItemKey::SampleListEntry::FloatValueItem: {
                    const FeatStd::Float* value = request.GetItem<FeatStd::Float>();
                    SetSampleListTestListValue(request.NewIndex(), *value);
                }
                break;
                }
                break;
            }
            break;

Integration of Monotype

This section provides an overview of the Monotype integration.

The current integration is a hardwired solution. Therefore, the choice of which engine shall be used, has to be made at precompile-time (CMake decision).

The following features have been integrated:

The font engine: iType

iType is a font engine which main purpose is fast and qualitative rasterization of fonts.

To see, which version of iType is currently supported, please have a look at the [3rd Party Software section].

There are two different approaches to integrate the third party code iType into CGIStudio:

CGIStudio supports both by CMake settings.

Monotype/iType has a special porting API with which target and OS specifics can be overridden.

CGIStudio provides a single solution for all targets. For this, the framework links the API to the device and operating system layers.

It is also possible to use an own customized port instead of the CGIStudio solution.

Cache support

The iType integration concentrates on the most performant cache types: BitmapCache and GlyphAtlas. Therefore, only these two cache types are fully supported.

Overview: CMake settings

Currently CMake supports general iType integration flags to include Monotype.

To switch to the font engine the following CMake flag has to be set:

If HarfBuzz is selected as the current TextShaper, the flag CANDERA_TEXTSHAPER automatically will change to WorldType-Shaper. Shaping can also be disabled.

This flag is called Monotype to switch to the available Monotype engines. The concrete font engine will be iType.

By enabling Monotype, several CMake flags become available.

The flag MONOTYPE_USE_BINARIES can be used to switch between the different building modes.

They have their own flags which will be described within the corresponding build process description.

Build process: iType as source code

For this mode, MONOTYPE_USE_BINARIES has to be disabled.

Build process iType as prebuilt library

For this mode, MONOTYPE_USE_BINARIES has to be enabled.

In general using the prebuilt library is similar to the source code version.

The flags MONOTYPE_FEATSTD_PORT_ENABLED, MONOTYPE_FONT_ENGINE_PORT_PATH and MONOTYPE_FONT_ENGINE_SRC_PATH are equal in usage as in the source code version. The only difference is, that the prebuilt library only requires header files.

The port files and header have to match with the build settings of the prebuilt library.

MONOTYPE_ITYPE_LIBRARY_FILEPATH is the path to the prebuilt library. And has to be defined by the user.

Monotype – Prepopulated font engine cache

This feature shall be used to load font bitmap data into the font engine cache.

CMAKE Configuration

1. Set CANDERA -> CANDERA_FONTENGINE to Monotype
2. Configure
3. Check MONOTYPE -> MONOTYPE_PREPOPULATED_CACHE_ENABLED
   

Usage

1. Include the previously created cache dump header file.
2. Include the “MtInclude” header
   
   #include <Candera/TextEngine/Monotype/MtInclude.h>    
3. Create an instance of a font that is present in the asset. The name of the font must match the “Candera Name” property of the font resource in the scene composer. The font size parameter of the Setup call is irrelevant.
   
    Candera::TextRendering::Font font;
    font.Setup("ConstructionKit##ConstructionKit#Resources#Fonts#Open Sans Light", 20);
   
4. Call FontEngine::InitPrepopulatedCache with the font and a reference to the utilCache variable from the cache dump file.
   
   Candera::TextRendering::FontEngine::Instance().InitPrepopulatedCache(font, &utilCache);
   

Possible Pitfalls

• The cache should be prepopulated during startup of the application. Thus, the above methods shall be called when the Courier::StartupMsg is received. 
• The “faceName” property of the Font::Setup call must match the “Candera Name” property of the font in the composer.
  
• The font size used when displaying the text, e.g. with a TextNode, must match the font size used when generating the cache dump file.
  
• While generating the cache dump file, the glyph maps must be retrieved as GRAYMAP’s by calling
  map = FS_get_glyphmap(FS_state_ptr, glyphIDs[i], FS_MAP_GRAYMAP8);  
  
• When generating the cache dump file, fs_config.h should match the configuration in cgi_studio_3psw\src\Monotype\iType\source\common\fs_config.h 
  

Text engine: Shaping

Shaping

Stored texts are ordered by the reading flow. This means that every text is placed from left to right within the memory. It does not matter which language it is. There is also no other information stored besides the text itself. Therefore, the memory representation of text has only logical information but no visual representation information.

The goal of shaping is to find the correct representation of the given text. For example Arabic letters differ in their visual representation depending on their position. Therefore, characters usually have four different forms: Isolated, Final, Medial and Initial. Additionally, there are many more tasks for a shaper to handle: Diacritics, ligatures, kerning...

All different languages have their own characteristics when it comes to shaping. Even Latin has some shaping cases.

For more detailed information about shaping:
WT-Shaper, HarfBuzz as well as different sources, e.g. Unicode.org and w3.org provides abundant information.

Supported shaper

Candera supports different shaper:

To see, which versions of shapers are currently supported, please have a look at the [3rd Party Software section].

WorldType Shaper

Integration of WT-Shaper

The integration is based on the same approach iType uses. (Reference to iType)

CMake Integration

In CMake WT-Shaper can only be selected when Monotype is set as CANDERA_FONTENGINE.

To switch to the shaper the following CMake flag has to be set:

If Freetype + HarfBuzz is slected, the flag CANDERA_TEXTSHAPER will automatically change to WorldType-Shaper.

Using prebuilt binaries or not is bound to the same CMake flag as The font engine: iType iType.

The flag MONOTYPE_USE_BINARIES can be used to switch between the different building modes.

Build process: WT-Shaper as source code

For this mode, MONOTYPE_USE_BINARIES has to be disabled.

Build process WT-Shaper as prebuilt library

For this mode, MONOTYPE_USE_BINARIES has to be enabled.

In general using the prebuilt library is similar to the source code version.

The flags MONOTYPE_FEATSTD_PORT_ENABLED, MONOTYPE_WTSHAPER_PORT_PATH and MONOTYPE_WTSHAPER_SRC_PATH are equal in usage as in the source code version. The only difference is, that the prebuilt library only requires header files.

The port files and header have to match with the build settings of the prebuilt library.

MONOTYPE_WTSHAPER_LIBRARY_FILEPATH is the path to the prebuilt library. And has to be defined by the user.

Monotype's Spark Engine

Introduction to Monotype’s Spark engine

The Spark engine is Monotype’s lightweight font engine, with a focus on devices with a limited feature set.

This is a powerful engine with many capabilities able to provide high quality font rasterization and shaping.

However, to support resource constrained devices, certain restrictions have been placed on the font forming.

For more details regarding the types of restrictions in place, please contact Monotype directly.

Integrating the Spark engine

Copy the source package provided by Monotype for the Spark engine to the following location,

The final folder’s substructure should be as follows,

Additional content may differ depending on the package received from Monotype.

By completing these steps, the Spark engine has now been integrated into CGI Studio.

Configuring the Spark engine

Configure the following entries within CMake as listed below,

By integrating the Spark engine into CGI Studio,

Updating the Spark engine configuration files

The following configuration flag must be present within the shaper’s configuration file (msconfig.h),

#define MS_STORE_SOURCE_INDEX

If this flag is not present, a warning message will be shown requesting that this flag be set.

General limitations

As a result of the Spark engine containing a minimal set of features, many optional features are not available. Some of these features include,

---

Colored Glyph Support

With the integration of Monotype’s iType library, the CGI Studio text engine now supports colored bitmaps from the CBDT table of truetype/opentype fonts.

Scope of new functionality

CMake configuration

A third party library ”lodepng” has been added to decode images in PNG format, and is licensed under the ”zlib License”. This library is available within the cgi_studio_3psw folder, with its path set to the CMake variable CGISTUDIO_LODEPNG_INCLUDE_PATH.

Cache: You can change the cache size for the maximum number of cached colored bitmap elements. The macro is defined as: CANDERA_TEXTENGINE_COLORBITMAP_CACHE_ELEMENT_COUNT - default value: 20 This macro can be changed using a compiler flag (-D... or cmake add_definitions). Alternatively, you can directly add this macro to the generated config headers.

Integration of CGI Player

Integration of the Player into SceneComposer

The Player can be started directly from SceneComposer through the new functionality: Play button starts the Player. New configuration panel has been added to define if and how asset is generated and how the Player is started.

Player integration as screen content into SceneComposer is currently not possible. Therefore the Player will still be used as the external player.

SceneComposer is able to start and stop the Player and provides an updated asset during runtime. If the update of the asset is not possible the Player will be restarted. The Player will be preconfigured with the currently selected scene. If no scene is selected another preconfigured or the first scene will be used. The platform configuration of the Player will be done by SceneComposer. To speed up the asset export there will be the possibilty to just export the current selected scene and all dependent scenes.

The Player execution into SceneComposer includes:

Input Handling

Touch Input Handling

Description

This chapter gives a detailed, technical overview of how the user touch input is handled internally which is important to understand further concepts like the Control States. The base part therefore is the CgiStudioControl::ControlTouchSession which handles the TouchEvent and emits several Events received by Controls with a Handle Control State Behavior (e.g. Control States).

Touch Event

The Touch Event is emitted by Courier and contains TouchInfo with following states:

ControlTouchSession

To simplify the process especially for Control developers, the states of a TouchInfo are mapped to several, more specific Events. Therefore the ControlTouchSession generates kind of virtual input events in the sense that a combination of touch events result in a new input event (e.g. Touch Down and Touch Up on the same Control leads to a Click Event). To be able to generate these events and to send them to the right Control the ControlTouchSession contains a list to register all Control State Behaviors. So be sure that each Control which should be handled by the Control Touch Session has to contain a Control State Behavior. For each of the following events it is important to know that the events are generated by the ControlTouchSession but they are dispatched from the Control which gets touched. To understand how Events get sent also check chapter Behaviors and Events .

Pressed Event

Basically the Pressed Event which has two different states is triggered by the users touch down (state: Pressed) or by the users touch up (state: Released).
Furthermore the TouchSession reacts to the move of the touch. So if the touch moves and the primarily touched Control is not touched any longer, the ControlTouchSession emits a Pressed Event with the state Released.
If the touch is still down and enters the primarily touched Control, the TouchSession again emits a Pressed Event with the state Pressed.

In many cases, especially concerning Controls, the Pressed Event gets received by the Handle Control State Behavior (see chapter Control States).

The Handle Control State Behavior even receives the Event via Local Dispatch Strategy (see Behaviors and Events). But the Event also gets dispatched via BubbleStrategy from the Control which enables other Behaviors of the Control to receive the event (e.g. PressedCondition).

Hovered Event

Emitting the Hovered Event works similar to the Pressed Event. But in difference to the Pressed Event the Hovered Event has an additional state in case of keep hovering over the same object.

Additionally the Event is emitted when the Hover leaves the currently hovered object (HoverLeave) and when the Hover enters and object (HoverEnter).
As for the Pressed Event also the Hover Event basically gets received by the Handle Control State Behavior (see chapter Control States). But the Event can also be received by another Behavior like the HoveredCondition.

Click Event

As the previously described Events also the Click Event is generated by the ControlTouchSession but it is dispatched from the Control which gets clicked.
But different to the PressedEvent and the HoveredEvent, the ClickEvent is not sent to the Handle Control State Behavior via Local Dispatch Strategy as it is not relevant for the states of a Control. But again the Event gets dispatched from the Handle Control State Behavior which enables the user to directly react on the Event via an EventHandler (also see EventHandler Tab). Furthermore it is important to know that the Click Event is emitted only on release of the touch point. Moreover the the Control of the touch down must be the same as the Control of the touch up. So following example would not trigger a Click Event:

The Click Event is often used in combination with a EventHandler Tab as shown below:

Focus Management

Focus Navigation on Computer

The user of the created HMI wants to move the focus from one control to another. When using the computer, usually a keyboard is used for focus navigation.

On a computer, the user can use the following keys to move the focus from one control to the other:

On targets without a keyboard, different input methods can be used for changing the focused control. Automotive targets use the rotary for focus navigation. Therefore, focus navigation is only loosely coupled with a keyboard.

 

---

Focus Navigation in CGI Studio

This section uses a phone keypad like the one below to demonstrate the focus changes.

The focused button in the example keypad above is the fifth button (Button 5), whose border is significantly wider.

Focus navigation can be performed in the Player. To start the Player click the play button next to "Generate and Play" in the toolbar below the menubar.

Next/Previous Navigation in CGI Studio

Next Navigation: After selecting a focusable control the focus can be moved to the next focusable control by pressing the TAB key of the keyboard. If you repeat pressing the TAB key, the focus will move to the next until the last focusable node is reached. Pressing TAB on the last focusable node will bring the focus back to the first node again.
Focus order when continuing pressing the TAB key: 5-6-7-8-9-0-1-2-3-4-5-6-7-...

Previous: To navigate the focus back to the previous focusable control, press the CTRL + TAB keys on the keyboard. If you repeat pressing the CTRL + TAB keys, the focus will move to the previous until the first focusable node is reached. Pressing CTRL + TAB on the first focusable node will bring the focus back to the last node.
Focus order when continuing pressing the CTRL + TAB keys: 5-4-3-2-1-0-9-8-7-6-5-4-3-2-1-...

Geometrical Navigation in CGI Studio

Geometrical Navigation means a navigation in one of the following directions: Left, Right, Up, Down, Up Left, Up Right, Down Left, Down Right
On the computer, navigations in those directions can be performed using the cursor control pad or the numeric pad (for diagonal navigation) of the keyboard.

The following describes the focus change that happens when repeatedly clicking the noted navigation key in the example keypad above. Initally, for every noted navigation key, the focus is on the fifth focusable control as in the image of the keypad above.

 

Managing the Focusable Nodes

Each keyboard focusable behavior notifies the KeyboardFocusManager about its view getting activated or deactivated.

 

Concept of the Next/Previous Navigation

The logical order of the focusable nodes is defined by the following criteria:

KeyboardFocusTabOrderBehavior
The tab order of a node is defined as relative or absolute. The default order is relative.

The next/previous navigation updates the logical order for each next/previous navigation event and sorts the focusable nodes, finds the currently focused node in that list and transfers the focus to the next/previous entry in the list.

 

Concept of the Geometrical Navigation (Left, Right, Up, Down, Up Left, Up Right, Down Left, Down Right)

For each geometrical navigation event the bounding box in the display of the node is calculated per camera in the scene. Each keyboard focusable node has one entry in the lookup list for each camera.

The keyboard focused node is extended by the camera that is responsible for the focus. A scene may have several cameras and the focus will be caused by one of them.

The following events may trigger a change of the keyboard focus:

1. Find the nearest node of the nodes that are at least partially within the top and the bottom boundary of the keyboard focused node. The distance of the right node boundary to the left boundary of the keyboard focused node is minimal. Limit the right node boundary to the left boundary of the keyboard focused node. For multiple matches use the same order criteria as for the previous/next navigation and take the first one.
2. If no node was found, find the nearest node (where the corner to corner distance is minimal) of the nodes that intersect the left sectors:

The same as navigation to the left but in this case, left is right, right is left, top is top and bottom is bottom in the description. Imagine a mirrored image.

The same as Left navigation but left is bottom, right is top, top is left and bottom is right in the description. This is a rotation by 90° counter clock wise

Navigate Down: The same as Left navigation but left is top, right is bottom, top is right and bottom is left in the description. Which is a rotation by 90° clock wise.

Find the nearest node (corner to corner distance is minimal) of the nodes the intersect the top left sector:

The same as UpLeft navigation but left is right, right is left, top is top and bottom is bottom in the description. Imagine a mirrored image.

The same as UpLeft navigation but left is bottom, right is top, top is left and bottom is right in the description. This is a rotation by 90° counter clock wise.

The same as UpLeft navigation but left is top, right is bottom, top is right and bottom is left in the description. This is a rotation by 90° clock wise.

GestureDetector

How to implement a custom GestureDetector

The ControlTouchSession supports GestureDetectors. You simply register your own detector and register it at the ControlTouchSession.

The ControlTouchSession will send these events to the gesture detector:

UpdateEvent

This event indicates an update iteration (one per frame)

GestureDetector::TouchInput

This is a single/multi touch event extended by this information:

The following states of the gesture detector session are available:

In between you will get updates in the following cases:

GestureDetector::AbortEvent

This event tells that another behavior has taken the exclusive touch control. Hence, no gesture detector will participate in the current gesture detector session and therefore has to reset all internal states and wait for the next session.

GestureDetector::DeregisterEvent

The provided behavior is removed from the ControlTouchSession. Hence the gesture detector also has to remove all references to that behavior.

See also:

Warping

Introduction

Image warping is the process of digitally manipulating an image such that shapes portrayed in the image have been distorted. Warping may be used for correcting image distortion as well as for creative purposes (e.g., morphing). The same techniques are equally applicable to video. CGI Studio warping is intended to be used for correction image distortion only. The following two components are involved in the process:

Following is a diagram depicting the information flow for warping:

Configuration

Description

Configuration information passed to the warping library is used to check constraints and as basis for computations.
Following is a description of the warping configuration parameters:

Reference Points

The reference points are represented by a 2D array with coordinates inside the display area to be warped. There are NumOfRefPointsX in horizontal direction and NumOfRefPointsY in vertical direction, both having values in the range 0..255. These are equally distributed over Bitmap-pixel.
Example:

The number of reference points used influence to output of the distorted image with regard to Bitmap size. The output image will be less jagged the higher the number of reference points are used for warping computation

PixResolution

The Resolution of warping parameters determinine the warping accuracy. The final displacement of the reference points is the product of warping parameter by parameter resolution. Therefore, a warping parameter is given by the desired displacement divided by resolution.

The warping library supports the following pixel:

Example:
If a texture point at (0,0) should be mapped at (10,10) the corresponding X[0] and Y[0] coordinates can be calculated by dividing the desired displacement by pixel resolution.
For a pixel resolution of ¹/₁₆ px (0.0625):

X[0] = Xnew[0] – Xold[0] / 0.0625 = 160 (0xA0)
Y[0] = Ynew[0] –Yold[0] / 0.0625 = 160 (0xA0)

For a pixel resolution of ¼ px (0.25):

X[0] = Xnew[0] – Xold[0] / 0.25 = 40 (0x28)
Y[0] = Ynew[0] –Yold[0] / 0.25 = 40 (0x28)

NumOfBitsPerParam

Represents the number of bits used for each parameter (n-bit representation = bit length of each parameter).
The value should be in the range is 1..16.
Example:

Example::

DisplaySizeX and DisplaySizeY

Width and height data (in pixel) of the display hardware (range: 0..65535).

Example:

BitmapAreaX and BitmapAreaY

Width and height data (in pixels) of source surface used as input for warp. The reference points are equally distributed over this range in x and y direction with values in the range 0..65535.

Example:

BitmapAreaCenter

The Bitmap Area Center Point describes the center point of the image area used by ABK.

BitmapAreaShift

The Bitmap Area Shift describes the connection vector between the origin of the bitmap coordinate system (0,0) and the center point of the bitmap area - i.e. the Bitmap Area Center Point.

BitmapAreaShiftX and BitmapAreaShiftY

Shift values of bitmap area center point in horizontal and vertical direction (range 0..65535).

Example:

IlluminatedDisplayAreaX and IlluminatedDisplayAreaY

Width and height data (in pixel) for illuminated area. This represents the region in which the warped surface will be rendered. If the source surface size extends beyond the IlluminatedDisplayArea it will be scaled down with regards to display size.

Example:

IlluminatedDisplayAreaShiftX and IlluminatedDisplayAreaShiftY

Shift values of illuminatedDisplay area center point in horizontal and vertical direction (range 0..65535).

Example:

RotationValue

The rotation value is represented in grad *100 with values in the range -18000 .. +18000. This is the default rotation value which will be applied to the warp image.

The rotation takes place around the warped center point of the bitmap area used. With an uneven number of reference points in x- and y-direction, this point coincides with the middle reference grid point, and the coordinates of the rotation axis are present. If an even number of reference grid points is used, the coordinates of the warped center point of the image are be calculated.

Example:

ParamSet

Set of reference point shift vectors column-ordered.

The warping parameter correspond to the shift vectors (in pixels) of warping interpolation points in warped images in comparison to reference points in non-warped images (divided by the specified resolution). To save memory space and computing time, the absolute coordinates are not saved as warping parameters, but rather only the distance from the reference points (without rotation and shifting).

ParamSetLength

Length of ParamSet in bytes. This is calculated by:

ParamSetLength = NumRefPointsX * NumRefPointsY * 2 * NumBitsPerParam

RotationLimit

This value represents the maximal rotation angle in grad – both positive and negative values are accepted. If the RotationLimit value is chosen such that at maxim rotation point, the image will extend beyond display size, it will be scaled down to the size that fits inside the display area when a rotation equal to RotationLimit is applied.

The display area comprises the whole image including the grey border.
The bitmap image area is the area within the grey border. This is the area we are interested in and which should be warped.
The reference points are evenly distributed over the bitmap image area.

Reference Point Shift Vectors

The warping parameters are based on reference point. These points are mapped by a 2D array containing coordinates inside the display area to be warped. For ++-each reference point, a shift vector is stored by the application. Every shift vector determines the amount of distortion to be applied to the corresponding point in x- and y-direction. Figure 2 shows a reference point grid with corresponding shift vectors.

To preserve memory, the shift vectors are stored in a compressed format. The format is determined by configuration information passed to warping library (number of bits used, value resolution) and is used by warping library to de- and encode shift vectors. The decoded shift vectors are cached in the warping library.

Warp Matrix

The warp matrix is computed by the warping library. It is a 2-dimensional matrix. Each point corresponds to a reference point. The value of each point is the vector-addition of the reference point and corresponding shift vector. All values of the warp matrix are normalized to the range [0..1].

Warp Image Bounds

Warp image bounds can be computed by the warping library. Warp image bounds comprise upper left corner point of the bitmap image area, its width, and height (normalized to the range [0..1]). They are used to specify to Candera which part of the rendered image shall be mapped to the warping mesh.

Default Adjustments

An adjustment is specified by a mode and a delta. Mode defines the way of the distortion, delta defines the amount. The following modes are available:

For each reference point and corresponding shift vector, the adjustment is computed and applied. The resulting shift vector is again cached in the warping library. This way of implementation allows incremental adjustments.

Following are tables detailing supported adjustments:

Enabling Warping

Following are the display settings required to enable warping in Candera:

Candera’s Display class uses a transaction based execution model for setting properties. Several changes can be queued. Changes have to be applied explicitly via a call to Display::ApplyChanges(). Warping matrix data from the warping library can be used directly in Candera.

Warping Sequence

Warping Library API

The public interface of the Warping Library is presented below:

Warping Candera API

The warping related public interface of the Candera::Display class is presented below:

RenderTarget Alpha Blending

Using the icons in the toolbar the user can switch between "Normal Scene Editor Rendering" and "Alpha Blending Scene Editor Rendering".

The alpha blending render mode shows the check pattern in the background. The actual scene is rendered to an offscreen buffer and then blended against the background, that displays the check pattern.

This approach enables the user to immediately test certain blend settings.