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