Arm-2D  
2D Image Processing Library for Cortex-M Processors
 
Loading...
Searching...
No Matches
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: 07. Feb 2023
25 * $Revision: V.1.3.11
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# pragma clang diagnostic ignored "-Wgnu-zero-variadic-macro-arguments"
47#endif
48
49/*!
50 * \addtogroup gHelper 7 Helper Services
51 * @{
52 */
53
54
55/*============================ MACROS ========================================*/
56/*============================ MACROFIED FUNCTIONS ===========================*/
57
58/*!
59 * \brief register / update the evtOnDrawNavigation event handler. You can use
60 * this event to draw an ALWAY-TOP navigation bar or title during switching
61 * period.
62 *
63 * \param[in] __DISP_ADAPTER_PTR the target scene player
64 * \param[in] __DRAW_HANDLER the event handler to draw the navigation bar and/or
65 * titles
66 * \param[in] __USER_TARGET_PTR the address of an user specified object. If it
67 * is NULL, ptThis will be used instead.
68 * \param[in] ... an optional dirty region list for the navigation layer. If
69 * ommited, NULL is used.
70 * \note if the optional dirty region list is omitted and the normal scene
71 * doesn't cover the region of the content in the navigation layer,
72 * you won't see the content.
73 * \return arm_2d_err_t the operation result
74 */
75#define arm_2d_scene_player_register_on_draw_navigation_event_handler( \
76 __DISP_ADAPTER_PTR, \
77 __DRAW_HANDLER, \
78 __USER_TARGET_PTR, \
79 ...) \
80 __arm_2d_scene_player_register_on_draw_navigation_event_handler( \
81 (__DISP_ADAPTER_PTR), \
82 (__DRAW_HANDLER), \
83 (__USER_TARGET_PTR), \
84 (NULL,##__VA_ARGS__))
85
86/*!
87 * \brief configure the scene switching mode
88 *
89 * \param[in] __DISP_ADAPTER_PTR the target scene player
90 * \param[in] __SWITCH_MODE a switching mode object
91 * \param[in] ... an optional configurations for the switching
92 */
93#define arm_2d_scene_player_set_switching_mode(__DISP_ADAPTER_PTR, \
94 __SWITCH_MODE, \
95 ...) \
96 __arm_2d_scene_player_set_switching_mode((__DISP_ADAPTER_PTR), \
97 &(__SWITCH_MODE), \
98 (0,##__VA_ARGS__))
99
100/*============================ TYPES =========================================*/
101
102/*!
103 * \brief scene switching mode
104 */
105typedef enum {
106
107 /* valid switching visual effects begin */
108 ARM_2D_SCENE_SWITCH_CFG_NONE = 0, //!< no switching visual effect
109 ARM_2D_SCENE_SWITCH_CFG_USER = 1, //!< user defined switching visual effect
110 ARM_2D_SCENE_SWITCH_CFG_FADE_WHITE = 2, //!< fade in fade out (white)
111 ARM_2D_SCENE_SWITCH_CFG_FADE_BLACK = 3, //!< fade in fade out (black)
116 ARM_2D_SCENE_SWITCH_CFG_ERASE_LEFT = 8, //!< erase to the right
118 ARM_2D_SCENE_SWITCH_CFG_ERASE_UP, //!< erase to the top
119 ARM_2D_SCENE_SWITCH_CFG_ERASE_DOWN, //!< erase to the bottom
120
121 /* valid switching visual effects end */
122 __ARM_2D_SCENE_SWITCH_CFG_VALID, //!< For internal user only
123
124 ARM_2D_SCENE_SWITCH_CFG_IGNORE_OLD_BG = _BV(8), //!< ignore the background of the old scene
125 ARM_2D_SCENE_SWITCH_CFG_IGNORE_OLD_SCEBE = _BV(9), //!< ignore the old scene
126 ARM_2D_SCENE_SWITCH_CFG_IGNORE_NEW_BG = _BV(10), //!< ignore the background of the new scene
127 ARM_2D_SCENE_SWITCH_CFG_IGNORE_NEW_SCEBE = _BV(11), //!< ignore the new scene
128
129 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_WHITE = 0 << 12, //!< use white as default background
130 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_BLACK = 1 << 12, //!< use black as default background
131 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_USER = 2 << 12, //!< use user defined default background
132
133 __ARM_2D_SCENE_SWTICH_CFG_IGNORE_msk = 0x0F << 8, //!< For internal user only
134 __ARM_2D_SCENE_SWTICH_CFG_IGNORE_pos = 8, //!< For internal user only
135 __ARM_2D_SCENE_SWTICH_CFG_DEFAULT_BG_msk = 3 << 12, //!< For internal user only
136 __ARM_2D_SCENE_SWTICH_CFG_DEFAULT_BG_pos = 12, //!< For internal user only
137
139
140
141
142/*!
143 * \brief an internal data structure for scene switching
144 *
145 * \note Please do not use it.
146 */
148
149 struct {
150 uint8_t chMode; //!< the switch visual effect
151 uint8_t bIgnoreOldSceneBG : 1; //!< when set, ignore the background of the old scene
152 uint8_t bIgnoreOldScene : 1; //!< when set, ignore the old scene
153 uint8_t bIgnoreNewSceneBG : 1; //!< when set, ignore the background of the new scene
154 uint8_t bIgnoreNewScene : 1; //!< when set, ignore the new scene
155 uint8_t u2DefaultBG : 2; //!< the default background
156 uint8_t : 2;
157 } Feature;
158 uint16_t hwSetting; //!< the setting value
159
161
162
163/*!
164 * \brief scene switching mode descriptor
165 */
166typedef const struct {
167 uint8_t chEffects; //!< switching effects
168 arm_2d_helper_draw_handler_t *fnSwitchDrawer; //!< switching algorithm
170
171
173
174/*!
175 * \brief a class for describing scenes which are the combination of a
176 * background and a foreground with a dirty-region-list support
177 *
178 */
179typedef struct arm_2d_scene_t arm_2d_scene_t;
181 arm_2d_scene_t *ptNext; //!< next scene
182 arm_2d_scene_player_t *ptPlayer; //!< points to the host scene player
183 arm_2d_region_list_item_t *ptDirtyRegion; //!< dirty region list for the foreground
184 arm_2d_helper_draw_handler_t *fnBackground; //!< the function pointer for the background
185 arm_2d_helper_draw_handler_t *fnScene; //!< the function pointer for the foreground
186 void (*fnOnBGStart)(arm_2d_scene_t *ptThis); //!< on-start-drawing-background event handler
187 void (*fnOnBGComplete)(arm_2d_scene_t *ptThis); //!< on-complete-drawing-background event handler
188 void (*fnOnFrameStart)(arm_2d_scene_t *ptThis); //!< on-frame-start event handler
189 void (*fnOnFrameCPL)(arm_2d_scene_t *ptThis); //!< on-frame-complete event handler
190
191 /*!
192 * \note We can use this event to initialize/generate the new(next) scene
193 */
194 void (*fnBeforeSwitchOut)(arm_2d_scene_t *ptThis); //!< before-scene-switch-out event handler
195
196 /*!
197 * \note We use fnDepose to free the resources
198 */
199 void (*fnDepose)(arm_2d_scene_t *ptThis); //!< on-scene-depose event handler
200 struct {
201 uint8_t bOnSwitchingIgnoreBG : 1; //!< ignore background during switching period
202 uint8_t bOnSwitchingIgnoreScene : 1; //!< ignore forground during switching period
203 };
204};
205
206/*!
207 * \brief a class to manage scenes
208 *
209 */
211 inherit(arm_2d_helper_pfb_t); //!< inherit from arm_2d_helper_pfb_t
212
213 ARM_PRIVATE(
214 struct {
215 arm_2d_scene_t *ptHead; //!< points to the head of the FIFO
216 arm_2d_scene_t *ptTail; //!< points to the tail of the FIFO
217 } SceneFIFO; //!< Scene FIFO
218
219 struct {
220 uint8_t bNextSceneReq : 1; //!< a flag to request switching-to-the next-scene
221 uint8_t bSwitchCPL : 1; //!< indication of scene switching completion
222 uint8_t bUpdateBG : 1; //!< update the background of the current scene
223 uint8_t : 5;
224 uint8_t chState; //!< the state of the FSM used by runtime.
225 } Runtime; //!< scene player runtime
226
227 struct {
228 arm_2d_scene_switch_mode_t *ptMode; //!< the switching mode
229 union {
230 uint8_t chState; //!< FSM state
231 struct {
232 uint8_t chState; //!< FSM state
233 uint8_t chOpacity; //!< opacity of the cover
234 bool bIsFadeBlack; //!< the colour of the cover
235 }Fade;
236 struct {
237 uint8_t chState; //!< FSM state
238 arm_2d_tile_t tSceneWindow; //!< scene window
239 arm_2d_tile_t tTemp; //!< a temp tile
240 int16_t iOffset; //!< erase offset
241 }Erase;
242 struct {
243 uint8_t chState; //!< FSM state
244 arm_2d_tile_t tSceneWindow; //!< scene window
245 int16_t iOffset; //!< slide offset
246 }Slide;
247 };
248 __arm_2d_helper_scene_switch_t tConfig; //!< the switching configuration
249 uint16_t hwPeriod; //!< the switching should finish in specified millisecond
250 int64_t lTimeStamp;
251 }Switch;
253};
254
255/*============================ GLOBAL VARIABLES ==============================*/
256
257extern
258arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_NONE;
259
260extern
261arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_USER;
262
263extern
264arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FADE_WHITE;
265
266extern
267arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FADE_BLACK;
268
269extern
270arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_LEFT;
271
272extern
273arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_RIGHT;
274
275extern
276arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_UP;
277
278extern
279arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_DOWN;
280
281extern
282arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_LEFT;
283
284extern
285arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_RIGHT;
286
287extern
288arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_UP;
289
290extern
291arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_DOWN;
292
293/*============================ LOCAL VARIABLES ===============================*/
294/*============================ PROTOTYPES ====================================*/
295
296/*!
297 * \brief flush the scene FIFO
298 *
299 * \param[in] ptThis the target scene player
300 */
301extern
302ARM_NONNULL(1)
304
305/*!
306 * \brief append a set of scenes to a scene player
307 *
308 * \param[in] ptThis the target scene player
309 * \param[in] ptScenes a scene array
310 * \param[in] hwCount the number of scenes in the array
311 */
312extern
313ARM_NONNULL(1)
315 arm_2d_scene_t *ptScenes,
316 int_fast16_t hwCount);
317
318/*!
319 * \brief request updating the background of the current scene
320 * \param[in] ptThis the target scene player
321 */
322ARM_NONNULL(1)
324
325/*!
326 * \brief request switching to the next scene safely
327 *
328 * \param[in] ptThis the target scene player
329 *
330 * \note Once received a request, the scene player will only switch to the
331 * next scene at the end of a frame.
332 */
333extern
334ARM_NONNULL(1)
336
337/*!
338 * \brief configure the scene switching mode
339 *
340 * \param[in] ptThis the target scene player
341 * \param[in] ptMode a switching mode object
342 * \param[in] hwSettings configurations for the switching
343 */
344extern
345ARM_NONNULL(1)
348 uint16_t hwSettings);
349
350/*!
351 * \brief read the current scene switching mode
352 *
353 * \param[in] ptThis the target scene player
354 * \return uint16_t the current setting value for the scene switching mode
355 */
356extern
357ARM_NONNULL(1)
359
360/*!
361 * \brief configure the scene switching period
362 *
363 * \param[in] ptThis the target scene player
364 * \param[in] hwMS period in millisecond
365 */
366extern
367ARM_NONNULL(1)
369 uint_fast16_t hwMS);
370
371
372/*!
373 * \brief register / update the evtOnDrawNavigation event handler. You can use
374 * this event to draw an ALWAY-TOP navigation bar or title during switching
375 * period.
376 *
377 * \param[in] ptThis the target scene player
378 * \param[in] fnHandler the event handler to draw the navigation bar and/or titles
379 * \param[in] pTarget the address of an user specified object. If it is NULL,
380 * ptThis will be used instead.
381 * \param[in] ptDirtyRegions a dirty region list for the navigation layer.
382 * \note if ptDirtyRegions is NULL and the normal scene doesn't cover the region
383 * of the content in the navigation layer, you won't see the content.
384 * \return arm_2d_err_t the operation result
385 */
386ARM_NONNULL(1,2)
388 arm_2d_scene_player_t *ptThis,
389 arm_2d_helper_draw_handler_t *fnHandler,
390 void *pTarget,
391 arm_2d_region_list_item_t *ptDirtyRegions);
392
393/*!
394 * \brief the scene player task function
395 *
396 * \param[in] ptThis the target scene player
397 *
398 * \note the event sequence of a scene:
399 * 1. when fnBackground is valid
400 * - invoke fnOnBGStart when it is valid
401 * - invoke fnBackground
402 * - invoke fnOnBGComplete when it is valid
403 * 2. invoke fnOnFrameStart when it is valid
404 * 3. invoke fnScene
405 * 4. invoke fnOnFrameCPL when it is valid
406 * 5. Check bNextSceneReq
407 * - false (0), go back to step 2
408 * - true, invoke fnDepose when it is valid and switch to the next scene
409 *
410 */
411extern
412ARM_NONNULL(1)
414
415/*! @} */
416
417#if defined(__clang__)
418# pragma clang diagnostic pop
419#endif
420
421#ifdef __cplusplus
422}
423#endif
424
425#endif