Handling screen orientation change for all platforms (#2762)

* Handling orientation change

* Gives the user a chance to re-layout scene content or reset designResolutionSize if needed

* Handling ios screen orientation change

* No longer need invoke applicationScreenSizeChanged in project template

* Committing clang-format changes

* Update copyright notice

* Committing clang-format changes

---------

Co-authored-by: axmol-bot <[email protected]>

Author: halx99

axmol/platform/Application.h

@@ -2,6 +2,7 @@
 Copyright (c) 2010-2012 cocos2d-x.org
 Copyright (c) 2013-2016 Chukong Technologies Inc.
 Copyright (c) 2017-2018 Xiamen Yaji Software Co., Ltd.
+Copyright (c) 2019-present Axmol Engine contributors (see AUTHORS.md).
 
 https://axmol.dev/
 

axmol/platform/ApplicationBase.cpp

@@ -36,4 +36,6 @@ ApplicationBase::~ApplicationBase()
     Director::destroyInstance();
 }
 
+void ApplicationBase::applicationScreenSizeChanged(int newWidth, int newHeight) {}
+
 }  // namespace ax

axmol/platform/ApplicationBase.h

@@ -39,8 +39,11 @@ namespace ax
  * @{
  */
 
+class RenderView;
 class AX_DLL ApplicationBase
 {
+    friend class RenderView;
+
 public:
     /** Since WINDOWS and ANDROID are defined as macros, we could not just use these keywords in enumeration(Platform).
      *  Therefore, we use C# code style to define Platform enums to avoid conflicts with the definitions of system
@@ -138,6 +141,20 @@ class AX_DLL ApplicationBase
      * @lua NA
      */
     virtual bool openURL(std::string_view url) = 0;
+
+protected:
+    /**
+     * @brief Called when the application screen size changes.
+     *
+     * Users can override this method to listen for screen size changes,
+     * including device rotation events. It is recommended to update the
+     * designResolutionSize and adjust the layout of objects in the scene
+     * accordingly when this callback is triggered.
+     *
+     * @param newWidth  The new width of the application screen in pixels.
+     * @param newHeight The new height of the application screen in pixels.
+     */
+    virtual void applicationScreenSizeChanged(int newWidth, int newHeight);
 };
 
 using ApplicationProtocol = ApplicationBase;

axmol/platform/RenderView.cpp

@@ -175,28 +175,65 @@ void RenderView::setDesignResolutionSize(float width, float height, ResolutionPo
     _designResolutionSize.set(width, height);
     _resolutionPolicy = resolutionPolicy;
 
-    updateDesignResolution();
+    if (!_isResolutionUpdateLocked)
+        updateDesignResolution();
 }
 
 const Vec2& RenderView::getDesignResolutionSize() const
 {
     return _designResolutionSize;
 }
 
-void RenderView::setRenderSize(float width, float height)
+void RenderView::updateRenderSurface(float width, float height, uint8_t updateFlag)
 {
-    _renderSize.set(width, height);
+    if (width == 0 || height == 0)
+        return;
+
+    Vec2 value{width, height};
+
+    if (updateFlag & SurfaceUpdateFlag::WindowSizeChanged)
+        _windowSize = value;
+
+    if (updateFlag & SurfaceUpdateFlag::RenderSizeChanged)
+    {
+        _isResolutionUpdateLocked = true;
+
+        _renderSize = value;
 
-    if (_windowSize.equals(Vec2::ZERO))
-        _windowSize = _renderSize;
+        // If designResolutionSize hasn't been set, default to renderSize
+        if (_designResolutionSize.equals(Vec2::ZERO))
+            _designResolutionSize = value;
 
-    // Github issue #16003 and #16485
-    // only update the designResolution if it wasn't previously set
-    if (_designResolutionSize.equals(Vec2::ZERO))
-        _designResolutionSize = _renderSize;
+        // Notify the application that the screen size has changed.
+        // This gives the user a chance to re-layout scene content or reset designResolutionSize if needed.
+        ax::Application::getInstance()->applicationScreenSizeChanged(width, height);
 
-    if (!_renderSize.equals(Vec2::ZERO))
+        // then we update resolution and viewport
         updateDesignResolution();
+
+        _isResolutionUpdateLocked = false;
+    }
+
+    // check does all updateed
+    maybeDispatchResizeEvent(updateFlag);
+}
+
+void RenderView::maybeDispatchResizeEvent(uint8_t updateFlag)
+{
+    const bool silentUpdate = (updateFlag & SurfaceUpdateFlag::SilentUpdate) != 0;
+    updateFlag &= ~SurfaceUpdateFlag::SilentUpdate;  // Remove temporary flag
+
+    _surfaceUpdateFlags |= updateFlag;
+
+    constexpr uint8_t requiredFlags = SurfaceUpdateFlag::WindowSizeChanged | SurfaceUpdateFlag::RenderSizeChanged;
+
+    const bool readyToDispatch = (_surfaceUpdateFlags == requiredFlags);
+
+    if (readyToDispatch && !silentUpdate)
+    {
+        _surfaceUpdateFlags = 0;
+        onSurfaceResized();
+    }
 }
 
 Rect RenderView::getVisibleRect() const
@@ -483,12 +520,13 @@ float RenderView::getScaleY() const
     return _viewScale.y;
 }
 
