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
Overview
4.10.5 Index images for blit operations
Blit operations like blending a t raffic sign to a target buffer can be proceeded like operations with standard RGB(A)
images because the surface contai ns the required information.
Note:
The following restrictions exis t for indexed images:
Surfaces describing an indexed image cannot be used as STORE buffer.
It is not possible to use indexed images as DST and SOURCE surface for one blit.
Indexed images cannot be scaled or rotated.
4.10.6 Index images for the windows
The display hardware can directly show indexed images. In this case the application needs to request the
MML_GDC_DISP_FEATURE_INDE X_COLOR feature while opening the window.
However, there are some restrict ions if the window also uses the MML_GDC_DISP_FEATURE_MULTI_LAYER
feature:
All windows with the same layer ID mus t use the same index width (red channel bit width) if they show indexed
images.
One layer with up to 8 sub-layer-windows can only store 256 palette entrie s. So if the index width is 8 for this
layer all windows will use the same pa l ette.
If the index width is smaller than 8 than the palette is split in 2 or more parts and the sub-layer-windows can
partly use different palettes. The following rule is implemented in hardware: the upper bits of the 8-bit look-up
index are then filled up with the upper bit s of the sub-layer index. Example: when a 6-bit color index value is
used (= 64 colors), 4 palettes can be stored, each shared by 2 layers (layer 0 and 1 use palette entries 0..63,
layers 2 and 3 use 64..127 and so on).
Note:
The driver does not check this rule. I f the application binds surfaces with di fferent palettes to windows sharing the
same hardware palette a wrong image w i ll be the result.
Like other settings also palettes are shadowed. It means you can commit the binding of a new indexed image
surface with a new palette while an old one is still visible. If sub-layer-windows share the same palette it is
recommended to hide all windows before the new palette becomes active.
Notes:
Unfortunately the hardware shadow handling for palettes is in some cases not as expected: Each update request in
a window group with the same palette t r i ggers the palette swap. For instance
2 (or more) sub-windows address the same palette part (e.g., if index width is 8 all sub-windows use the
same palette).
Only one window uses the palette.
The commits for all windows without palette may also trigger the palette s wap. (for example with index width
8 it means that each commit of a window with the same layer id can trigger the swap and the window with
the indexed surface will sometimes show the correct and sometimes wrong colors.)
To avoid this problem the applicatio n must commit a surface with a new palette twice. The two times commits
ensure that the shadow palette is filled with the correct color table. I n practice the application may call 2 tim es
mmlGdcDispWinCommit() directly. In this case the CPU will be blocked until the first commit is taken over by the
hardware (when a new display frame is started). If blocking is not accept able the application must take care that the
next render loop calls the mmlGdcDis pWinCommit() for this window. As soon as the application changes proper ties
for this window (e.g., change global transparency for fading) the mmlGdcDispWinCommit() call is anyway
necessary.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 31
Name
Description
Term to summarize the functions of the Graphics driver that use the 2D Graphics
by the hardware.
Blend Operation stands for a calculation of output pixels depending on the color and
alpha information of 2 input pixels.
bpp stands for "bit per pixel" and describes how many bits are required to define the
support the following bpp sizes: 1, 2, 4, 8, 16, 18, 24, 32.
The term display is used to describe the output device showing the content generated
buffer in this case.
afterwards it’s content will be shown on a connected display.
A color plane in front of the display background color from the visitors point of view. If
the display can be the blend result of background color and all layer levels.
Address - Virtual Address
Stands for Pixel Engine: Part of a chip based on the 2D core components that is
much more.
5. Glossary
Basic Graphics
Blend Operation
bpp
Display
External Alpha
Frame buffer
Indexed image
Layer
Physical Address
hardware. Used to differentiate it from other graphics functions like OGL, if supported
color and alpha values on one pixel in an image. Most modules inside the 2D core
by the 2D core. Depending on connected hardware it can be an (LCD) panel, monitor,
beamer or similar. In context with the Basics Graphics Driver it is also the short name
for the 2D core Display Controller, a part of the 2D Graphics hardware.
External alpha stands for an image buffer containing an alpha channel that is used as
transparency information while blending a different color buffer over a background
image. The external alpha value will be multiplied with the alpha channel of the color
A frame buffer is an image buffer that is typical first used as render target and
An indexed image does not store for each color a separate RGB(A) value but a single
index value. This index value points to a color look up table with up to 256 RGB(A)
values that will be used as pixel color. Such images can not contain more than 256
different colors but the size of such images are smaller. The alpha channel can be part
of the look up table, it can be a separate channel beside the index channel or the
image does not contain alpha information.
multiple planes or layers are supported by hardware they will have a defined z-order.
Each upper level can modify the pixel color of the lower level. In the end one pixel on
The Physical Address stands for an address representing the "real" hardware address
of a register or start of a memory block or similar. In contrast to Virtual Address this
address type is used by 2D Graphics hardware components. See also Physical
PixEng
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 32
responsible for pixel buffer based transformations like copying, rotation, bending and
Glossary
Name
Description
If images contain an alpha channel this alpha channel will be often used for per pixel
Abbreviation for Run-Length Adaptive Dithering. This is a lossy compression type of
Abbreviation for Run-Length Adaptive Dithering with Uniform package size. This is a
lossy compression type of an image supported by the 2D Graphics hardware.
RLC
Abbreviation for Run-Length Coded. Synonym for RLE.
Abbreviation for Run-Length Encoded. This is a lossless compression type of an
image supported by the 2D Graphics hardware.
Raster Operation with 2 sources. A bit field defines how the color data bits of the first
final color.
Raster Operation with 3 sources. A bit field defines how the color data bits of the 3
source are combined to achieve the final color.
blending. The required blending formula depends on the way how the color channels
RGB are stored in such an image:
− Non-pre-multiplied: they contain the original pixel color independent of the alpha value for
this pixel.
− Pre-multiplied: the stored pixel color is already multiplied with the alpha value of the same
pixel.
PNG images are often stored as non-pre-multiplied images. An 2D core render buffer
is typical a pre-multiplied image.
Alpha channel of an image:
Color channels if it is an "non-pre-multiplied" image. Required blend formula: C =
CsrcAsrc + Cdst(1-Asrc).
Pre-multiply
Color channels if it is a "pre-multiplied" image. Required blend formula: C = Csrc +
Cdst(1-Asrc).
Expected blend result:
RLA
RLAD
RLAD_Uniform
Abbreviation for Run-Length Adaptive. This is a lossless compression type of an
image supported by the 2D Graphics hardware.
an image supported by the 2D Graphics hardware.
RLE
ROP2
ROP3
source are be combined with the color data bits of the second source to achieve the
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 33
Glossary
Name
Description
We talk about simple transformation if an image source is translated, mirrored and/or
The amount of bytes that must be skipped over to get from one pixel in an image to
the pixel with the same horizontal position in the next line of this image.
A sub-layer is analog to layers an image that is blended over a background in the
will be used for the layer blend operation.
functions. See also Surface Overview.
Physical Address - Virtual Address.
Abbreviation for Video Random Access Memory. This is a dedicated memory with
external memory as VRAM.
The term Window is used to describe a software object that keeps all parameters to
push a rectangular image to the display.
rotated by a multiple of 90°. Nearly all 2D core components can do simple
transformation while reading an image. For instance a display controller can directly
show horizontal mirrored images.
Simple Transformation
Stride
Sub-layer
Note:
90°and 270°rotations result in a higher memory read rate. Especially for
high resolution displays it is no t recommended to use this feature.
Compressed images cannot be used w i th simple transformations.
display controller. A sub-layer is always part of a layer. Different to layers it is not
possible to blend overlapping sub-layers together if they share the same layer id. Only
the top most sub-layer image pixel will be read from memory and this color information
Surface
Virtual Address
VRAM
Window
Surface stands for an memory object describing one or more memory blocks
describing an image. Many 2D Graphics Driver API calls use surface objects for the
The Virtual Address stands for an address representing the CPU view of an hardware
address like a register or start of a memory block. In contrast to the Physical Address
this address type cannot be used by 2D Graphics hardware components. See also
short read and write access time that is designed to store and buffer images. The
VRAM can be part of the 2D Graphics hardware block but it is also possible to use
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 34
6. Tutorial
6.1 About the Tutori al
The tutorial is comprised of chapters which demonstrate the use and possibilities of the driver API. The tutorial
chapters are of different comple xity levels, starting with basic chapt ers to become familiar with the way to use the
API. The complexity then progressiv ely increases to provide examples which demonstrate special features and
ways to achieve effects with the 2D Gr aphics hardware.
6.2 Application framework
All sample applications are const r ucted according to a common scheme, based on Cypress’s FM 4 application
template. Basic setup of peripherals, timers, etc. is handled in main.c, which looks similar for all examples. The
following application specific functions are called from main():
InitIrisExample(): Application specific graphics initialization.
IrisExampleDraw(): Graphics code executed in a loop, (e.g., once per frame).
IrisExampleCleanup(): Reset graphics system; interactive applications use the buttons of the FM4 Star ter Kit to
control the software. This is accomplished by state variables set in ButtonCallback() and passed on to
IrisExampleDraw().
6.3 Restrictions
Please note that the sample code for this r elease may differ from the final versio n.
Especially the usage of synchronization instructions might not always represent the final version.
6.4 Tutorial chapters
The Tutorial 1: Surfaces_Blit_Display Basic show the basic steps to use the 2D Graphics Driver. It starts explaining
surface objects, executes some s imple graphical operations to fill a pixel buffer and it ends up showing the r endered
buffer on a screen connected to the S6E2D hardware.
The Tutorial: Display Basic demonst r ates the capabilities of the displa y p ath based on an example showing a
navigation solution includin g different display layers.
The Tutorial: Display_Extended dem onstrates buffer swapping technique for multiple windows.
The Tutorial: Speedometer demonstrates an application for creating a speed gauge including a rotating needle.
Application uses techniques such as active area and background restoration.
The Tutorial: Chart shows a single render buffer solution.
The Tutorial: Cover Flow demonstr ates several PixelEngine features in form of a cover flow.
The Tutorial: Digital Picture Frame demonstrates several PixelEngi ne features in form of digital picture frame.
The Tutorial: Simple Drawing shows how complex features can be realized in software by combining simple
hardware features.
The Tutorial Utility Library collects some functions used in different tutorials.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 35
Tutorial
6.5 Tutorial 1: Surfaces_Blit_Display Basic
6.5.1 Description
This is a very simple start-up application to show the usage of MML_GD C_SURFACE and
MML_GDC_PE_CONTEXT.
A surface is required to perform operat ions in the blit and display path.
Please note: Although all APIs use a M ML_GDC_SURFACE parameter you need to declare
MML_GDC_SURFACE_CONTAINER objects and use t he pointer to these objects for all APIs. It holds the following
information:
Buffer dimension
Memory address of the pixel data
Color format
and optionally:
Compression format and parameter
Color look-up table parameters
6.5.2 MML_GDC_SURFACE
6.5.2.1 Color format
The color format defines the color depth (bits per pixel) for each color channel (red, green, blue, alpha). A lot of
common color formats are pre-defined, for example
MML_GDC_SURF_FORMAT_R8G8B8A8 (32 bits per pixel, 8 bits for each channel)
MML_GDC_SURF_FORMAT_R5G6B5 (16 bits per pixel, 5 bits for red, 6 bits for green, 5 bits for blue)
MML_GDC_SURF_FORMAT_RGB8 (8 bit per pixel for red, green and blue, which m eans 256 gray scale
values)
MML_GDC_SURF_FORMAT_RGB1 (1 bit per pixel for red, green and blue, which means black-and-white)
...
6.5.2.2 Compression format and parameter
The 2D Graphics Core can use different ki nds of pixel buffer compression: RLC, RLA, RLAD or RLAD_UNIFORM.
The surface holds information abo ut compression format and related properties.
6.5.2.3 Color look-up table parameters
A color lookup table can be assigned to a surface by using the function mmlGdcSm AssignClut. Lookup tables can
be used for indexed images: the value for r ed in the image defines an index of the col or l ookup table. The color of
the table entry defines the pixel color at this point.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 36
Tutorial
6.5.3 Initialization
Driver initialization and 1kB for the command sequencer FIFO.
// driver initialization
UTIL_SUCCESS(ret, mmlGdcSysInitializeDriver(0));
// get virtual addresses (not requir ed for devices without MMU) */
MM_GDC_PHYS_TO_VIRT((MM_ADDR)instructionBufferAddr, &vInstrBufferAddr);
// recalculate addresses using the vI mgAddr as start
MM_GDC_PHYS_TO_VIRT((MM_ADDR)imgAddr, &vImgAddr);
patternAddr = (MM_U32)vImgAddr + imgS ize;
textAddr = patternAddr + patternSize; storeAddr = textAddr + textSize;
// set up an instruction buffer for the c om mand sequencer
UTIL_SUCCESS(ret, mmlGdcSysSetInstructionBuffer( vInstrBufferAddr, instructionBufferSize));
6.5.4 Fill with constant color
First of all the store surface surfStore has to be initialized with mmlGdcSmResetSurfaceObject. We us e
MML_GDC_SURF_FORMAT_R5G6B5 as the color format, which means
5 bits for red channel.
6 bits for green channel.
5 bits for blue channel.
We use 0/0/255/255 (pure blue, non-transparent) as the constant color for the store surface. To setup the blit pat h,
the context has to be reset and the store sur face is bound to MML_GDC_PE_STORE.
mmlGdcPeFill finally fills the store surface with the given constant color.
// the store surface
mmlGdcSmResetSurfaceObject(surfStore);
// use format 5/6/5
UTIL_SUCCESS(ret, mmlGdcSmAssignBuffer(surfStore, storeWidth, storeHeight,
MML_GDC_SURF_FORMAT_R5G6B5, (void *)storeAddr, 0));
// the context must be reset like the surface
mmlGdcPeResetContext(ctx);
// we use a coordinate system start ing i n the upper left corner
mmlGdcPeAttribute(ctx, MML_GDC_PE_ATTR_ZERO_POINT, MML_GDC_PE_ATTR_ZERO_TOP_LEFT);
// Bind the surface to the context
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(ctx, MML_GDC_PE_STORE, surfStore));
// define the constant color
UTIL_SUCCESS(ret, mmlGdcPeColor(ctx, 0, 0, 255, 255));
UTIL_SUCCESS(ret, mmlGdcPeFill(ctx, 0, 0, storeWidth, storeHeight));
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 37
Tutorial
6.5.5 A simple black-and-white image
Now a second surface surfSrc is needed for the sourc e path. It has to be initialized with
mmlGdcSmResetSurfaceObject and filled with the image data; a simple 32 x 32 pixel black-and-white image. A s i t is
a 1 bpp image, MML_GDC_SURF_FORMAT_RGB1 is used for the color format.
The store surface keeps the same, but t he new source surface has to be added to the context. mmlGdcPeBlt copies
the image to the store surface at position 20/20.
// initialization of surfSrc
mmlGdcSmResetSurfaceObject(surfSrc);
CopyToVram(black_and_white, (MM_U32)vImgAddr, imgSize);
// use the black-and-white format
UTIL_SUCCESS(ret, mmlGdcSmAssignBuffer(surfSrc, imgWidth, imgHeight,
MML_GDC_SURF_FORMAT_RGB1, vImgAddr, 0));
// add it to the context as ’source’
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(ctx, MML_GDC_PE_SRC, surfSrc));
UTIL_SUCCESS(ret, mmlGdcPeBlt(ctx, 20.0f, 20.0f));
CopyToVram is a small helper funct i on to copy the image data to its destination in the VRAM.
static void CopyToVram(const void* data, MM_U32 addr, MM_U32 size)
{
void *vaddr = (void *)addr;
MM_GDC_LOCK(vaddr, size, MA_WRITE);
memcpy(vaddr, data, size);
MM_GDC_UNLOCK(vaddr);
}
Figure 13. Constant color
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 38
Tutorial
Figure 14. Black&White image on consta nt color
6.5.6 A simple auto-generated pattern
Fill the source surface with a simple pat tern and copy it to the store surface.
We reuse surfSrc, but we use MML_GDC_SURF_FORMAT_R8G8B8A8 for the surface color format because it is
much easier to write the data when each pixel is 4-byte aligned. mmlGdcPeBlt copies the pattern to the store
surface at position 35/45, so again t he existing content of the store surf ace is overwritten in that area.
// re-use the source surface for the pattern
mmlGdcSmResetSurfaceObject(surfSrc);
UTIL_SUCCESS(ret, mmlGdcSmAssignBuffer(surfSrc, patternWidth, patt er nH eight,
MML_GDC_SURF_FORMAT_R8G8B8A8, (void *)patternAddr, 0));
// create the pattern directly to VRAM
CreatePattern((MM_U32)patternAddr, patternSize, patternWidth, patternHeight);
// add it to the context as ’source’
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(ctx, MML_GDC_PE_SRC, surfSrc));
UTIL_SUCCESS(ret, mmlGdcPeBlt(ctx, 35.0f, 45.0f));
Creating the pattern:
static void CreatePattern(MM_U32 addr, MM_U32 size, MM_U32 width, MM_U32 height)
{
MM_U32 x;
MM_U32 y;
MM_U32 red;
MM_U32 green;
MM_U32 blue;
MM_U32 alpha;
MM_GDC_LOCK(addr, size, MA_WRITE);
for (x = 0; x < width; x++)
{
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 39
Tutorial
for (y = 0; y < height; y++)
{
red = 255 - (2 * x);
green = y * 4;
blue = 0;
alpha = 255;
*((MM_U32 *)(addr + (4*((y * width) + x)))) = ((red << 24) | (green << 16) | (blue << 8) | alpha);
}
}
MM_GDC_UNLOCK(addr);
}
Figure 15. Pattern on Black&White imag e on constant color
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 40
Tutorial
6.5.7 Blending two surfaces
To blend an image with an alpha channel onto the existing store surface, we have to connect surfStore both as
destination (input) and store (output).
The second input surface is again surf S rc. It has to be reset because now it holds another image with just 8 bit alpha
values. Therefore MML_GDC_SURF_FORMAT_A8 has to be used. We define 255/0/0/255 as the constant color to
see the text in red. The alpha channel i n the constant color definition has n o effect, because it is defined by the
image!
// re-use the source surface for the text
mmlGdcSmResetSurfaceObject(surfSrc);
UTIL_SUCCESS(ret, mmlGdcSmAssignBuffer(surfSrc, textWidth, textHeight, MML_GDC_SURF_FORMAT_A8,
(void *)textAddr, 0));
UTIL_SUCCESS(ret, mmlGdcPeSurfColor(ctx, MML_GDC_PE_SRC, 255, 0, 0, 255));
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(ctx, MML_GDC_PE_STORE | MML_GDC_PE_DST, surfStore));
UTIL_SUCCESS(ret, mmlGdcPeBlt(ctx, 50.0f, 70.0f));
Figure 16. Blended text
6.5.8 Bring it to the display
To see the surface on the display, we need a to create a display object by calling mmlGdcDispOpenDisplay. Beside
this a window is required using mmlG dc D ispWinCreate. Finally our surfSt or e must be set to the window using
mmlGdcDispWinSetSurface and mmlGdcDispWinCommit activates the changes.
// set up the display
// complete the display params
dispParams.xResolution = 480;
dispParams.yResolution = 272;
UTIL_SUCCESS(ret, mmlGdcDispOpenDisplay(&dispParams, &display));
// create a display window and connect the store surface to it
// complete the windows params
winprop.width = dispParams.xResolution; // horizontal display resolution
winprop.height = dispParams.yResolution; // vertical display resolut ion
UTIL_SUCCESS(ret, mmlGdcDispWinCreate(display, &winprop, &win));
UTIL_SUCCESS(ret, mmlGdcDis pWinSetSurface(win, MML_GDC _DISP_BUFF_TARGET_COLOR_BUFF,
surfStore));
UTIL_SUCCESS(ret, mmlGdcDispWinCommit(win));
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 41
Tutorial
6.6 Tutorial: Display Basic
6.6.1 Description
This example realizes an animated but very simple navigation demo done just by the use of layer properties and
operations. The focus of this tutori al is to introduce different layer pro per ties and how to set them up.
Figure 17. Expected result
6.6.1.1 Learning Goals
The following techniques and featur es are used:
Blend 4 layers with pixel based alphas and different color formats.
Fade a layer.
Move a layer.
Switch buffers.
Use multi layer feature.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 42
Tutorial
name
Format
6.6.1.2 Layer overview
The example uses the following 4 surfaces:
Layer
LAYER 0 sMap
LAYER 1 sFrame
LAYER 2 sPosition
Surface
Preview Dimension
1024 1024
320 240
32 32
Color
8 bits per
pixel RGB
(332)
16 bits per
pixel RGBA
(R3G3B4A6)
32 bit per
pixel RGBA
Shown features
The surface will be moved in a
way that only a part of it is
visible.
Sub-pixel precise movements
for a smooth animation.
The unusual format (3 bit red, 3
bit green, 2 bit blue) realizes an
acceptable memory
requirement.
Note:
Compression cannot be used for
layers if the whole frame is not
inside the display.
The unusual format (3 bit red, 3
bit green, 4 bit blue, 6 bit
alpha) realizes an acceptable
memory requirement.
Note:
Compression cannot be used for
this window because it is multi
layer window.
The layer will be faded in and
out.
LAYER 3
sArrow,
sArrow_l,
sArrow_r
about 40 50
1 and 2 bit
per pixel
Alpha
The image does not include any
color data but only transparency.
The limited number of layer blend units r equires using the multi layer feature. It means we use one "normal" window
as background window showing the mov ing map. The frame, the arrow and the pos i tion will be realized as multi
layer windows, which means that they cannot be blended to each other but they can be blended to the map
background window using different properties. The multi layer windows can overlap too like in this e xample however
only the top most window color will be f etched and used for blending.
6.6.2 Chapters
1. Code Description
2. Map Laye r
3. Frame Layer
4. Positi on Layer
5. Arrow Layer
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 43
Tutorial
6.6.3 Code Description
We start with driver initialization and setup of the display. The macro UTIL_SUCCESS used in this e x ample is a
simple error handling helper.
/* Initialize the driver */
UTIL_SUCCESS(ret, mmlGdcSysInitializeDriver(0));
UTIL_SUCCESS(ret, utMmanReset() );
/* Allocate some of VRAM for Instruction buffer for the command sequencer . Note, that mmlGdcVideoAlloc is an
application defined routine to m anage the VRAM space.
The 2D core driver does not include any ma nagement of the VRAM. */
vInstrBuffer = mmlGdcVideoAlloc(fifo_size, 0, NULL);
UTIL_SUCCESS(ret, mmlGdcSysSetInstructionBuffer(vInstrBuffer, fifo_size));
/* Setup and enable the display */
UTIL_SUCCESS(ret, mmlGdcDispOpenDisplay(&dispParams, &display));
Reset the surfaces to apply default v alues.
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(sFrame));
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(sMap));
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(sPosition));
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(sArrow));
We load the surfaces for the example using a utility function. The utility function sets all the related properties
including compression paramet er .
/* First we load the the map surface with 1024 * 1024 pixel resolution.
Of course we will read only a part if we use it as layer in this example. */
UTIL_SUCCESS(ret, utSurfLoadBitmap(sMap, map2d, MM_FALSE));
/* Now we load the blue frame surface. P l ease note that this surface is run length encoded. */
UTIL_SUCCESS(ret, utSurfLoadBitmap(sFrame, frame, MM_FALSE));
/* Next we load a position indicator bitmap */
UTIL_SUCCESS(ret, utSurfLoadBitmap(sPosition, position, MM_FALSE));
/* Finally we load the arrow bitmaps ( 1 bpp and 2 bpp alpha channel) */
UTIL_SUCCESS(ret, utSurfLoadBitmap(sArrow, arrow, MM_FALSE));
Additional we have to create 4 windows:
/* create 4 windows for the layer */
//sMap
winprop.topLeftX = 0;
winprop.topLeftY = 0;
winprop.width = dispParams.xResolution; // horizontal display res ol ution
winprop.height = dispParams.yResolution; // vertical display res olution
winprop.features = MML_GDC_DISP_FEATURE_DECODE; / * We do not need decode.
However it ensures the driver uses this fetch and not the multilayer fetch.
Other way: just open this window as the last one. */
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 44
Tutorial
winprop.layerId = MML_GDC_DISP_LAYER_0; // use layer 0
UTIL_SUCCESS(ret, mmlGdcDispWinCreate(display, &winprop, &wMap));
//sFrame
winprop.topLeftX = 0;
winprop.topLeftY = 0;
winprop.width = dispParams.xResolution; // horizontal display resolution
winprop.height = dispParams.yResolution; // vertical display resolution
winprop.features = MML_GDC_DISP_FEATURE_MULTI_LAYER; // use multi layer feature to get more windows
winprop.layerId = MML_GDC_DISP_LAYER_1; // use layer 1
winprop.sub_layerId = MML_GDC_DISP_SUB_LAYER_DEFAULT; // sub layer default means the driver will assign
the sub window order. The first opened window is the bottom most.
UTIL_SUCCESS(ret, mmlGdcDis pWinCreate(display, &winprop, &wFrame));
//sPosition
winprop.topLeftX = CENTER_X - 16;
winprop.topLeftY = CENTER_Y - 16;
winprop.width = 32;
winprop.height = 32;
winprop.features = MML_GDC_DISP_F EATURE_MULTI_LAYER;
winprop.layerId = MML_GDC_DISP_LAYER_1;
UTIL_SUCCESS(ret, mmlGdcDis pWinCreate(display, &winprop, &wPosition));
//sArrow
winprop.topLeftX = 30;
winprop.topLeftY = 25;
winprop.width = 50;
winprop.height = 50;
winprop.features = MML_GDC_DISP_F EATURE_MULTI_LAYER;
winprop.layerId = MML_GDC_DISP_LAYER_1;
UTIL_SUCCESS(ret, mmlGdcDispWinCreate(display, &winprop, &wArrow));
The following sections describe how these surfaces are used in this example.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 45
Tutorial
6.6.4 Map Layer
The map will be assigned to the wMap window:
UTIL_SUCCESS(ret, mmlGdcDis pWinSetSurface(wMap, MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF,
sMap));
Besides this we want to see a moving map. That means we have to move the layer in our animation loop. The driver
ensures that only pixels inside the screen of this surface are read from memory.
GetPosition(frameCount, &x, & y, &winker);
/* To get a moving map we have to recalculate a new matrix for the map layer. */
utMat3x2LoadIdentity(mat_geo);
/* Move it in a way that the requested center point fits the current position */
utMat3x2Translate(mat_geo, (M M_FLOAT)(CENTER_X - x), (MM_FLOAT)(CENTER_Y - y));
/* Assign the matrix to the windo w */
UTIL_SUCCESS(ret, mmlGdcDispWinSetMatrix(wMap, MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF,
mat_geo));
UTIL_SUCCESS(ret, mmlGdcDispWinCommit(wMap));
6.6.5 Frame Layer
The frame layer is the simplest layer f or this example because it is not included i n an animation:
UTIL_SUCCESS(ret, mmlGdcDispWinSetSurface(wFrame, MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF,
sFrame));
UTIL_SUCCESS(ret, mmlGdcDis pWinSetBlendMode(wFrame, M ML_GDC_DISP_BLEND_SOURCE_ALPHA |
MML_GDC_DISP_BLEND_SOURCE_MULTIPLY_ALPHA));
UTIL_SUCCESS(ret, mmlGdcDis pWinSetAttribute(wFrame, MML_GDC_DISP_WIN_ATTR_COLOR,
0x80FFFFFF));
UTIL_SUCCESS(ret, mmlGdcDispWinCommit(wFrame));
The related properties required f or the compression were already assigned to the surface in the utSurfLoadBi tmap
function. In this case the RLA compression is used because it shrinks the size for this bitmap to 12.0% of the origina l
size.
6.6.6 Position Layer
The position layer demonstrates the fading capabilities of the hardware. To fade a layer with pixel base d alpha
information, the following calculation inside the hardware is required:
Alpha = Alpha pix * Alpha fade
For the calculation of the Alpha value we have to assign the related properties to the wPosition window:
UTIL_SUCCESS(ret, mmlGdcDis pWinSetSurface(wPosition, M ML_GDC_DISP_BUFF_TARGET _C OLOR_BUFF,
sPosition));
/* We want to fade this layer: multiply pixel-alpha * const alpha. */
UTIL_SUCCESS(ret, mmlGdcDis pWinSetBlendMode(wPosition, MML_GDC_DISP_BLEND_GLOBAL_ALPHA |
MML_GDC_DISP_BLEND_SOURCE_ALPHA | MML_GDC_DISP_BLEND_SOURCE_MULTIPLY_ALPHA));
UTIL_SUCCESS(ret, mmlGdcDispWinSetAttribute(wPosition, MML_GDC_DISP_WIN_ATTR_COLOR,
0xFF0000FF));
To realize the blink effect we have to mod ify the color:
UTIL_SUCCESS(ret, mmlGdcDis pWinSetAttribute(wPosition, M ML_GDC_DISP_WIN_ATTR_COLO R , blink));
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 46
Tutorial
UTIL_SUCCESS(ret, mmlGdcDispWinCommit(wPosition));
6.6.7 Arrow Layer
The arrow layer is a one bit alpha mask onl y. So we have to define a constant color for the missing color data. In
addition we enable the pre-multiplication of color and alpha because the default layer blend mode expects a premultiplied image and we have a constant color only.
UTIL_SUCCESS(ret, mmlGdcDis pWinSetBlendMode(wArrow, MML_GDC_DISP_BLEND_SOURCE_ALPHA |
MML_GDC_DISP_BLEND_SOURCE_MULTIPLY_ALPHA));
UTIL_SUCCESS(ret, mmlGdcDis pWinSetAttribute(wArrow, MML_GDC_DISP_WIN_ATTR_COLOR, 0x 0000FFFF));
In the animation loop we simple chang e the arrow:
switch(winker)
{
case -1: surfArrow = sArrow_l; break;
case 0: surfArrow = sArrow; break;
case 1: surfArrow = sArrow_r; break;
}
/* Some 2D core drivers use layer rotat i on at this position to animate the arrow.
We cannot use simple rotation while using sub-windows but we can change the image.
So the following matrix calcul ation just moves the surface to the window center.
*/
utMat3x2LoadIdentity(mat_geo);
utMat3x2Translate(mat_geo, 25. 0f, 25.0f);
utMat3x2Translate(mat_geo, (- (MM_FLOAT)utSurfWidth(sArrow) * 0.5f), (- (MM_FLOAT)utSurfHeight(sArrow) *
0.5f));
/* Set matrix */
UTIL_SUCCESS(ret, mmlGdcDispWinSetMatrix(wArrow, MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF,
mat_geo));
/* Set new surface */
UTIL_SUCCESS(ret, mmlGdcDispWinSetSurface(wArrow, MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF,
surfArrow));
UTIL_SUCCESS(ret, mmlGdcDispWinCommit(wArrow));
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 47
Tutorial
6.7 Tutorial: Display_Extended
6.7.1 Description
The focus of Display_Extended is the synchronization of blit and buffer swap operations.
Open multiple windows on the display and prepare double buffering.
Trigger simple render operations and buffer swaps for each window.
Use different swap intervals for windo ws.
Figure 18. DisplayExtended
6.7.2 Setup
The initialization routine open s the display controller. Then it opens any vertical arranged windows. Each window
prepares
2 frame buffers that will be used as foreground and bac kground buffer.
A blit context.
And a sync object.
A structure for each window keeps all important variables to control the window:
struct DOUBLE_BUFFERED_WINDOW{
MML_GDC_DISP_WINDOW win; // the window handle
MML_GDC_SURFACE_CONTAINER sFramebuffer[2]; // two buffers described in surface objects.
MML_GDC_SYNC_CONTAINER sync; // a sync object used
MML_GDC_PE_CONTEXT_CONTAINER ctx; // cont ext for drawing
MM_U08 id; // an id storing which buffer is currently the foreground buffer
MM_FLOAT fRot; // a draw related parameter
};
The final step for each window is get ting a sync object of the window pipe. This sync object can be used to detect if
the OpenWindow call is finished in the HW.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 48
Tutorial
6.7.3 Draw function
The main draw function calls a draw for each window. Each window draw funct ion checks first the window sync
object. If the sync object signals a timeout the function returns.
ret = mmlGdcSyncWait(&pdbWin->sync, 0);
if (ret == MML_ERR_GDC_SYNC_TIMEOUT)
return MML_OK;
Using this mechanism the drawing loop will not consume CPU time if the previous buffer swap is not yet finished.
The next step is rendering the new frame in the back buffer. All these rend er operations will be pushed in the
command sequencer queue and executed sequential by the hardware. So if we now assign the new buffer to the
window it is possible that the new buffer becomes visible before rendering is finished.
To avoid this it is possible to poll the e nd of the blit operation using mmlGdcPeFinish(). A better way is to use a sync
object:
UTIL_SUCCESS(ret, mmlGdcPeSync(&pdbWin->sync));
UTIL_SUCCESS(ret, mmlGdcDispWinW aitSync(pdbWin->win, &pdbWi n->sync));
UTIL_SUCCESS(ret, mmlGdcDis pWinSetSurface(pdbWin->win,
MML_GDC_DISP_BUFF_TARGET _COLOR_BUFF, &pdbWin->sFramebuffer[pdbWin->id] ));
UTIL_SUCCESS(ret, mmlGdcDispWinCommit( pdbW in ->win));
It requests a sync object from the pi xe l engine and pushes it to the window pipe before the new buffer is assigned to
the window. All these functions ar e non blocking for the CPU and the driver will ensure that the hardware will be
triggered in the correct order.
6.7.4 Swap interval
The windows are set to different swap inter vals:
UTIL_SUCCESS(ret, mmlGdcDispWinSetAttribute(s_dbw[i].win, MML_GDC_DISP_WIN_ATTR_SWAP_INTERVAL,
window_assignment[i].swap_interval));
This feature can be used to control the window refresh interval. Very important windows may keep the default swap
interval 1 but low priority windows with may be GPU consuming draw operat ions can be set to a swap interval 2 or
3. In this case the window will be updated with 30 Hz or 20 Hz for a display with 60 Hz refresh rate.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 49
Tutorial
6.8 Tutorial: Speedometer
6.8.1 Summary
This example realizes a simple speedometer. The aim is to use 2 layers:
One as a static background for the scale.
And one dynamic layer with a rotating n eedle and a fixed hub around the rotation center. The hub image has a
light shadow and must not be rotated with the needle.
The user can switch between 4 possible drawing versions which are commented on later, by pressing the "right"
button. By pressing the "left" but ton, the bShowDrawRects property can be toggled, which draws differ ent rectangles
to visualize the drawing areas.
The sample uses a "single buffer r ender mode". However different to the Char t sample this demo uses only the
blanking period of the panel timing. That’s why it is important to use very f ast render operations.
Figure 19. Expected result
6.8.2 Learning Goals
The following techniques and featur es are used:
Show different ways to restore and render the needle layer.
Usage of mmlGdcPeSelectArea, mmlGdcPeActiveArea and mmlGdcPeGetDrawBox.
Show the coordinate system transf ormation.
Use a colored 4 bit per pixel layer.
6.8.3 Chapters
1. Preparation
2. Matrix operations to scale, rotate and transl ate images
3. Show different versions to restore and draw the needle layer
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 50
Tutorial
6.8.4 Preparation
First step is to initialize the driver and setup the display:
/* Initialization of driver and dis pl ay */
/* Initialize the driver */
UTIL_SUCCESS(ret, mmlGdcSysInitializeDriver(0));
UTIL_SUCCESS(ret, utMmanReset() );
/* Allocate some of VRAM for Instruction buffer for the command sequencer. Note, that mmlGdcVideoAlloc is an
application defined routine to m anage the VRAM space. The 2D core driver does not include any management of
the VRAM. */
vInstrBuffer = mmlGdcVideoAlloc(fifo_size, 0, NULL);
UTIL_SUCCESS(ret, mmlGdcSysSetInstructionBuffer(vInstrBuffer, fifo_size));
/* Setup and enable the display */
UTIL_SUCCESS(ret, mmlGdcDispOpenDisplay(&dispParams, &s_display));
If bShowDrawRects is set, we prepare an additional layer sComment. This layer represents a minimal colored layer:
only one bit is reserved for each color c hannel and for alpha. As the utility function utSurfCreateBuffer only supports
common color formats, we create our own function CreateCommentSurface.
static MM_ERROR CreateCommentSurface(M ML_GDC_SURFACE sComment)
{
MM_ERROR ret = MML_OK;
void *vp;
vp = mmlGdcVideoAlloc( (BGR_WIDTH * BGR_HEIGHT * 4 / 8), 0, NULL);
if (vp == NULL)
{
return MML_ERR;
}
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(sComment));
mmlGdcSmSetAttribute(sComment, MML_GDC_SURF_ATTR_WIDTH, BGR_WIDTH);
mmlGdcSmSetAttribute(sComment, MML_GDC_SURF_ATTR_HEIGHT, BGR_HEIGHT);
mmlGdcSmSetAttribute(sComment, MML_GDC_SURF_ATTR_BITPERPIXEL, 4);
mmlGdcSmSetAttribute(sComment, M ML_GDC_SURF_ATTR_COLORBITS, 0x01010101);
mmlGdcSmSetAttribute(sComment, M ML_GDC_SURF_ATTR_COLORSHIFT , 0x03020100);
mmlGdcSmSetAttribute(sComment, MML_GDC_SURF_ATTR_BASE_ADDRESS, (MM_U32)vp);
return ret;
}
The background layer (the scale) will only be visible if bShowDrawRect s is not set, to keep the example simple. As
this layer is not of interest for the tutorial, we just use a helper function DrawBgr() to draw several image sources in
our sBgr buffer.
/* Create a surface for background */
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(&s_sBgr));
UTIL_SUCCESS(ret, utSurfCreateBuffer(&s_sBgr, BGR_WIDTH, BGR_HEIGHT,
MML_GDC_SURF_FORMAT_R5G6B5));
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 51
Tutorial
/* draw the scale on background surface. You may use a fixed bitmap too. */
UTIL_SUCCESS(ret, DrawBgr(&s_sBgr, s_sSrc, s_mat));
/* display the background surface on background layer */
UTIL_SUCCESS(ret, mmlGdcDispWinSetSurface(s_winBgr, MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF,
&s_sBgr));
UTIL_SUCCESS(ret, mmlGdcDispWinCommit(s_winBgr));
Now we create a layer for the hub and needle. We need a buffer with an alpha channel bec ause the layer blending
should only pass the needle and hub. All other parts must have an alpha = 0 value so th at they are not visible.
/* Create a window for needle layer */
windowProp.layerId = MML_GDC_DISP_LAYER_1;
UTIL_SUCCESS(ret, mmlGdcDispWinCreate(s_display, &windowProp, &s_winNeedle));
UTIL_SUCCESS(ret, mmlGdcDis pWinSetBlendMode(s_winNeedle,
MML_GDC_DISP_BLEND_SOURCE_ALPHA));
UTIL_SUCCESS(ret, mmlGdcPeResetContext(&s_ctx));
/* Create a target surface for the need l e.This is the focus layer for this de m onstration. */
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(&s_sNeedle));
UTIL_SUCCESS(ret, utSurfCr eateBuffer(&s_sNeedle, BGR_WIDTH, BGR_HEIGHT,
MML_GDC_SURF_FORMAT_R6G6B6));
6.8.5 Matrix operations to scale, rotate and translate images
All geometry changes such as transl ation, rotation, sharing, scaling and mirroring in the blit path are based on matrix
settings. The application can calc ulate such matrices on its own or by using the utility functions from the driver. The
x, y offset in the mmlGdcPeBlt funct i on c an be used for simple translations.
The default behavior is that all mat r i c es are reset to identity matrices. That means a
mmlGdcPeBlt(&ctx, 10, 20)
would copy the source buffer to the tar get buffer with an offset x = 10 and y = 20. Depending on the
MML_GDC_PE_ATTR_ZERO_POINT settings the y offset is counted from the upper or lower left store surface
coordinate.
An equivalent operation with a matrix would be the following if sSrc is the source surface.
Mat3x2LoadIdentity(mat);
Mat3x2Translate(mat, 10, 20);
mmlGdcPeSetMatrix(ctx, MML_GDC_PE_SRC, mat);
mmlGdcPeBlt(0, 0);
However there are differences if several source buffers are involved. If the offset x, y is represented by a matr i x.
Moffs =
The following relationship to the st or e surface is be valid for the SRC and MAS K surface (represented by ’Ms’):
Xstore
Ystore
The path for the DST calculation is a little bit different (Mdst is the DST matrix):
Xstore
Ystore
1 0
0 1
= Moffs × Ms ×
Xdst
= Mdst ×
Ydst
Xs
Ys
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 52
Tutorial
This means the offsets are valid for all blit paths except the DST and the indivi dual matrix for each source buffer is
used for this path only.
This behavior can be used to simplif y any operations. For instance, you can s et a mirror matrix to the store and
without any other changes you can mirror all blit operations for this target.
In the speedometer example, we calculate matrices for the rotation cent er of the images and use the blit offset t o
move it to the correct position.
mmlGdcPeBlt(&ctx, BGR_WIDTH * 0.5f, ROT_CENTER_Y);
All source surfaces including hub get a similar matrix (except background) in Prepare Surfaces.
utMat3x2LoadIdentity(mat[0]);
/* we have 7 sources so we can simply handle it in an array. */
for (i = 1; i < 7; i++)
{
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(&sSrc[i]));
UTIL_SUCCESS(ret, utSurfLoadBitmap(&sSrc[i], mysrc[i].name, MM_FALSE));
// prepare matrix array for surfaces
utMat3x2LoadIdentity(mat[i]);
// align the rotation centers of surfaces
utMat3x2Translate(mat[i], -(MM_FLOAT)
utSurfWidth(&sSrc[i]) * 0.5f, -mysrc[i].fCenterY);
}
The rotation angle is changed frame by frame, so we have to calculate a new matr ix each time for this surface. W e
encapsulated it in the function GetRotMatrix:
static MM_ERROR GetRotMatrix(MM_U32 SurfID, MML_GDC_SURFACE_CONTAINER *sSrc, MM_FLOAT fAngle,
Mat3x2 *mat)
{
MM_ERROR ret = MML_OK;
// move the surface to the rotation center
utMat3x2LoadIdentity(mat[SurfID]);
utMat3x2Translate(mat[SurfID], (MM_FLOAT)BGR_WIDTH * 0.5f, (MM_FLOAT)ROT_CENTER_Y);
utMat3x2Rot(mat[SurfID], fAngle);
utMat3x2Translate(mat[SurfID], -(MM_FLOAT)
utSurfWidth(&sSrc[SurfID]) * 0.5f, -mysrc[SurfID].fCenterY);
return ret;
}
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 53
Tutorial
6.8.6 Show different versions to restore and draw the needle layer
Figure 20. Previous layer frame
As mentioned, we want to discuss different possibilities. The scenar io should be always the same: a previous frame
of the sNeedle surface was drawn and the new needle position must be drawn instead.
Version 1
Version 2
Version 3
Version 4
6.8.6.1 Version 1
A typical draw loop clears the buff er and draws the new objects on it. We perform 3 rendering steps:
The fill instruction clears the whol e buffer.
Next the rotated needle is drawn.
Finally the hub is drawn.
// Set target to sNeedle surface and ena bl e blending with MML_GDC_PE_DST
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_STORE | MML_GDC_PE_DST, &sNeedle));
while(TRUE)
{
// Clear the last frame
UTIL_SUCCESS(ret, mmlGdcPeColor(&ctx, 0, 0, 0, 0));
UTIL_SUCCESS(ret, mmlGdcPeFill(&ctx, 0, 0, BGR_WIDTH, BGR_HEIGHT));
// Draw the rotated needle
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_SRC, &sSrc[BMP_NEEDLE]));
UTIL_SUCCESS(ret, mmlGdcPeSetMatrix(&ctx, MML_GDC_PE_SRC,
MML_GDC_PE_GEO_MATRIX_FORMAT_3X2, mat[BMP_NEEDLE]));
UTIL_SUCCESS(ret, mmlGdcPeBlt(&ctx, 0, 0));
// Draw the hub
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_SRC, &sSrc[BMP_HUB]));
UTIL_SUCCESS(ret, mmlGdcPeSetMatrix(&ctx, MML_GDC_PE_SRC,
MML_GDC_PE_GEO_MATRIX_FORMAT_3X2, mat[BMP_HUB]));
UTIL_SUCCESS(ret, mmlGdcPeBlt(&ctx, BGR_WIDTH * 0.5f, ROT_CENTER_Y));
}
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 54
Tutorial
The next image shows the draw boxes for t hes e 3 rendering steps:
6.8.6.2 Version 2
In the previous implementation the s tore buffer is read twice, first when blending the needle, then again when
blending the hub on top of it. To avoid this addi tional memory access, we can blend both sources in one step onto
the store buffer. The problem: by default the driver only processes the bounding box of the source buffer. In our
example, the hub must be blended over t he needle so just a part of the needle would be visible. To avoid this issue
we can force the driver to process both the SRC and the DST frame buffer by using t he mmlGdcPeSelectArea
function.
/* Here we blend hub over rotated needle to store */
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_STORE, &sNeedle));
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_DST, &sSrc[BMP_NEEDLE]));
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_SRC, &sSrc[BMP_HUB]));
UTIL_SUCCESS(ret, mmlGdcPeSetMatrix(&ctx, MML_GDC_PE_SRC,
MML_GDC_PE_GEO_MATRIX_FORMAT_3X2, mat[BMP_HUB]));
/* We have to render the combined bounding box of needle and hub in this case */
UTIL_SUCCESS(ret, mmlGdcPeSelectArea(&ctx, MML_GDC_PE_SRC | MML_GDC_PE_DST));
while(TRUE)
{
/* Clear the last frame */
UTIL_SUCCESS(ret, mmlGdcPeColor(&ctx, 0, 0, 0, 0));
UTIL_SUCCESS(ret, mmlGdcPeFill(&ctx, 0, 0, BGR_WIDTH, BGR_HEIGHT));
/* Blend the hub over rotated needle */
UTIL_SUCCESS(ret, mmlGdcPeSetMatrix(&ctx, MML_GDC_PE_DST,
MML_GDC_PE_GEO_MATRIX_FORMAT_3X2, mat[BMP_NEEDLE]));
UTIL_SUCCESS(ret, mmlGdcPeBlt(&ctx, BGR_WIDTH * 0.5f, ROT_CENTER_Y));
}
This time only 2 rendering steps are r equired:
The fill instruction clears the whol e buffer.
Blend the hub over the rotated needle. The driver will calculate and render the bou nding box of the rotated
needle and the hub.
Figure 21. Version 1
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 55
Tutorial
6.8.6.3 Version 3
Can we use only one rendering pass by rendering images that are larger than the source? We can! We just define
that the rendering rectangle is defi ned by the target buffer.
/* Again blend hub over rotated needle to store ... */
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_STORE, &sNeedle));
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_DST, &sSrc[BMP_NEEDLE]));
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_SRC, &sSrc[BMP_HUB]));
UTIL_SUCCESS(ret, mmlGdcPeSetMatrix(&ctx, MML_GDC_PE_SRC,
MML_GDC_PE_GEO_MATRIX_FORMAT_3X2, mat[BMP_HUB]));
/* ... but we render the whole target buffer in one step. */
UTIL_SUCCESS(ret, mmlGdcPeSelectArea(&ctx, MML_GDC_PE_STORE));
while(TRUE)
{
/* Blend the hub over rotated needle but we draw the whole target frame so we don’t need to clear the buffer */
UTIL_SUCCESS(ret, mmlGdcPeSetMatrix(&ctx, MML_GDC_PE_DST,
MML_GDC_PE_GEO_MATRIX_FORMAT_3X2, mat[BMP_NEEDLE]));
UTIL_SUCCESS(ret, mmlGdcPeBlt(&ctx, BGR_WIDTH * 0.5f, ROT_CENTER_Y));
}
Now we have only one rendering step. The hardware fills black pixels outside the hub and needle buffer, and this is
exactly what we need to clear the previous fram e.
Figure 22. Version 2
Figure 23. Version3
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 56
Tutorial
6.8.6.4 Version 4
The previous version must always update the whole layer frame although only a very small part (the old needle)
must be redrawn. The most efficient way would be to re-render only the new and the old needle parts.
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_STORE, &sNeedle));
/* Blend hub over rotated needle to store. */
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_DST, &sSrc[BMP_NEEDLE]));
UTIL_SUCCESS(ret, mmlGdcPeBindSurface(&ctx, MML_GDC_PE_SRC, &sSrc[BMP_HUB]));
UTIL_SUCCESS(ret, mmlGdcPeSetMatrix(&ctx, MML_GDC_PE_SRC,
MML_GDC_PE_GEO_MATRIX_FORMAT_3X2, mat[BMP_HUB]));
/* Needle and store define the bounding box. */
UTIL_SUCCESS(ret, mmlGdcPeSelectArea(&ctx, MML_GDC_PE_DST | MML_GDC_PE_STORE));
while(TRUE)
{
UTIL_SUCCESS(ret, mmlGdcPeSetMatrix(&ctx, MML_GDC_PE_DST,
MML_GDC_PE_GEO_MATRIX_FORMAT_3X2, mat[BMP_NEEDLE]));
/* Blend the hub over rotated needle */
UTIL_SUCCESS(ret, mmlGdcPeBlt(&ctx, (MM_FLOAT)BGR_WIDTH * 0.5f, (MM_FLOAT)ROT_CENTER_Y));
/* Determine draw box for the current frame ... */
UTIL_SUCCESS(ret, mmlGdcPeGetDrawBox(&ctx, &x, &y, &w, &h, MM_TRUE));
/* ... and assign it as active area to the target for the next frame. This box includes the current needle and must be
repainted in the next frame */
UTIL_SUCCESS(ret, mmlGdcPeActiveArea(&ctx, MML_GDC_PE_STORE, x, y, w, h));
}
Again we have only one rendering st ep, but this time the rendering box (r ed) is much smaller. It is the bounding box
from the previously rendered needle (green) and the new needle box (blue). T he m mlGdcPeGetDrawBox returns the
drawing box of the last rendering step and this box is set as the ActiveArea for the store surface. Please note that
mmlGdcPeGetDrawBox does not include the drawing box of the store surface, otherwise the box would be
increased with each new frame.
Figure 24. Version4
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 57
Tutorial
6.9 Tutorial: Chart (Single render buffer sample)
6.9.1 Summary
This example shows an animated chart using a single buffer render mode. S ource code:
04_sample/basic_graphics/chart/.
Figure 25. chart
6.9.1.1 Learning Goals
The following techniques and featur es are used:
Work with clip rectangle for the STORE surface.
Synchronize display read and blit operations.
Analyze render time.
Analyze command sequencer buffer size.
Color matrix operations for blit operations.
Use alpha multiply with MASK surface.
6.9.1.2 Memory Calculation for VRAM
The target device has a VRAM size of 512 kByte. The panel used for our samples has a size of 480 272 pixels.
The sample should use a high qualit y render buffer requiring an alpha channel . If we want to use at least 6 bit for all
color and the alpha channel we need 480 272 24 2 / 8 = 765 kByte.
That means double buffering is not pos sible for such a resolution and col or format. To render such targets anyway it
is possible to use a single buffer rend er mode. In single buffer mode we need only 383 kByte to store the frame
buffer.
The command sequencer size assigned by mmlGdcSysSetInstructionBuf fer() must be big enough to store all
operations for one render loop. This i s i m portant because the blit operations m ust be queued until the display
controller passes a defined line in a si ngle buffer environment. The exam ple starts with a Command Sequencer
buffer size measurement for the firs t frame if MEASURE_CMD_SEQ is def ined with the following result:
CmdSeq buffer size: 13.46 of 16.00 kB used
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 58
Tutorial
The sample draws 10 bars, 2 background images and a debug bar in one half of the frame. It means the driver
needs approximately 500 Byte (or 125 registers writes) for one blit in this sample. Please note, the required bytes for
a blit depends on the operation and pr operties. We need 3 sources to rend er the bars. In many cases only 2 sources
are used. However, a blit with a surface with an index table of 256 colors needs m uch more instruction buffer
because the palette with 256 4 register v alues already requires 1 kB command sequencer space.
To allow a fancy background animation the init function also allocates a 1281284 (alpha) bpp surface and renders
the following pattern in this surface:
Figure 26. Background pattern
All these memory blocks together need about 411 kB VRAM.
6.9.1.3 Render time analysis
To generate a render job that generates a real GPU load for the 2D render hard ware this sample uses a background
animation using 2 bilinear full sc r een rotations. For real applications this is not a typical use case and the GPU load
will be smaller. The animated bars of the chart are the foreground for this sample. Approximately up to 75% of the
screen size are filled by the bars. It means that the buffer will be filled about 2.75 times by bilinear blit operations.
Bilinear blits (here rotation and sub-pixel movement) need 2 clock cycles for one pixel so we expect 48027222.75
clock cycles to render one frame. For a 160 MHz clocked blit engine it requires about 5 ms or 1/3 frame if we use a
60 Hz panel. In practice the render time will be much longer because the cylinderical bitmap used to blit the bars will
be read from external flash and access to external resources are not as fast as VR A M access. To see the render
time of about 5 ms you can simple chang e the line
UTIL_SUCCESS(ret, s_sCylinder.SurfLoadBitmap(cylinder));
to
UTIL_SUCCESS(ret, s_sCylinder.SurfLoadBitmap(cylinder, MM_TRUE));
This change copies the bitmap to VRAM with fast access time. The example does not make a VRAM copy to
generate the high GPU load.
6.9.1.4 Single buffer render mode
One possible implementation for s i ngle buffer render mode is to use the blank ing period of the timing only. This
procedure is used in the Speedometer sample.
In many cases the banking period is too short to redraw all animated buf fers. In this case the application can force
the HW only to update a part of the frame bu ffer, if this part of the frame buffer is currently not read by the display
controller.
This example uses a single full screen buffer, splitted into an upper and a lower part. It is also possible to div ide the
screen resolution by using smaller windows. Using different windows is the preferred version because it allows to
render a window one time per frame. However, the size and position of the windows must fit the memory scan order
for the panel. Typical panels are lan ds cape panels that means the windo ws must be arranged vertical.
For a single buffer window solution the render function must ensure that only parts of the buffer a updated. This can
be realized by using the STORE clipping function of the driver:
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 59
Tutorial
/* To use partial rendering we switch on clipping and set the rectangle */
mmlGdcPeSurfAttribute(s_ctx, MML_GDC_PE_STORE, MML_GDC_PE_SURF_ATTR_USE_CLIPPING,
MM_TRUE);
mmlGdcPeActiveArea(s_ctx, MML_GDC_PE_STORE, 0, y_start , s_win.GetWidth(), lines);
This code ensures that all mmlGdcPeB lt() calls never write pixels to the t arget buffer below line y_start or above
y_start + lines. In some cases the driver will detect that a blit operation for the upper part does not affect any pixels
in the clipped target buffer. The driv er will generate a warning in this case and does not trigger any operation in t he
HW.
Note:
Please remember the default zero point for blit operations is the lower l eft corner of the buffer.
To render the whole frame we need to call our render function 2 times and add the re quired instructions for
synchronization:
UTIL_SUCCESS(ret, mmlGdcPeWaitForDispFrameEnd(s_display, s_nSyncPoint));
UTIL_SUCCESS(ret, Render(s_display.GetHeight() - s_nSyncPoint, s_nSyncPoint));
UTIL_SUCCESS(ret, mmlGdcPeWaitForDispFrameEnd(s_display, s_display. GetHeight()));
UTIL_SUCCESS(ret, Render(0, s_display.GetHeight() - s_nSyncPoint));
The first instruction is a wait instruc tion for the line position s_nSyncPoint. Then we render the buffer part above the
sync point. Now we wait for the end of the screen and start to render the lower part of the screen.
s_nSyncPoint is set to a line below the middle of the screen because the bars ar e more present in the lower part so
this part will take more time.
This example splits the target buffer into 2 parts. It is possible to use 3 or m ore parts however it is not recommended
because each sync point will gener ate a render gap because the command sequencer must wait for a display
controller line.
Note:
It is possible to get a frame drop if the ren der time is too long for one part and the display line sync point is already
passed when the command sequencer r eaches this instruction. It means the command sequencer will wait one
frame until the expected line is pass ed next time.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 60
Tutorial
6.9.1.5 Render time visualization
If the render time is critical for a single buffer solution it might be helpful to visualize the render time. The sample
application blits for both render par ts a red line at different positions on the left side of the screen. Different to all
other blits this line will be drawn over t he whole surface including the part that is currently read by the display
controller. The display will not show the line while the render task is still ongoing. But if the blit queue e x ecutes this
line drawing operation the displa y controller will read this new rendere d object.
Figure 27. Render time analysis
The application supports the keys on the developer board. For this exampl e the up and down keys can be used to
modify the line split of the upper and lower part. It can be used to force a wrong spl itting and see the render issues.
The left key can be used to switch off the ba ckground animation. You can see a rel axed render time in that case.
6.9.1.6 Render tricks
The following render tricks are used for this sample:
Background animation: Two rotated and up scaled buffers with weak alpha valu e generate the background
animation.
Mask buffer multiplication: To draw the diagram it is necessary to modify the cylinderical bar height. Scaling is
not possible because it deforms the 3D-optic. Therefore the sample reads for each cylinderical bar and blit the
bitmap twice. The MASK surface only needs t he alpha channel of the bitmap. The SRC surface reads the alpha
and the color channels of the bitmap but with a vertical offset realized by a geometry matrix operation. The
default operation for MASK and SRC surface is alpha multiplication. An additional constant alpha m ultiplication
realizes the semi-transparency of some bars. The result of this product is finally used for the bl end operation
against the animated background.
Color modification: The sample uses the color matrix to colorize the gray image sour ce.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 61
Tutorial
6.10 Tutorial: Cover Flow
6.10.1 Summary
This example demonstrates severa l Pixel Engine features in form of a cover flow. Source code:
04_sample/basic_graphics/coverflow/.
Figure 28. coverflow
6.10.2 Usage
Use the "right" button to switch between circle and perspective mode.
6.10.2.1 Learning Goals
The following techniques and featur es are used:
Work with matrices
z-order sorting
The focus in this tutorial is not the init ialization nor the double buffer technique.
6.10.2.2 Matrix Calculation
The driver supports an 32 matrix. I t allows to translate, rotate, sc al e and share an bitmap.
However to simplify the development task we decide to make the matrix calc ulation with a 44 matrix first. This is a
matrix format that is well documented because it is used for many OpenGL appl i c ations.
A matrix calculation like this for the circle mode can be the following. Please note:
It is easier to read the matrix operation f rom bottom to top.
For each cover (bitmap) we need a separate matrix.
/* Start with the pre matrix */
/* Load identity matrix */
utMat4x4LoadIdentity(m_m44Pre);
/* Scale the dimension 0..2 to screen dimension */
utMat4x4Scale(m_m44Pre, GetWidth() / 2.0f, GetHeight() / 2.0f, 1);
/* Move the window from 0, 0 to 1, 1 coordin ates */
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 62
Tutorial
utMat4x4Translate(m_m44Pre, 1.0f, 1.0f, 0);
/* An OpenGL like perspective calculation */
utMat4x4Perspective(m_m44Pre, s_fLensAngle, (float)GetWi dth() / GetHeight(), (float)0.1, 100.0) ;
/* get a distance to the object */
utMat4x4Translate(m_m44Pre, 0, 0, s_fViewDist);
/* Now the cover movement */
/* Turn the view center point a little bit down */
utMat4x4RotX(m44, s_fViewAngle);
/* Move a little bit over the scene */
utMat4x4Translate(m44, 0, s_fVi ewPoint, 0);
/* Push the image on a circle */
utMat4x4Translate(m44, s_fCi r cleRadius * cos_angle, 0, s_fCircleRadius * sin_angle);
/* to get the 2-D lock we turn the cover here to correct the s_fViewAngle */
utMat4x4RotX(m44, -s_fViewAngle);
/* Scale it */
utMat4x4Scale(m44, s_fCoverScaling, s_fCoverScaling, 1.0f);
/* Now the post matrix */
/* Translate it to -1, -1. The center point is now 0 ,0 */
utMat4x4Translate(m_m44Post, -1.0f, -1.0f, 0);
/* Scale the cover bitmap of a size 0..2 */
utMat4x4Scale(m_m44Post, (float)2 / COVER_SIZE, (float)2 / COVER_SIZE, 1.0f);
As described all operations must be calc ulated for each frame for each cov er . To reduce the effort it is spit into 3
parts. The pre and post matrix is constant over the scene. That’s why it can be calc ulated once during the
initialization. Only the dynamic part must be calculated for each cover. The final matrix is:
M = Mpre * Mdynamic * Mpost
For transformation of the 44 to a 32 matr ix we use a utility function. The idea i s just to remove the z component for
the matrix. The z values are stored in the 3 l ine and 3 row.
Beside this the 4 line of the matrix must be removed. Such a conversion a s sumes that the 4x4 matrix realizes only
affine transformations. This is only realized if the values are (0 0 1 Vscale). All matrix elements must be divided by
Vscale.
utMat4x4ToMat3x2(mat44[0], pos.m at32);
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 63
Tutorial
6.10.2.3 z-order sorting
The hardware is not able to detect any z-or der. The bitmaps will be drawn in the or der as specified in the command
list. Later drawn bitmaps are on top of previously drawn bitmaps. For this reas on we calculate a z-value of the
center of each bitmap manually by using the 44 matrix.
utMat4x4GetXYZ(mat44[0], COVER_SIZE/2, COVER_SIZE/2, 0, &fX, &fY, &fZ);
To sort the draw order we just sort a list of all bitmaps:
qsort(&positions[0], (size_t)positions.size(), sizeof(positions[0]), CompareFnc);
The compare function is:
int Coverflow::CompareFnc( const void *arg1, const void *ar g2 )
{
Coverflow::COVERPOS *p1 = (Coverflow::COVERPOS *)arg1;
Coverflow::COVERPOS *p2 = (Coverflow::COVERPOS *)arg2;
if (p1->z < p2->z)
return -1;
if (p1->z > p2->z)
return +1;
return 0;
}
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 64
Tutorial
6.11 Tutorial: Digital Picture Frame
6.11.1 Summary
This example demonstrates severa l Pixel Engine features in form of digital picture frame software.
It includes several blend classes t o s how different old picture, new picture animations by using different features like.
Movements.
Rotation.
Alpha blend.
Alpha masking.
Color matrix modification.
6.12 Tutorial: Simple Drawing
6.12.1 Summary
This is a more complex example that draws lines, circles, rectangles and text.
The example shows how complex features can be achieved in software by combining simple features supported by
the hardware:
Draw lines with different widths and line ends.
Draw circles and points.
Draw rectangles.
Figure 29. Expected result
Some information text is also displayed. The functions for drawing lines, circles and texts are implemented as utility
functions in the util_lib directory.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 65
Tutorial
6.12.2 Code documentation
6.12.2.1 Preparation
Once again, we start with a collection of several driver and display initializations.
/* Initialization of driver and dis pl ay */
/* Initialize the driver */
UTIL_SUCCESS(ret, mmlGdcSysInitializeDriver(0));
UTIL_SUCCESS(ret, utMmanReset() );
/* Allocate some of VRAM for Instruction buffer for the command sequencer . Note, that mmlGdcVideoAlloc is an
application defined routine to m anage the VRAM space. The 2D core driver does not include any management of
the VRAM. */
vInstrBuffer = mmlGdcVideoAlloc(fifo_size, 0, NULL);
UTIL_SUCCESS(ret, mmlGdcSysSetInstructionBuffer(vInstrBuffer, fifo_size));
We need target surface in VRAM to render strings in it.
/* Allocate our buffers */
for (i = 0; i < BUFFER_COUNT; i++) {
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(&target_c[i]));
target[i] = &target_c[i];
UTIL_SUCCESS(ret, utSurfCreateB uffer(target[i], windowProp.width, windowProp.height,
MML_GDC_SURF_FORMAT_R5G6B5));
We want to print some information on the screen. We can set up a font by using t he utility functions of this tutorial
with the code:
/* Load a font bitmap */
mmlGdcSmGenSurfaceObjects(1, &sFont);
UTIL_SUCCESS(ret, utSurfLoadBitmap(sFont, courier_12, MM_FALSE));
/* Set it as font for the util lib */
utSetFont(&utCtx, sFont);
Then we create a point 50 pixels in diameter (actually a bitmap) again using utility functions.
/* Initialize the driver */
UTIL_SUCCESS(ret, mmlGdcSysInitializeDriver(0));
UTIL_SUCCESS(ret, utMmanReset() );
/* Allocate some of VRAM for Instruction buffer for the command sequencer . Note, that mmlGdcVideoAlloc is an
application defined routine to manage the VRAM space. The 2D core driver does not include any management of
the VRAM. */
vInstrBuffer = mmlGdcVideoAlloc(fifo_size, 0, NULL);
UTIL_SUCCESS(ret, mmlGdcSysSetInstructionBuffer(vInstrBuffer, fifo_size));
/* Setup and enable the display */
UTIL_SUCCESS(ret, mmlGdcDispOpenDisplay(&dispParams, &display));
windowProp.topLeftX = (dispParams.xResolution - BGR_WIDTH) / 2;
windowProp.topLeftY = (dispParams.yResolution - BGR_HEIGHT) / 2;
windowProp.width = BGR_WIDTH;
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 66
Tutorial
windowProp.height = BGR_HEIGHT;
windowProp.layerId = MML_GDC_DIS P_LAYER_0;
/* Create a window and assign it as layer 0 */
UTIL_SUCCESS(ret, mmlGdcDispWinCreate(display, &windowProp, &win));
/* Allocate our buffers */
for (i = 0; i < BUFFER_COUNT; i++) {
UTIL_SUCCESS(ret, mmlGdcSmResetSurfaceObject(&target_c[i]));
target[i] = &target_c[i];
UTIL_SUCCESS(ret, utSurfCreateB uffer(target[i], windowProp.width, windowProp.height,
MML_GDC_SURF_FORMAT_R5G6B5));
}
utResetContext(&utCtx);
/* Load a font bitmap */
mmlGdcSmGenSurfaceObjects(1, &sFont);
UTIL_SUCCESS(ret, utSurfLoadBitmap(sFont, courier_12, MM_FALSE));
/* Set it as font for the util lib */
utSetFont(&utCtx, sFont);
/* Initialize a point bitmap */
UTIL_SUCCESS(ret, utInitPoint(&utCtx, 50));
6.12.2.2 Doing the animation
Now begin with the animation: slight ly different scenes 360 times. Fir st clear the screen.
/* Clear the whole frame (You should optimize and only redraw the changed parts) */
UTIL_SUCCESS(ret, utRect(& utCtx, 0, 0, 320, 240));
Then draw a rounded rectangle with a border.
/* Now we draw a RoundRect with border. The simplest way is to draw it twice with different sizes and color */
utColor(&utCtx, 0, 255, 0, 255);
UTIL_SUCCESS(ret, utRoundRect(&utCtx, 163, 83, 154, 154, 10, 10));
And then draw the different part s of the complete scene.
/* The Drawing part is split into 5 sections. The result of DrawSample is used for DrawMix. Don’t change the order!
*/
UTIL_SUCCESS(ret, DrawLines(&utCtx));
UTIL_SUCCESS(ret, utInitPoint(&utCtx, 20));
UTIL_SUCCESS(ret, DrawPoints(&utCtx));
UTIL_SUCCESS(ret, DrawSample(&utCtx, f));
UTIL_SUCCESS(ret, DrawLineEnds(&utCtx, f));
UTIL_SUCCESS(ret, DrawMix(&utCtx, target[nCurBuffer]));
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 67
Tutorial
6.12.3 The drawing functions
6.12.3.1 Drawlines
We draw some "flowers" made of lines at different angles centered on the sam e point. First set up the line width and
line end, write some information an d then draw the flower.
/* Draw 4 "flowers" with lines of diff erent width */
MM_U32 DrawLines(UTIL_CONTEXT *putCtx)
{
MM_U32 ret = MML_OK;
MM_FLOAT f, cx, cy, px, py, s, c;
/* Set the line end to round */
utLineEnd(putCtx, UT_LINE_END_B UTT);
px = 5;
py = 0;
/* The the paint color */
utColor(putCtx, 255, 255, 255, 255);
/* Change the line width to 0.5 pixel */
utLineWidth(putCtx, 0.6f);
/* Print a text as comment */
UTIL_SUCCESS(ret, utTextOut(putCtx, (MM_S32)px, (MM_S32)py, "W i dth 0.6"));
cx = 30 + px;
cy = 50 + py;
/* Draw lines in a loop */
for (f = 0; f < 180; f+= 9.0f)
{
c = 30 * cosf(f*DegreeToPI);
s = 30 * sinf(f*DegreeToPI);
UTIL_SUCCESS(ret, utLinef(putCtx, cx - c, cy - s, cx + c, cy + s));
}
Repeat with different line widths at different positions on the screen.
/* repeat the code with different offsets and line width */
px += 80;
utLineWidth(putCtx, 1.0f);
UTIL_SUCCESS(ret, utTextOut (putCtx, (MM_S32)px, (MM_S32)py, "Width 1.0"));
cx = 30 + px;
cy = 50 + py;
for (f = 0; f < 180; f+= 9.0f)
{
c = 30 * cosf(f*DegreeToPI);
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 68
Tutorial
s = 30 * sinf(f*DegreeToPI);
UTIL_SUCCESS(ret, utLinef(putCtx, c x - c, cy - s, cx + c, cy + s));
}
px += 80;
utLineWidth(putCtx, 1.5f);
UTIL_SUCCESS(ret, utTextOut (putCtx, (MM_S32)px, (MM_S32)py, "Width 1.5"));
cx = 30 + px;
cy = 50 + py;
for (f = 0; f < 180; f+= 9.0f)
{
c = 30 * cosf(f*DegreeToPI);
s = 30 * sinf(f*DegreeToPI);
UTIL_SUCCESS(ret, utLinef(putCtx, c x - c, cy - s, cx + c, cy + s));
}
px += 80;
utLineWidth(putCtx, 2.0f);
UTIL_SUCCESS(ret, utTextOut (putCtx, (MM_S32)px, (MM_S32)py, "Width 2.0"));
cx = 30 + px;
cy = 50 + py;
for (f = 0; f < 180; f+= 9.0f)
{
c = 30 * cosf(f*DegreeToPI);
s = 30 * sinf(f*DegreeToPI);
UTIL_SUCCESS(ret, utLinef(putCtx, c x - c, cy - s, cx + c, cy + s));
}
return ret;
6.12.3.2 Drawpoints
Draws 12 points with different sizes using the utility function.
/* Now paint */
for (i = 1; i < 12; i++)
{
utPointSize(putCtx, (MM_FLOAT)i);
UTIL_SUCCESS(ret, utPoint(putCtx, 5 + i * i, 105));
}
6.12.3.3 DrawSample
This function draws a flower with different line widths and colors.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 69
Tutorial
6.12.3.4 DrawLineEnds
Draws the end of the lines by combinin g l ine and point draw utility functions.
6.12.3.5 DrawMix
Draws some text, lines and points with di fferent colors or a brush.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 70
7. Module Index
7.1 Modules
Here is a list of all modules:
Basic Graphics
Driver Initialization API
Configuration API
Surface API
Display API
Pixel Engine API
Synchronization API
2D Core Interrupt Controller API
Error Reporting API
Error Codes
Basic Graphics Type Definitio ns
Version Numbers
Type Definition
Macro Definition
Tutorial Utility Library
Utilities for the Memory Management
Utility functions for matrix calculations
Utilities for the compatibility with other drivers
Utilities for the Surface Management
Utilities for the compression
Utilities for RLA (run length adapt ive compression)
Utilities for RLC (run length compression)
Util class collection
CCtx
CDevice
CDisplay
CMenu
CSurface
CWindow
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 71
8. Hierarchical Index
8.1 Class Hierarchy
This inheritance list is sorted roughly, but not completely, alphabet i cally:
RLAD::BitStream
CCtx
CDevice
CDisplay
CMenuItem
CSurface< NUM_BUFFERS >
CSurface< 1 >
CTextWindow
CMenu
CWindow
CSurfaceWindow< NUM_BUFFERS >
CSurfaceWindow< 1 >
CStaticSurfaceWindow
RLAD::Frame
MML_GDC_DISP_MODE_LINE
MML_GDC_DISP_PROPERTIES
MML_GDC_DISP_TCON_PROPERTIES
MML_GDC_DISP_WINDOW_PROPERTIES
MML_GDC_PE_CONTEXT_CONTAINER
MML_GDC_SURFACE_CONTAINER
MML_GDC_SYNC_CONTAINER
MML_GDC_SYSINIT_INFO
RLAD::Package
RLAD::Frame::Pixel
RLAD
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 72
9. Data Structure Index
9.1 Data Structures
Here are the data structures with brief descriptions:
RLAD::BitStream
CCtx
CDevice
CDisplay
CMenu
CMenuItem
CStaticSurfaceWindow
CSurface< NUM_BUFFERS >
CSurfaceWindow< NUM_BUFFERS >
CWindow
RLAD::Frame
MML_GDC_DISP_MODE_LINE
MML_GDC_DISP_PROPERTIES
MML_GDC_DISP_TCON_PROPERTIES
MML_GDC_DISP_WINDOW_PROPERTIES
MML_GDC_PE_CONTEXT_CONTAINER
MML_GDC_SURFACE_CONTAINER
MML_GDC_SYNC_CONTAINER
MML_GDC_SYSINIT_INFO
RLAD::Package
RLAD::Frame::Pixel
RLAD
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 73
10. File Index
10.1 File List
Here is a list of all documented files with brief descriptions:
flash_resource.h
Include this file before the defi nition of a bitmap
mm_defines.h
Common macro definitions for all modules
mm_gdc_erp.h
Error Reporting API
mm_gdc_errors.h
Error Codes for the Basic Graphics modules
mm_gdc_module_id.h
Basic Graphics module ids (common)
mm_gdc_version.h
Basic Graphics Driver Version Numbers
mm_types.h
Basic type definitions
mmd_gdc_interrupthandler.h
2D Core Interrupt Controller API
mml_gdc_config.h
Controls global graphics driver and hardware configurations
mml_gdc_display.h
Display API
mml_gdc_erp.h
Error Reporting API
mml_gdc_pixeng.h
Pixel Engine API
mml_gdc_surfman.h
Surface Manager Interface
mml_gdc_sync.h
Synchronization of framebuffe r operations
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 74
File Index
mml_gdc_sysinit.h
Driver Initialization Module
pe_matrix.h
Provide some matrix utility functions
sm_util.h
This is just a helper implementation for development and will be removed in the final version
ut_class_ctx.h
This class abstracts an MML_GDC_PE_CONTEXT
ut_class_device.h
This class abstracts the device initialization
ut_class_display.h
This class abstracts the display in i tialisation
ut_class_menu.h
This class realizes a simple menu
ut_class_rlad.h
This sample code can be used to compress a buffer using the MML_GDC_SURF_CO MP_RLA,
MML_GDC_SURF_COMP_RLAD or ::MML_GDC_SURF_CO M P _RLAD_UNIFORM format
ut_class_surface.h
This class abstracts MML_GDC_SURFACE objects
ut_class_window.h
This class abstracts windows
ut_compatibility.h
This file defines some interfaces that are part of other drivers. The util li br ary implements very simple inst anc es of it
but they must be not used for soft ware products. However it allows to run the sam ple applications
ut_compression.h
This file defines a helper function t hat can be used to compress a surface
ut_memman.h
This file defines some interfaces for the memory management
ut_rlc.h
This sample code can be used to create a run-length encoded buffer
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 75
11. Module Documentation
11.1 Basic Graphics
This section collects all APIs of the driver.
Modules
Driver Initialization API
The Driver Initialization API exposes functions to initialize and un initialize the driver.
Configuration API
The Configuration API allows changing or reading global graphics driv er configurations or status information.
Surface API
The Surface API provides all functions to manage memory blocks with image content, called image buffer. (See also
Surface Overview)
Display API
The Display API exposes all the hardware features of the display unit. S ee also Display Overview.
Pixel Engine API
Pixel Engine (PixEng) API.
Synchronization API
Synchronization API - Synchronization of framebuffer operations.
2D Core Interrupt Controller API
2D Core Interrupt Controller handler functions
Error Reporting API
Error Reporting API - Error Reporting for selected modules and level.
Error Codes
Error Codes of this driver.
Basic Graphics Type Definitions
Version Numbers
The Version numbers of this driver.
11.1.1 Detailed Description
This section collects all APIs of the driver. The collection of APIs includes:
APIs for the access of the hardware units (e.g. Displays, Pixel Engine (2D Rendering)).
APIs for services like driver initial ization, synchronization, surface management, configuration.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 76
Module Documentation
11.2 Driver Initialization API
The Driver Initialization API exposes functions to initialize and un initialize the driver.
Data Structures
struct MML_GDC_SYSINIT_INFO
Macros
#define GFX_PLL_MIN 20000000U
#define GFX_PLL_MAX 415000000U
Functions
MM_ERROR mmlGdcSysInitializeDriver (MML_GDC_SYSINIT_INFO pDriverInitInfo)
MM_ERROR mmlGdcSysUninitializeDriver (void)
MM_ERROR mmlGdcSysSetInstructionBuffer (void address, MM_U32 size)
Default initializer
#define MML_GDC_SYSINIT_INITIALIZER
Resource names
#define MM_GDC_RES_DISP0 (1U << 0U)
#define MM_GDC_RES_LAYER0 (1U << 1U)
#define MM_GDC_RES_LAYER1 (1U << 2U)
#define MM_GDC_RES_FETCH_DECO D E0 (1U << 3U)
#define MM_GDC_RES_FETCH_LAYER0 (1U << 4U)
11.2.1 Detailed Description
The Driver Initialization API exposes functions to initialize and un initialize the driver.
#include "mml_gdc_sysinit.h"
11.2.2 Macro Definition Documentation
11.2.2.1 #define GFX_PLL_MAX 415000000U
maximum GFX PLL 415 MHz
11.2.2.2 #define GFX_PLL_MIN 20000000U
Allowed PLL frequency range minimum GFX PLL 20 MHz
11.2.2.3 #define MML_GDC_SYSINIT_INITIALIZER
Value:
{ \
0U, /* no safety driver */ \
320000000U /* GFX PLL 320 MHz */ \
}
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 77
Module Documentation
11.2.3 Function Documentation
11.2.3.1 MM_ERROR mmlGdcSysInitializeDriver(MML_GDC_SYSINIT_INFO pDriverInitInfo)
Used to initialize the driver at startup. Applications must initializ e the driver before they can call other dr iver
functions.
Note:
The 2D core hardware must be in default state, i.e. no registers may be altered bet ween HW reset and the call of
mmlGdcSysInitializeDriver(). The only except exception are the LockUnlock registers, which can be us ed by a safety
driver to protect specific streams agains t non-privileged access. The registers related to these streams may also be
altered by the safety driver before mmlGdcSysInitializeDriver () is called.
Parameters
pDriverInitInfo
Can be NULL or a pointer to a MML_GDC_SYSINIT_INFO driver initialization structure.
Return values
MML_OK
MML_ERR_GDC_SYS_DEVICE_INVALID_PARAMETER
MML_ERR_GDC_SYS_DEVICE_ALREADY_INITIALIZED
MML_ERR_GDC_SYS_DEVICE_INIT_FAILED
Successfully initialized driver
GfxPll parameter out of range.
already initialized.
Initialization of the driver failed.
11.2.3.2 MM_ERROR mmlGdcSysSetInstructionBuffer(void address, MM_U32 size)
Assign internal VRAM for command q ueue
Note:
The command queue is required to buffer t he render instructions to allow a non-blocking API handling. The requ ired
instruction buffer size depends on the amount and complexity of the render instructions and which synchronization
instructions are used. A recommended size is 8 kByte. To get information a bout the instruction buffer us age an
application can use the mmlGdcConfigGetAttribute function wit h attribute
MML_GDC_CONFIG_ATTR_MIN_INSTRUCTION_BUFFER. The function mus t be called after
mmlGdcSysInitializeDriver before any render or display operations. A reconfiguration of the instruction buffer is not
possible.
Parameters
address Start address in the VRAM. Must be 32 byte aligned.
size
Size in bytes of the buffer to assign, must be DWORD (4 Bytes) aligned, the function will return
an error otherwise. The application must ensure that the address as well as the address plus
size are within the range of the 2D core VRAM memory, the function will not do this.
Return values
MML_OK on success, otherwise the related error code
11.2.3.3 MM_ERROR mmlGdcSysUninitializeDriver( void )
Used to shutdown the driver. Applications must uninitialize the driver after calling mmlGdcSysInitializeDriver.
Return values
MML_OK Successfully shutdown the driver
MML_ERR_GDC_SYS_DEVICE_NOT_YET_INITIALIZED not yet initialized.
MML_ERR_GDC_SYS_DEVICE_CLOSE_FAILED Driver shutdown failed.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 78
Module Documentation
11.3 Configuration API
The Configuration API allows changing or reading global graphics driv er configurations or status information.
Enumerations
enum MML_GDC_CONFIG_ATTR {
MML_GDC_CONFIG_ATTR_MAJOR_VERSION = 0,
MML_GDC_CONFIG_ATTR_MINOR_VERSION,
MML_GDC_CONFIG_ATTR_BUILD_VERSION,
MML_GDC_CONFIG_ATTR_MIN_INSTRUCTION_BUFFER,
MML_GDC_CONFIG_ATTR_CURRENT_INSTRUCTION_BUFFER,
MML_GDC_CONFIG_ATTR_DISPLAY_NOBLOCK,
MML_GDC_CONFIG_ATTR_BUILD_TYPE
}
Functions
MM_ERROR mmlGdcConfigSetAt tribute (MML_GDC_CONFIG_ATTR pname, MM_U32 param)
MM_ERROR mmlGdcConfigGetAttribute (MML_GDC_CONFIG_ATTR pname, MM_U32 pParam)
Detailed Description
The Configuration API allows changing or reading global graphics driv er configurations or stat us i nformation.
#include "mml_gdc_config.h"
11.3.1 Enumeration Type Documentation
11.3.1.1 enum MML_GDC_CONFIG_ATTR
Enumeration of the different config attributes
Enumerator
MML_GDC_CONFIG_ATTR_MAJOR_VERSION
Returns the major version of the driver . This is a read only attribute. Setting this attribute will result in err or.
MML_GDC_CONFIG_ATTR_MINOR_VERSION
Returns the minor version of the driver . This is a read only attribute. Setting this attribute will result in error.
MML_GDC_CONFIG_ATTR_BUILD_VERSION
Returns the build version of the driver. This is a read only attribute. Sett ing this attribute will result in erro r .
MML_GDC_CONFIG_ATTR_MIN_INSTRUCTION_BUFFER
This attribute is only available in mmlGdcConfigGetAttribute() . The returned value represents t he smallest
available InstructionBuffer in bytes during all calls. A function c all with this parameter resets the measur ement.
The returned value can be used by an application to measure the usage of the ins truction buffer assigned by
mmlGdcSysSetInstructionBuffer.
MML_GDC_CONFIG_ATTR_CURRENT_INSTRUCTION_BUFFER
This attribute is only available in mmlGdcConfigGetAttribute() . The returned value represents the current
available InstructionBuffer in bytes. The returned value can be used by an application to decide whether or not
further render steps should be delaye d and continued later because the hardware is currently still busy.
MML_GDC_CONFIG_ATTR_DISPLAY_NOBLOCK
The following functions can not be e xecuted, if a previous reconfiguration of a corresponding window or display
is not yet finished:
mmlGdcDispOpenDisplay
mmlGdcDispCloseDisplay
mmlGdcDispWinCreate
mmlGdcDispWinDestroy
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 79
Module Documentation
mmlGdcDispCommit
mmlGdcDispWinCommit
If this attribute is 0 (default), the function will block the CPU until it can be executed. If this attribute is not 0, the
function will return immediately in that case with error MML_ERR_GDC_ DISP_DEV_BUSY. It is up to the
application to handle this case and reschedule the function call later .
Note:
The application can also use the synchronization API to find out if the previous reconfiguration is finished.
MML_GDC_CONFIG_ATTR_BUILD_TYPE
Returns the build type of the driver. The returned values can be ’d’ for debug version of driver ’r’ for release
version of driver ’p’ for production version of driver This is a read only attribute. Setting this attribute will r es ul t in
error.
11.3.2 Function Documentation
11.3.2.1 MM_ERROR mmlGdcConfigGetAttribute(MML_GDC_CONFIG_ATTR pname, MM_U32
pParam)
Gets the current value of a graphics library attribute. See MML_GDC_CON FIG_ATTR for a list of attributes.
Parameters
in pname Name of the attribute to get. See MML_GDC_CONFIG_ATTR
out pParam Address where the read value of the attribute is stored
Return values
MML_OK on success
MML_ERR_GDC_CONFIG_INVALID_PARAMETER if pname is invalid
MML_ERR_GDC_CONFIG_INTERNAL_ERROR if value could not be retrieved
11.3.2.2 MM_ERROR mmlGdcConfigSetAttribute(MML_GDC_CONFIG_ATTR pname, MM_U32 param)
Sets a graphics library attribute. See MML_GDC_CONFIG_ATTR for a list of attributes.
Parameters
in pname Name of the attribute to set. See MML_GDC_CONFIG_ATTR
in param Value to set for the attribute
Return values
MML_OK on success
MML_ERR_GDC_CONFIG_INVALID_PARAMETER if a parameter is invalid
MML_ERR_GDC_CONFIG_INTERNAL_ERROR if value could not be set
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 80
Module Documentation
11.4 Surface API
The Surface API provides all funct i ons to manage memory blocks with image c ontent, called image buffer. (See also
Surface Overview)
Data Structures
struct MML_GDC_SURFACE_CONTAINER
Macros
#define MML_GDC_SURFACE_MAX_WIDTH 4096
#define MML_GDC_SURFACE_MAX_HEIGHT 4096
#define MML_GDC_SURFACE_CONTROL_WIDTH 2048
#define MML_GDC_SURFACE_CONTROL_HEIGHT 2048
Typedefs
typedef MML_GDC_SURFACE_CONTAINER MML_GDC_SURFACE
Enumerations
enum MML_GDC_SURF_FORMAT {
MML_GDC_SURF_FORMAT_R8G8B8A8 = 0x00,
MML_GDC_SURF_FORMAT_A8B8G8R8,
MML_GDC_SURF_FORMAT_A8R8G8B8,
MML_GDC_SURF_FORMAT_B8G8R8A8,
MML_GDC_SURF_FORMAT_R8G8B8X8,
MML_GDC_SURF_FORMAT_X8B8G8R8,
MML_GDC_SURF_FORMAT_X8R8G8B8,
MML_GDC_SURF_FORMAT_R8G8B8,
MML_GDC_SURF_FORMAT_B8G8R8,
MML_GDC_SURF_FORMAT_R6G6B6,
MML_GDC_SURF_FORMAT_R4G4B4A4,
MML_GDC_SURF_FORMAT_A4R4G4B4,
MML_GDC_SURF_FORMAT_R5G5B5A1,
MML_GDC_SURF_FORMAT_A1R5G5B5,
MML_GDC_SURF_FORMAT_A1B5G5R5,
MML_GDC_SURF_FORMAT_B5G5R5A1,
MML_GDC_SURF_FORMAT_R5G6B5,
MML_GDC_SURF_FORMAT_A8RGB8,
MML_GDC_SURF_FORMAT_RGB8,
MML_GDC_SURF_FORMAT_A8,
MML_GDC_SURF_FORMAT_A4RGB4,
MML_GDC_SURF_FORMAT_A4,
MML_GDC_SURF_FORMAT_A2,
MML_GDC_SURF_FORMAT_A1,
MML_GDC_SURF_FORMAT_RGB1
}
enum MML_GDC_SURF_COMP {
MML_GDC_SURF_COMP_NON = 0x4,
MML_GDC_SURF_COMP_RLC = 0x3,
MML_GDC_SURF_COMP_RLA = 0x2,
MML_GDC_SURF_COMP_RLAD = 0x0
}
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 81
Module Documentation
enum MML_GDC_SURF_CLF {
MML_GDC_SURF_CLF_R8G8B8,
MML_GDC_SURF_CLF_B8G8R8,
MML_GDC_SURF_CLF_R5G5B5,
MML_GDC_SURF_CLF_A1R5G5B5,
MML_GDC_SURF_CLF_A4R4G4B4
}
enum MML_GDC_SURF_CLM {
MML_GDC_SURF_CLM_NEUTRAL = 0x0,
MML_GDC_SURF_CLM_INDEX_RGB,
MML_GDC_SURF_CLM_INDEX_RGBA
}
enum MML_GDC_SURF_ATTR {
MML_GDC_SURF_ATTR_BASE_ADDRESS = 0x0,
MML_GDC_SURF_ATTR_PHYS_ADDRESS,
MML_GDC_SURF_ATTR_BASE_ADDRESS2,
MML_GDC_SURF_ATTR_PHYS_ADDRESS2,
MML_GDC_SURF_ATTR_WIDTH,
MML_GDC_SURF_ATTR_HEIGHT,
MML_GDC_SURF_ATTR_STRIDE,
MML_GDC_SURF_ATTR_BITPERPIXEL,
MML_GDC_SURF_ATTR_COLORBITS,
MML_GDC_SURF_ATTR_COLORSHIFT,
MML_GDC_SURF_ATTR_COMPRESSION_FORMAT,
MML_GDC_SURF_ATTR_RLAD_MAXCOLORBITS,
MML_GDC_SURF_ATTR_SIZEINBYTES,
MML_GDC_SURF_ATTR_CLUTMODE,
MML_GDC_SURF_ATTR_CLUTCOUNT,
MML_GDC_SURF_ATTR_CLUTBITPERPIXEL,
MML_GDC_SURF_ATTR_CLUTCOLORBITS,
MML_GDC_SURF_ATTR_CLUTCOLORSHIFT,
MML_GDC_SURF_ATTR_CLUTBUFFERADDRESS,
MML_GDC_SURF_ATTR_CLUTBUFFER_PHYS_ADDRESS,
MML_GDC_SURF_ATTR_SURF_FORMAT,
MML_GDC_SURF_ATTR_USERDEFINED
}
Functions
MM_ERROR mmlGdcSmResetSurfaceObject(MML_GDC_SURFACE surf)
MM_ERROR mmlGdcSmAssignBuffer(MML_GDC_SURFACE surf, MM_U32 uWidth, MM_U32 uHeight,
MML_GDC_SURF_FORMAT eFormat, void pBufferAddress, MM_U32 uRleWords)
MM_ERROR mmlGdcSmAssignClut(MML_GDC_SURFACE surf, MML_GDC_SURF_CLM eMode, MM_U32
uCount, MML_GDC_SURF_CLF eFor mat, void pBufferAddress)
MM_ERROR mmlGdcSmSetAttribute(const MML_GDC_SURFACE surf, MML_GDC_SUR F_ATTR eName,
MM_U32 uValue)
MM_ERROR mmlGdcSmGetAttribute(const MML_GDC_SURFACE surf, MML_GDC_SURF_ATTR eName,
MM_U32 puValue)
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 82
Module Documentation
11.4.1 Detailed Description
The Surface API provides all funct i ons to manage memory blocks with image c ontent, called image buffer. (See also
Surface Overview)
#include "mml_gdc_surfman.h"
The Surface API provides all funct i ons to manage memory blocks with image c ontent, called image buffer. A
"surface" is a description of suc h an image buffer, including dimension of the image, pixel format and physic al
address in memory. The described im age can be a (compressed) RGB(A) buff er and optionally use a color lookup
table.
Most modules of this driver can work on surfaces. Examples are display and PixEng. The Surface API allows for
instance to:
Pass surfaces created by the applicat ion to PixEng for further processin g
Pass surfaces created by the applicat ion to Display for displaying on t he screen, etc.
The properties can be assigned by using the helper functions mmlGdcS m AssignBuffer and mmlGdcSmAssi gnClut
or "manually" using mmlGdcSmSetA ttribute calls. In the second case the minimal required attributes ar e typically
MML_GDC_SURF_ATTR_BASE_ADDRESS, MML_GDC_SURF_ATTR_WIDTH,
MML_GDC_SURF_ATTR_HEIGHT, MML_GDC_SURF_A TTR_BITPERPIXEL,
MML_GDC_SURF_ATTR_COLORBITS and MML_GDC_S URF_ATTR_COLORSHIFT.
Optionally a color lookup table can be defined for the image. A color lookup t abl e is a list with a defined number of
red, green, blue and optionally alpha values. If an index table is defined f or an image the blue and green color parts,
if the image are not longer used but the red component is used as "pointer" to the color lookup table and the related
red, green, blue (and alpha) value def ine the pixel color.
pixel color: r g b
1 1 1
color lookup table: index r g b
0 0 0 0
1 255 255 255
2 0 255 255
resulting color: 255 255 255
A color lookup table can be defined with the helper function mmlGdcSmAss ignClut or "manually" using
mmlGdcSmSetAttribute calls. In the second case the minimal r equired attributes are
MML_GDC_SURF_ATTR_CLUTMODE, MML_GDC_SU RF_ATTR_CLUTCOUNT,
MML_GDC_SURF_ATTR_CLUTBITPERPIXEL, MML_GDC_SURF_ATTR_CLUTCOLORBITS,
MML_GDC_SURF_ATTR_CLUTCOLORSHIFT and MML_GDC_SURF_ATTR_CLUTBUFFERADDRESS.
Note:
The maximal bits per pixel for an index entry is 24. Therefore if an alpha channel is required a reduced bit with for
the color channels are required (e.g., R6G6B6A6). If this is not enough the alpha channel can also be stored in the
image pixel.
If an indexed image is used it is required that the red component starts at the lowest bit for each pixel (see
MML_GDC_SURF_ATTR_COLORBITS).
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 83
Module Documentation
11.4.2 Macro Definition Documentation
11.4.2.1 #define MML_GDC_SURFACE_CONTROL_HEIGHT 2048
Maximum supported height for surfaces .
11.4.2.2 #define MML_GDC_SURFACE_CONTROL_WIDTH 2048
Maximum supported width for surfaces.
11.4.2.3 #define MML_GDC_SURFACE_MAX_HEIGHT 4096
Absolute maximum height for surfaces.
11.4.2.4 #define MML_GDC_SURFACE_MAX_WIDTH 4096
Absolute maximum width for surfac es.
11.4.3 Typedef Documentation
11.4.3.1 typedef MML_GDC_SURFACE_CONTAINER MML_GDC_SURFACE
The surface object definition
11.4.4 Enumeration Type Documentation
11.4.4.1 enum MML_GDC_SURF_ATTR
Surface attribute.
Enumerator
MML_GDC_SURF_ATTR_BASE_ADDRESS
Virtual base address (initial: 0).
Note:
The base address should be used to address images inside the VRAM. While setting a virtual address the
physical address will be overwr i tten.
MML_GDC_SURF_ATTR_PHYS_ADDRESS
Physical base address (initial: 0).
Note:
Can be used to read image buffers direc t from NOR flash. While setting a phys i c al address the virtual address
will be overwritten.
MML_GDC_SURF_ATTR_BASE_ADDRESS2
Not used for S6E2D! Virtual base addr es s of the UV buffer (initial: 0).
MML_GDC_SURF_ATTR_PHYS_ADDRESS2
Not used for S6E2D! Physical base addr ess of the UV buffer (initial: 0).
MML_GDC_SURF_ATTR_WIDTH
Width in pixels (initial: 0). MML_GDC_SURF_ATTR_HEIGHT Height in pixels (initial: 0).
MML_GDC_SURF_ATTR_STRIDE Size of a line in bytes ( initial: 0).
Note:
If stride is 0, the default stride for the image buffer is assumed represented by the following formula:
stride = ((Width * BitPerPixel + 7) >> 3)
The GetAttribute call will return t he previously set "custom" stride value or the default stride calculat ed with the
formula above. The stride value is not important for compressed ima ges. If the surface describes a compressed
image the returned value will be 0.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 84
Module Documentation
MML_GDC_SURF_ATTR_BITPERPIXEL
Size of one pixel in bits. Can be one of 1, 2, 4, 8, 12, 16, 24, 32(initial: 32).
MML_GDC_SURF_ATTR_COLORBITS
Color component size in bits 0xRRGG BBAA or 0xY0U0Y1V0 (initial: 0x08080808).
color_bits = red_bits<<24 + green _bi ts<<16 + blue_bits<<8 + alpha_bits //for RGBA format,
MML_GDC_SURF_ATTR_COLORSHIFT
Color component shift (0xRRGG BBAA) or (0xY0U0Y1V0) (initial: 0x18100800).
color_shift = red_shift<<24 + green_shift<<16 + blue_shift<<8 + alpha_shift //for RGBA format,
MML_GDC_SURF_ATTR_COMPRESSION_FORMAT
Compression format (must be one of MM L_GDC_SURF_COMP, initial MML_GDC_SURF_COMP_NON).
MML_GDC_SURF_ATTR_RLAD_MAXCOLORBITS
Maximum for average number of bits per compressed pixel. This value is used f or surfaces with compression
format MML_GDC_SURF_COMP_RLA D. The format is analog to MML_GDC_SURF_ATTR_COLORBITS
(0xRRGGBBAA) or (0xY0U0Y1V0). The initial value is 0x08080808. If the surface is used as t arget buffer (blit)
and the compression format is MML_GDC _SURF_COMP_RLAD, the RLAD_BITPERPIXEL value defines the
maximum write buffer size (see MML_GD C_SURF_ATTR_SIZEINBYT E S). The application can use the
MML_GDC_SURF_ATTR_SIZEINB YTES parameter to calculate the requir ed buffer size and can allocate and
assign a VRAM space for this operati on.
MML_GDC_SURF_ATTR_SIZEINBYTES
Buffer size in bytes (initial: 0).
Note:
This value must be set for images wit h compression type MML_GDC_SURF_COMP_RLC and
MML_GDC_SURF_COMP_RLA. The size can be set to zero for all other image t ypes. If size is zero
mmlGdcSmGetAttribute will retur n the following size depending of the giv en compression type:
MML_GDC_SURF_COMP_NON: required buffer size (Height Stride).
MML_GDC_SURF_COMP_RLC: 0 (correc t size must be set by application).
MML_GDC_SURF_COMP_RLA: 0 (correct size must be set by application).
MML_GDC_SURF_COMP_RLAD: the maximal required size for the given com pr ession settings.
MML_GDC_SURF_ATTR_CLUTMODE
Color look up table mode (must be one of MML_G D C_SURF_CLM, initial
MML_GDC_SURF_CLM_NEUTRAL).
MML_GDC_SURF_ATTR_CLUTCOUNT
Number of color look up table entries (0..255, initial: 0 = no color look up table).
MML_GDC_SURF_ATTR_CLUTBITPERPIXEL
Size of one entry in bits (1, 2, 4, 8, 16, 24, 32, initial: 0).
MML_GDC_SURF_ATTR_CLUTCOLORBITS
Color component size of one entry in bit s (0xRRGGBBAA), initial: 0.
MML_GDC_SURF_ATTR_CLUTCOLORSHIFT
Color component shift of one entry in bit s (0xRRGGBBAA), initial: 0.
MML_GDC_SURF_ATTR_CLUTBUFFERADDRESS
Virtual address of CLUT data, initial: 0.
ML_GDC_SURF_ATTR_CLUTBUFFER_PHYS_ADDRESS
Physical address of CLUT data, initi al:0.
MML_GDC_SURF_ATTR_SURF_FORMAT
Macro attribute to set and get MML_GDC_SURF_FORMAT
Note:
A mmlGdcSmSetAttribute call wi th the attribute MML_GDC_SURF_ATTR _SURF_FORMAT will implicitly set
the attributes MML_GDC_SURF_ATTR_BITPERPIXEL, MML_GDC_S UR F_ATTR_COLORBITS and
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 85
Module Documentation
MML_GDC_SURF_ATTR_COLORSHIFT. A mmlGdcSmGetAttribute call with the attribute
MML_GDC_SURF_ATTR_SURF_FO R M AT will return the related color format if the same attributes match the
MML_GDC_SURF_FORMAT definition.
MML_GDC_SURF_ATTR_USERDEFINED
User defined (initial: 0).
11.4.4.2 enum MML_GDC_SURF_CLF
Color format of color lookup table.
Enumerator
MML_GDC_SURF_CLF_R8G8B8
R8G8B8
MML_GDC_SURF_CLF_B8G8R8
B8G8R8
MML_GDC_SURF_CLF_R5G5B5
R5G5B5
MML_GDC_SURF_CLF_A1R5G5B5
A1R5G5B5
MML_GDC_SURF_CLF_A4R4G4B4
A4R4G4B4
11.4.4.3 enum MML_GDC_SURF_CLM
Mode definition for color lookup t able.
Enumerator
MML_GDC_SURF_CLM_NEUTRAL
Module in neutral mode, input data is bypassed to the output.
MML_GDC_SURF_CLM_INDEX_RGB
Module in color index table mode (LUT hol ds a R, G, B color value, indexed with the red input color).
MML_GDC_SURF_CLM_INDEX_RGBA
Module in color index table mode (LUT holds a R, G, B, A color value, indexed with the red input color).
11.4.4.4 enum MML_GDC_SURF_COMP
Compression format.
Enumerator
MML_GDC_SURF_COMP_NON
The buffer is not compressed.
MML_GDC_SURF_COMP_RLC
Run-Length Encoded (allowed for read buffers only).
MML_GDC_SURF_COMP_RLA
Run-Length Adaptive (lossless compression, allowed for read buffers only).
MML_GDC_SURF_COMP_RLAD
Run-Length Adaptive Dithering ( lossy compression).
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 86
Module Documentation
11.4.4.5 enum MML_GDC_SURF_FORMAT
Color format of surface buffer. The syntax for RGBA buffers is the following: R, G, B, A and X stands for red, green,
blue, alpha and unused. The field desc r i ption(s) is followed by the bit width. For instance R5G6B5 used 5 red, 6
green and 5 blue bits but no alpha.
Note:
Additional formats are supported by the PixEng hardware. They can be defined with the attribute function.
The following examples show the related memory organization:
R8G8B8A8:
Byte 0 1 2 3 4 5 6 7
Color A0 B0 G0 R0 A1 B1 G1 R1
RGB8A8:
Byte 0 1 2 3
Color A0 RGB0 A1 RGB1
The memory organisation is descr ibed with below.
Enumerator
MML_GDC_SURF_FORMAT_R8G8B8A8
32 bpp RGBA format.
MML_GDC_SURF_FORMAT_A8B8G8R8
32 bpp ABGR format.
MML_GDC_SURF_FORMAT_A8R8G8B8
32 bpp ARGB format.
MML_GDC_SURF_FORMAT_B8G8R8A8
32 bpp BGRA format.
MML_GDC_SURF_FORMAT_R8G8B8X8
32 bpp RGB format.
MML_GDC_SURF_FORMAT_X8B8G8R8
32 bpp BGR format.
MML_GDC_SURF_FORMAT_X8R8G8B8
32 bpp RGB format.
MML_GDC_SURF_FORMAT_R8G8B8
24 bpp RGB format.
MML_GDC_SURF_FORMAT_B8G8R8
24 bpp BGR format.
MML_GDC_SURF_FORMAT_R6G6B6
18 bpp BGR format.
MML_GDC_SURF_FORMAT_R4G4B4A4
16 bpp RGBA format.
MML_GDC_SURF_FORMAT_A4R4G4B4
16 bpp ARGB format.
MML_GDC_SURF_FORMAT_R5G5B5A1
16 bpp RGBA format (5 bit for RGB, 1 bit alpha).
MML_GDC_SURF_FORMAT_A1R5G5B5
16 bpp ARGB format (5 bit for RGB, 1 bit alpha).
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 87
Module Documentation
MML_GDC_SURF_FORMAT_A1B5G5R5
16 bpp ABGR format (5 bit for RGB, 1 bit alpha).
MML_GDC_SURF_FORMAT_B5G5R5A1
16 bpp BGRA format (5 bit for RGB, 1 bit alpha).
MML_GDC_SURF_FORMAT_R5G6B5
16 bpp BGR format (5 bit for RB, 6 bit for G).
MML_GDC_SURF_FORMAT_A8RGB8
16 bpp, A8RGB8 can be used for gray or indexed image buffers with additional alpha value. For the second use
case an indexed color lookup table mus t be defined in the surface.
MML_GDC_SURF_FORMAT_RGB8
8 bpp, RGB8 can be used for gray or indexed image buffers. For the second use case an indexed color lookup
table must be defined in the surface.
MML_GDC_SURF_FORMAT_A8
8 bpp alpha format, can be used (e.g., as text buffer or external alpha mask buffer).
MML_GDC_SURF_FORMAT_A4RGB4
8 bpp, A4RGB4 can be used for gray or inde xed image buffers with additional alpha value. For the second use
case an indexed color lookup table mus t be defined in the surface.
MML_GDC_SURF_FORMAT_A4
4 bpp alpha format, can be used (e.g., as text buffer or external alpha mask buffer).
MML_GDC_SURF_FORMAT_A2
2 bpp alpha format, can be used (e.g., as text buffer or external alpha mask buffer).
MML_GDC_SURF_FORMAT_A1
1 bpp alpha format, can be used (e.g., as text buffer or external alpha mask buffer).
MML_GDC_SURF_FORMAT_RGB1
1 bpp back/white buffer (no alpha).
11.4.5 Function Documentation
11.4.5.1 MM_ERROR mmlGdcSmAssignBuffer(MML_GDC_SURFACE surf, MM_U32 uWidth,
MM_U32 uHeight, MML_GDC_SURF_FORMAT eFormat, void
uRleWords)
Assign a memory address, width, height and color format representing an image to a surface object. The buffer is
owned by the calling function. I t just describes how the image buffer must be used by a function. The application
must ensure that the memory is availab le as long as the surface is being used.
Note:
The mmlGdcSmAssignBuffer call is a fast way to assign an ima ge to a surface object. Alternatively it is
also possible to assign the same properties with several calls of mmlGdcSmSetAttribute.
The eFormat value can be used to define the most useful color formats. Please note that not all
hardware units support all color f ormats. The MML_GDC_SURF_FORMAT description includes hints
which format can be used with which unit.
The PixEng HW can operate with many more color formats. Use mmlG dcSmSetAttribute in this case to
assign the correct format to the surface.
In some cases pBufferAddress can be zero. Such surfaces c an be used as source surfaces in PixEng
operations. In this case the hardware will not access surface memory but the dr i v er uses the geometry
settings of the surface.
Surfaces with run length encoded buffers (uRleWords != 0) are only supported for source surfaces in
PixEng operations. If uRleWor ds is different from zero MML_GDC_SURF_COMP_RLC will be set to
MML_GDC_SURF_ATTR_COMPRESSION_FORMAT, otherwiseMML_GDC_SURF_COMP_NON.
pBufferAddress, MM_U32
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 88
Module Documentation
Parameters
in surf The surface object.
in uWidth The width in pixels of the image.
in uHeight The height in pixels of the image.
in eFormat
in pBufferAddress The memory address of the image. The buffer starts with the upper left pixel.
in uRleWords
The format of the image. The format defines the fields BitPerPixel, ColorBits,
ColorShift, Color format.
Number of 32-bit words that are required to decode the run length encoded source
buffer. Zero indicates an uncompressed buffer.
Return values
MML_OK On success.
MML_ERR_GDC_SURF_INVALID_SURFACE If NULL pointer is given for surf.
MML_ERR_GDC_SURF_INVALID_FORMAT If illegal value is given for eFormat.
MML_ERR_GDC_SURF_INVALID_PARAMETER
If surface size is out of range, see
MML_GDC_SURFACE_MAX_WIDTH and
MML_GDC_SURFACE_MAX_HEIGHT.
11.4.5.2 MM_ERROR mmlGdcSmAssignClut(MML_GDC_SURFACE surf, MML_GDC_SURF_CLM
eMode, MM_U32 uCount, MML_GDC_SURF_CLF eFormat, void
Assign a color lookup table to a surface. It points to a VRAM memory address owned by the application. The
application must ensure that the memory is available as long as the surface is still in use and that the memory bl ock
is large enough with respect to the width, height and format parameter s of the surface.
Note:
uCount = 0 or pBufferAddress = 0 set the CLUT in neutral mode, input data is bypassed to the output.
Parameters
pBufferAddress)
in surf The surface object getting this new property.
in eMode Defines the operation mode for the CLUT.
in uCount Number of table entries to be written.
in eFormat Format of the table entries.
in pBufferAddress The address of the color index buffer.
Return values
MML_OK On success.
MML_ERR_GDC_SURF_INVALID_SURFACE If NULL pointer is given for surf.
MML_ERR_GDC_SURF_INVALID_PARAMETER If illegal value is given for eMode.
MML_ERR_GDC_SURF_INVALID_FORMAT If illegal value is given for eFormat.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 89
Module Documentation
11.4.5.3 MM_ERROR mmlGdcSmGetAttribute(const MML_GDC_SURFACE surf,
MML_GDC_SURF_ATTR eName, MM_U32
puValue)
Get surface attributes.
Parameters
in surf The surface.
in eName Name of the attribute. See MML_GDC_SURF_ATTR.
out puValue Pointer to a variable to receive the parameter value.
Return values
MML_OK On success.
MML_ERR_GDC_SURF_INVALID_ATTRIBUTE If illegal value is given for eName.
MML_ERR_GDC_SURF_INVALID_SURFACE If NULL pointer is given for surf.
11.4.5.4 MM_ERROR mmlGdcSmResetSurfaceObject(MML_GDC_SURFACE surf)
Reset a surface object with default v alues.
Parameters
in,out surf The surface to reset.
Return values
MML_OK On success, otherwise the related error code.
11.4.5.5 MM_ERROR mmlGdcSmSetAttribute(const MML_GDC_SURFACE surf, MML_GDC_SURF_ATTR eName, MM_U32 uValue)
Set surface attributes. The application must ensure that the parameter s like stride, height, size and format of the
surface are always consistent and match the size of the memory block alloc ated for the surface.
Parameters
in surf The surface object.
in eName Name of the attribute. See MML_GDC_SURF_ATTR.
in uValue The new value.
Return values
MML_OK On success.
MML_ERR_GDC_SURF_INVALID_ATTRIBUTE If illegal value is given for eName.
MML_ERR_GDC_SURF_INVALID_SURFACE If NULL pointer is given for surf.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 90
Module Documentation
11.5 Display API
The Display API exposes all the hardware features of the display unit. S ee also Display Overview.
Data Structures
struct MML_GDC_DISP_MODE_LINE
struct MML_GDC_DISP_TCON_PROPERTIES
struct MML_GDC_DISP_PROPERTIES
struct MML_GDC_DISP_WINDOW_PROPERTIES
Typedefs
typedef struct MML_GDC_DISPLAY MML_GDC_DISPLAY
typedef structMML_GDC_DISP_WINDOW MML_GDC_DISP_WINDOW
Enumerations
enum MML_GDC_DISP_CONTROLLE R {
MML_GDC_DISP_CONTROLLER_0 = 0
}
enum MML_GDC_DISP_MODE {
MML_GDC_DISP_SINGLE_SCREEN = 0,
MML_GDC_DISP_DUAL_SCREEN,
MML_GDC_DISP_DUAL_VIEW
}
enum MML_GDC_DISP_OUTPUT_SCREEN {
MML_GDC_DISP_OUTPUT_SCREEN_PRIMARY = 0,
MML_GDC_DISP_OUTPUT_SCREEN_SECONDARY,
MML_GDC_DISP_OUTPUT_SCREEN_BOTH
}
enum MML_GDC_DISP_FILTER {
MML_GDC_DISP_FILTER_NEAREST = 0,
MML_GDC_DISP_FILTER_BILINEAR
}
enum MML_GDC_DISP_TILE_MODE {
MML_GDC_DISP_TILE_MODE_ZERO = 0,
MML_GDC_DISP_TILE_MODE_CONST = 1,
MML_GDC_DISP_TILE_MODE_PAD = 2,
MML_GDC_DISP_TILE_MODE_CLIP = 3
}
enum MML_GDC_DISP_LAYER {
MML_GDC_DISP_LAYER_0 = 0,
MML_GDC_DISP_LAYER_1
}
enum MML_GDC_DISP_SUB_LAYER {
MML_GDC_DISP_SUB_LAYER_DEFAULT = 0,
MML_GDC_DISP_SUB_LAYER_1,
MML_GDC_DISP_SUB_LAYER_2,
MML_GDC_DISP_SUB_LAYER_3,
MML_GDC_DISP_SUB_LAYER_4,
MML_GDC_DISP_SUB_LAYER_5,
MML_GDC_DISP_SUB_LAYER_6,
MML_GDC_DISP_SUB_LAYER_7,
MML_GDC_DISP_SUB_LAYER_8
}
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 91
Module Documentation
enum MML_GDC_DISP_DCK_DELAY_ENABLE {
MML_GDC_DISP_DCK_DELAY_OFF = 0,
MML_GDC_DISP_DCK_DELAY_ON
}
enum MML_GDC_DISP_DCK_INVERT_ENABLE {
MML_GDC_DISP_DCK_INVERT_OFF = 0,
MML_GDC_DISP_DCK_INVERT_ON
}
enum MML_GDC_DISP_DITHER_ENABLE {
MML_GDC_DISP_DITHOFF = 0,
MML_GDC_DISP_DITHON
}
enum MML_GDC_DISP_DITHER_MODE {
MML_GDC_DISP_TEMPDITH = 0,
MML_GDC_DISP_SPATDITH = (1 << 4)
}
enum MML_GDC_DISP_DITHER_RANGE {
MML_GDC_DISP_DITHRS11LOW = 0
}
enum MML_GDC_DISP_DITHER_FORMAT {
MML_GDC_DISP_DITHER108 = 0x08080800,
MML_GDC_DISP_DITHER107 = 0x07070700,
MML_GDC_DISP_DITHER106 = 0x06060600,
MML_GDC_DISP_DITHER105 = 0x05060500
}
enum MML_GDC_DISP_CLUT_FORMAT {
MML_GDC_DISP_CLUT_FORMAT_33 = 33
}
enum MML_GDC_DISP_CMATRIX_FORMAT {
MML_GDC_DISP_CMATRIX_FORMAT_4X3 = 0,
MML_GDC_DISP_CMATRIX_FORMAT_5X4
}
enum MML_GDC_DISP_ATTR {
MML_GDC_DISP_ATTR_OUTPUT_CONTROLLER = 0,
MML_GDC_DISP_ATTR_X_RESOLUTION,
MML_GDC_DISP_ATTR_Y_RESOLUTION,
MML_GDC_DISP_ATTR_BUFF_ERR,
MML_GDC_DISP_ATTR_BACKGROUND_COLOR
}
enum MML_GDC_DISP_WIN_ATTR {
MML_GDC_DISP_WIN_ATTR_LAYER_ID = 0,
MML_GDC_DISP_WIN_ATTR_SUB_LAYER_ID,
MML_GDC_DISP_WIN_ATTR_TOPLEFT_X,
MML_GDC_DISP_WIN_ATTR_TOPLEFT_Y,
MML_GDC_DISP_WIN_ATTR_WIDTH,
MML_GDC_DISP_WIN_ATTR_HEIGHT,
MML_GDC_DISP_WIN_ATTR_SCREEN,
MML_GDC_DISP_WIN_ATTR_COLOR,
MML_GDC_DISP_WIN_ATTR_DISABLE,
MML_GDC_DISP_WIN_ATTR_SWAP_INTERVAL,
MML_GDC_DISP_WIN_ATTR_MAX_BUFFER,
MML_GDC_DISP_WIN_ATTR_TILE_MODE,
MML_GDC_DISP_WIN_ATTR_FEATURE
}
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 92
Module Documentation
Layer feature request
#define MML_GDC_DISP_FEATURE_INDEX_COLOR (1 << 0)
#define MML_GDC_DISP_FEATURE_DECODE (1 << 1)
#define MML_GDC_DISP_FEATURE_MULTI_LAYER (1 << 7)
Buffer target
#define MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF (1 << 1)
Blend modes
#define MML_GDC_DISP_BLEND_NONE (0)
#define MML_GDC_DISP_BLEND_TRANSPARENCY (1U << 0)
#define MML_GDC_DISP_BLEND_GLO B AL_ALPHA (1U << 1)
#define MML_GDC_DISP_BLEND_SOURCE_ALPHA (1U << 2)
#define MML_GDC_DISP_BLEND_SOURCE_MULTIPLY_ALPHA (1U << 4)
Polarity control.
#define MML_GDC_DISP_HSYNC_LOW (0)
#define MML_GDC_DISP_HSYNC_HIGH (1U << 0)
#define MML_GDC_DISP_VSYNC_LOW (0)
#define MML_GDC_DISP_VSYNC_HIGH (1U << 1)
#define MML_GDC_DISP_DE_LOW ( 0)
#define MML_GDC_DISP_DE_HIGH (1U << 2)
#define MML_GDC_DISP_RGB_LOW (0)
#define MML_GDC_DISP_RGB_HIGH (1U << 3)
Default initializer
#define MML_GDC_DISP_PROPERTIES_INITIALIZER
#define MML_GDC_DISP_WINDOW_PROPERTIES_INITIALIZER
Display Functions
MM_ERROR mmlGdcDispOpenDisplay (MML_GDC_DISP_PROPERTIES *mode, MML_GDC_DISPLAY
*display)
MM_ERROR mmlGdcDispCloseDisplay (MML_GDC_DISPLAY display)
MM_ERROR mmlGdcDispDitherCtrl (MML_GDC_DISPLAY display, MML_GDC_DISP_DITHER_ENABLE
enable, MML_GDC_DISP_DITHER _M ODE mode, MML_GDC_DISP_DITHER_RANGE range,
MML_GDC_DISP_DITHER_FORMAT format)
MM_ERROR mmlGdcDispCLUTData (MML_GDC_DISPLAY display, MML_GDC_DISP_CLUT_FORMAT
format, const MM_S16 *pRed, const MM_S16 pGreen, const MM_S16 *pBlue)
MM_ERROR mmlGdcDispSyncVSync (MML_GDC_DISPLAY display, MML_GDC_SYNC sync, MM_S32
vsyncCnt)
MM_ERROR mmlGdcDispSetAttribute (MML_GDC_DISPLAY display, MML_GDC_DISP_ATTR pname,
MM_U32 param)
MM_ERROR mmlGdcDispGetAttribute (MML_GDC_DISPLAY display, MML_GDC_DISP_ATTR pname,
MM_U32 *pParam)
MM_ERROR mmlGdcDispCommit (MML_GDC_DISPLAY display)
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 93
Module Documentation
Window Functions
MM_ERROR mmlGdcDispWinCreate (MML_GDC_DISPLAY display,
MML_GDC_DISP_WINDOW_PROPERTIES *properties, MML_GDC_DISP_WINDOW *pWin)
MM_ERROR mmlGdcDispWinDestroy (MML_GDC_DISP_WINDO W win)
MM_ERROR mmlGdcDispWinSetSurface (MML_GDC_DISP_WINDOW win, MM_U32 target,
MML_GDC_SURFACE surf)
MM_ERROR mmlGdcDispWinSetBl endMode (MML_GDC_DISP_WINDOW win, MM_U32 blend_mode)
MM_ERROR mmlGdcDispWinSetMatr ix (MML_GDC_DISP_WINDOW win, MM_U32 target, const MM_FLOAT
*matrix)
MM_ERROR mmlGdcDispWinSync (MML_GDC_DISP_WINDOW win, MML_GDC_SYNC sync)
MM_ERROR mmlGdcDispWinWaitSync (MML_GDC_DISP_WINDOW win, MML_GDC_SYNC sync)
MM_ERROR mmlGdcDispWinSetAttribute (MML_GDC_DISP_WINDOW win, MML_GDC_DISP_W IN_ATTR
pname, MM_U32 param)
MM_ERROR mmlGdcDispWinGetAttribute (MML_GDC_ DISP_WINDOW win, MML_GDC_DISP_WIN_ATTR
pname, MM_U32 *pParam)
MM_ERROR mmlGdcDispWinCommit (MML_GDC_DISP_WINDO W win)
11.5.1 Detailed Description
The Display API exposes all the hardware features of the display unit. S ee also Display Overview.
#include "mml_gdc_display.h"
The software interface provides 2 objects required to use and control the display unit:
The MML_GDC_DISPLAY is a software handle for a hardware display controller and is required to
Set up video modes.
Configure dithering or gamma correc tion.
The MML_GDC_DISP_WINDOW is the software handle for hardware layers and is required
To use hardware layers to show rendere d content.
To configure blending and transparency of layers.
For synchronization between layers and other hardware components.
The following example demonst r ates the steps to show an image on Displ ay 0:
// Use default initializer for the pr operties and change later the important fields.
MML_GDC_DISP_PROPERTIES dispProp = MML_GDC_DISP_PROPERTIES_INITIALIZER;
MML_GDC_DISP_WINDOW_PROPERTIES windowProp =
MML_GDC_DISP_WINDOW_PROPERTIES_INITIALIZER;
MML_GDC_DISPLAY display;
MML_GDC_DISP_WINDOW win;
MML_GDC_SURFACE target;
// Set your requested display properties.
dispProp.outputController= M ML_GDC_DISP_CONTROLLER_0;
dispProp.xResolution = 640;
dispProp.yResolution = 480;
// Open the display
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 94
Module Documentation
MML_GDC_DISP_FEATURE_IN
The window can show an indexed
mmlGdcDispOpenDisplay( &dispProp, &display);
// Set Window properties.
windowProp.topLeftX = 0;
windowProp.topLeftY = 0;
windowProp.width = 640;
windowProp.height = 480;
//Create the window.
mmlGdcDispWinCreate(display, &windowProp, &win);
// Draw something in a surface.
MyDrawFunction(target);
// Push the surface to the surface to the window.
mmlGdcDispWinSetSurface(win, target);
mmlGdcDispWinCommit(win);
//Close Window and Display.
mmlGdcDispWinDestroy(win);
mmlGdcDispCloseDisplay(display);
Like mentioned in the Display Over v i ew enhanced features (MML_GDC_DISP_WINDOW_PROPERTIES) can be
requested while opening (mmlGdcDispWinCreate) a window. The table below lists the available feature types and
there restrictions:
Window Feature Comment Restrictions
DEX_COLOR
MML_GDC_DISP_FEATURE_D
ECODE
MML_GDC_DISP_FEATURE_M
ULTI_LAYER
image.
The window can display a RLE or
RLAD buffer.
Up to 8 windows with different size,
color format and buffer address but
the same layerId can be opened
and used simultaneously for one
display. The combined windows
represent a common layer that can
be blended to the lower level
windows. For overlapping windows
ID the resulting pixel is defined by
the latest opened window.
The surface must not be mirrored, rotated
if compression is used.
Cannot be combined with
MML_GDC_DISP_FEATURE_MULTI_LAY
ER.
Only 2 windows with this feature are
available.
Overlapping windows of this layer cannot
be blended one on top of the other. Only
the top most window will be blended
against the background.
Cannot be combined with
MML_GDC_DISP_FEATURE_DECODE.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 95
Module Documentation
11.5.2 Macro Definition Documentation
11.5.2.1 #define MML_GDC_DISP_BLEND_GLOBAL_ALPHA (1U << 1)
Enable global alpha blending.
11.5.2.2 #define MML_GDC_DISP_BLEND_NONE (0)
Disable blending.
11.5.2.3 #define MML_GDC_DISP_BLEND_SOURCE_ALPHA (1U << 2)
Enable per pixel source alpha blending.
11.5.2.4 #define MML_GDC_DISP_BLEND_SOURCE_MULTIPLY_ALPHA (1U << 4)
Enable source alpha multiplicat i on.
11.5.2.5 #define MML_GDC_DISP_BLEND_TRANSPARENCY (1U << 0)
Enable transparency.
11.5.2.6 #define MML_GDC_DISP_BUFF_TARGET_COLOR_BUFF (1 << 1)
Color buffer as target buffer.
11.5.2.7 #define MML_GDC_DISP_DE_HIGH (1U << 2)
Data enable signal high active.
11.5.2.8 #define MML_GDC_DISP_DE_LOW (0)
Data enable signal low active.
11.5.2.9 #define MML_GDC_DISP_FEATURE_DECODE (1 << 1)
Show encoded images.
11.5.2.10 #define MML_GDC_DISP_FEATURE_INDEX_COLOR (1 << 0)
Indexed color support .
11.5.2.11 #define MML_GDC_DISP_FEATURE_MULTI_LAYER (1 << 7)
The window is a "Multi-Window", (i.e. , it shares the same layer with all oth er "Multi-Windows").
11.5.2.12 #define MML_GDC_DISP_HSYNC_HIGH (1U << 0)
Hsync signal high active.
11.5.2.13 #define MML_GDC_DISP_HSYNC_LOW (0)
Hsync signal low active.
11.5.2.14 #define MML_GDC_DISP_PROPERTIES_INITIALIZER
Value:
{ MML_GDC_DISP_CONTROLLER_0, MML_GDC_DISP_SINGLE_SCREEN, 0, 0, 60, 0, 0, 0, 0 }
11.5.2.15 #define MML_GDC_DISP_RGB_HIGH (1U << 3)
Pixel data inverted.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 96
Module Documentation
11.5.2.16 #define MML_GDC_DISP_RGB_LOW (0)
No inversion of pixel data.
11.5.2.17 #define MML_GDC_DISP_VSYNC_HIGH (1U << 1)
Vsync signal high active.
11.5.2.18 #define MML_GDC_DISP_VSYNC_LOW (0)
Vsync signal low active.
11.5.2.19 #define MML_GDC_DISP_WINDOW_PROPERTIES_INITIALIZER
Value:
{ MML_GDC_DISP_OUTPUT_SCREEN_PRIMARY, 0, 0, 0, 0, MML_GDC_DISP_LAYER_0, 0,
MML_GDC_DISP_SUB_LAYER_DEFAULT}
11.5.3 Typedef Documentation
11.5.3.1 typedef struct MML_GDC_DISP_WINDOW MML_GDC_DISP_WINDOW
Window object.
11.5.3.2 typedef struct MML_GDC_DISPLAY MML_GDC_DISPLAY
Display object.
11.5.4 Enumeration Type Documentation
11.5.4.1 enum MML_GDC_DISP_ATTR
Enumeration of the different configuration attributes for display controllers.
Enumerator
MML_GDC_DISP_ATTR_OUTPUT_CONTROLLER
Display controller used for the display (see MML_GDC_DISP_CONTROLLER). This attribute can only be read.
MML_GDC_DISP_ATTR_X_RESOLUTION
Horizontal resolution. This attribute can only be read.
MML_GDC_DISP_ATTR_Y_RESOLUTION
Vertical resolution. This attribute can only be read.
MML_GDC_DISP_ATTR_BUFF_ERR
If internal response time to read SDRAM is too long, internal FIFO buff er fails to supply display data. This
attribute shows error status of t he FIFO for this display controller. This attribute can only be read. The hardware
status is cleared after read operation.
Get value = 0, no buffer error.
Get value != 0, buffer error occurred.
MML_GDC_DISP_ATTR_BACKGROUND_COLOR
Sets background color 0xRRGGBB AA for the screen area not included in any display window. Background
color is default blended with dis pl ay layers. The default value is 0 (black ).
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 97
Module Documentation
11.5.4.2 enum MML_GDC_DISP_CLUT_FORMAT
For size of entries for the CLUT.
Enumerator
MML_GDC_DISP_CLUT_FORMAT_33
Each array for RGB contains 33 10-bit v alues to describe the 0-255 index range. The missing values are
interpolated (see mmlGdcDispCLUT D ata for details).
11.5.4.3 enum MML_GDC_DISP_CMATRIX_FORMAT
Color matrix format.
Enumerator
MML_GDC_DISP_CMATRIX_FORMAT_4X3
float[12] array with 4 column and 3 lines.
MML_GDC_DISP_CMATRIX_FORMAT_5X4
float[20] array with 5 column and 4 lines.
11.5.4.4 enum MML_GDC_DISP_CONTROLLER
Enumeration of display controllers .
Enumerator
MML_GDC_DISP_CONTROLLER_0
Display controller 0.
11.5.4.5 enum MML_GDC_DISP_DCK_DELAY_ENABLE
Display clock delay disable/enable flags.
Enumerator
MML_GDC_DISP_DCK_DELAY_OFF
Disable the display clock delay.
MML_GDC_DISP_DCK_DELAY_ON
Enable the display clock delay.
11.5.4.6 enum MML_GDC_DISP_DCK_INVERT_ENABLE
Inversion of display clock disable/ enable flags.
Enumerator
MML_GDC_DISP_DCK_INVERT_OFF
Display clock output signal is not inv erted.
MML_GDC_DISP_DCK_INVERT_ON
Display clock output signal is inverted.
11.5.4.7 enum MML_GDC_DISP_DITHER_ENABLE
Dither enable.
Enumerator
MML_GDC_DISP_DITHOFF
Flag to disable dithering.
MML_GDC_DISP_DITHON
Flag to enable dithering.
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 98
Module Documentation
11.5.4.8 enum MML_GDC_DISP_DITHER_FORMAT
Dither format 0x0R0G0B00.
Enumerator
MML_GDC_DISP_DITHER108
Flag to specify dithering output format of RGB 10x10x10 -> 8x8x8.
MML_GDC_DISP_DITHER107
Flag to specify dithering output format of RGB 10x10x10 -> 7x7x7.
MML_GDC_DISP_DITHER106
Flag to specify dithering output format of RGB 10x10x10 -> 6x6x6.
MML_GDC_DISP_DITHER105
Flag to specify dithering output format of RGB 10x10x10 -> 5x6x5.
11.5.4.9 enum MML_GDC_DISP_DITHER_MODE
Dither mode.
Enumerator
MML_GDC_DISP_TEMPDITH
Flag to specify temporal dithering.
MML_GDC_DISP_SPATDITH
Flag to specify spatial dithering.
11.5.4.10 enum MML_GDC_DISP_DITHER_RANGE
Dither range.
Enumerator
MML_GDC_DISP_DITHRS11LOW
Flag to specify dither range: add 0s to lower bits.
11.5.4.11 enum MML_GDC_DISP_FILTER
Enumeration of possible filter settings for a window.
Enumerator
MML_GDC_DISP_FILTER_NEAREST
Nearest filter enable.
MML_GDC_DISP_FILTER_BILINEAR
Bilinear filter enable.
11.5.4.12 enum MML_GDC_DISP_LAYER
Enumeration of layers.
Enumerator
MML_GDC_DISP_LAYER_0
Layer 0
MML_GDC_DISP_LAYER_1
Layer 1
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 99
Module Documentation
11.5.4.13 enum MML_GDC_DISP_MODE
Enumeration of display modes.
Enumerator
MML_GDC_DISP_SINGLE_SCREEN
Single screen mode.
MML_GDC_DISP_DUAL_SCREEN
Reserved for future use.
MML_GDC_DISP_DUAL_VIEW
Reserved for future use.
11.5.4.14 enum MML_GDC_DISP_OUTPUT_SCREEN
Enumeration of possible locations to show a layer on a display.
Enumerator
MML_GDC_DISP_OUTPUT_SCREEN_PRIMARY
Show layer on primary screen.
MML_GDC_DISP_OUTPUT_SCREEN_SECONDARY
Show layer on secondary screen (implies using dual screen mode see MM L_GDC_DISP_PROPERTIES).
MML_GDC_DISP_OUTPUT_SCREEN_BOTH
Show layer on both screens (implies using dual screen mode see MML_GDC_DISP_PROPERTIES).
11.5.4.15 enum MML_GDC_DISP_SUB_LAYER
Enumeration of sub-layers for windows with feature MML_GDC_DISP_FEATURE_MULTI_LAYER.
Enumerator
MML_GDC_DISP_SUB_LAYER_DEFAULT
Window is not a Multi Window or the next free sub-layer is used.
MML_GDC_DISP_SUB_LAYER_1
sub layer 1
MML_GDC_DISP_SUB_LAYER_2
sub layer 2
MML_GDC_DISP_SUB_LAYER_3
sub layer 3
MML_GDC_DISP_SUB_LAYER_4
sub layer 4
MML_GDC_DISP_SUB_LAYER_5
sub layer 5
MML_GDC_DISP_SUB_LAYER_6
sub layer 6
MML_GDC_DISP_SUB_LAYER_7
sub layer 7
MML_GDC_DISP_SUB_LAYER_8
sub layer 8
FM4, S6E2DH/S6E2DF/S6E2D5/S6E2D3 Series, 32-Bit Microcontroller, Graphic Driver User Manual, Doc. No. 002-04387 Rev. *A 100
Loading...