Arm-2D  
2D Image Processing Library for Cortex-M Processors
arm_2d_helper_scene.h
1/*
2 * Copyright (C) 2022 Arm Limited or its affiliates. All rights reserved.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Licensed under the Apache License, Version 2.0 (the License); you may
7 * not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19/* ----------------------------------------------------------------------
20 * Project: Arm-2D Library
21 * Title: #include "arm_2d_helper_scene.h"
22 * Description: Public header file for the scene service
23 *
24 * $Date: 23. July 2022
25 * $Revision: V.1.1.0
26 *
27 * Target Processor: Cortex-M cores
28 * -------------------------------------------------------------------- */
29
30#ifndef __ARM_2D_HELPER_SCENE_H__
31#define __ARM_2D_HELPER_SCENE_H__
32
33/*============================ INCLUDES ======================================*/
34#include "arm_2d_helper_pfb.h"
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40#if defined(__clang__)
41# pragma clang diagnostic push
42# pragma clang diagnostic ignored "-Wunknown-warning-option"
43# pragma clang diagnostic ignored "-Wreserved-identifier"
44# pragma clang diagnostic ignored "-Wdeclaration-after-statement"
45# pragma clang diagnostic ignored "-Wpadded"
46#endif
47
48/*!
49 * \addtogroup gHelper 7 Helper Services
50 * @{
51 */
52
53
54/*============================ MACROS ========================================*/
55/*============================ MACROFIED FUNCTIONS ===========================*/
56/*============================ TYPES =========================================*/
57
58/*!
59 * \brief scene switching mode
60 */
61typedef enum {
62
63 /* valid switching visual effects begin */
64 ARM_2D_SCENE_SWITCH_MODE_NONE = 0, //!< no switching visual effect
65 ARM_2D_SCENE_SWITCH_MODE_USER = 1, //!< user defined switching visual effect
66 ARM_2D_SCENE_SWITCH_MODE_FADE_WHITE = 2, //!< fade in fade out (white)
67 ARM_2D_SCENE_SWITCH_MODE_FADE_BLACK = 3, //!< fade in fade out (black)
72 ARM_2D_SCENE_SWITCH_MODE_ERASE_LEFT = 8, //!< erase to the right
74 ARM_2D_SCENE_SWITCH_MODE_ERASE_UP, //!< erase to the top
75 ARM_2D_SCENE_SWITCH_MODE_ERASE_DOWN, //!< erase to the bottom
76
77 /* valid switching visual effects end */
78 __ARM_2D_SCENE_SWITCH_MODE_VALID, //!< For internal user only
79
80
81
82 ARM_2D_SCENE_SWITCH_MODE_IGNORE_OLD_BG = _BV(8), //!< ignore the background of the old scene
83 ARM_2D_SCENE_SWITCH_MODE_IGNORE_OLD_SCEBE = _BV(9), //!< ignore the old scene
84 ARM_2D_SCENE_SWITCH_MODE_IGNORE_NEW_BG = _BV(10), //!< ignore the background of the new scene
85 ARM_2D_SCENE_SWITCH_MODE_IGNORE_NEW_SCEBE = _BV(11), //!< ignore the new scene
86
87 ARM_2D_SCENE_SWITCH_MODE_DEFAULT_BG_WHITE = 0 << 12, //!< use white as default background
88 ARM_2D_SCENE_SWITCH_MODE_DEFAULT_BG_BLACK = 1 << 12, //!< use black as default background
89 ARM_2D_SCENE_SWITCH_MODE_DEFAULT_BG_USER = 2 << 12, //!< use user defined default background
90
91 __ARM_2D_SCENE_SWTICH_MODE_IGNORE_msk = 0x0F << 8, //!< For internal user only
92 __ARM_2D_SCENE_SWTICH_MODE_IGNORE_pos = 8, //!< For internal user only
93 __ARM_2D_SCENE_SWTICH_MODE_DEFAULT_BG_msk = 3 << 12, //!< For internal user only
94 __ARM_2D_SCENE_SWTICH_MODE_DEFAULT_BG_pos = 12, //!< For internal user only
95
97
99 struct {
100 uint8_t chMode; //!< the switch visual effect
101 uint8_t bIgnoreOldSceneBG : 1; //!< when set, ignore the background of the old scene
102 uint8_t bIgnoreOldScene : 1; //!< when set, ignore the old scene
103 uint8_t bIgnoreNewSceneBG : 1; //!< when set, ignore the background of the new scene
104 uint8_t bIgnoreNewScene : 1; //!< when set, ignore the new scene
105 uint8_t u2DefaultBG : 2; //!< the default background
106 uint8_t : 2;
107 } Feature;
108 uint16_t hwSetting; //!< the setting value
110
111/*!
112 * \brief a class for describing scenes which are the combination of a
113 * background and a foreground with a dirty-region-list support
114 *
115 */
116typedef struct arm_2d_scene_t arm_2d_scene_t;
118 arm_2d_scene_t *ptNext; //!< next scene
119 arm_2d_region_list_item_t *ptDirtyRegion; //!< dirty region list for the foreground
120 arm_2d_helper_draw_handler_t *fnBackground; //!< the function pointer for the background
121 arm_2d_helper_draw_handler_t *fnScene; //!< the function pointer for the foreground
122 void (*fnOnBGStart)(arm_2d_scene_t *ptThis); //!< on-start-drawing-background event handler
123 void (*fnOnBGComplete)(arm_2d_scene_t *ptThis); //!< on-complete-drawing-background event handler
124 void (*fnOnFrameStart)(arm_2d_scene_t *ptThis); //!< on-frame-start event handler
125 void (*fnOnFrameCPL)(arm_2d_scene_t *ptThis); //!< on-frame-complete event handler
126
127 /*!
128 * \note We use fnDepose to free the resources
129 */
130 void (*fnDepose)(arm_2d_scene_t *ptThis); //!< on-scene-depose event handler
131 struct {
132 uint8_t bOnSwitchingIgnoreBG : 1; //!< ignore background during switching period
133 uint8_t bOnSwitchingIgnoreScene : 1; //!< ignore forground during switching period
134 };
135};
136
137/*!
138 * \brief a class to manage scenes
139 *
140 */
141typedef struct arm_2d_scene_player_t {
142 inherit(arm_2d_helper_pfb_t); //!< inherit from arm_2d_helper_pfb_t
143
144 ARM_PRIVATE(
145 struct {
146 arm_2d_scene_t *ptHead; //!< points to the head of the FIFO
147 arm_2d_scene_t *ptTail; //!< points to the tail of the FIFO
148 } SceneFIFO; //!< Scene FIFO
149
150 struct {
151 uint8_t bNextSceneReq : 1; //!< a flag to request switching-to-the next-scene
152 uint8_t bSwitchCPL : 1; //!< indication of scene switching completion
153 uint8_t : 6;
154 uint8_t chState; //!< the state of the FSM used by runtime.
155 } Runtime; //!< scene player runtime
156
157 struct {
158 union {
159 uint8_t chState;
160 struct {
161 uint8_t chState;
162 uint8_t chOpacity;
163 bool bIsFadeBlack;
164 }Fade;
165 struct {
166 uint8_t chState;
167 arm_2d_tile_t tSceneWindow;
168 arm_2d_tile_t tTemp;
169 }Erase;
170 struct {
171 uint8_t chState;
172 arm_2d_tile_t tSceneWindow;
173 }Slide;
174 };
175 __arm_2d_helper_scene_switch_t tConfig; //!< the switching configuration
176 uint16_t hwPeriod; //!< the switching should finish in specified millisecond
177 int64_t lTimeStamp;
178 }Switch;
181
182/*============================ GLOBAL VARIABLES ==============================*/
183/*============================ LOCAL VARIABLES ===============================*/
184/*============================ PROTOTYPES ====================================*/
185
186/*!
187 * \brief flush the scene FIFO
188 *
189 * \param[in] ptThis the target scene player
190 */
191extern
192ARM_NONNULL(1)
194
195/*!
196 * \brief append a set of scenes to a scene player
197 *
198 * \param[in] ptThis the target scene player
199 * \param[in] ptScenes a scene array
200 * \param[in] hwCount the number of scenes in the array
201 */
202extern
203ARM_NONNULL(1)
205 arm_2d_scene_t *ptScenes,
206 int_fast16_t hwCount);
207
208/*!
209 * \brief request switching to the next scene safely
210 *
211 * \param[in] ptThis the target scene player
212 *
213 * \note Once received a request, the scene player will only switch to the
214 * next scene at the end of a frame.
215 */
216extern
217ARM_NONNULL(1)
219
220/*!
221 * \brief configure the scene switching mode
222 *
223 * \param[in] ptThis the target scene player
224 * \param[in] hwSettings a combination of valid settings defined in
225 * arm_2d_scene_player_switch_mode_t
226 */
227extern
228ARM_NONNULL(1)
230 uint_fast16_t hwSettings);
231
232/*!
233 * \brief read the current scene switching mode
234 *
235 * \param[in] ptThis the target scene player
236 * \return uint16_t the current setting value for the scene switching mode
237 */
238extern
239ARM_NONNULL(1)
241
242/*!
243 * \brief configure the scene switching period
244 *
245 * \param[in] ptThis the target scene player
246 * \param[in] hwMS period in millisecond
247 */
248extern
249ARM_NONNULL(1)
251 uint_fast16_t hwMS);
252
253/*!
254 * \brief the scene player task function
255 *
256 * \param[in] ptThis the target scene player
257 *
258 * \note the event sequence of a scene:
259 * 1. when fnBackground is valid
260 * - invoke fnOnBGStart when it is valid
261 * - invoke fnBackground
262 * - invoke fnOnBGComplete when it is valid
263 * 2. invoke fnOnFrameStart when it is valid
264 * 3. invoke fnScene
265 * 4. invoke fnOnFrameCPL when it is valid
266 * 5. Check bNextSceneReq
267 * - false (0), go back to step 2
268 * - true, invoke fnDepose when it is valid and switch to the next scene
269 *
270 */
271extern
272ARM_NONNULL(1)
274
275/*! @} */
276
277#if defined(__clang__)
278# pragma clang diagnostic pop
279#endif
280
281#ifdef __cplusplus
282}
283#endif
284
285#endif