-void RenderView::onRenderResized()
+void RenderView::onSurfaceResized()
 {
-    AXLOGD("RenderView::onRenderResized");
+    AXLOGD("RenderView::onSurfaceResized");
 
-    Director::getInstance()->resizeSwapchain(static_cast<uint32_t>(_renderSize.width),
-                                             static_cast<uint32_t>(_renderSize.height));
+    int screenWidth  = static_cast<uint32_t>(_renderSize.width);
+    int screenHeight = static_cast<uint32_t>(_renderSize.height);
+    Director::getInstance()->resizeSwapchain(screenWidth, screenHeight);
 
 #ifdef AX_ENABLE_VR
     if (_vrRenderer) [[unlikely]]

axmol/platform/RenderView.h

@@ -112,6 +112,16 @@ class AX_DLL RenderView : public Object
     friend class Director;
 
 public:
+    enum SurfaceUpdateFlag : uint8_t
+    {
+        WindowSizeChanged = 1,       // Indicates that window size has changed
+        RenderSizeChanged = 1 << 1,  // Indicates that render surface size has changed
+        SilentUpdate      = 1 << 2,  // Temporary flag: suppresses event dispatch for this update only.
+                                     // Should be stripped before accumulating into persistent state.
+        AllUpdates         = WindowSizeChanged | RenderSizeChanged,
+        AllUpdatesSilently = AllUpdates | SilentUpdate
+    };
+
     /**
      */
     RenderView();
@@ -254,7 +264,8 @@ class AX_DLL RenderView : public Object
      * ratio, two areas of your game view will be cut. [3] SHOW_ALL  Full screen with black border: if the design
      * resolution ratio of width to height is different from the screen resolution ratio, two black borders will be
      * shown.
-     * @remark You shoud only set once
+     * @remark For applications with a static design resolution, this method should typically be called only once during
+     * initialization.
      */
     virtual void setDesignResolutionSize(float width, float height, ResolutionPolicy resolutionPolicy);
 
@@ -456,29 +467,39 @@ class AX_DLL RenderView : public Object
     const std::unique_ptr<IVRRenderer>& getVR() const { return _vrRenderer; }
 #endif
 
-protected:
-    float transformInputX(float x) { return (x - _viewportRect.origin.x) / _viewScale.x; }
-    float transformInputY(float y) { return (y - _viewportRect.origin.y) / _viewScale.y; }
-
     /**
-     * @brief Sets the render size (framebuffer/render target size) and updates the viewport and scaling.
+     * @brief Updates the render surface size (framebuffer/render target) and synchronizes related view parameters.
+     *
+     * This method performs the following actions:
+     * - Sets `_renderSize` to the specified dimensions;
+     * - On mobile platforms (Android/iOS), `_windowSize` is synchronized to match `_renderSize`;
+     * - On desktop platforms, `_windowSize` is only initialized to `_renderSize` if it hasn't been set yet;
+     * - If `_designResolutionSize` is unset (`Vec2::ZERO`), it is initialized to `_renderSize`;
+     * - Calls `updateDesignResolution()` to recalculate `_viewScale` and `_viewportRect` based on the current
+     *   `ResolutionPolicy`, and updates the Director's logical size and projection matrix accordingly.
+     *
+     * @param width      The target width of the render surface. Its meaning depends on `updateFlag`:
+     *                   it may represent the framebuffer width, logical window width, or design resolution width.
+     * @param height     The target height of the render surface. Its meaning depends on `updateFlag`:
+     *                   it may represent the framebuffer height, logical window height, or design resolution height.
+     * @param updateFlag Optional flags to control which parts of the view should be updated.
+     *                   Defaults to `SurfaceUpdateFlag::AllUpdates`.
      *
-     * This method will:
-     * - Overwrite `_renderSize` with the given dimensions;
-     * - If `_windowSize` has not been initialized (equals `Vec2::ZERO`), initialize it to `_renderSize`;
-     * - If `_designResolutionSize` has not been initialized (equals `Vec2::ZERO`), initialize it to `_renderSize`;
-     * - Call `updateDesignResolution()` to compute `_viewScale` and `_viewportRect` based on the current
-     *   `ResolutionPolicy`, and synchronize the Director's logical size and projection.
+     * @warning This method may initialize `_windowSize` and `_designResolutionSize` on first invocation.
+     * @note No update will occur if the given size is (0, 0).
      *
-     * @param width  The width of the render size.
-     * @param height The height of the render size.
+     * @internal This method is intended for internal use by platform-specific window or surface managers.
+     *           It should be called when the native surface size changes (e.g., orientation change, resize event).
      *
-     * @warning This method has side effects: on the first call, it may initialize `_windowSize`
-     *          and `_designResolutionSize`.
-     * @note If the given size is (0,0), no update will be performed.
      * @see updateDesignResolution(), setDesignResolutionSize()
      */
-    void setRenderSize(float width, float height);
+    void updateRenderSurface(float width, float height, uint8_t updateFlag);
+
+protected:
+    float transformInputX(float x) { return (x - _viewportRect.origin.x) / _viewScale.x; }
+    float transformInputY(float y) { return (y - _viewportRect.origin.y) / _viewScale.y; }
+
+    void maybeDispatchResizeEvent(uint8_t updateFlag);
 
     /**
      * @brief Callback invoked after the RenderView size has changed and all related updates are complete.
@@ -488,7 +509,7 @@ class AX_DLL RenderView : public Object
      * It serves as a notification hook for any components that need to respond
      * to the final, settled render size.
      */
-    void onRenderResized();
+    void onSurfaceResized();
 
     void setScissorRect(float x, float y, float w, float h);
     const ScissorRect& getScissorRect() const;
@@ -516,6 +537,13 @@ class AX_DLL RenderView : public Object
     Vec2 _viewScale;
     ResolutionPolicy _resolutionPolicy;
 
+    // Flags indicating whether the window or framebuffer size was updated.
+    // On desktop platforms, callback order is: framebufferSize => windowSize.
+    // On WebAssembly, the order is reversed: windowSize => framebufferSize.
+    uint8_t _surfaceUpdateFlags{0};
+
+    bool _isResolutionUpdateLocked{false};
+
 #ifdef AX_ENABLE_VR
     std::unique_ptr<IVRRenderer> _vrRenderer{nullptr};
 #endif

axmol/platform/SAXParser.h

@@ -2,6 +2,9 @@
  Copyright (c) 2010 cocos2d-x.org
  Copyright (c) 2010 Максим Аксенов
  Copyright (c) 2017-2018 Xiamen Yaji Software Co., Ltd.
+ Copyright (c) 2019-present Axmol Engine contributors (see AUTHORS.md).
+
+ https://axmol.dev/
 
  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal

axmol/platform/android/Application-android.cpp

@@ -2,6 +2,7 @@
 Copyright (c) 2010-2012 cocos2d-x.org
 Copyright (c) 2013-2016 Chukong Technologies Inc.
 Copyright (c) 2017-2018 Xiamen Yaji Software Co., Ltd.
+Copyright (c) 2019-present Axmol Engine contributors (see AUTHORS.md).
 
 https://axmol.dev/
 
@@ -110,8 +111,6 @@ bool Application::openURL(std::string_view url)
     return JniHelper::callStaticBooleanMethod(applicationHelperClassName, "openURL", url);
 }
 
