microui  4.0.1
microui
ui_display_brs.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_H
7 #define UI_DISPLAY_BRS_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*
14  * @file
15  * @brief Provides some implementations of the LLUI_DISPLAY_impl.h functions relating
16  * to the display buffer strategy (BRS).
17  *
18  * A BRS
19  * - implements the LLUI_DISPLAY_impl.h's API LLUI_DISPLAY_IMPL_refresh() and
20  * LLUI_DISPLAY_IMPL_newDrawingRegion().
21  * - calls the LLUI_DISPLAY_impl.h's API LLUI_DISPLAY_IMPL_flush() to let the display
22  * driver transmit / copy / flush back buffer data to the front buffer or swap back and
23  * front buffer (double or triple buffer management).
24  * - ensures the coherence of the back buffer's content before and after a flush.
25  *
26  * Several BRS are available in ui_display_brs_configuration.h (the implementation has
27  * to select one of them).
28  *
29  * @author MicroEJ Developer Team
30  * @version 4.0.1
31  */
32 
33 // -----------------------------------------------------------------------------
34 // Includes
35 // -----------------------------------------------------------------------------
36 
37 #include <LLUI_DISPLAY_impl.h>
38 
39 #include "ui_util.h"
40 #include "ui_display_brs_configuration.h"
41 #include "ui_log.h"
42 
43 // -----------------------------------------------------------------------------
44 // Configuration Sanity Check
45 // -----------------------------------------------------------------------------
46 
55 #if !defined UI_DISPLAY_BRS_CONFIGURATION_VERSION
56 #error "Undefined UI_DISPLAY_BRS_CONFIGURATION_VERSION, it must be defined in ui_display_brs_configuration.h"
57 #endif
58 
59 #if defined UI_DISPLAY_BRS_CONFIGURATION_VERSION && UI_DISPLAY_BRS_CONFIGURATION_VERSION != 1
60 #error "Version of the configuration file ui_display_brs_configuration.h is not compatible with this implementation."
61 #endif
62 
63 // -----------------------------------------------------------------------------
64 // Macros and defines
65 // -----------------------------------------------------------------------------
66 
67 /*
68  * @brief Logs a region (a rectangle)
69  */
70 #define LOG_REGION(log,rect) LLTRACE_record_event_u32x4((LLUI_EVENT_group), (LLUI_EVENT_offset) + (log), (rect)->x1, (rect)->y1, (rect)->x2, (rect)->y2)
71 
72 
73 // --------------------------------------------------------------------------------
74 // Display BRS public API
75 // --------------------------------------------------------------------------------
76 
77 /*
78  * @brief Restores (copies) the given rectangular region from old back buffer to the graphics
79  * context's current buffer (the destination buffer can be retrieved thanks
80  * LLUI_DISPLAY_getBufferAddress(&gc->image)).
81  *
82  * When the copy is synchronous (immediate), the implementation has to return
83  * DRAWING_DONE. When the copy is asynchronous (performed by a DMA for instance), the
84  * the implementation has to return DRAWING_RUNNING. As the end of the asynchronous
85  * copy, the implementation has to call LLUI_DISPLAY_notifyAsynchronousDrawingEnd()
86  * to unlock the caller of this function.
87  *
88  * The implementation of this function is optional; a weak function provides a simple
89  * implementation using memcpy().
90  *
91  * @param[in] gc the MicroUI GraphicsContext that targets the current back buffer
92  * @param[in] old_back_buffer a MicroUI Image that symbolizes (targets) the old back buffer.
93  * @param[in] rect the rectangular region to copy from old back buffer to new back
94  * buffer.
95  */
96 DRAWING_Status UI_DISPLAY_BRS_restore(MICROUI_GraphicsContext* gc, MICROUI_Image* old_back_buffer, ui_rect_t* rect);
97 
98 // --------------------------------------------------------------------------------
99 // EOF
100 // --------------------------------------------------------------------------------
101 
102 #ifdef __cplusplus
103 }
104 #endif
105 #endif // UI_DISPLAY_BRS_H