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: 2. Nov 2023
25 * $Revision: V.1.4.5
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 __SCENE_PLAYER_PTR, \
77 __DRAW_HANDLER, \
78 __USER_TARGET_PTR, \
79 ...) \
80 __arm_2d_scene_player_register_on_draw_navigation_event_handler( \
81 (__SCENE_PLAYER_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(__SCENE_PLAYER_PTR, \
94 __SWITCH_MODE, \
95 ...) \
96 __arm_2d_scene_player_set_switching_mode((__SCENE_PLAYER_PTR), \
97 &(__SWITCH_MODE), \
98 (0,##__VA_ARGS__))
99
100/*!
101 * \brief register / update the evtBeforeSwitching event handler. You can use
102 * this event to prepare next scenes.
103 *
104 * \param[in] ptThis the target scene player
105 * \param[in] fnHandler the event handler
106 * \param[in] ... optional, the address of an user specified object.
107 * \return arm_2d_err_t the operation result
108 */
109#define arm_2d_scene_player_register_before_switching_event_handler( \
110 __SCENE_PLAYER_PTR, \
111 __HANDLER, \
112 ...) \
113 __arm_2d_scene_player_register_before_switching_event_handler( \
114 (__SCENE_PLAYER_PTR), \
115 (__HANDLER), \
116 (NULL,##__VA_ARGS__))
117
118
119/*============================ TYPES =========================================*/
120
121/*!
122 * \brief scene switching mode
123 */
124typedef enum {
125
126 /* valid switching visual effects begin */
127 ARM_2D_SCENE_SWITCH_CFG_NONE = 0, //!< no switching visual effect
128 ARM_2D_SCENE_SWITCH_CFG_USER = 1, //!< user defined switching visual effect
129 ARM_2D_SCENE_SWITCH_CFG_FADE_WHITE = 2, //!< fade in fade out (white)
130 ARM_2D_SCENE_SWITCH_CFG_FADE_BLACK = 3, //!< fade in fade out (black)
135 ARM_2D_SCENE_SWITCH_CFG_ERASE_LEFT = 8, //!< erase to the right
137 ARM_2D_SCENE_SWITCH_CFG_ERASE_UP, //!< erase to the top
138 ARM_2D_SCENE_SWITCH_CFG_ERASE_DOWN, //!< erase to the bottom
139
140 /* valid switching visual effects end */
141 __ARM_2D_SCENE_SWITCH_CFG_VALID, //!< For internal user only
142
143 ARM_2D_SCENE_SWITCH_CFG_IGNORE_OLD_BG = _BV(8), //!< ignore the background of the old scene
144 ARM_2D_SCENE_SWITCH_CFG_IGNORE_OLD_SCEBE = _BV(9), //!< ignore the old scene
145 ARM_2D_SCENE_SWITCH_CFG_IGNORE_NEW_BG = _BV(10), //!< ignore the background of the new scene
146 ARM_2D_SCENE_SWITCH_CFG_IGNORE_NEW_SCEBE = _BV(11), //!< ignore the new scene
147
148 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_WHITE = 0 << 12, //!< use white as default background
149 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_BLACK = 1 << 12, //!< use black as default background
150 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_USER = 2 << 12, //!< use user defined default background
151
152 __ARM_2D_SCENE_SWTICH_CFG_IGNORE_msk = 0x0F << 8, //!< For internal user only
153 __ARM_2D_SCENE_SWTICH_CFG_IGNORE_pos = 8, //!< For internal user only
154 __ARM_2D_SCENE_SWTICH_CFG_DEFAULT_BG_msk = 3 << 12, //!< For internal user only
155 __ARM_2D_SCENE_SWTICH_CFG_DEFAULT_BG_pos = 12, //!< For internal user only
156
158
159
160
161/*!
162 * \brief an internal data structure for scene switching
163 *
164 * \note Please do not use it.
165 */
167
168 struct {
169 uint8_t chMode; //!< the switch visual effect
170 uint8_t bIgnoreOldSceneBG : 1; //!< when set, ignore the background of the old scene
171 uint8_t bIgnoreOldScene : 1; //!< when set, ignore the old scene
172 uint8_t bIgnoreNewSceneBG : 1; //!< when set, ignore the background of the new scene
173 uint8_t bIgnoreNewScene : 1; //!< when set, ignore the new scene
174 uint8_t u2DefaultBG : 2; //!< the default background
175 uint8_t : 2;
176 } Feature;
177 uint16_t hwSetting; //!< the setting value
178
180
181
182/*!
183 * \brief scene switching mode descriptor
184 */
185typedef const struct {
186 uint8_t chEffects; //!< switching effects
187 arm_2d_helper_draw_handler_t *fnSwitchDrawer; //!< switching algorithm
189
190
192
193/*!
194 * \brief a class for describing scenes which are the combination of a
195 * background and a foreground with a dirty-region-list support
196 *
197 */
198typedef struct arm_2d_scene_t arm_2d_scene_t;
200 arm_2d_scene_t *ptNext; //!< next scene
201 arm_2d_scene_player_t *ptPlayer; //!< points to the host scene player
202
203 /*! \note Please do NOT use it unless it is necessary */
204 arm_2d_helper_draw_handler_t *fnBackground;
205
206 arm_2d_region_list_item_t *ptDirtyRegion; //!< dirty region list for the scene
207 arm_2d_helper_draw_handler_t *fnScene; //!< the function pointer for the scene
208
209 void (*fnOnBGStart)(arm_2d_scene_t *ptThis); //!< on-start-drawing-background event handler
210 void (*fnOnBGComplete)(arm_2d_scene_t *ptThis); //!< on-complete-drawing-background event handler
211 void (*fnOnFrameStart)(arm_2d_scene_t *ptThis); //!< on-frame-start event handler
212 void (*fnOnFrameCPL)(arm_2d_scene_t *ptThis); //!< on-frame-complete event handler
213
214 /*!
215 * \note We can use this event to initialize/generate the new(next) scene
216 */
217 void (*fnBeforeSwitchOut)(arm_2d_scene_t *ptThis); //!< before-scene-switch-out event handler
218
219 /*!
220 * \note We use fnDepose to free the resources
221 */
222 void (*fnDepose)(arm_2d_scene_t *ptThis); //!< on-scene-depose event handler
223 struct {
224 uint8_t bOnSwitchingIgnoreBG : 1; //!< ignore background during switching period
225 uint8_t bOnSwitchingIgnoreScene : 1; //!< ignore forground during switching period
226 };
227};
228
229/*!
230 * \brief the scene player event handler
231 *
232 * \param[in] pTarget a user attached target address
233 * \param[in] ptPlayer the scene player
234 * \param[in] ptScene the old scene that is to be switched out
235 */
237 void *pTarget,
238 arm_2d_scene_player_t *ptPlayer,
239 arm_2d_scene_t *ptScene);
240
241/*!
242 * \brief on low level render event
243 */
246 void *pTarget; //!< user attached target
248
249/*!
250 * \brief a class to manage scenes
251 *
252 */
254 inherit(arm_2d_helper_pfb_t); //!< inherit from arm_2d_helper_pfb_t
255
256 struct {
257 uint32_t wMin;
258 uint32_t wMax;
259 uint64_t dwTotal;
260 uint64_t dwRenderTotal;
261 uint32_t wAverage;
262 float fCPUUsage;
263 uint32_t wIterations;
264 uint32_t wLCDLatency;
265 int64_t lTimestamp;
266 } Benchmark;
267
268 ARM_PRIVATE(
269 struct {
270 arm_2d_scene_t *ptHead; //!< points to the head of the FIFO
271 arm_2d_scene_t *ptTail; //!< points to the tail of the FIFO
272 } SceneFIFO; //!< Scene FIFO
273
274 struct {
275 uint8_t bNextSceneReq : 1; //!< a flag to request switching-to-the next-scene
276 uint8_t bSwitchCPL : 1; //!< indication of scene switching completion
277 uint8_t bUpdateBG : 1; //!< update the background of the current scene
278 uint8_t : 5;
279 uint8_t chState; //!< the state of the FSM used by runtime.
280 } Runtime; //!< scene player runtime
281
282 struct {
283 arm_2d_scene_switch_mode_t *ptMode; //!< the switching mode
284 union {
285 uint8_t chState; //!< FSM state
286 struct {
287 uint8_t chState; //!< FSM state
288 uint8_t chOpacity; //!< opacity of the cover
289 bool bIsFadeBlack; //!< the colour of the cover
290 }Fade;
291 struct {
292 uint8_t chState; //!< FSM state
293 arm_2d_tile_t tSceneWindow; //!< scene window
294 arm_2d_tile_t tTemp; //!< a temp tile
295 int16_t iOffset; //!< erase offset
296 }Erase;
297 struct {
298 uint8_t chState; //!< FSM state
299 arm_2d_tile_t tSceneWindow; //!< scene window
300 int16_t iOffset; //!< slide offset
301 }Slide;
302 };
303 __arm_2d_helper_scene_switch_t tConfig; //!< the switching configuration
304 uint16_t hwPeriod; //!< the switching should finish in specified millisecond
305 int64_t lTimeStamp;
306 }Switch;
307
308 struct {
309 /*!
310 * \note We can use this event to initialize/generate the new(next) scene
311 */
312 arm_2d_scene_before_scene_switching_evt_t evtBeforeSwitching; //!< before-scene-switch-out event handler
313 } Events;
315};
316
317/*============================ GLOBAL VARIABLES ==============================*/
318
319extern
320arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_NONE;
321
322extern
323arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_USER;
324
325extern
326arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FADE_WHITE;
327
328extern
329arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FADE_BLACK;
330
331extern
332arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_LEFT;
333
334extern
335arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_RIGHT;
336
337extern
338arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_UP;
339
340extern
341arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_DOWN;
342
343extern
344arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_LEFT;
345
346extern
347arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_RIGHT;
348
349extern
350arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_UP;
351
352extern
353arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_DOWN;
354
355/*============================ LOCAL VARIABLES ===============================*/
356/*============================ PROTOTYPES ====================================*/
357
358/*!
359 * \brief flush the scene FIFO
360 *
361 * \param[in] ptThis the target scene player
362 */
363extern
364ARM_NONNULL(1)
366
367/*!
368 * \brief append a set of scenes to a scene player
369 *
370 * \param[in] ptThis the target scene player
371 * \param[in] ptScenes a scene array
372 * \param[in] hwCount the number of scenes in the array
373 */
374extern
375ARM_NONNULL(1)
377 arm_2d_scene_t *ptScenes,
378 int_fast16_t hwCount);
379
380/*!
381 * \brief request updating the background of the current scene
382 * \param[in] ptThis the target scene player
383 */
384ARM_NONNULL(1)
386
387/*!
388 * \brief request switching to the next scene safely
389 *
390 * \param[in] ptThis the target scene player
391 *
392 * \note Once received a request, the scene player will only switch to the
393 * next scene at the end of a frame.
394 */
395extern
396ARM_NONNULL(1)
398
399/*!
400 * \brief configure the scene switching mode
401 *
402 * \param[in] ptThis the target scene player
403 * \param[in] ptMode a switching mode object
404 * \param[in] hwSettings configurations for the switching
405 */
406extern
407ARM_NONNULL(1)
410 uint16_t hwSettings);
411
412/*!
413 * \brief read the current scene switching mode
414 *
415 * \param[in] ptThis the target scene player
416 * \return uint16_t the current setting value for the scene switching mode
417 */
418extern
419ARM_NONNULL(1)
421
422/*!
423 * \brief configure the scene switching period
424 *
425 * \param[in] ptThis the target scene player
426 * \param[in] hwMS period in millisecond
427 */
428extern
429ARM_NONNULL(1)
431 uint_fast16_t hwMS);
432
433
434/*!
435 * \brief register / update the evtOnDrawNavigation event handler. You can use
436 * this event to draw an ALWAY-TOP navigation bar or title during switching
437 * period.
438 *
439 * \param[in] ptThis the target scene player
440 * \param[in] fnHandler the event handler to draw the navigation bar and/or titles
441 * \param[in] pTarget the address of an user specified object. If it is NULL,
442 * ptThis will be used instead.
443 * \param[in] ptDirtyRegions a dirty region list for the navigation layer.
444 * \note if ptDirtyRegions is NULL and the normal scene doesn't cover the region
445 * of the content in the navigation layer, you won't see the content.
446 * \return arm_2d_err_t the operation result
447 */
448extern
449ARM_NONNULL(1)
451 arm_2d_scene_player_t *ptThis,
452 arm_2d_helper_draw_handler_t *fnHandler,
453 void *pTarget,
454 arm_2d_region_list_item_t *ptDirtyRegions);
455
456/*!
457 * \brief hide the navigation layer
458 * \param[in] ptThis an initialised scene player
459 */
460extern
461ARM_NONNULL(1)
463
464/*!
465 * \brief show the navigation layer if there is a valid one
466 * \param[in] ptThis an initialised scene player
467 */
468extern
469ARM_NONNULL(1)
471
472/*!
473 * \brief register / update the evtBeforeSwitching event handler. You can use
474 * this event to prepare next scenes.
475 *
476 * \param[in] ptThis the target scene player
477 * \param[in] fnHandler the event handler
478 * \param[in] pTarget the address of an user specified object.
479 * \return arm_2d_err_t the operation result
480 */
481extern
482ARM_NONNULL(1)
484 arm_2d_scene_player_t *ptThis,
486 void *pTarget
487 );
488
489/*!
490 * \brief the scene player task function
491 *
492 * \param[in] ptThis the target scene player
493 *
494 * \note the event sequence of a scene:
495 * 1. when fnBackground is valid
496 * - invoke fnOnBGStart when it is valid
497 * - invoke fnBackground
498 * - invoke fnOnBGComplete when it is valid
499 * 2. invoke fnOnFrameStart when it is valid
500 * 3. invoke fnScene
501 * 4. invoke fnOnFrameCPL when it is valid
502 * 5. Check bNextSceneReq
503 * - false (0), go back to step 2
504 * - true, invoke fnDepose when it is valid and switch to the next scene
505 *
506 */
507extern
508ARM_NONNULL(1)
510
511/*! @} */
512
513#if defined(__clang__)
514# pragma clang diagnostic pop
515#endif
516
517#ifdef __cplusplus
518}
519#endif
520
521#endif