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