From 79dae80818670812d2c306c2acaa03b4b1247edf Mon Sep 17 00:00:00 2001 From: Hannes Winkler Date: Thu, 12 Dec 2024 08:55:50 +0100 Subject: [PATCH 1/4] embedder: Improve documentation for backing store lifecycle --- shell/platform/embedder/embedder.h | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/shell/platform/embedder/embedder.h b/shell/platform/embedder/embedder.h index 4b880a6855d93..75026c8f6e3c1 100644 --- a/shell/platform/embedder/embedder.h +++ b/shell/platform/embedder/embedder.h @@ -2011,6 +2011,14 @@ typedef struct { /// The callback should return true if the operation was successful. FlutterLayersPresentCallback present_layers_callback; /// Avoid caching backing stores provided by this compositor. + /// + /// The engine has an internal backing store cache. Instead of + /// creating & destroying backing stores for every frame, created + /// backing stores are automatically reused for subsequent frames. + /// + /// If you wish to change this behavior and destroy backing stores after + /// they've been used once, and create new backing stores for every frame, + /// you can set this bool to true. bool avoid_backing_store_cache; /// Callback invoked by the engine to composite the contents of each layer /// onto the specified view. From 12e6b482a7256d52f6c087f8369597451db48033 Mon Sep 17 00:00:00 2001 From: Hannes Winkler Date: Thu, 12 Dec 2024 09:12:06 +0100 Subject: [PATCH 2/4] embedder: list wayland equivalents for software pixel formats --- shell/platform/embedder/embedder.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/shell/platform/embedder/embedder.h b/shell/platform/embedder/embedder.h index 75026c8f6e3c1..e18bc0600ddc7 100644 --- a/shell/platform/embedder/embedder.h +++ b/shell/platform/embedder/embedder.h @@ -352,12 +352,16 @@ typedef enum { /// r = (p >> 11) & 0x1F; /// g = (p >> 5) & 0x3F; /// b = p & 0x1F; + /// + /// This is equivalent to wayland format RGB565 (WL_DRM_FORMAT_RGB565). kFlutterSoftwarePixelFormatRGB565, /// Pixel with 4 bits each for alpha, red, green, blue; in 16-bit word. /// r = (p >> 8) & 0xF; /// g = (p >> 4) & 0xF; /// b = p & 0xF; + /// + /// This is equivalent to wayland format RGBA4444 (WL_DRM_FORMAT_RGBA4444). /// a = (p >> 12) & 0xF; kFlutterSoftwarePixelFormatRGBA4444, @@ -366,12 +370,16 @@ typedef enum { /// g = p[1]; /// b = p[2]; /// a = p[3]; + /// + /// This is equivalent to wayland format ABGR8888 (WL_DRM_FORMAT_ABGR8888). kFlutterSoftwarePixelFormatRGBA8888, /// Pixel with 8 bits each for red, green and blue and 8 unused bits. /// r = p[0]; /// g = p[1]; /// b = p[2]; + /// + /// This is equivalent to wayland format XBGR8888 (WL_DRM_FORMAT_XBGR8888) kFlutterSoftwarePixelFormatRGBX8888, /// Pixel with 8 bits each for blue, green, red and alpha. @@ -379,6 +387,8 @@ typedef enum { /// g = p[1]; /// b = p[0]; /// a = p[3]; + /// + /// This is equivalent to wayland format ARGB8888 (WL_DRM_FORMAT_ARGB8888). kFlutterSoftwarePixelFormatBGRA8888, /// Either kFlutterSoftwarePixelFormatBGRA8888 or From 558ac2e8328d9bb21f0b8290b109f220d0a729d1 Mon Sep 17 00:00:00 2001 From: Hannes Winkler Date: Thu, 12 Dec 2024 09:12:54 +0100 Subject: [PATCH 3/4] embedder: fix cut-off documentation comment in `FlutterSoftwareBackingStore2` --- shell/platform/embedder/embedder.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/shell/platform/embedder/embedder.h b/shell/platform/embedder/embedder.h index e18bc0600ddc7..ceb611fd7a885 100644 --- a/shell/platform/embedder/embedder.h +++ b/shell/platform/embedder/embedder.h @@ -1751,7 +1751,8 @@ typedef struct { /// store. VoidCallback destruction_callback; /// The pixel format that the engine should use to render into the allocation. - /// In most cases, kR + /// + /// On Linux, kFlutterSoftwarePixelFormatBGRA8888 is most commonly used. FlutterSoftwarePixelFormat pixel_format; } FlutterSoftwareBackingStore2; From a3d659fce329843f7e26764566173f4d79fad987 Mon Sep 17 00:00:00 2001 From: Hannes Winkler Date: Thu, 12 Dec 2024 11:17:11 +0100 Subject: [PATCH 4/4] embedder: account for big-endian systems in pixel format docs --- shell/platform/embedder/embedder.h | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/shell/platform/embedder/embedder.h b/shell/platform/embedder/embedder.h index ceb611fd7a885..1d656e355baa3 100644 --- a/shell/platform/embedder/embedder.h +++ b/shell/platform/embedder/embedder.h @@ -353,16 +353,18 @@ typedef enum { /// g = (p >> 5) & 0x3F; /// b = p & 0x1F; /// - /// This is equivalent to wayland format RGB565 (WL_DRM_FORMAT_RGB565). + /// On most (== little-endian) systems, this is equivalent to wayland format + /// RGB565 (WL_DRM_FORMAT_RGB565, WL_SHM_FORMAT_RGB565). kFlutterSoftwarePixelFormatRGB565, /// Pixel with 4 bits each for alpha, red, green, blue; in 16-bit word. /// r = (p >> 8) & 0xF; /// g = (p >> 4) & 0xF; /// b = p & 0xF; - /// - /// This is equivalent to wayland format RGBA4444 (WL_DRM_FORMAT_RGBA4444). /// a = (p >> 12) & 0xF; + /// + /// On most (== little-endian) systems, this is equivalent to wayland format + /// RGBA4444 (WL_DRM_FORMAT_RGBA4444, WL_SHM_FORMAT_RGBA4444). kFlutterSoftwarePixelFormatRGBA4444, /// Pixel with 8 bits each for red, green, blue, alpha. @@ -371,7 +373,8 @@ typedef enum { /// b = p[2]; /// a = p[3]; /// - /// This is equivalent to wayland format ABGR8888 (WL_DRM_FORMAT_ABGR8888). + /// This is equivalent to wayland format ABGR8888 (WL_DRM_FORMAT_ABGR8888, + /// WL_SHM_FORMAT_ABGR8888). kFlutterSoftwarePixelFormatRGBA8888, /// Pixel with 8 bits each for red, green and blue and 8 unused bits. @@ -379,7 +382,8 @@ typedef enum { /// g = p[1]; /// b = p[2]; /// - /// This is equivalent to wayland format XBGR8888 (WL_DRM_FORMAT_XBGR8888) + /// This is equivalent to wayland format XBGR8888 (WL_DRM_FORMAT_XBGR8888, + /// WL_SHM_FORMAT_XBGR8888). kFlutterSoftwarePixelFormatRGBX8888, /// Pixel with 8 bits each for blue, green, red and alpha. @@ -388,7 +392,8 @@ typedef enum { /// b = p[0]; /// a = p[3]; /// - /// This is equivalent to wayland format ARGB8888 (WL_DRM_FORMAT_ARGB8888). + /// This is equivalent to wayland format ARGB8888 (WL_DRM_FORMAT_ARGB8888, + /// WL_SHM_FORMAT_ARGB8888). kFlutterSoftwarePixelFormatBGRA8888, /// Either kFlutterSoftwarePixelFormatBGRA8888 or @@ -2023,7 +2028,7 @@ typedef struct { FlutterLayersPresentCallback present_layers_callback; /// Avoid caching backing stores provided by this compositor. /// - /// The engine has an internal backing store cache. Instead of + /// The engine has an internal backing store cache. Instead of /// creating & destroying backing stores for every frame, created /// backing stores are automatically reused for subsequent frames. ///