32-Bit Microcontroller, Graphic Driver
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series
User Manual
Doc. No. 002-04387 Rev. *A
Cypress Semiconductor
198 Champion Court
San Jose, CA 95134-1709
http://www.cypress.com
Copyrights
© Cypress Semiconductor C orporation, 2015-2016. This document is the propert y of Cy press Sem iconduc tor Corp oration and
its subsidiaries, including Spansion LLC (“Cypress”). This document, including any software or firmware included or
referenced in this document ( “Software”), is o wned by Cypress under the int ellectual property la ws and treaties of the Unit ed
States and other countries worldwide. Cypress reserves all rights under such laws and treaties and does not, except as
specifically stated in this p aragraph, grant any lic ense under its patent s, copyrights, tradem arks, or other intel lectual property
rights. If the Software is not accomp anied by a license agreement and you do not ot herwise have a written agreement with
Cypress governing the use of the Software, then Cypress hereby grants you a personal, non-exclusive, nontransferable
license (without the right to sublicens e) (1) under its copyr ight rights in the Software (a) for Software provided i n source code
form, to modify and reproduce the Software solely for use with Cypress hardware products, only internally within your
organization, and (b) to distribut e the Software in binar y code form external ly to end users (either dir ectly or indirectl y through
resellers and distributors), s olely for use on Cypress har dware product units, and (2) under those cl aims of Cypress’s patents
that are infringed by the Software (as provided by Cypress, unmodified) to make, use, distribute, and import the Software
solely for use with Cypress hardware pro ducts. Any other use, reproduction, modificati on, translation, or compilation of the
Software is prohibited.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, WITH REGARD TO THIS DOCUMENT OR ANY SOFTWARE O R ACCOMPANYING HARDWARE, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. To the extent permitted b y applicable law, Cypress reserves the right to make changes to this doc ument without
further notice. Cypress does not assum e any liabilit y arising out of the applic ation or use of any product or circuit descr ibed in
this document. Any information prov ided in this document, including any sample design information or programming code, is
provided only for reference pu rposes. It is the r espons ibilit y of the user of this d ocum ent t o proper ly des ign, pr ogram, and t est
the functionality and safety of any app lication made of this information and any res ulting product. Cypress products are not
designed, intended, or authorized for use as critical components in systems designed or intended for the operation of
weapons, weapons systems, nuclear installations, life-support devices or systems, other medical devices or systems
(including resuscitation equip ment and surgical implants), pollution control or hazard ous substances management, or other
uses where the failure of the device or s yste m c ould ca use perso nal i nj ur y, deat h, or pro p ert y damag e ( “Unint end ed Us es ”). A
critical component is any com ponent of a de vice or system whose fail ure to perform can be reas onabl y expected t o cause the
failure of the device or syste m, or to affect it s safety or effecti veness. Cypress is not liable, in whole or in part, and y ou shall
and hereby do release Cypress fr om any claim, damage, or other liability arising from or related to all Unintended Uses of
Cypress products. You shall indemnify and hold Cypress harmless fr om and against all claims, costs, dama ges, and other
liabilities, including claims f or personal injury or death, arising from or related to any Unintended Uses of Cypress products.
Cypress, the Cypress logo, Spans ion, the Spans ion logo, and com binations thereof , PSoC, CapSe nse, EZ-USB, F-RAM, and
Traveo are trademarks or registered trad emark s of Cypres s in t he United St ates and oth er count ries. For a more com pl et e list
of Cypress trademarks, visit cypres s .com. Other names and brands may be claimed as property of their respectiv e owners.
.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 2
Contents
1. 2D Graphics Driver ...................................................................................................................................................... 11
1.1 Target products.................................................................................................................................................... 11
1.2 About this Document ........................................................................................................................................... 11
1.3 Obtaining the Graphic Driver ............................................................................................................................... 11
2. Introduction .................................................................................................................................................................. 12
2.1 Target system ...................................................................................................................................................... 12
3. Getting Started ............................................................................................................................................................. 13
3.1 Installation ........................................................................................................................................................... 13
3.2 How to run an application .................................................................................................................................... 13
3.3 Writing an application .......................................................................................................................................... 13
4. Overview ....................................................................................................................................................................... 14
4.1 2D Graphics Driver parts ..................................................................................................................................... 14
4.2 Surface Overview ................................................................................................................................................ 14
4.2.1 Surface objects ....................................................................................................................................... 14
4.3 Display Overview ................................................................................................................................................. 15
4.3.1 Usage ..................................................................................................................................................... 17
4.4 Overview Pixel Engine (PixEng) .......................................................................................................................... 18
4.4.1 Pixel Engine ............................................................................................................................................ 18
4.5 Synchronization Overview ................................................................................................................................... 21
4.5.1 Processing Units ..................................................................................................................................... 21
4.5.2 Synchronization ...................................................................................................................................... 22
4.5.3 Sample use cases .................................................................................................................................. 23
4.6 Error Reporting Overview .................................................................................................................................... 25
4.7 Memory Management .......................................................................................................................................... 26
4.7.1 System Memory: ..................................................................................................................................... 26
4.7.2 Video Memory (VRAM): .......................................................................................................................... 26
4.7.3 Flash Memory: ........................................................................................................................................ 26
4.7.4 Physical Address - Virtual Address ......................................................................................................... 26
4.8 Coordinate System Hints ..................................................................................................................................... 27
4.8.1 Surface (Image) buffer ............................................................................................................................ 27
4.8.2 Display coordinates ................................................................................................................................ 27
4.8.3 PixEng coordinates ................................................................................................................................. 27
4.8.4 Matrix helper functions ............................................................................................................................ 28
4.9 Image Compression ............................................................................................................................................. 28
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 3
Contents
4.9.1 Compression Formats ............................................................................................................................. 29
4.10 Images With Color Index Table ........................................................................................................................... 30
4.10.1 Alpha support .......................................................................................................................................... 30
4.10.2 Image buffer ............................................................................................................................................ 30
4.10.3 Color table .............................................................................................................................................. 30
4.10.4 Surface properties for indexed images ................................................................................................... 30
4.10.5 Index images for blit operations .............................................................................................................. 31
4.10.6 Index images for the windows ................................................................................................................. 31
5. Glossary ....................................................................................................................................................................... 32
6. Tutorial ......................................................................................................................................................................... 35
6.1 About the Tutorial ................................................................................................................................................ 35
6.2 Application framework ......................................................................................................................................... 35
6.3 Restrictions .......................................................................................................................................................... 35
6.4 Tutorial chapters .................................................................................................................................................. 35
6.5 Tutorial 1: Surfaces_Blit_Display Basic ............................................................................................................... 36
6.5.1 Description .............................................................................................................................................. 36
6.5.2 MML_GDC_SURFACE ........................................................................................................................... 36
6.5.3 Initialization ............................................................................................................................................. 37
6.5.4 Fill with constant color............................................................................................................................. 37
6.5.5 A simple black-and-white image ............................................................................................................. 38
6.5.6 A simple auto-generated pattern ............................................................................................................. 39
6.5.7 Blending two surfaces ............................................................................................................................. 41
6.5.8 Bring it to the display............................................................................................................................... 41
6.6 Tutorial: Display Basic ......................................................................................................................................... 42
6.6.1 Description .............................................................................................................................................. 42
6.6.2 Chapters ................................................................................................................................................. 43
6.6.3 Code Description .................................................................................................................................... 44
6.6.4 Map Layer ............................................................................................................................................... 46
6.6.5 Frame Layer ........................................................................................................................................... 46
6.6.6 Position Layer ......................................................................................................................................... 46
6.6.7 Arrow Layer ............................................................................................................................................ 47
6.7 Tutorial: Display_Extended .................................................................................................................................. 48
6.7.1 Description .............................................................................................................................................. 48
6.7.2 Setup ...................................................................................................................................................... 48
6.7.3 Draw function .......................................................................................................................................... 49
6.7.4 Swap interval .......................................................................................................................................... 49
6.8 Tutorial: Speedometer ......................................................................................................................................... 50
6.8.1 Summary ................................................................................................................................................ 50
6.8.2 Learning Goals ....................................................................................................................................... 50
6.8.3 Chapters ................................................................................................................................................. 50
6.8.4 Preparation ............................................................................................................................................. 51
6.8.5 Matrix operations to scale, rotate and translate images .......................................................................... 52
6.8.6 Show different versions to restore and draw the needle layer ................................................................ 54
6.9 Tutorial: Chart (Single render buf fer sample) ....................................................................................................... 58
6.9.1 Summary ................................................................................................................................................ 58
6.10 Tutorial: Cover Flow ............................................................................................................................................. 62
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 4
Contents
6.10.1 Summary ................................................................................................................................................ 62
6.10.2 Usage ..................................................................................................................................................... 62
6.11 Tutorial: Digital Picture Frame ............................................................................................................................. 65
6.11.1 Summary ................................................................................................................................................ 65
6.12 Tutorial: Simple Drawing ...................................................................................................................................... 65
6.12.1 Summary ................................................................................................................................................ 65
6.12.2 Code documentation ............................................................................................................................... 66
6.12.3 The drawing functions ............................................................................................................................. 68
7. Module Index ................................................................................................................................................................ 71
7.1 Modules ............................................................................................................................................................... 71
8. Hierarchical Index ........................................................................................................................................................ 72
8.1 Class Hierarchy ................................................................................................................................................... 72
9. Data Structure Index .................................................................................................................................................... 73
9.1 Data Structures .................................................................................................................................................... 73
10. File Index ...................................................................................................................................................................... 74
10.1 File List ................................................................................................................................................................ 74
11. Module Documentation ............................................................................................................................................... 76
11.1 Basic Graphics .................................................................................................................................................... 76
11.1.1 Detailed Description ................................................................................................................................ 76
11.2 Driver Initialization API ......................................................................................................................................... 77
11.2.1 Detailed Description ................................................................................................................................ 77
11.2.2 Macro Definition Documentation ............................................................................................................. 77
11.2.3 Function Documentation ......................................................................................................................... 78
11.3 Configuration API................................................................................................................................................. 79
11.3.1 Enumeration Type Documentation ......................................................................................................... 79
11.3.2 Function Documentation ......................................................................................................................... 80
11.4 Surface API ......................................................................................................................................................... 81
11.4.1 Detailed Description ................................................................................................................................ 83
11.4.2 Macro Definition Documentation ............................................................................................................. 84
11.4.3 Typedef Documentation .......................................................................................................................... 84
11.4.4 Enumeration Type Documentation ......................................................................................................... 84
11.4.5 Function Documentation ......................................................................................................................... 88
11.5 Display API .......................................................................................................................................................... 91
11.5.1 Detailed Description ................................................................................................................................ 94
11.5.2 Macro Definition Documentation ............................................................................................................. 96
11.5.3 Typedef Documentation .......................................................................................................................... 97
11.5.4 Enumeration Type Documentation ......................................................................................................... 97
11.5.5 Function Documentation ....................................................................................................................... 103
11.6 Pixel Engine API ................................................................................................................................................ 113
11.6.1 Detailed Description .............................................................................................................................. 116
11.6.2 Macro Definition Documentation ........................................................................................................... 117
11.6.3 Typedef Documentation ........................................................................................................................ 119
11.6.4 Enumeration Type Documentation ....................................................................................................... 119
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 5
Contents
11.6.5 Function Documentation ....................................................................................................................... 122
11.7 Synchronization API .......................................................................................................................................... 135
11.7.1 Detailed Description .............................................................................................................................. 135
11.7.2 Typedef Documentation ........................................................................................................................ 135
11.7.3 Function Documentation ....................................................................................................................... 136
11.8 2D Core Interrupt Controller API ........................................................................................................................ 137
11.8.2 Macro Definition Documentation ........................................................................................................... 138
11.8.3 Function Documentation ....................................................................................................................... 139
11.9 Error Reporting API ........................................................................................................................................... 140
11.9.1 Detailed Description .............................................................................................................................. 141
11.9.2 Macro Definition Documentation ........................................................................................................... 142
11.9.3 Typedef Documentation ........................................................................................................................ 143
11.9.4 Enumeration Type Documentation ....................................................................................................... 143
11.9.5 Function Documentation ....................................................................................................................... 144
11.10 Error Codes ....................................................................................................................................................... 146
11.10.1 Detailed Description .............................................................................................................................. 149
11.10.2 Macro Definition Documentation ........................................................................................................... 149
11.11 Basic Graphics Type Definitions ........................................................................................................................ 156
11.12 Version Numbers ............................................................................................................................................... 156
11.12.1 Detailed Description .............................................................................................................................. 156
11.12.2 Macro Definition Documentation ........................................................................................................... 156
11.13 Type Definition ................................................................................................................................................... 157
11.13.1 Detailed Description .............................................................................................................................. 157
11.13.2 Typedef Documentation ........................................................................................................................ 157
11.14 Macro Definitio n ................................................................................................................................................. 159
11.14.1 Detailed Description .............................................................................................................................. 159
11.14.2 Macro Definition Documentation ........................................................................................................... 159
11.15 Tutorial Utilit y Library ......................................................................................................................................... 161
11.15.1 Detailed Description .............................................................................................................................. 161
11.16 Utilities for the Memory Management ................................................................................................................ 162
11.16.1 Detailed Description .............................................................................................................................. 162
11.16.2 Macro Definition Documentation ........................................................................................................... 162
11.16.3 Typedef Documentation ........................................................................................................................ 163
11.16.4 Function Documentation ....................................................................................................................... 163
11.17 Utility functions for matrix calculations ............................................................................................................... 166
11.17.1 Detailed Description .............................................................................................................................. 167
11.17.2 Macro Definition Documentation ........................................................................................................... 168
11.17.3 Typedef Documentation ........................................................................................................................ 168
11.17.4 Function Documentation ....................................................................................................................... 169
11.18 Utilities for the compatibility with other drivers ................................................................................................... 177
11.18.1 Detailed Description .............................................................................................................................. 177
11.18.2 Enumeration Type Documentation ....................................................................................................... 177
11.18.3 Function Documentation ....................................................................................................................... 178
11.19 Utilities for the Surface Management ................................................................................................................. 182
11.19.1 Detailed Description .............................................................................................................................. 182
11.19.2 Macro Definition Documentation ........................................................................................................... 183
11.19.3 Function Documentation ....................................................................................................................... 183
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 6
Contents
11.20 Utilities for the compression ............................................................................................................................... 186
11.20.1 Detailed Description .............................................................................................................................. 186
11.20.2 Function Documentation ....................................................................................................................... 186
11.21 Utilities for RLA (run length adaptive compression) ........................................................................................... 187
11.21.1 Detailed Description .............................................................................................................................. 187
11.22 Utilities for RLC (run length compression) ......................................................................................................... 187
11.22.1 Detailed Description .............................................................................................................................. 187
11.22.2 Function Documentation ....................................................................................................................... 187
11.23 Util class collection ............................................................................................................................................ 188
11.23.1 Detailed Description .............................................................................................................................. 188
11.24 CCtx ................................................................................................................................................................... 188
11.24.1 Detailed Description .............................................................................................................................. 188
11.25 CDevice ............................................................................................................................................................. 188
11.25.1 Detailed Description .............................................................................................................................. 188
11.26 CDisplay ............................................................................................................................................................ 188
11.26.1 Detailed Description .............................................................................................................................. 188
11.27 CMenu ............................................................................................................................................................... 189
11.27.1 Detailed Description .............................................................................................................................. 189
11.28 CSurface ............................................................................................................................................................ 190
11.28.1 Detailed Description .............................................................................................................................. 190
11.28.2 Function Documentation ....................................................................................................................... 190
11.29 CWindow ........................................................................................................................................................... 193
11.29.1 Detailed Description .............................................................................................................................. 193
12. Data Structure Documentation ................................................................................................................................. 194
12.1 RLAD::BitStream Class Reference .................................................................................................................... 194
12.1.1 Detailed Description .............................................................................................................................. 194
12.1.2 Constructor & Destructor Documentation ............................................................................................. 194
12.1.3 Member Function Documentation ......................................................................................................... 194
12.2 CCtx Class Reference ....................................................................................................................................... 196
12.2.1 Detailed Description .............................................................................................................................. 196
12.2.2 Constructor & Destructor Documentation ............................................................................................. 196
12.2.3 Member Function Documentation ......................................................................................................... 196
12.3 CDevice Class Reference .................................................................................................................................. 197
12.3.1 Detailed Description .............................................................................................................................. 197
12.3.2 Constructor & Destructor Documentation ............................................................................................. 197
12.3.3 Member Function Documentation ......................................................................................................... 197
12.4 CDisplay Class Reference ................................................................................................................................. 198
12.4.1 Detailed Description .............................................................................................................................. 198
12.4.2 Member Function Documentation ......................................................................................................... 198
12.5 CMenu Class Reference .................................................................................................................................... 200
12.5.1 Detailed Description .............................................................................................................................. 200
12.5.2 Member Enumeration Documentation .................................................................................................. 200
12.5.3 Member Function Documentation ......................................................................................................... 201
12.6 CMenuItem Class Reference ............................................................................................................................. 203
12.7 CStaticSurfaceWindow Class Ref erence ........................................................................................................... 204
12.7.1 Detailed Description .............................................................................................................................. 204
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 7
Contents
12.7.2 Member Function Documentation ......................................................................................................... 204
12.8 CSurface< NUM_BUFFERS > Class Template Reference ............................................................................... 206
12.8.1 Detailed Description .............................................................................................................................. 206
12.8.2 Constructor & Destructor Documentation ............................................................................................. 207
12.8.3 Member Function Documentation ......................................................................................................... 207
12.8.4 Field Documentation ............................................................................................................................. 208
12.9 CSurfaceWindow< NUM_BUFFERS > Class Template Reference ................................................................... 209
12.9.1 Detailed Description .............................................................................................................................. 209
12.9.2 Member Function Documentation ......................................................................................................... 209
12.9.3 Field Documentation ............................................................................................................................. 210
12.10 CWindow Class Reference ................................................................................................................................ 211
12.10.1 Detailed Description .............................................................................................................................. 211
12.10.2 Constructor & Destructor Documentation ............................................................................................. 211
12.10.3 Member Function Documentation ......................................................................................................... 212
12.10.4 Field Documentation ............................................................................................................................. 213
12.11 RLAD::Frame Class Reference ......................................................................................................................... 214
12.11.1 Detailed Description .............................................................................................................................. 214
12.11.2 Constructor & Destructor Documentation ............................................................................................. 214
12.11.3 Member Function Documentation ......................................................................................................... 214
12.12 MML_GDC_DISP_MODE_LINE Struct Reference ............................................................................................ 215
12.12.1 Detailed Description .............................................................................................................................. 215
12.12.2 Field Documentation ............................................................................................................................. 215
12.13 MML_GDC_DISP_PROPERTIES Struct Reference .......................................................................................... 217
12.13.1 Detailed Description .............................................................................................................................. 217
12.13.2 Field Documentation ............................................................................................................................. 218
12.14 MML_GDC_DISP_TCON_PROPERTI ES St ruct Reference ............................................................................. 219
12.14.1 Detailed Description .............................................................................................................................. 219
12.14.2 Field Documentation ............................................................................................................................. 219
12.15 MML_GDC_DISP_WINDOW_PROPERTIES Struct Reference ........................................................................ 220
12.15.1 Detailed Description .............................................................................................................................. 220
12.15.2 Field Documentation ............................................................................................................................. 220
12.16 MML_GDC_PE_CONTEXT_CONTAINER Struct Reference ............................................................................ 221
12.16.1 Detailed Description .............................................................................................................................. 221
12.16.2 Field Documentation ............................................................................................................................. 221
12.17 MML_GDC_SURFACE_CONTAINER Struct Reference ................................................................................... 221
12.17.1 Detailed Description .............................................................................................................................. 221
12.17.2 Field Documentation ............................................................................................................................. 221
12.18 MML_GDC_SYNC_CONTAINER Struct Reference .......................................................................................... 222
12.18.1 Detailed Description .............................................................................................................................. 222
12.18.2 Field Documentation ............................................................................................................................. 222
12.19 MML_GDC_SYSINIT_INFO Struct Reference .................................................................................................. 222
12.19.1 Detailed Description .............................................................................................................................. 222
12.19.2 Field Documentation ............................................................................................................................. 222
12.20 RLAD::Package Struct Reference ..................................................................................................................... 223
12.20.1 Detailed Description .............................................................................................................................. 223
12.20.2 Field Documentation ............................................................................................................................. 223
12.21 RLAD::Frame::Pixel Struct Reference ............................................................................................................... 224
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 8
Contents
12.21.1 Detailed Description .............................................................................................................................. 224
12.21.2 Field Documentation ............................................................................................................................. 224
12.22 RLAD Class Reference ...................................................................................................................................... 225
12.22.1 Detailed Description .............................................................................................................................. 226
12.22.2 Member Enumeration Documentation .................................................................................................. 226
12.22.3 Member Function Documentation ......................................................................................................... 226
12.22.4 Field Documentation ............................................................................................................................. 228
13. File Documentation .................................................................................................................................................. 229
13.1 flash_resource.h File Reference ........................................................................................................................ 229
13.1.1 Detailed Description .............................................................................................................................. 229
13.2 mm_defines.h File Reference ............................................................................................................................ 229
13.2.1 Detailed Description .............................................................................................................................. 230
13.3 mm_gdc_erp.h File Reference .......................................................................................................................... 230
13.3.1 Detailed Description .............................................................................................................................. 230
13.4 mm_gdc_errors.h File Reference ...................................................................................................................... 230
13.4.1 Detailed Description .............................................................................................................................. 233
13.5 mm_gdc_module_id.h File Reference ............................................................................................................... 233
13.5.1 Detailed Description .............................................................................................................................. 234
13.6 mm_gdc_version.h File Reference .................................................................................................................... 234
13.6.1 Detailed Description .............................................................................................................................. 234
13.7 mm_types.h File Reference ............................................................................................................................... 234
13.7.1 Detailed Description .............................................................................................................................. 234
13.8 mmd_gdc_interrupthandler.h File Reference ..................................................................................................... 235
13.8.1 Detailed Description .............................................................................................................................. 235
13.9 mml_gdc_config.h File Refere nc e ..................................................................................................................... 236
13.9.1 Detailed Description .............................................................................................................................. 236
13.10 mml_gdc_display.h File Reference .................................................................................................................... 236
13.10.1 Detailed Description .............................................................................................................................. 240
13.11 mml_gdc_erp.h F il e Reference .......................................................................................................................... 240
13.11.1 Detailed Description .............................................................................................................................. 240
13.12 mml_gdc_pixeng.h File Reference .................................................................................................................... 240
13.12.1 Detailed Description .............................................................................................................................. 243
13.13 mml_gdc_surfm an.h File Reference .................................................................................................................. 244
13.13.1 Detailed Description .............................................................................................................................. 245
13.14 mml_gdc_sync. h File Reference........................................................................................................................ 246
13.14.1 Detailed Description .............................................................................................................................. 246
13.15 mml_gdc_sysinit.h File Reference ..................................................................................................................... 247
13.15.1 Detailed Description .............................................................................................................................. 247
13.16 pe_matrix.h File Reference ................................................................................................................................ 248
13.16.1 Detailed Description .............................................................................................................................. 249
13.17 sm_util.h File Ref erence .................................................................................................................................... 250
13.17.1 Detailed Description .............................................................................................................................. 250
13.18 ut_class_ctx.h File Reference ............................................................................................................................ 251
13.18.1 Detailed Description .............................................................................................................................. 251
13.19 ut_class_device.h File Reference ...................................................................................................................... 251
13.19.1 Detailed Description .............................................................................................................................. 251
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 9
Contents
13.20 ut_class_display.h File Reference ..................................................................................................................... 251
13.20.1 Detailed Description .............................................................................................................................. 251
13.21 ut_class_menu.h File Reference ....................................................................................................................... 252
13.21.1 Detailed Description .............................................................................................................................. 252
13.22 ut_class_rlad. h File Reference .......................................................................................................................... 253
13.22.1 Detailed Description .............................................................................................................................. 253
13.22.2 Macro Definition Documentation ........................................................................................................... 253
13.23 ut_class_surface.h File Reference ..................................................................................................................... 254
13.23.1 Detailed Description .............................................................................................................................. 254
13.24 ut_class_window.h File Reference .................................................................................................................... 254
13.24.1 Detailed Description .............................................................................................................................. 254
13.25 ut_compatibility.h File Reference ....................................................................................................................... 255
13.25.1 Detailed Description .............................................................................................................................. 255
13.26 ut_compression.h File Reference ...................................................................................................................... 256
13.26.1 Detailed Description .............................................................................................................................. 256
13.27 ut_memman.h File Reference ........................................................................................................................... 256
13.27.1 Detailed Description .............................................................................................................................. 256
13.28 ut_rlc.h File Reference ....................................................................................................................................... 257
13.28.1 Detailed Description .............................................................................................................................. 257
14. Major Changes ........................................................................................................................................................... 258
15. Revision History ........................................................................................................................................................ 259
Document Revision History ......................................................................................................................................... 259
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 10
1. 2D Graphics Driver
1.1 Target products
This application note is described about below products;
(TYPE4-M4)
Series
S6E2DH S6E2DH5G0A, S6E2DH5GAA, S6E2DH5GJA, S6E2DH5J0A, S6E2DH5JAA
S6E2DF S6E2DF5G0A, S6E2DF5GAA, S6E2DF5GJA, S6E2DF5J0A, S6E2DF5JAA
S6E2D5 S6E2D55G0A, S6E2D55GAA, S6E2D55GJA, S6E2D55J0A, S6E2D55JAA
S6E2D3 S6E2D35G0A, S6E2D35GAA, S6E2D35GJA, S6E2D35J0A, S6E2D35JAA
Product Number(not included Package suffix）
1.2 About this Document
This document describes the API and us age of the 2D Graphics Driver requir ed to use the 2D Graphics core.
The document does not describe the required application frame work or t he usage of other peripherals apar t from
the 2D Graphics core.
Please refer to the Delivery Note of your product for devices currently supported with this product.
1.3 Obtaining the Graphic Driver
To obtain the graphic driver, please contact your local sales office.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 11
2. Introduction
2.1 Target system
The 2D Graphics core and its encircl ing graphics sub system is a hardware sub-component of an integrated
SOC like S6E2D.
Beside the graphical sub-system the c hi p s upports many different peripher als.
The following image shows the basic SOC hardware and software components required to run a typical
application.
Figure 1. Hardware and software components
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 12
3. Getting Started
3.1 Installation
Unpack the archive to a location of your choice.
This package contains all headers, li braries and documentation needed to develop graphics applications for the
S6E2D Graphics Hardware. The top level directory contains the following directory structure:
00_s6e2dh_demeter_sw_framework - Cypress FM4 application template, startup code and peripheral dr i v ers.
01_bin - Graphics Core libraries.
02_driver - API header files.
04_sample - Sample applicati on s ource code.
05_util - Utility library source code used by some of the samples.
08_tool - Tools used by some of the samples.
11_doc - User Documentation.
Building examples: For each sample application there is a subdirectory IAR, ARM or GNU (depending on the
supported platform) containing a project file for the respective tool chain ( e.g., IAR Embedded Workbench 7.10 or
Keil uVision).
3.2 How to run an application
If the tool chain provides flash support for both internal flash and external hyper flash, the tutorial applications can be
started from the debugger. Otherwise an appropriate flash programmer is required to download the code and ima ge
data to the S6E2D Starter Kit.
3.3 Writing an application
The following steps list the typical fl ow of an application using the 2D Graphi c s hardware:
1. Initial ize the graphics driver (see Driver Initialization API).
2. Open the display (see Display API).
3. Create one or more windows (or ’layers’) for each display (see Display API).
4. Use the Surface API to describe source and target frame buffers (see Surface API).
5. Use any of the APIs described below to create and m anipulate graphics content (see Pixel Engine API).
6. Close al l created windows (see Display API).
7. Close the display (see Display API).
8. Uninitialize the driver (see Driver Initialization API).
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 13
4. Overview
4.1 2D Graphics Driver parts
As shown in the Introduction the 2D Graphi cs Driver consists of different modules. The following sub-pages will give
an overview about the function of som e of these modules. Beside these overview pages this document includes a
detailed API documentation for each module.
4.2 Surface Overview
4.2.1 Surface objects
The 2D Graphics Driver uses ’surface objects’ to store information about video memory blocks representing an
image, a frame buffer and similar things . That means the surface contains the related information about memory
address(es), color format, dimension, compression format and more.
The following diagram shows the generic usage of a surface object.
Figure 2. Surface usage
Note:
Not all hardware blocks can operate with each surface format. Please check the related API description about the
supported formats.
See Surface API for details.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 14
Overview
4.3 Display Overview
The 2D Graphics core has one display co ntroller that can be connected to a scr een (in the following named Display).
The Display has a constant background color "BG Color".
Up to 9 different frame buffers can be used to show content at individual rect angles (called Windows) on the displ ay.
The Windows are arranged in a defined z -order which is determined by the layer i d and sub-layer id (specified in the
properties of each window).
The display controller of the S6E2D device supports up to 2 layers. One of them supports up to 8 sub-layers. It
means it is possible to open 8 windows with the same layer id. To use the sub-layers the related window must be
opened with the MML_GDC_DISP _FEATURE_MULTI_LAYER feature request. Windows that share the same
layerId are called Multi-Window: u p to 8 windows with identical layerId, but with different sub_layerIds (a lso specified
in the properties of each window). Multi-Windows that overlap c annot be blended with each other, they are dr awn
opaque, (i.e., only the content of the window with the highest sub_laye rId is visible).
Windows that overlap can be drawn opaque (only the highest layer is visible) or they can be blended using up to 2
blend units.
Overlapping Windows with the diff erent layer ids can be blended with each other.
Overlapping Windows with the same layer id cannot be blended with each ot her . Only the content of the window
with the highest sub-layer id will be used for the layer blend operation.
Note:
Please note that the hardware manual uses a different wording compared to the software manual and API. The
following table describes the different meaning:
Hardware manual naming Software manual naming Description
Background Plane Background (BG) color of display
Foreground Plane Layer See glossary layer
Layer Sub-Layer See glossary sub-layer
Each display controller has the capability to
generate a full screen constant color.
When a Window is created it is assign ed to a Display.
Figure 3. S6E2D display unit
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 15
Overview
This architecture allows creating c om plex scenes with low VRAM usage a nd low memory usage. The following
example shows a possible scene for one display controller for a device with 5 blend units and up to 26 windows. The
S6E2D cannot handle such complex scene however the sample shows the idea behind the layers and windows:
Figure 4. Sample display scene
A single layer architecture requires to render all details for each frame. It requires much CPU time and VRAM. The
display window concept allows t he following architecture visualiz ed as perspective view:
The gray colored window shows a background layer that might be a compressed 8 bpp indexed image buffer
because the content is static.
The yellow colored windows repres ent the second layer. Each separate window may be rendered and updated
with a different frame rate and color format.
The green colored windows represent the next layer blend level.
The red colored windows are the most top windows. In this case they show stat i c 4 bpp indexed images and
can be independently switched and faded.
Figure 5. Perspective view to the sc ene
All windows support a minimum functionality: show a image or frame buffer with red, green, blue or gray and
optional alpha information. The color and optional alpha information will be read from a continuous video mem ory
block with a defined width, height and s tride. The bits per pixel (BPP) can be 1, 2, 4, 8, 16, 18, 24 or 32. The
mapping to the color or alpha channels can be selected freely. The images can be used with Simple Transformation.
Some windows support special feat ures beside this standard feature set . The different window names in the image
above reflect such features. The usage of such an advanced feature may restrict other Display or Windows
properties.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 16
4.3.1 Usage
The following image shows the st eps required to use one 2D core Display Cont roller with one Window.
Overview
Figure 6 .Activity diagram
The Display API lists all supported f eatures and the related restrictions.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 17
Overview
4.4 Overview Pixel Engine (PixEng)
4.4.1 Pixel Engine
The Pixel Engine is a hardware IP that efficiently performs pixel oper ations on two-dimensional memory blocks. It
reads simultaneously from up to t hree source rectangles, executes pix el processing operations on these and s tores
the result in another rectangular memory region.
The Pixel Engine functionality i s covered by the Pixel Engine API of t he 2D Graphics Driver. The Pixel Engine API
uses the concept of ’surface objects ’ and ’context objects’ to perform al l operations. Surface objects are created and
bound to a context to perform blit operat i ons to the memory and deleted when no longer needed. A context needs
always a surface bound to the STORE target where the resulting pixel da ta will be stored. Depending on the
requested operation a SRC, DST and MAS K surface must also be bound to the conte xt. SRC, DST and MASK
surfaces define the pixel sources for a blit operation. A surface object can be associated to a memory address to
operate with this memory. It is also possible to use a surface without an attached memory address and use it as a
blit source. In this case only some pro per ties such as the clear color and geometry are used.
Figure 7. PixEng usage
The active API calls (processing and writing pixel data) of the Pixel Eng i ne API are mmlGdcPeFill and
mmlGdcPeBlt. The mmlGdcPeFill call with a previously attached store surface can be used to fill a buffer.
mmlGdcPeBlt can be used for all other operations like copying, scaling, r otation, blending and color manipulating
processing and combinations of them. The surfaces bound to the context and the properties set to the context define
the requested operations. The following table shows the required and optional surfaces to perform an operation.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 18
Overview
Operation Output (required) Input (required)
Fill STORE - - Copy, Scale, Rotate STORE SRC DST MASK
ROP3 STORE SRC, DST, MASK - -
Optional with
Blend operation
Optional with
ROP2 or External
Alpha
Note:
Please note that the hardware manual uses a different wording compared to the software manual and API. The
following table describes the different meaning:
Hardware manual naming Software manual naming Description
Please note that the Pixel Engine defined in
Pixel Engine Pixel Engine (PixENG)
hardware manuel has a diffrent meaning.
See glossary PixEng.
The processing flow for the related op erations are visualized in the following image:
Figure 8. Processing flow for blit oper ations
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 19
Overview
channels
channel (A)
Operation
Copy
Blend Operation
Blend with external alpha
STORE=Surface 1
MASK=Surface 3
Example: The following images ar e us ed
Surface 1 color channels Surface 2 color (RGB)
A blit operation will show the following result depending on the bounded surfaces
Bound
surfaces
Result
STORE=Surface 1
SRC=Surface 2
All geometry related settings li ke translation, scaling or mirrorin g can be calculated using matrices. E ach source
surface can get its own matrix, so dif ferent translations for source buffer and blend destination are possible. The
coordinate center is per default the lower left corner of each surface so a simple copy instruction will co py the source
surface to the lower left corner of the store surface.
Furthermore, the connected surfaces (STORE, SRC, DST and MASK) can hav e different properties like color f ormat
dimension or compression. Not all properties are supported for each pipe configuration. Surface properties may also
restrict other blit features. For i ns tance it is not possible to rotate a compr essed image. The mmlGdcPeBlt call
reports an error if the given properties cannot be applied to the hardware. In this case the application dev el oper
must simplify the blit operation or may split it into 2 separate blit instructions with a temporary buffer.
Surface 2 alpha (A)
STORE=Surface 1
SRC=Surface 2
DST=Surface 1
Surface 3 alpha (A) channel
SRC=Surface 2
DST=Surface 1
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 20
Overview
Target
Surface and context properties
STORE
− All RGBA formats.
rotation)
The following table gives an overv iew about supported surface propert ies and features:
− All RGBA formats.
SRC
DST
− Geometry operations like translation, scaling, rotation and perspective transformation.
− Decompression or indexed color. (Restriction: DST must not use these features, only scale and translation
operations are supported)
− Warping. (No geometry operations possible)
− All RGBA formats.
− Geometry operations like translation, mirroring and simple rotation (multiple of 90 degree).
− Decompression or indexed color. (Restriction: SRC must not use these features, no mirroring or simple
MASK
− All RGBA formats except 18 bpp.
− Geometry operations like translation, mirroring and multiple of 90 degree rotations
− Scaling. (Restriction: SRC must use the same scale factors)
Note:
The pixel operations may not be finished after a mmlGdcPeFill or mmlGdcPeBlt call. That means the involved
buffers may still be in use. Please use s ynchronization objects or simply mmlGdcPeFinish to ensure that all
operations are complete.
Pixel Engine operations can be queu ed by the driver to enhance performance especially in a multi-threading
environment. The fast execution esp ecially of long processing commands can be forced by an mmlGdcPeFlush call.
For more details about the usage of the Pixel Engine API see the tutorials and the respective sample code that are
part of this driver documentation.
4.5 Synchronization Overview
4.5.1 Processing Units
The S6E2D hardware consists of s everal independent, parallel running units. The driver is designed so that
applications can use this parallel processing also in single threaded env i ronment. The driver distinguis hes the
following processing pipelin es:
CPU: The ARM core executing the program code.
The PixEng processing block. All blit instructions for this pi peline will be pushed by the driver into the Command
Sequencer queue. That means the applicatio n ( the CPU) can initiate many fill and blit c ommands in a series,
without having to wait for completion of these commands. The graphics hardware starts operating in parallel,
typically it requires more time t o pr ocess the pixels than to setup the proc essing by the CPU.
Windows: All graphics hardware layers are represented as Windows in the driver and handled as separate
processing units. Changing properties like the frame buffer address of a window must be committed using
mmlGdcDispWinCommit(). The new properties become active with the next f rame start on the display. A commit
instruction may block the CPU, if the previously called mm lGdcDispWinCommit() is not yet active in the HW.
That means if two calls of mmlGdcDispWinCommit() are called one after the other, the second call will be
blocked until the next frame start . This behavior can be changed using the
MML_GDC_CONFIG_ATTR_DISPLAY_NOBLOCK attribute of mmlGdcConfigSetAttribute() or by using the
driver synchronization API.
Display: The display (more precisely: display controller) is also handled as a separate unit.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 21
Overview
4.5.2 Synchronization
The Synchronization API provides mechanisms to synchronize the processing blocks. This is done through sync
objects. A sync object describes a sync condition, (e.g., a certain image buffer operation that has to be completed).
Sync objects are managed through the Synchronization API, which provi des functions to reset sync objects and to
wait for a sync condition to become true. Setting a sync condition (in a sync obj ec t) is done by the component that
owns the sync type. For example, the Display API provides a function to writ e the sync condition "Surface to be
displayed is actually shown on the sc reen" to a sync object. Waiting for a sync condition can be done by an
application (as described above) , which is called a "client wait", but also in a graphics processing pipeline
withoutintervention by the appli c ation. This is called a "server wait ". Server waits are implemented by the com ponent
that owns the graphics processing pipeline. For example, the Pixel Engine API provides a function to submit a sync
condition to the Pixel Engine command queue (queue to hold the submitted PixEng operations). PixEng operations
submitted after the sync, will onl y be executed after the sync condition becomes true.
Following are a few examples to illustrate the use of sync objects:
An application renders 2D graphics o nto the screen using double-buffering. It can use sync objects to make
sure a pixel buffer has already been displa ye d, (i.e., is free to render a new 2D graphics into it).
The following processing unit events can be used to generate a sync condition:
Display Controller VSync (new frame started): see mmlGdcDispSyncVSync()
Window mmlGdcDispWinCommit() is executed: see mmlGdcDispWinSync()
Previously committed PixEng operations are finished: see mmlGdcP eSync()
The following possibilities for sync server waits exist within the 2D Graphics Driver:
The Window mmlGdcDispWinCommit() may wait for a sync condition: see mmlGdcDispWinWaitSync()
The Pixel Engine command queue can wait for a sync condition: see mmlGdcPeWaitSync()
The CPU can check a sync condition:
Check sync condition: see mmlGdcSyncWait()
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 22
Overview
4.5.3 Sample use cases
4.5.3.1 Double buffered window
A typical application must render a new frame content for each display loop. D ouble buffered frame buffers are used
to render the next frame in a background buffer while the foreground buffer memory is read by the display controller.
The following sample code shows how the application can use the 2D Graphic s D r i ver Synchronization API to
realize a double buffered Window:
// This structure contains the objects required for a double buffered window.
struct DOUBLE_BUFFERED_WINDOW
{
MML_GDC_DISP_WINDOW win; // the window handle
MML_GDC_SURFACE_CONTAINER sFramebuffer[2]; // Two buffers described as surface objects.
MML_GDC_SYNC_CONTAINER sync; // A sync object.
MM_U08 id; // An id storing which buffer is c ur rently the foreground buffer.
};
// This is the draw function for the window including buffer swap and synchronization.
MM_ERROR draw(DOUBLE_BUFFERED_WINDOW *pdbW in)
{
// Return if the last render operation is still ongoing.
if (mmlGdcSyncWait(&pdbWin->sync, 0) == MML_ERR_GDC_SYNC_TIMEOUT)
return MML_OK;
// Bind new background buffer to render context.
mmlGdcPeBindSurface(&ctx, MML_GDC_PE_STORE |
MML_GDC_PE_DST, &pdbWin->sFramebuffer[pdbWin->id]);
// Render the next frame
mmlGdcPe..
mmlGdcPe..
mmlGdcPe..
// Get a sync object for the last blit operat ion ...
mmlGdcPeSync(&pdbWin->sync);
// ...and push it in the windows pipe. (It ens ures that the new buffer becomes
//visible after the last blit is execute d in the hardware.)
mmlGdcDispWinWaitSync(pdbWin->win, &pdbWin->sync));
// Swap the foreground and background layer on display.
mmlGdcDispWinSetSurface( pdbWin->win,
MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF, &pdbWin->sFramebuffer[pdbWin->id] );
// Commit changes.
mmlGdcDispWinCommit( pdbWin->win );
// Get a sync object for this commit function for the next loop.
mmlGdcDispWinSync( pdbWin->win, &pdbWin->sync );
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 23
Overview
// Switch foreground and background buffer id.
pdbWin->id = (pdbWin->id == 0) ? 1 : 0;
return MML_OK;
}
// Here is the calling render loop.
main
{
DOUBLE_BUFFERED_WINDOW win_struct;
// Init variables, open window, ...
// Bind new background buffer to render context.
mmlGdcPeBindSurface(&ctx, MML_GDC_PE_STORE |
MML_GDC_PE_DST, &win_struct.sFramebuffer[win_struct.id]);
// Render the first frame.
mmlGdcPe..
mmlGdcPe..
mmlGdcPe..
// Reset the sync.
mmlGdcSyncReset(&win_struct.sync);
// Get a sync object for the first blit operat i on.
mmlGdcPeSync(&win_struct.sync);
while()
{
// Proceed with any non-graphics related operations.
do_anything();
// Call the render routine.
// Note that the draw function will only render new content if a frame swap
// was executed. Otherwise the draw function will return immediately so that
// do_anything() is called again.
draw(&win_struct);
}
}
The draw() function starts rendering if the previously rendered buffer becomes visible. The application can push all
render instructions in the queue, adds a sync instruction that the next buffer swap has to wait for blit complete and
assigns the new buffer to the window. Afterwards the CPU can handle other tasks. Please note that the comman d
sequencer queue (see mmlGdcSysSet InstructionBuffer()) must be big enough to store all blit operations.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 24
Overview
4.5.3.2 Single buffered window
As double buffering requires more m em ory, it is worthwhile to consider whether a single buffer is sufficient for a
specific application. In this case c are must be taken that rendering does not affect the part of the window that is
currently read by the display controller to avoid tearing. A simple technique is to do the rendering comp letely in the
blanking period of the display (as demonstrated in the Speedometer sample) . A more sophisticated approach sp li ts
the frame buffer into several regions and updates only the region that is curr ently not read by the display controller
(as demonstrated in the Chart sample).
See Synchronization API for details.
4.6 Error Reporting Overview
This API provides functions to confi gure the reporting of ERROR, WAR NING and INFO messages. The level of
these messages can be specified per module.
See Error Reporting API for details.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 25
Overview
4.7 Memory Management
Different to many other graphic s drivers the 2D Graphics Driver for S6E2D does not include or use any memory
management routines (dynamic memory usage). However memory is req uired for different functions:
4.7.1 System Memory:
System Memory is a memory block assigned to the CPU as operating memory for OS and application. The driver
requires some static memory blocks t hat should be assigned by the linker t o this block. In the reference
implementation, S6E2D’s SRAM0 is used for this purpose.
2D Graphics hardware blocks can r ead and write system memory. Typically the 2D Graphics components should
not be configured to access system memory because especially frame buf fer and similar operations are optimized
for the VRAM access.
4.7.2 Video Memory (VRAM):
The Video Memory is a dedicated memory block inside the Graphics hardware designed to store graphical content.
The VRAM is also used as command list b uffer. Therefore, it is required that the CPU must also have access to the
VRAM.
4.7.3 Flash Memory:
Program code and image data are typically read from (embedded or external) flash memory. In most of the example
applications, the embedded fl as h i s used for code and external (hyper) flash for data used by the graphics engine
("RES_SECTION"). This is accomplished by a linker directive (see flash_resource.h).
4.7.4 Physical Address - Virtual Address
In this document, in particular in the Surface API description, the terms Virtual Address and Physical Add ress are
used.
For S6E2D devices the physical and vir tual address of a register or memory block are identical because the
hardware does not contain a Memory Man agement Unit. Such a Memory Manageme nt Unit is typically used by
complex operating systems to assign different applications or driver s individual (virtual) memory ranges different
from the real physical addresses. If the 2D Graphics Driver is used in such a system an address type differentiatio n
and translation is required and therefore the driver partly supports both types.
Because the 2D Graphics Driver was developed using a software model of the 2D c ore that requires a differentiation
of physical and virtual address, some tutorial examples use an address translation macro. The macro does not
change the address for the final 2D Graphi cs Driver.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 26
Overview
4.8 Coordinate System Hints
Driver APIs for graphical operation use different coordinate systems. The following definitions are used inside the 2D
Graphics Driver:
4.8.1 Surface (Image) buffer
Images (described by a surface) ar e always line based from top to down, left to right. That means the first bits in a
surface memory buffer describe the u pper left pixel, the next bits describe the pixel right of the first, and so on.
Figure 9. Zoomed image with pixel enumerat ion
4.8.2 Display coordinates
Analog to images the display coordinate system always starts at the top left pixel.
4.8.3 PixEng coordinates
For compatibility reasons the PixE ng c oordinate system starts per default with the bottom left pixel.
Note:
The very first pixel starts at 0.0, 0.0 and ends at 1.0, 1.0. That means the geometrical center of this pixel is 0.5, 0.5.
The following image is the result of a c opy instruction of the 4 3 pixel image above with offset 0, 0.
Figure 10. Zoomed blit and draw result with bot tom left coordinate system setting
For some use cases it is much simpler to use the same coordinate system like t he di splay. Besides this some
graphics formats (e.g., SVG) and APIs use the opposite coordinate syst em. That’s why the 2D Graphics Dr i v er
supports the mirrored coordinate system too and the user can switch the coordinate handling to top left zero point.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 27
Overview
The same image rendered above will now show the following result:
Figure 11. Zoomed blit and draw result with top l eft coordinate system setting
4.8.4 Matrix helper functions
The 2D Graphics Driver comes with many tutorial samples and sample cod e. For geometrical operation the util ity
part includes matrix calculation helpers. Different matrix form ats are available
Mat3x2: This matrix format can be used for 2 dimensional operations like translation, scaling and rotation.
Mat3x3: This matrix format must be used for the API in the blit path for the source image if a "3D" operation is
required.
Mat4x4: The 4x4 matrix is just a helper format. The related functions are basically similar to other "3D" render
APIs like OpenGL. However, the depth information is not used, so t he 2D Graphics Driver API does not support
this matrix format. An application can anyway use these helper functions for the view calculation, because the
matrix result can be converted into a 3x3 matrix by removing the depth (z) par ts from the matrix.
The following example shows the required Mat3X2 operations to rotat e the image above at the center of second
pixel in the second line and blend the result to a target. The rotation center of the source pixel will be located at the
center of pixel 4, 2 in the target.
//reset the matrix
utMat3x2LoadIdentity(mat);
//translate to target coordinates
utMat3x2Translate(mat, 4.5f, 2. 5f);
//90 degrees rotation
utMat3x2Rot(mat, 90.0f);
//translate to center of pixel 1, 1 in s ource coordinate system
utMat3x2Translate(mat, -1.5f, -1.5f);
Figure 12. Zoomed blit result with matrix operation (bottom left coordinate c enter)
4.9 Image Compression
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 28
Overview
case
dimension.
To reduce the amount of required memory the 2D core HW supports compressed images.
4.9.1 Compression Formats
The following compression format s for pixel buffer are supported by the 2D c ore.
Name Features Limitations
− Lossless compression.
Run-length coded
MML_GDC_SURF_COMP_RLC
Run-Length Adaptive
MML_GDC_SURF_COMP_RLA
Run-Length Adaptive
Dithering
MML_GDC_SURF_COMP_RLA
D
− Backward compatible to
legacy devices.
− RLC compression can be
used in combination with
indexed color.
− Lossless compression.
− Good compression
results for images with
smooth content borders.
− The 2D core HW can
read and write this
format.
− Maximum buffer size can
be calculated (1).
− Only supported as read
buffer for blit operations and
as window content.
− Rotation or mirroring is not
supported.
− Only supported as read
buffer for blit operations and
as window content.
− Rotation or mirroring is not
supported.
− A compressed buffer must
not exceed the window
dimension.
− Lossy compression.
− Rotation or mirroring is not
supported.
− A compressed buffer must
not exceed the window
4.9.1.1 Calculation of required buffer size for RLAD compression
The following formula can be used to calculate the maximal required buffer size:
pixel_size = cbpc0_max + cbpc1_max + c bpc2_max + cbpc3_max
header_size = (cbpc0_width + cbpc1_width + cbpc2_width + cbpc3_width) + (bpc0 + bpc1 + bpc2 + bpc3)
num_header = ceil(frame_width / 8) * frame_height
buf_size = num_header * header_size + frame_width * frame_height * pixel _s i ze
buf_words = ceil(buf_size / 32)
bpc0/1/2/3: ComponentBitsR ed/Green/Blue/Alpha (see MML_GDC_SURF_ATTR_COLORBITS).
cbpc0/1/2/3_max = RLADCompBitsR ed/Green/Blue/Alpha
(see MML_GDC_SURF_ATTR_RLAD_MAXCOLORBITS).
cbpc0/1/2/3_width = floor(log2(bpc0/1/2/3)) +1 or 0 if the component s i z e is 0.
frame_width/height = dimension of input frame.
Some typical setups and resulting compression rates (compressed/uncompressed) for RGB888 image data:
RLADCompBitsRed/Green/Blue
4/5/4 => 73 %
3/4/3 => 61 %
2/3/2 => 48 %
Note:
Images compressed with MML_GDC_SURF_COMP_RLAD may result in a smaller size however also for worst case
images the maximum size will not be exc eeded.
Recommended use
− Compression of
source images with
long line parts with
constant color.
− Compression of
source images.
− Compression of
source images with
size limitation.
4.9.1.2 How to create compressed images
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 29
Overview
colors
Images without per pixel alpha and a maximum of
256 different colors.
Images with 16 colors only (please note: the
and 1 transparent color).
Images with 8 levels of transparency (alpha) and
RGB1 1 1 0 2
All images with only 2 different colors.
The Tutorial Utility Library contains a Utilities for the compression part providing sample code to create r un-lengthcoded and run-length-adaptive compres sed buffers. Furthermore the 2D Core Driver package contains a windows
command line tool "ResourceGenerat or.exe" that can be used to convert a png im age into a compressed buffer and
store it in a c compliant header file. Afterwards this content can be used by the utSurfLoadBitmap() function t o fill a
MML_GDC_SURFACE object that can be used for blit or display API functi ons .
4.10 Images With Color Index Table
To reduce the amount of required memory the HW supports images with indexed colors. In this case the image
requires 2 buffers:
One buffer contains all possible colors for this image: the color table or "color look up table".
The second buffer is the typical image buffer. But for each pixel in the image, it only stores an index pointing to
a color in the color table.
4.10.1 Alpha support
Index images can also include per pixel alpha values to control the transp arency of the addressed color. The alpha
information can be stored either in t he image buffer beside the index pointer or it can be part of the color table.
4.10.2 Image buffer
Like other image buffers also image b uffer for indexed images can use dif ferent sizes. Depending on the bit width of
the index pointer the image can store a d efined maximum of different color s . Beside the index pointer the i m age
buffer may also contain alpha bits. The sum of alpha and index bits must be 1, 2, 4, 16, 24 or 32. The index bits
must start at bit position 0.
The following table shows some possible pixel buffer color formats for indexed images. Only the size of red channel
in a surface defines the index width. The green and blue channel definition is not used for such images. Therefor e a
short format RGB8 is equivalent to 8 bit index.
Short format
RGB8 8 8 0 256
RGB4 4 4 0 16
A8RGB8 16 8 8 256
A3RGB5 8 5 3 32
Bit per
pixel
Index
bits
Alpha bits
4.10.3 Color table
The color table can store up to 256 different colors. Each entry defines the RGB and optionally the alpha value. The
maximum number of bits to store these val ues are 24 bit per entry. Therefore s upported color table format s are
R8G8B8 or R6G6B6A6 but R8G8B8A8 with 32 bit per color is not supported.
4.10.4 Surface properties for indexed images
Like other images also indexed images are described by surface objects. In this case the application must def ine the
format and address of the image buff er and color table buffer.
Maximum
of visible
Use case
palette may include an alpha bit too. That’s why it
is a possible use case to address 15 visible colors
Images with per pixel alpha and a maximum of
256 different colors.
a maximum of 32 different colors.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 30
Loading...