Board features

Supported color depths

The reference port for these boards supports 32 bits per pixel color depth.

There is also support for 16 bits per pixel and 24 bits per pixel with the ItemLayer API, but not with QUL_COLOR_DEPTH.

See Color depth for more information.

Layers support

To enable optimal VRAM usage as well as support for larger displays, the Infineon/Cypress Traveo II supports the following rendering modes:

• IBO mode
• LBO to memory mode
• OTF mode (LBO to display).

Overview

With IBO mode, blitting happens directly to the target framebuffer in the same order that the drawing commands are issued. LBO performs drawing line-by-line into a line buffer, before writing the complete line buffer back into the framebuffer. The LBO mode saves bandwidth and can thus offer higher performance.

LBO can be used to write into a framebuffer (LBO to memory) or directly to the display (LBO to display). The latter method is also called OTF (on-the-fly). In the case of OTF, only a fraction of a full frame buffer is needed, in order to store the potentially much smaller line buffer in VRAM.

Specifically, while IBO mode requires width*height*bpp*2 bytes to store a double buffered set of framebuffers, the LBO line buffer only requires width*lines*bpp bytes, where lines is the height of the line buffer. By default lines is set to 128, but it can be configured using the approach described in the Advanced layer configuration section. Some additional smaller buffers are also needed for rendering instructions and other rendering related tasks.

Because of the performance and memory usage benefits of OTF mode, it is the default layer configuration in Qt Quick Ultralite.

The drawback of OTF mode is that if there are too many rendering operations, LBO might not be able to finish writing to the line buffer in time, and visual glitches could appear on the display. So when using OTF mode, the application should make sure to not have too many visual elements displayed at the same time, especially transformed image assets as they take a longer time to blit.

Choosing a rendering mode per layer

When creating an ItemLayer, the ItemLayer::renderingHints property can be used to control which rendering mode is used. The default rendering hint is OptimizeForSize, which will result in the OTF rendering mode.

In order to use IBO mode, use the rendering hint NoRenderingHint:

ItemLayer {
    renderingHints: ItemLayer.NoRenderingHint
}

And in order to use LBO to memory mode, use the rendering hint OptimizeForSpeed:

ItemLayer {
    renderingHints: ItemLayer.OptimizeForSpeed
}

Advanced layer configuration

In some cases, it might be necessary to override some OTF layer configuration values specific to Infineon/Cypress Traveo II.

For this, the Qt Quick Ultralite configuration API for Infineon/Cypress Traveo II can be used. It works by using the ItemLayer::platformId API to give a specific platform id to the layer whose configuration should be changed, and then using the provided Tvii::Configuration::setConfigForOTFLayer C++ API to set the custom layer properties before the Qt Quick Ultralite application is started.

Here's how the platform id would be set:

ItemLayer {
    platformId: 1
}

Here's how to include the correct header in order to use the C++ API:

#include <tviiextras/tviiconfiguration.h>

And here's how the OTF layer would be configured:

Tvii::Configuration::setConfigForOTFLayer(1, 64, 128 * 1024, 256);

The first parameter is the platform id of the layer, as specified in the QML file.

The second parameter is the number of copses, which are used for rendering images with compression in LBO mode. If any errors appear when using a lot of compressed images in a given layer, this value could be increased from the default value of 16.

The third parameter is the size of the FIFO used to buffer instructions for the command sequencer. A large number of visual elements might require bigger FIFO buffer size. The default value is 64 * 1024.

The last parameter is the size of the line buffer used by LBO. A bigger line buffer consumes more VRAM, but also reduces the risk of visual glitches that could result if a line does not finish rendering before the time it should be displayed using OTF mode.

For more information see the Graphics Driver for Traveo II Cluster Series User Guide.

Platform limitations

There are some hardware limitations when using the Layers QML APIs:

• Changing the z-order or size of layers at runtime is not supported.
• An application can have a maximum of two OTF layers.
• The maximum size of an OTF layer is 1300x720, so on larger displays it's necessary to use multiple layers.

When using vector outlines for text rendering, the Shape API, or Qul::PlatformInterface::DrawingEngine::blendPath() APIs to draw paths, there are some limitations to take into account:

• Complicated paths might produce errors or have parts missing. It might be possible to increase the QUL_PLATFORM_TVII_DRAW_CONTEXT_ALPHA_BUFFER_WIDTH, QUL_PLATFORM_TVII_DRAW_CONTEXT_ALPHA_BUFFER_HEIGHT, and QUL_PLATFORM_TVII_DRAW_CONTEXT_PATH_BUFFER_SIZE values in platform_config.h to fix this issue.
• Self intersecting paths might cause visual artifacts. This is a hardware limitation (refer to the Traveo II Graphics Driver User Guide).

Other know issues:

• HyperFlash™ NOR Flash Memory is not supported on TRAVEO™ T2G CYT4DN in this release, as it requires the TRAVEO™ T2G Cluster Series V2e.2.0 graphics driver, along with version 7.9.0 of the TRAVEO™ T2G Sample Driver Library.

Using drawing engine for text rendering

If using the Monotype Spark font engine, it's possible to enable an experimental Qt Quick Ultralite feature in order to use vector outlines for text rendering. This utilizes the path drawing capabilities of the Traveo II hardware drawing engine to draw the text into a surface stored in video memory, and then blend that surface in order to display the text.