-void Application::applicationScreenSizeChanged(int newWidth, int newHeight) {}
-
 }  // namespace ax
 
 #undef LOGD

axmol/platform/android/Application-android.h

@@ -89,13 +89,6 @@ class AX_DLL Application : public ApplicationBase
      */
     bool openURL(std::string_view url) override;
 
-    /**
-    @brief  This function will be called when the application screen size is changed.
-    @param new width
-    @param new height
-    */
-    virtual void applicationScreenSizeChanged(int newWidth, int newHeight);
-
 protected:
     static Application* sm_pSharedApplication;
 };

axmol/platform/android/RenderViewImpl-android.cpp

@@ -95,7 +95,7 @@ bool RenderViewImpl::initWithRect(std::string_view /*viewName*/,
                                   float /*frameZoomFactor*/,
                                   bool /*resizable*/)
 {
-    setRenderSize(rect.size.width, rect.size.height);
+    updateRenderSurface(rect.size.width, rect.size.height, SurfaceUpdateFlag::AllUpdatesSilently);
     return true;
 }
 

axmol/platform/android/javaactivity-android.cpp

@@ -147,7 +147,9 @@ JNIEXPORT jintArray JNICALL Java_dev_axmol_lib_AxmolActivity_getGLContextAttrs(J
 
 JNIEXPORT void JNICALL Java_dev_axmol_lib_AxmolRenderer_nativeOnSurfaceChanged(JNIEnv*, jclass, jint w, jint h)
 {
-    ax::Application::getInstance()->applicationScreenSizeChanged(w, h);
+    auto renderView = ax::Director::getInstance()->getRenderView();
+    if (renderView)
+        renderView->updateRenderSurface(w, h, ax::RenderView::AllUpdates);
 }
 }
 #undef LOGD