microui  4.1.0
microui
ui_display_brs_configuration.h
1 /*
2  * Copyright 2023-2024 MicroEJ Corp. All rights reserved.
3  * Use of this source code is governed by a BSD-style license that can be found with this software.
4  */
5 
6 #ifndef UI_DISPLAY_BRS_CONFIGURATION_H
7 #define UI_DISPLAY_BRS_CONFIGURATION_H
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11 
12 /*
13  * @file
14  * @brief Provides some implementations of the LLUI_DISPLAY_impl.h functions relating
15  * to the display buffer strategy (BRS).
16  *
17  * Several BRS are available. This header file allows to select an existing BRS or to
18  * let the BSP implements its own strategy. Note that if no strategy is used, the default
19  * Graphics Engine's strategy is used that consists to only called LLUI_DISPLAY_IMPL_flush()
20  * (always full screen, no restore).
21  *
22  * @author MicroEJ Developer Team
23  * @version 4.1.0
24  */
25 
26 #error \
27  "This header must be customized with VEE Port specific configuration. Remove this #error when done. This file is not modified when a new version of the CCO is installed."
28 
29 /*
30  * @brief Compatibility sanity check value.
31  * This define value is checked in the implementation to validate that the version of this configuration
32  * is compatible with the implementation.
33  *
34  * This value must not be changed by the user of the CCO.
35  * This value must be incremented by the implementor of the CCO when a configuration define is added, deleted or
36  * modified.
37  */
38 #define UI_DISPLAY_BRS_CONFIGURATION_VERSION (1)
39 
40 // -----------------------------------------------------------------------------
41 // Display Buffer Refresh Strategies (BRS)
42 // -----------------------------------------------------------------------------
43 
44 /*
45  * @brief Defines the "legacy" strategy (equivalent to the one available in UI Packs 13.x)
46  * dedicated to the buffer policy SWAP (see MicroEJ documentation).
47  */
48 #define UI_DISPLAY_BRS_LEGACY (0u)
49 
50 /*
51  * @brief Defines the "single" strategy dedicated to the display with one buffer on the MCU side
52  * and one buffer on the display side (the front buffer is not mapped to the MCU address
53  * space). The refresh consists in transmitting the back buffer data to the front buffer. The
54  * content to transmit is a list of rectangles that have been modified since last flush or an
55  * unique rectangle that encapsulates all regions (see the option UI_DISPLAY_BRS_FLUSH_SINGLE_RECTANGLE).
56  *
57  * Note: the maximum number of rectangles given as parameter to the function
58  * LLUI_DISPLAY_IMPL_flush() is equal to UI_RECT_COLLECTION_MAX_LENGTH.
59  */
60 #define UI_DISPLAY_BRS_SINGLE (1u)
61 
62 /*
63  * @brief Defines the "predraw" strategy that consists in restoring the back buffer with the
64  * content of the previous drawings (the past) just before the very first drawing after a
65  * flush (and not just after the flush).
66  *
67  * This strategy requires the available number of back buffers (i.e. the number of buffers
68  * where the drawings can be performed):
69  *
70  * #define UI_DISPLAY_BRS_DRAWING_BUFFER_COUNT (2u)
71  *
72  * This strategy manages, by default, two or three back buffers. Its implementation can be
73  * easily modified to manage more back buffers. An error is thrown if the code is not modified
74  * and the number of back buffers is higher than three.
75  *
76  * A warning is thrown if there is only one back buffer because this strategy is optimized
77  * for two or more back buffers. However, this strategy works with only one buffer but it
78  * is a little bit too complex for this use case.
79  *
80  * Notes:
81  * - The maximum number of rectangles given as parameter to the function LLUI_DISPLAY_IMPL_flush()
82  * is equal to UI_RECT_COLLECTION_MAX_LENGTH.
83  * - This BRS takes in consideration the option UI_DISPLAY_BRS_FLUSH_SINGLE_RECTANGLE.
84  */
85 #define UI_DISPLAY_BRS_PREDRAW (2u)
86 
87 // -----------------------------------------------------------------------------
88 // Display BRS Implementation and Options
89 // -----------------------------------------------------------------------------
90 
91 /*
92  * @brief Defines the display buffer strategy (BRS) to use: one of the strategies above,
93  * the Graphics Engine's default flush strategy or a BSP's custom flush strategy.
94  *
95  * When not set, the BSP has to implement the LLUI_DISPLAY_impl.h's API to define its custom
96  * display buffer strategy (otherwise the basic Graphics Engine's strategy will be used, see
97  * file comment).
98  */
99 #ifndef UI_DISPLAY_BRS
100 #define UI_DISPLAY_BRS (UI_DISPLAY_BRS_PREDRAW)
101 #endif
102 
103 /*
104  * @brief Defines the available number of drawing buffers; in other words, the number of buffers the
105  * Graphics Engine can use to draw into. According to the display BRS and the LCD connection, a drawing
106  * buffer can be alternatively a back buffer (the buffer currently used by the Graphics Engine), a
107  * front buffer (the buffer currently used by the LCD driver to map the LCD device), a transmission
108  * buffer (the buffer currently used by the LCD driver to transmit the data to the LCD device) or a free
109  * buffer (a buffer currently unused).
110  *
111  * Warning: This counter only defines the buffers the Graphics Engine can use and not the buffer reserved
112  * to the LCD device (mapped or or not on the MCU address space).
113  */
114 #ifndef UI_DISPLAY_BRS_DRAWING_BUFFER_COUNT
115 #define UI_DISPLAY_BRS_DRAWING_BUFFER_COUNT (2u)
116 #endif
117 
118 /*
119  * @brief Defines the number of rectangles the strategy uses when calling LLUI_DISPLAY_IMPL_flush().
120  * When set, the strategy gives only one rectangle that includes all dirty regions (a rectangle that
121  * encapsulates all rectangles). When not set, the strategy gives all rectangles.
122  *
123  * When the implementation of LLUI_DISPLAY_IMPL_flush() only consists to swap the back buffers, the
124  * rectangles list is useless.
125  *
126  * When the implementation of LLUI_DISPLAY_IMPL_flush() consists to transmit an unique portion of the
127  * back buffer (for instance: the back buffer is transmitted to the LCD through a DSI bus), the single
128  * rectangle mode is useful.
129  *
130  * When the implementation of LLUI_DISPLAY_IMPL_flush() consists to transmit several portions of the back
131  * buffer (for instance: the back buffer is transmitted to the LCD through a SPI bus), the rectangle list
132  * is useful.
133  *
134  * By default, the rectangles list is given as-is (the option is not enabled).
135  * @see the strategies comments to have more information on the use of this option.
136  */
137 //#define UI_DISPLAY_BRS_FLUSH_SINGLE_RECTANGLE
138 
139 // --------------------------------------------------------------------------------
140 // EOF
141 // --------------------------------------------------------------------------------
142 
143 #ifdef __cplusplus
144 }
145 #endif
146 #endif // UI_DISPLAY_BRS_CONFIGURATION_H