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: 25. July 2024
25 * $Revision: V.1.8.2
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/*============================ MACROS ========================================*/
50
51/*!
52 * \addtogroup Deprecated
53 * @{
54 */
55#define arm_2d_scene_player_set_switching_period \
56 arm_2d_scene_player_set_auto_switching_period
57/*! @} */
58
59/*!
60 * \addtogroup gHelper 8 Helper Services
61 * @{
62 */
63/*============================ MACROFIED FUNCTIONS ===========================*/
64
65/*!
66 * \brief register / update the evtOnDrawNavigation event handler. You can use
67 * this event to draw an ALWAY-TOP navigation bar or title during switching
68 * period.
69 *
70 * \param[in] __DISP_ADAPTER_PTR the target scene player
71 * \param[in] __DRAW_HANDLER the event handler to draw the navigation bar and/or
72 * titles
73 * \param[in] __USER_TARGET_PTR the address of an user specified object. If it
74 * is NULL, ptThis will be used instead.
75 * \param[in] ... an optional dirty region list for the navigation layer. If
76 * ommited, NULL is used.
77 * \note if the optional dirty region list is omitted and the normal scene
78 * doesn't cover the region of the content in the navigation layer,
79 * you won't see the content.
80 * \return arm_2d_err_t the operation result
81 */
82#define arm_2d_scene_player_register_on_draw_navigation_event_handler( \
83 __SCENE_PLAYER_PTR, \
84 __DRAW_HANDLER, \
85 __USER_TARGET_PTR, \
86 ...) \
87 __arm_2d_scene_player_register_on_draw_navigation_event_handler( \
88 (__SCENE_PLAYER_PTR), \
89 (__DRAW_HANDLER), \
90 (__USER_TARGET_PTR), \
91 (NULL,##__VA_ARGS__))
92
93/*!
94 * \brief configure the scene switching mode
95 *
96 * \param[in] __DISP_ADAPTER_PTR the target scene player
97 * \param[in] __SWITCH_MODE a switching mode object
98 * \param[in] ... an optional configurations for the switching
99 */
100#define arm_2d_scene_player_set_switching_mode(__SCENE_PLAYER_PTR, \
101 __SWITCH_MODE, \
102 ...) \
103 __arm_2d_scene_player_set_switching_mode((__SCENE_PLAYER_PTR), \
104 &(__SWITCH_MODE), \
105 (0,##__VA_ARGS__))
106
107/*!
108 * \brief register / update the evtBeforeSwitching event handler. You can use
109 * this event to prepare next scenes.
110 *
111 * \param[in] ptThis the target scene player
112 * \param[in] fnHandler the event handler
113 * \param[in] ... optional, the address of an user specified object.
114 * \return arm_2d_err_t the operation result
115 */
116#define arm_2d_scene_player_register_before_switching_event_handler( \
117 __SCENE_PLAYER_PTR, \
118 __HANDLER, \
119 ...) \
120 __arm_2d_scene_player_register_before_switching_event_handler( \
121 (__SCENE_PLAYER_PTR), \
122 (__HANDLER), \
123 (NULL,##__VA_ARGS__))
124
125
126/*============================ TYPES =========================================*/
127
128/*!
129 * \brief scene switching mode
130 */
131typedef enum {
132
133 /* valid switching visual effects begin */
134 ARM_2D_SCENE_SWITCH_CFG_NONE = 0, //!< no switching visual effect
135 ARM_2D_SCENE_SWITCH_CFG_USER = 1, //!< user defined switching visual effect
136 ARM_2D_SCENE_SWITCH_CFG_FADE_WHITE = 2, //!< fade in fade out (white)
137 ARM_2D_SCENE_SWITCH_CFG_FADE_BLACK = 3, //!< fade in fade out (black)
138 ARM_2D_SCENE_SWITCH_CFG_SLIDE_LEFT = 4, //!< slide left
139 ARM_2D_SCENE_SWITCH_CFG_SLIDE_RIGHT, //!< slide right
140 ARM_2D_SCENE_SWITCH_CFG_SLIDE_UP, //!< slide up
141 ARM_2D_SCENE_SWITCH_CFG_SLIDE_DOWN, //!< slide down
142 ARM_2D_SCENE_SWITCH_CFG_ERASE_LEFT = 8, //!< erase to the right
143 ARM_2D_SCENE_SWITCH_CFG_ERASE_RIGHT, //!< erase to the left
144 ARM_2D_SCENE_SWITCH_CFG_ERASE_UP, //!< erase to the top
145 ARM_2D_SCENE_SWITCH_CFG_ERASE_DOWN, //!< erase to the bottom
146 ARM_2D_SCENE_SWITCH_CFG_FLY_IN_FROM_LEFT = 12, //!< fly in from left
147 ARM_2D_SCENE_SWITCH_CFG_FLY_IN_FROM_RIGHT, //!< fly in from right
148 ARM_2D_SCENE_SWITCH_CFG_FLY_IN_FROM_TOP, //!< fly in from top
149 ARM_2D_SCENE_SWITCH_CFG_FLY_IN_FROM_BOTTOM, //!< fly in from bottom
150
151 /* valid switching visual effects end */
152 __ARM_2D_SCENE_SWITCH_CFG_VALID, //!< For internal user only
153
154 ARM_2D_SCENE_SWITCH_CFG_IGNORE_OLD_BG = _BV(8), //!< ignore the background of the old scene
155 ARM_2D_SCENE_SWITCH_CFG_IGNORE_OLD_SCEBE = _BV(9), //!< ignore the old scene
156 ARM_2D_SCENE_SWITCH_CFG_IGNORE_NEW_BG = _BV(10), //!< ignore the background of the new scene
157 ARM_2D_SCENE_SWITCH_CFG_IGNORE_NEW_SCEBE = _BV(11), //!< ignore the new scene
158
159 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_WHITE = 0 << 12, //!< use white as default background
160 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_BLACK = 1 << 12, //!< use black as default background
161 ARM_2D_SCENE_SWITCH_CFG_DEFAULT_BG_USER = 2 << 12, //!< use user defined default background
162
163 __ARM_2D_SCENE_SWTICH_CFG_IGNORE_msk = 0x0F << 8, //!< For internal user only
164 __ARM_2D_SCENE_SWTICH_CFG_IGNORE_pos = 8, //!< For internal user only
165 __ARM_2D_SCENE_SWTICH_CFG_DEFAULT_BG_msk = 3 << 12, //!< For internal user only
166 __ARM_2D_SCENE_SWTICH_CFG_DEFAULT_BG_pos = 12, //!< For internal user only
167
168 ARM_2D_SCENE_SWITCH_CFG_BG_BLUR = _BV(14), //!< blurring the background when possible
169
170} arm_2d_scene_player_switch_mode_t;
171
172/*!
173 * \brief the scene switching status
174 *
175 */
176typedef enum {
177 ARM_2D_SCENE_SWITCH_STATUS_AUTO, //!< time-based auto switching
178 ARM_2D_SCENE_SWITCH_STATUS_MANUAL, //!< offset-based manual switching
179 ARM_2D_SCENE_SWITCH_STATUS_MANUAL_CANCEL, //!< cancel existing manual switching
180 ARM_2D_SCENE_SWITCH_STATUS_MANUAL_AUTO_CPL, //!< automatically finish the rest part of switching.
181} arm_2d_scene_player_switch_status_t;
182
183/*!
184 * \brief an internal data structure for scene switching
185 *
186 * \note Please do not use it.
187 */
188typedef union __arm_2d_helper_scene_switch_t {
189
190 struct {
191 uint8_t chMode; //!< the switch visual effect
192 uint8_t bIgnoreOldSceneBG : 1; //!< when set, ignore the background of the old scene
193 uint8_t bIgnoreOldScene : 1; //!< when set, ignore the old scene
194 uint8_t bIgnoreNewSceneBG : 1; //!< when set, ignore the background of the new scene
195 uint8_t bIgnoreNewScene : 1; //!< when set, ignore the new scene
196 uint8_t u2DefaultBG : 2; //!< the default background
197 uint8_t bBlurBG : 1; //!< when set, enable blurring when possible
198 uint8_t : 1;
199 } Feature;
200 uint16_t hwSetting; //!< the setting value
201
202}__arm_2d_helper_scene_switch_t;
203
204typedef struct arm_2d_scene_player_t arm_2d_scene_player_t;
205
206/*!
207 * \brief scene switching mode descriptor
208 */
209typedef const struct {
210 uint8_t chEffects; //!< switching effects
211 arm_2d_helper_draw_handler_t *fnSwitchDrawer; //!< switching algorithm
212
213 void (*fnOnRequestChangeSwitchingStatus)(arm_2d_scene_player_t *ptThis); //!< on request change-switch-status event handler
214 void (*fnOnSwitchComplete) (arm_2d_scene_player_t *ptThis); //!< on request switch complete event handler
215} arm_2d_scene_switch_mode_t;
216
217/*!
218 * \brief a class for describing scenes which are the combination of a
219 * background and a foreground with a dirty-region-list support
220 *
221 */
222typedef struct arm_2d_scene_t arm_2d_scene_t;
223struct arm_2d_scene_t {
224ARM_PRIVATE(
225 arm_2d_scene_t *ptNext; //!< next scene
226
227 struct {
228 uint8_t bLoaded : 1;
229 uint8_t : 7;
230 };
231)
232 arm_2d_scene_player_t *ptPlayer; //!< points to the host scene player
233
234 arm_2d_colour_t tCanvas; //!< the canvas colour
235
236 /*! \note Please do NOT use it unless it is necessary */
237 arm_2d_helper_draw_handler_t *fnBackground;
238
239 arm_2d_region_list_item_t *ptDirtyRegion; //!< dirty region list for the scene
240 arm_2d_helper_draw_handler_t *fnScene; //!< the function pointer for the scene
241
242 void (*fnOnLoad)(arm_2d_scene_t *ptThis); //!< on load event handler
243 void (*fnAfterSwitch)(arm_2d_scene_t *ptThis); //!< after scene switching event handler
244 void (*fnOnBGStart)(arm_2d_scene_t *ptThis); //!< on-start-drawing-background event handler
245 void (*fnOnBGComplete)(arm_2d_scene_t *ptThis); //!< on-complete-drawing-background event handler
246 void (*fnOnFrameStart)(arm_2d_scene_t *ptThis); //!< on-frame-start event handler
247 void (*fnOnFrameCPL)(arm_2d_scene_t *ptThis); //!< on-frame-complete event handler
248
249 /*!
250 * \note We can use this event to initialize/generate the new(next) scene
251 */
252 void (*fnBeforeSwitchOut)(arm_2d_scene_t *ptThis); //!< before-scene-switch-out event handler
253
254 /*!
255 * \note We use fnDepose to free the resources
256 */
257 void (*fnDepose)(arm_2d_scene_t *ptThis); //!< on-scene-depose event handler
258 struct {
259 uint8_t bOnSwitchingIgnoreBG : 1; //!< ignore background during switching period
260 uint8_t bOnSwitchingIgnoreScene : 1; //!< ignore forground during switching period
261 uint8_t : 2;
262 uint8_t : 3;
263 uint8_t bUseDirtyRegionHelper : 1; //!< indicate whether use the built-in dirty region helper.
264 };
265
266 arm_2d_helper_dirty_region_t tDirtyRegionHelper;
267};
268
269/*!
270 * \brief the scene player event handler
271 *
272 * \param[in] pTarget a user attached target address
273 * \param[in] ptPlayer the scene player
274 * \param[in] ptScene the old scene that is to be switched out
275 */
276typedef void arm_2d_scene_before_scene_switching_handler_t(
277 void *pTarget,
278 arm_2d_scene_player_t *ptPlayer,
279 arm_2d_scene_t *ptScene);
280
281/*!
282 * \brief on low level render event
283 */
284typedef struct arm_2d_scene_before_scene_switching_evt_t {
285 arm_2d_scene_before_scene_switching_handler_t *fnHandler; //!< event handler function
286 void *pTarget; //!< user attached target
287} arm_2d_scene_before_scene_switching_evt_t;
288
289/*!
290 * \brief a class to manage scenes
291 *
292 */
293struct arm_2d_scene_player_t {
294 inherit(arm_2d_helper_pfb_t); //!< inherit from arm_2d_helper_pfb_t
295
296 struct {
297 uint32_t wMin;
298 uint32_t wMax;
299 uint64_t dwTotal;
300 uint64_t dwRenderTotal;
301 uint32_t wAverage;
302 float fCPUUsage;
303 uint16_t hwIterations;
304 uint16_t hwFrameCounter;
305 uint32_t wLCDLatency;
306 int64_t lTimestamp;
307 } Benchmark;
308
309 ARM_PRIVATE(
310 struct {
311 arm_2d_scene_t *ptHead; //!< points to the head of the FIFO
312 arm_2d_scene_t *ptTail; //!< points to the tail of the FIFO
313 } SceneFIFO; //!< Scene FIFO
314
315 struct {
316
317 uint8_t bNextSceneReq : 1; //!< a flag to request switching-to-the next-scene
318 uint8_t bManualSwitchReq : 1; //!< a flag to request using manual switching
319 uint8_t bCancelSwitchReq : 1; //!< a flag to request cancel a manual switching
320 uint8_t bFinishManualSwitchReq : 1; //!< a flag to request finishing a manual switching
321 uint8_t : 4;
322
323 uint8_t bManualSwitch : 1; //!< manual switching
324 uint8_t bCancelSwitch : 1; //!< cancel a manual switching
325 uint8_t bFinishManualSwitch : 1; //!< finish a manual switching
326 uint8_t bFirstFrameAfterSwitch : 1;
327 uint8_t : 4;
328
329 uint8_t bSwitchCPL : 1; //!< indication of scene switching completion
330 uint8_t bUpdateBG : 1; //!< update the background of the current scene
331 uint8_t : 2;
332 uint8_t bCallOldSceneFrameCPL : 1; //!< call the old scene frame complete event handler
333 uint8_t bCallNewSceneFrameCPL : 1; //!< call the new scene frame complete event handler
334 uint8_t bCallOldSceneBGCPL : 1; //!< call the old scene Background complete event handler
335 uint8_t bCallNewSceneBGCPL : 1; //!< call the new scene Background complete event handler
336
337 uint8_t chState; //!< the state of the FSM used by runtime.
338 } Runtime; //!< scene player runtime
339
340 struct {
341 arm_2d_scene_switch_mode_t *ptMode; //!< the switching mode
342 uint8_t chState; //!< FSM state
343 int16_t iOffset; //!< erase offset
344 union {
345 struct {
346 uint8_t chOpacity; //!< opacity of the cover
347 bool bIsFadeBlack; //!< the colour of the cover
348 } Fade;
349 struct {
350 arm_2d_tile_t tSceneWindow; //!< scene window
351 arm_2d_tile_t tTemp; //!< a temp tile
352 } Erase;
353 struct {
354 arm_2d_tile_t tSceneWindow; //!< scene window
355 arm_2d_filter_iir_blur_descriptor_t tBlurOP; //!< for blur
356 } FlyIn;
357 struct {
358 arm_2d_tile_t tSceneWindow; //!< scene window
359 } Slide;
360 };
361 __arm_2d_helper_scene_switch_t tConfig; //!< the switching configuration
362
363 arm_2d_location_t tTouchPointer; //!< the coordinate offset for manual switching mode, used in erasing, sliding etc.
364 int16_t iFullLength; //!< the full length of the axis of switching
365 uint16_t hwPeriod; //!< the switching should finish in specified millisecond
366 int64_t lTimeStamp;
367 }Switch;
368
369 struct {
370 /*!
371 * \note We can use this event to initialize/generate the new(next) scene
372 */
373 arm_2d_scene_before_scene_switching_evt_t evtBeforeSwitching; //!< before-scene-switch-out event handler
374 } Events;
375 )
376};
377
378/*============================ GLOBAL VARIABLES ==============================*/
379
380extern
381arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_NONE;
382
383extern
384arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_USER;
385
386extern
387arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FADE_WHITE;
388
389extern
390arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FADE_BLACK;
391
392extern
393arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_LEFT;
394
395extern
396arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_RIGHT;
397
398extern
399arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_UP;
400
401extern
402arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_SLIDE_DOWN;
403
404extern
405arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_LEFT;
406
407extern
408arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_RIGHT;
409
410extern
411arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_UP;
412
413extern
414arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_ERASE_DOWN;
415
416extern
417arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FLY_IN_FROM_LEFT;
418
419extern
420arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FLY_IN_FROM_RIGHT;
421
422extern
423arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FLY_IN_FROM_TOP;
424
425extern
426arm_2d_scene_switch_mode_t ARM_2D_SCENE_SWITCH_MODE_FLY_IN_FROM_BOTTOM;
427
428/*============================ LOCAL VARIABLES ===============================*/
429/*============================ PROTOTYPES ====================================*/
430
431/*!
432 * \brief flush the scene FIFO
433 *
434 * \param[in] ptThis the target scene player
435 */
436extern
437ARM_NONNULL(1)
438void arm_2d_scene_player_flush_fifo(arm_2d_scene_player_t *ptThis);
439
440/*!
441 * \brief append a set of scenes to a scene player
442 *
443 * \param[in] ptThis the target scene player
444 * \param[in] ptScenes a scene array
445 * \param[in] hwCount the number of scenes in the array
446 */
447extern
448ARM_NONNULL(1)
449void arm_2d_scene_player_append_scenes(arm_2d_scene_player_t *ptThis,
450 arm_2d_scene_t *ptScenes,
451 int_fast16_t hwCount);
452
453/*!
454 * \brief request updating the background of the current scene
455 * \param[in] ptThis the target scene player
456 */
457ARM_NONNULL(1)
458void arm_2d_scene_player_update_scene_background(arm_2d_scene_player_t *ptThis);
459
460
461/*!
462 * \brief get the screen size of a specified display adapter.
463 *
464 * \param[in] ptThis the target scene player
465 * \return arm_2d_size_t the screen size
466 */
467extern
468ARM_NONNULL(1)
469arm_2d_size_t arm_2d_scene_player_get_screen_size(arm_2d_scene_player_t *ptThis);
470
471/*!
472 * \brief request switching to the next scene safely
473 *
474 * \param[in] ptThis the target scene player
475 *
476 * \note Once received a request, the scene player will only switch to the
477 * next scene at the end of a frame.
478 */
479extern
480ARM_NONNULL(1)
481void arm_2d_scene_player_switch_to_next_scene(arm_2d_scene_player_t *ptThis);
482
483/*!
484 * \brief configure the scene switching mode
485 *
486 * \param[in] ptThis the target scene player
487 * \param[in] ptMode a switching mode object
488 * \param[in] hwSettings configurations for the switching
489 */
490extern
491ARM_NONNULL(1)
492void __arm_2d_scene_player_set_switching_mode(arm_2d_scene_player_t *ptThis,
493 arm_2d_scene_switch_mode_t *ptMode,
494 uint16_t hwSettings);
495
496/*!
497 * \brief read the current scene switching mode
498 *
499 * \param[in] ptThis the target scene player
500 * \return uint16_t the current setting value for the scene switching mode
501 */
502extern
503ARM_NONNULL(1)
504uint16_t arm_2d_scene_player_get_switching_cfg(arm_2d_scene_player_t *ptThis);
505
506/*!
507 * \brief configure the scene switching period in auto-switching
508 *
509 * \param[in] ptThis the target scene player
510 * \param[in] iMS period in millisecond
511 */
512extern
513ARM_NONNULL(1)
514void arm_2d_scene_player_set_auto_switching_period( arm_2d_scene_player_t *ptThis,
515 int_fast16_t iMS);
516
517extern
518ARM_NONNULL(1)
519/*!
520 * \brief use manual switch mode and set the offset
521 *
522 * \param[in] ptThis the target scene player
523 * \param[in] tPointer the touch pointer location
524 */
525void arm_2d_scene_player_set_manual_switching_offset( arm_2d_scene_player_t *ptThis,
526 arm_2d_location_t tPointer);
527
528extern
529ARM_NONNULL(1)
530/*!
531 * \brief end the manual switching and finish the left part in a specific period (ms)
532 *
533 * \param[in] ptThis the target scene player
534 * \param[in] bMoveToPreviousScene a boolean value indicating whether move back to the
535 * previous scene, i.e. whether cancel the current switching
536 * \param iInMS the planned period as if the switching is done in auto-switching mode
537 * \return arm_2d_err_t configuration result
538 */
539arm_2d_err_t arm_2d_scene_player_finish_manual_switching( arm_2d_scene_player_t *ptThis,
540 bool bMoveToPreviousScene,
541 int_fast16_t iInMS);
542
543/*!
544 * \brief check whether scene player is switching scenes
545 *
546 * \param[in] ptThis the target scene player
547 * \return true the scene player is switching scenes
548 * \return false the scene player stays in tge current scene.
549 */
550extern
551ARM_NONNULL(1)
552bool arm_2d_scene_player_is_switching(arm_2d_scene_player_t *ptThis);
553
554/*!
555 * \brief get the scene player switching status
556 *
557 * \param[in] ptThis the target scene player
558 * \return arm_2d_scene_player_switch_status_t the switching status
559 */
560extern
561ARM_NONNULL(1)
562arm_2d_scene_player_switch_status_t
563arm_2d_scene_player_get_switching_status(arm_2d_scene_player_t *ptThis);
564
565/*!
566 * \brief register / update the evtOnDrawNavigation event handler. You can use
567 * this event to draw an ALWAY-TOP navigation bar or title during switching
568 * period.
569 *
570 * \param[in] ptThis the target scene player
571 * \param[in] fnHandler the event handler to draw the navigation bar and/or titles
572 * \param[in] pTarget the address of an user specified object. If it is NULL,
573 * ptThis will be used instead.
574 * \param[in] ptDirtyRegions a dirty region list for the navigation layer.
575 * \note if ptDirtyRegions is NULL and the normal scene doesn't cover the region
576 * of the content in the navigation layer, you won't see the content.
577 * \return arm_2d_err_t the operation result
578 */
579extern
580ARM_NONNULL(1)
581arm_2d_err_t __arm_2d_scene_player_register_on_draw_navigation_event_handler(
582 arm_2d_scene_player_t *ptThis,
583 arm_2d_helper_draw_handler_t *fnHandler,
584 void *pTarget,
585 arm_2d_region_list_item_t *ptDirtyRegions);
586
587/*!
588 * \brief hide the navigation layer
589 * \param[in] ptThis an initialised scene player
590 */
591extern
592ARM_NONNULL(1)
593void arm_2d_scene_player_hide_navigation_layer(arm_2d_scene_player_t *ptThis);
594
595/*!
596 * \brief show the navigation layer if there is a valid one
597 * \param[in] ptThis an initialised scene player
598 */
599extern
600ARM_NONNULL(1)
601void arm_2d_scene_player_show_navigation_layer(arm_2d_scene_player_t *ptThis);
602
603/*!
604 * \brief register / update the evtBeforeSwitching event handler. You can use
605 * this event to prepare next scenes.
606 *
607 * \param[in] ptThis the target scene player
608 * \param[in] fnHandler the event handler
609 * \param[in] pTarget the address of an user specified object.
610 * \return arm_2d_err_t the operation result
611 */
612extern
613ARM_NONNULL(1)
614arm_2d_err_t __arm_2d_scene_player_register_before_switching_event_handler(
615 arm_2d_scene_player_t *ptThis,
616 arm_2d_scene_before_scene_switching_handler_t *fnHandler,
617 void *pTarget
618 );
619
620/*!
621 * \brief the scene player task function
622 *
623 * \param[in] ptThis the target scene player
624 *
625 * \note the event sequence of a scene:
626 * 1. when fnBackground is valid
627 * - invoke fnOnBGStart when it is valid
628 * - invoke fnBackground
629 * - invoke fnOnBGComplete when it is valid
630 * 2. invoke fnOnFrameStart when it is valid
631 * 3. invoke fnScene
632 * 4. invoke fnOnFrameCPL when it is valid
633 * 5. Check bNextSceneReq
634 * - false (0), go back to step 2
635 * - true, invoke fnDepose when it is valid and switch to the next scene
636 *
637 */
638extern
639ARM_NONNULL(1)
640arm_fsm_rt_t arm_2d_scene_player_task(arm_2d_scene_player_t *ptThis);
641
642/*!
643 * \brief append dirty regions to the a specified scene
644 * \param[in] ptScene the target scene
645 * \param[in] ptItems the dirty regions
646 * \param[in] tCount the number of dirty regions
647 * \retval true operation is successful
648 * \retval false the operation is failed.
649 */
650extern
651ARM_NONNULL(1,2)
652bool arm_2d_scene_player_append_dirty_regions(arm_2d_scene_t *ptScene,
653 arm_2d_region_list_item_t *ptItems,
654 size_t tCount);
655
656/*!
657 * \brief remove dirty regions from the a specified scene
658 * \param[in] ptScene the target scene
659 * \param[in] ptItems the dirty regions
660 * \param[in] tCount the number of dirty regions
661 * \retval true operation is successful
662 * \retval false the operation is failed.
663 */
664extern
665ARM_NONNULL(1,2)
666bool arm_2d_scene_player_remove_dirty_regions(arm_2d_scene_t *ptScene,
667 arm_2d_region_list_item_t *ptItems,
668 size_t tCount);
669
670/*!
671 * \brief get the current scene of a given scene player
672 * \param[in] ptThis the target scene player
673 * \return arm_2d_scene_t * the current scene
674 */
675extern
676ARM_NONNULL(1)
677arm_2d_scene_t *
678arm_2d_scene_player_get_the_current_scene(arm_2d_scene_player_t *ptThis);
679
680
681/*-----------------------------------------------------------------------------*
682 * Dynamic Dirty Region Helper Service *
683 *-----------------------------------------------------------------------------*/
684
685/*!
686 * \brief initialize a user dynamic dirty region
687 *
688 * \param[in] ptThis the target region list item. If it is NULL, this function will
689 * allocate an object from the heap
690 * \param[in] ptScene the target scene.
691 * \return arm_2d_region_list_item_t* the target region list item
692 */
693extern
694arm_2d_region_list_item_t *arm_2d_scene_player_dynamic_dirty_region_init(
695 arm_2d_region_list_item_t *ptThis,
696 arm_2d_scene_t *ptScene);
697
698/*!
699 * \brief depose a given user dynamic dirty region
700 *
701 * \param[in] ptThis the target region list item.
702 * \param[in] ptScene the target scene.
703 */
704extern
705ARM_NONNULL(1)
706void arm_2d_scene_player_dynamic_dirty_region_depose(
707 arm_2d_region_list_item_t *ptThis,
708 arm_2d_scene_t *ptScene);
709
710/*! @} */
711
712#if defined(__clang__)
713# pragma clang diagnostic pop
714#endif
715
716#ifdef __cplusplus
717}
718#endif
719
720#endif