Use the MCU.Config.fontVectorOutlinesDrawing QmlProject option to enable vector outlines. Refer to Text Rendering and Fonts for more detail about how to use the Monotype Spark font engine.

Resource cache policy

By default, the resource data for the application is copied to VRAM on application startup. In order to keep resources in flash, and not load them to VRAM on startup, use the ImageFiles.MCU.resourceCachePolicy QmlProject property with the value NoCaching when adding resources to the application with ImageFiles.files.

Including compressed assets

The Infineon/Cypress Traveo II supports some custom Run-length encoding based (RLE) compression formats, which can be decoded directly by the blit engine. Assets compressed in this way don't require additional CPU time and memory for decoding and storing a decompressed copy of the image data, as in the case of the standard PNG compressed assets that Qt Quick Ultralite supports. A limitation of the Infineon/Cypress Traveo II's RLE compression is that the images compressed in this way can't be transformed. Some images will also not get a good compression ratio using RLE.

Using AutomaticCompressedLossless

The simplest way to use RLE compressed images on Infineon/Cypress Traveo II is to set ImageFiles.MCU.resourceImagePixelFormat to AutomaticCompressedLossless:

ImageFiles {
    files: "image.png"
    MCU.resourceImagePixelFormat: "AutomaticCompressedLossless"
}

Using the ResourceGenerator.cmake CMake module

See tests/manual/traveoii/compressed_images for the ResourceGenerator.cmake CMake module, which can be used to configure assets specifically for the Infineon/Cypress Traveo II, in order to specify color format, RLE compression flags, and asset location.

Compared to AutomaticCompressedLossless, it enables more explicit control over which compression method and pixel format to use.

Here's a snippet showing how the ResourceGenerator.cmake CMake module should be used:

set(external_resources "${CMAKE_CURRENT_BINARY_DIR}/external_resources.cpp")
start_generated_external_resources_file(${external_resources})
    compress_with_resource_generator(test_tvii_compressed_images images/cover01.png "VRAM" "R8G8B8" "" ${external_resources} 128 128 OFF)
    compress_with_resource_generator(test_tvii_compressed_images images/cover02.png "InternalFlash" "R8G8B8" "c" ${external_resources} 128 128 OFF)
end_generated_external_resources_file(${external_resources})
target_sources(test_tvii_compressed_images PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/external_resources.cpp)
qul_add_resource(test_tvii_compressed_images
    FILES
        images/cover01.png
        images/cover02.png)

The first parameter to compress_with_resource_generator is the target, and the second parameter is the image location.

The third parameter is the asset location, and the value can be "InternalFlash", "VRAM", or "HyperRAM", corresponding to one of the following memory banks:

The fourth parameter is the color format, with possible values such as R8G8B8A8 (32 bpp RGBA), X8B8G8R8 (32 bpp BGR), R8G8B8 (24 bpp RGB), R6G6B6 (18 bpp RGB), R4G4B4A4 (16 bpp RGBA), A1R5G5B5 (16 bpp ARGB), A8 (8 bpp alpha format), and so on. For full list of possibilities see the Graphics Driver for Traveo II Cluster Series User Guide.

The fifth parameter specifies compression, and the values can be "" for no compression, "c" for RLE compression, "cRLA" for RLA compression, "cRLAD" for RLAD compression, or "cRLAD<rgba>" where the RGBA values specify the maximum average number of bits for the channels red, green, blue and alpha. For example "cRLAD4442".

The sixth parameter is the name of a source file that the compressed assets will get written to. It should be added as a source to the target in the end.

The seventh and eighth parameters are the widh and height of the image asset, respectively.

The final parameter controls whether to enable object partitioning. Enabling it can improve blit engine throughput when using LBO to IBO or LBO to OTF layers, by splitting compressed assets into smaller partitions. For non-compressed assets, or direct IBO layers, it has no benefit.

Warping

The Infineon/Cypress Traveo II supports warping, enabling distorting the coordinate system of the displayed application.

A CYGFX_WARP_PARAM_S struct as well as a warping buffer needs to be provided by the application. For information about how to prepare these, refer to chapter 3.11.6 Warping Buffer of the Graphics Driver for Traveo II Cluster Series User Guide.

Using the Qt Quick Ultralite warping API for Infineon/Cypress Traveo II, it's possible to set a specific layer to use warping buffers.

First include the necessary header file:

#include <tviiextras/layerwarping.h>

Then call set the warping buffer for the layer with a given platform id like this:

Tvii::Warping::setWarpingBufferForLayer(platformId, warpBuffer, &warpParameters);

Finally, you must link your application against Qul::PlatformTraveoIIExtras.

Traveo II Extras module

Qt Quick Ultralite comes with a Traveo II Extras module which includes additional APIs specific to Traveo II. To use these APIs, link Qul::PlatformTraveoIIExtras to your project.

The following APIs are available through the extras module:

Traveo II custom effects

To make use of some of the custom hardware blending capabilities of the Traveo II it's possible to use the PaintedItem API.

The Qt Quick Ultralite tvii_effects Example demonstrates some effects using the PaintedItem API on Traveo II. The effects included in this example can also be used as components in a custom application.

Other board revisions

For Traveo II 6M, by default the TVII-C-2D-6M-327-SET (REV-01) board revision is supported. To use other Traveo II 6M board revisions, rebuild the platform from source with the following CMake configure options: