APL-CORE: October 2022 Release of APL 2022.2 compilant core engine (2022.2.0)

For more details on this release refer to CHANGELOG.md

To learn about APL see: https://developer.amazon.com/docs/alexa-presentation-language/understand-apl.html

Author: achsaini

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2022.2]
+
+This release adds support for version 2022.2 of the APL specification.
+
+### Added
+
+- Support selective preservation of sequencers and associated state upon re-inflation.
+- Allow easy synchronization of visual and audio with onSpeechMark handler.
+- Alpha feature: Scene graph rendering to provide simplified drawing instructions to the view host.
+
+### Changed
+
+- Bug fixes.
+- Videos can be muted/unmuted by setting the corresponding property.
+
 ## [2022.1.1]
 
 ### Changed

CMakeLists.txt

@@ -16,14 +16,13 @@
 include(FetchContent OPTIONAL RESULT_VARIABLE HAS_FETCH_CONTENT)
 
 cmake_minimum_required(VERSION 3.5)
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 project(APLCoreEngine
         VERSION 1.0.0
         LANGUAGES CXX)
 
-set(CMAKE_CXX_STANDARD 11)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-
 if (NOT APL_CORE_DIR)
     set(APL_CORE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
 endif()

apl-dev-env.sh

@@ -109,6 +109,14 @@ function apl-build-core {  # Run make for the core build
     )
 }
 
+function apl-install-core {  # Run make install
+    (
+        apl-switch-to-build-directory build $@ && \
+        $CMAKE -DBUILD_TESTS=ON -DCOVERAGE=OFF .. && \
+        make install -j$APL_BUILD_PROCS
+    )
+}
+
 function apl-check-core {  # Run make for the core build with -Werror
     (
         apl-switch-to-build-directory build $@ && \

aplcore/CMakeLists.txt

@@ -53,15 +53,18 @@ if (TARGET yoga)
     add_dependencies(apl yoga)
 endif()
 
-add_dependencies(apl pegtl-build)
+if (NOT HAS_FETCH_CONTENT)
+    add_dependencies(apl pegtl-build)
+endif()
 
 # When not using the system rapidjson build the library, add a dependency on the build step
-if (NOT USE_SYSTEM_RAPIDJSON)
+if (NOT USE_SYSTEM_RAPIDJSON AND NOT HAS_FETCH_CONTENT)
     add_dependencies(apl rapidjson-build)
 endif()
 
 add_subdirectory(src/action)
 add_subdirectory(src/animation)
+add_subdirectory(src/audio)
 add_subdirectory(src/command)
 add_subdirectory(src/component)
 add_subdirectory(src/content)
@@ -76,6 +79,9 @@ add_subdirectory(src/livedata)
 add_subdirectory(src/media)
 add_subdirectory(src/primitives)
 add_subdirectory(src/scaling)
+if(ENABLE_SCENEGRAPH)
+    add_subdirectory(src/scenegraph)
+endif(ENABLE_SCENEGRAPH)
 add_subdirectory(src/time)
 add_subdirectory(src/touch)
 add_subdirectory(src/utils)
@@ -99,7 +105,9 @@ if (ENABLE_PIC)
   )
 endif()
 
+# Generate a pkg-config file
 configure_file(apl.pc.in apl.pc @ONLY)
+
 target_include_directories(apl
     PUBLIC
         $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}/include>
@@ -157,6 +165,10 @@ install(DIRECTORY ${PROJECT_SOURCE_DIR}/aplcore/include/apl
         DESTINATION include
         FILES_MATCHING PATTERN "*.h")
 
+# Put the generated pkg-config file in the right directory?
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/apl.pc
+        DESTINATION lib/pkgconfig)
+
 if (NOT USE_SYSTEM_RAPIDJSON)
 install(DIRECTORY ${RAPIDJSON_INCLUDE}/rapidjson
         DESTINATION include

aplcore/apl.pc.in

@@ -8,5 +8,5 @@ Description: @PROJECT_DESCRIPTION@
 Version: @PROJECT_VERSION@
 
 Requires:
-Libs: -L${libdir} -lapl
+Libs: -L${libdir} -lapl @YOGA_PC_LIBS@
 Cflags: -I${includedir}

aplcore/include/apl/action/action.h

@@ -192,6 +192,19 @@ class Action : public std::enable_shared_from_this<Action>,
 
     friend streamer& operator<<(streamer&, Action&);
 
+    /**
+     * Freeze action state and memoize any of state required to "revive" this action in the different
+     * context.
+     */
+    virtual void freeze();
+
+    /**
+     * Revive an action in the new context.
+     * @param context new RootContext.
+     * @return true if successful, false otherwise.
+     */
+    virtual bool rehydrate(const RootContext& context);
+
 protected:
     virtual void onFinish() {}
 

aplcore/include/apl/action/animatedscrollaction.h

@@ -17,6 +17,7 @@
 #define _APL_ANIMATED_SCROLL_ACTION_H
 
 #include "apl/action/resourceholdingaction.h"
+#include "apl/primitives/object.h"
 
 namespace apl {
 
@@ -27,6 +28,10 @@ class AnimatedScrollAction : public ResourceHoldingAction {
 public:
     CoreComponentPtr getScrollableContainer() const { return mContainer; }
 
+
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
+
 protected:
     AnimatedScrollAction(const TimersPtr& timers,
                          const ContextPtr& context,
@@ -43,6 +48,7 @@ class AnimatedScrollAction : public ResourceHoldingAction {
     std::shared_ptr<AutoScroller> mScroller;
     ActionPtr mCurrentAction;
     apl_duration_t mDuration;
+    std::string mFrozenContainerId;
 };
 
 

aplcore/include/apl/action/animateitemaction.h

@@ -37,10 +37,14 @@ class AnimateItemAction : public ResourceHoldingAction {
                       const std::shared_ptr<CoreCommand>& command,
                       bool fastMode);
 
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
+
 private:
     void start();
     void advance();
     void finalize();
+    void extractAnimators();
 
 private:
     std::shared_ptr<CoreCommand> mCommand;

aplcore/include/apl/action/autopageaction.h

@@ -26,12 +26,6 @@ class Component;
 
 /**
  * Scroll or page to bring a target component into view.
- *
- * This action results in either a kEventScrollTo or kEventPageTo event being fired.
- * The following properties are passed with the event:
- *
- *    kCommandPropertyDirection        Set to forward/back (only for PageTo)
- *    kCommandPropertyPosition         The scroll position or the page number.
  */
 class AutoPageAction : public ResourceHoldingAction {
 public:
@@ -45,13 +39,17 @@ class AutoPageAction : public ResourceHoldingAction {
                    int end,
                    apl_time_t duration);
 
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
+
 private:
     void advance();
 
 private:
     std::shared_ptr<CoreCommand> mCommand;
     ComponentPtr mContainer;
     ActionPtr mCurrentAction;
+    size_t mCurrentIndex;
     size_t mNextIndex;
     size_t mEndIndex;
     apl_time_t mDuration;

aplcore/include/apl/action/delayaction.h

@@ -35,6 +35,9 @@ class DelayAction : public Action {
      */
     DelayAction(const TimersPtr& timers, const CommandPtr& command, bool fastMode);
 
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
+
 private:
     /**
      * This method must be called to start the action running.

aplcore/include/apl/action/playmediaaction.h

@@ -17,6 +17,7 @@
 #define _APL_PLAY_MEDIA_ACTION_H
 
 #include "apl/action/resourceholdingaction.h"
+#include "apl/primitives/object.h"
 
 namespace apl {
 
@@ -38,12 +39,18 @@ class PlayMediaAction : public ResourceHoldingAction {
                     const std::shared_ptr<CoreCommand>& command,
                     const ComponentPtr& target);
 
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
+
 private:
     void start();
 
 private:
     std::shared_ptr<CoreCommand> mCommand;
     ComponentPtr mTarget;
+    MediaPlayerPtr mPlayer;
+    Object mSource;
+    Object mPlayingState;
 };
 
 } // namespace apl

aplcore/include/apl/action/resourceholdingaction.h

@@ -28,6 +28,9 @@ class ResourceHoldingAction : public Action {
     ResourceHoldingAction(const TimersPtr& timers,
                           const ContextPtr& context);
 
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
+
 protected:
     void onFinish() override;
 

aplcore/include/apl/action/scrollaction.h

@@ -26,11 +26,6 @@ class AnimatedProperty;
 
 /**
  * Scroll to position in scrollable component.
- *
- * This action results in a kEventTypeScrollTo event being fired.
- * The following properties are passed with the event:
- *
- *    kEventPropertyPosition  The scroll position.
  */
 class ScrollAction : public AnimatedScrollAction {
 public:
@@ -54,14 +49,17 @@ class ScrollAction : public AnimatedScrollAction {
                                               const ContextPtr& context,
                                               const CoreComponentPtr& target,
                                               const Object& targetDistance,
-                                              apl_duration_t duration = 0);
+                                              apl_duration_t duration = -1);
 
     ScrollAction(const TimersPtr& timers,
                  const ContextPtr& context,
                  const CoreComponentPtr& target,
                  const Object& targetDistance,
                  apl_duration_t duration);
 
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
+
 private:
     void start();
 

aplcore/include/apl/action/scrolltoaction.h

@@ -26,12 +26,6 @@ class Component;
 
 /**
  * Scroll or page to bring a target component into view.
- *
- * This action results in either a kEventScrollTo or kEventPageTo event being fired.
- * The following properties are passed with the event:
- *
- *    kCommandPropertyDirection        Set to forward/back (only for PageTo)
- *    kCommandPropertyPosition         The scroll position or the page number.
  */
 class ScrollToAction : public AnimatedScrollAction {
 public:
@@ -62,7 +56,7 @@ class ScrollToAction : public AnimatedScrollAction {
     /**
      * Called from rootcontext by viewhost during line karaoke.
      * @param timers Timer reference.
-     * @param align Scroll slignment.
+     * @param align Scroll alignment.
      * @param subBounds Bounds within the target to scroll to.
      * @param context Target context.
      * @param target Component to scroll to.
@@ -74,6 +68,25 @@ class ScrollToAction : public AnimatedScrollAction {
                                                 const ContextPtr& context,
                                                 const CoreComponentPtr& target = nullptr);
 
+    /**
+     * @param timers Timer reference.
+     * @param align Scroll alignment.
+     * @param subBounds Bounds within the target to scroll to.
+     * @param context Target context.
+     * @param scrollToSubBounds Scroll to sub-bounds.
+     * @param target Component to scroll to.
+     * @param duration Scrolling duration.
+     * @return The scroll to action or null if it is not needed.
+     */
+    static std::shared_ptr<ScrollToAction> make(const TimersPtr& timers,
+                                                const CommandScrollAlign& align,
+                                                const Rect& subBounds,
+                                                const ContextPtr& context,
+                                                bool scrollToSubBounds,
+                                                const CoreComponentPtr& target = nullptr,
+                                                apl_duration_t duration = -1,
+                                                bool useSnap = false);
+
     /**
      * Called in order to bring child into view, utilizing snap setting if exists.
      * @param timers Timer reference.
@@ -94,16 +107,10 @@ class ScrollToAction : public AnimatedScrollAction {
                    const CoreComponentPtr& scrollableParent,
                    apl_duration_t duration);
 
-private:
-    static std::shared_ptr<ScrollToAction> make(const TimersPtr& timers,
-                                                const CommandScrollAlign& align,
-                                                const Rect& subBounds,
-                                                const ContextPtr& context,
-                                                bool scrollToSubBounds,
-                                                const CoreComponentPtr& target = nullptr,
-                                                apl_duration_t duration = 0,
-                                                bool useSnap = false);
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
 
+private:
     void start();
     void pageTo();
     void scrollTo();
@@ -113,6 +120,10 @@ class ScrollToAction : public AnimatedScrollAction {
     Rect mSubBounds;
     bool mScrollToSubBounds;
     CoreComponentPtr mTarget;
+
+    std::string mFrozenContainerId;
+    std::string mFrozenTargetId;
+    size_t mFrozenTargetIndex = -1;
 };
 
 

aplcore/include/apl/action/sequentialaction.h

@@ -24,20 +24,22 @@ namespace apl {
 class SequentialAction : public Action {
 public:
     static std::shared_ptr<SequentialAction> make(const TimersPtr& timers,
-                                                  std::shared_ptr<const CoreCommand> command, bool fastMode) {
-        auto ptr = std::make_shared<SequentialAction>(timers, command, fastMode);
-        ptr->advance();
-        return ptr;
-    }
+                                                  std::shared_ptr<CoreCommand>& command,
+                                                  bool fastMode);
 
-    SequentialAction(const TimersPtr& timers, std::shared_ptr<const CoreCommand> command, bool fastMode);
+    SequentialAction(const TimersPtr& timers,
+                     std::shared_ptr<CoreCommand>& command,
+                     bool fastMode);
+
+    void freeze() override;
+    bool rehydrate(const RootContext& context) override;
 
 private:
     void advance();
     bool doCommand(const Object& command);
 
 private:
-    std::shared_ptr<const CoreCommand> mCommand;
+    std::shared_ptr<CoreCommand> mCommand;
     bool mFastMode;
     bool mStateFinally;