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