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: 29. Aug 2022
25 * $Revision: V.1.3.4
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
114
115/*!
116 * \brief a class for describing scenes which are the combination of a
117 * background and a foreground with a dirty-region-list support
118 *
119 */
120typedef struct arm_2d_scene_t arm_2d_scene_t;
122 arm_2d_scene_t *ptNext; //!< next scene
123 arm_2d_scene_player_t *ptPlayer; //!< points to the host scene player
124 arm_2d_region_list_item_t *ptDirtyRegion; //!< dirty region list for the foreground
125 arm_2d_helper_draw_handler_t *fnBackground; //!< the function pointer for the background
126 arm_2d_helper_draw_handler_t *fnScene; //!< the function pointer for the foreground
127 void (*fnOnBGStart)(arm_2d_scene_t *ptThis); //!< on-start-drawing-background event handler
128 void (*fnOnBGComplete)(arm_2d_scene_t *ptThis); //!< on-complete-drawing-background event handler
129 void (*fnOnFrameStart)(arm_2d_scene_t *ptThis); //!< on-frame-start event handler
130 void (*fnOnFrameCPL)(arm_2d_scene_t *ptThis); //!< on-frame-complete event handler
131
132 /*!
133 * \note We use fnDepose to free the resources
134 */
135 void (*fnDepose)(arm_2d_scene_t *ptThis); //!< on-scene-depose event handler
136 struct {
137 uint8_t bOnSwitchingIgnoreBG : 1; //!< ignore background during switching period
138 uint8_t bOnSwitchingIgnoreScene : 1; //!< ignore forground during switching period
139 };
140};
141
142/*!
143 * \brief a class to manage scenes
144 *
145 */
147 inherit(arm_2d_helper_pfb_t); //!< inherit from arm_2d_helper_pfb_t
148
149 ARM_PRIVATE(
150 struct {
151 arm_2d_scene_t *ptHead; //!< points to the head of the FIFO
152 arm_2d_scene_t *ptTail; //!< points to the tail of the FIFO
153 } SceneFIFO; //!< Scene FIFO
154
155 struct {
156 uint8_t bNextSceneReq : 1; //!< a flag to request switching-to-the next-scene
157 uint8_t bSwitchCPL : 1; //!< indication of scene switching completion
158 uint8_t : 6;
159 uint8_t chState; //!< the state of the FSM used by runtime.
160 } Runtime; //!< scene player runtime
161
162 struct {
163 union {
164 uint8_t chState;
165 struct {
166 uint8_t chState;
167 uint8_t chOpacity;
168 bool bIsFadeBlack;
169 }Fade;
170 struct {
171 uint8_t chState;
172 arm_2d_tile_t tSceneWindow;
173 arm_2d_tile_t tTemp;
174 int16_t iOffset;
175 }Erase;
176 struct {
177 uint8_t chState;
178 arm_2d_tile_t tSceneWindow;
179 int16_t iOffset;
180 }Slide;
181 };
182 __arm_2d_helper_scene_switch_t tConfig; //!< the switching configuration
183 uint16_t hwPeriod; //!< the switching should finish in specified millisecond
184 int64_t lTimeStamp;
185 }Switch;
187};
188
189/*============================ GLOBAL VARIABLES ==============================*/
190/*============================ LOCAL VARIABLES ===============================*/
191/*============================ PROTOTYPES ====================================*/
192
193/*!
194 * \brief flush the scene FIFO
195 *
196 * \param[in] ptThis the target scene player
197 */
198extern
199ARM_NONNULL(1)
201
202/*!
203 * \brief append a set of scenes to a scene player
204 *
205 * \param[in] ptThis the target scene player
206 * \param[in] ptScenes a scene array
207 * \param[in] hwCount the number of scenes in the array
208 */
209extern
210ARM_NONNULL(1)
212 arm_2d_scene_t *ptScenes,
213 int_fast16_t hwCount);
214
215/*!
216 * \brief request switching to the next scene safely
217 *
218 * \param[in] ptThis the target scene player
219 *
220 * \note Once received a request, the scene player will only switch to the
221 * next scene at the end of a frame.
222 */
223extern
224ARM_NONNULL(1)
226
227/*!
228 * \brief configure the scene switching mode
229 *
230 * \param[in] ptThis the target scene player
231 * \param[in] hwSettings a combination of valid settings defined in
232 * arm_2d_scene_player_switch_mode_t
233 */
234extern
235ARM_NONNULL(1)
237 uint_fast16_t hwSettings);
238
239/*!
240 * \brief read the current scene switching mode
241 *
242 * \param[in] ptThis the target scene player
243 * \return uint16_t the current setting value for the scene switching mode
244 */
245extern
246ARM_NONNULL(1)
248
249/*!
250 * \brief configure the scene switching period
251 *
252 * \param[in] ptThis the target scene player
253 * \param[in] hwMS period in millisecond
254 */
255extern
256ARM_NONNULL(1)
258 uint_fast16_t hwMS);
259
260/*!
261 * \brief the scene player task function
262 *
263 * \param[in] ptThis the target scene player
264 *
265 * \note the event sequence of a scene:
266 * 1. when fnBackground is valid
267 * - invoke fnOnBGStart when it is valid
268 * - invoke fnBackground
269 * - invoke fnOnBGComplete when it is valid
270 * 2. invoke fnOnFrameStart when it is valid
271 * 3. invoke fnScene
272 * 4. invoke fnOnFrameCPL when it is valid
273 * 5. Check bNextSceneReq
274 * - false (0), go back to step 2
275 * - true, invoke fnDepose when it is valid and switch to the next scene
276 *
277 */
278extern
279ARM_NONNULL(1)
281
282/*! @} */
283
284#if defined(__clang__)
285# pragma clang diagnostic pop
286#endif
287
288#ifdef __cplusplus
289}
290#endif
291
292#endif