0.3.0 release

CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 <br>
 
+# 0.3.0 → 2023-01-23
+
+Highlights
+----------
+
+- Performance improvement with new rules for widget update. Only widgets inside the window, or on the current screen (when using `ScreenManager`) will be updated, avoiding unnecessary computation of widgets that are not being viewed.
+- Improved integration with `ModalView`.
+- Significant performance improvement when using multiple moving `FrostedGlass` widgets (like inside a `ScrollView`).
+- Added support for auto-update when using videos as background.
+- Improved performance when animating the `blur_size` property.
+- Minor bug fixes.
+
+Docs
+----------
+- Added usage example with `ModalView`.
+- Updated overview video with new example using `ModalView`.
+
+Internal
+----------
+
+- Removed final effect widget from child widget tree. Now the effect is drawn directly on the canvas.
+- General refactoring.
+
+<br>
+
 # 0.2.0 → 2022-03-08
 
 Highlights

README.md

@@ -1,8 +1,12 @@
 # FrostedGlass
 
-**FrostedGlass** is a widget with translucent frosted glass effect, that creates a context with the background behind it.
+**FrostedGlass** is a widget with translucent frosted glass effect, that
+creates a context with the background behind it.
+
+The effect created is based on the widget/layout passed in as the background.
+You can control the blur size, saturation, luminosity, overlay color, noise
+opacity, border radius and the outline (color and width).
 
-The effect created is based on the widget passed in as the background. You can control the blur size, saturation, luminosity, overlay color, noise opacity, border radius and the outline (color and width).
 
 ![](https://github.com/kivy-garden/frostedglass/blob/main/doc/images/example_1.png?raw=true)
 ![](https://github.com/kivy-garden/frostedglass/blob/main/doc/images/example_2.gif?raw=true)
@@ -14,8 +18,15 @@ The effect created is based on the widget passed in as the background. You can c
     pip install kivy_garden.frostedglass
 
 ## Import
+
+**_python_ import:**
+
     from kivy_garden.frostedglass import FrostedGlass
 
+**or _kvlang_ import:**
+
+    #: import FrostedGlass kivy_garden.frostedglass
+
 ## Usage
 
 *FrostedGlass* will apply the effect to the background passed to it. Make sure you assign the correct id of the widget/layout that is behind *FrostedGlass* to the `background` property.
@@ -50,30 +61,55 @@ FrostedGlass:
         color: 'black'
         font_size: dp(25)
 ```
-### You can find more usage examples in the 🔷[examples folder](https://github.com/kivy-garden/frostedglass/tree/main/examples)🔷
 
----
+<br>
+
+## FrostedGlass Showcase:
+
+**You can find the source code in the 🔷[examples folder](https://github.com/kivy-garden/frostedglass/tree/main/examples)🔷**
+
+https://user-images.githubusercontent.com/73297572/214139558-f995ac2c-77bb-4952-a82b-212e2f31d65f.mp4
+
+<br>
 
 ## Overview of *FrostedGlass* creation process
 
-To reach the final result of the FrostedGlass widget, the steps described in the image below are followed:
+To reach the final result of the **FrostedGlass** widget, the steps described in the image below are followed:
 
 ![](https://github.com/kivy-garden/frostedglass/blob/main/doc/images/FrostedgGlass_overview.png?raw=true)
 
----
+<br>
+
+## Features
+
+FrostedGlass is efficient and makes internal optimizations to deliver the best performance while maintaining the quality of the effect, regardless of implementation, for all platforms supported by Kivy.
+
+Overview:
+
+- Automatic effect update, with auto bind to background properties.
+- Updates effect only when needed. The effect update will only occur when some background or FrostedGlass property requires the update.
+- Avoid unnecessary computation of the effect. If any FrostedGlass widget is not visible, it will not be updated.
+- Full control over FrostedGlass properties. The widget is not limited to the frosted glass effect, it can be used simply as an option to achieve gaussian blur of some "background".
+
+<br>
 
 ## Guidelines
-The FrostedGlass widget will attempt to update the effect whenever there is a change to its properties or background properties that require an effect update to keep the effect in sync. But if it doesn't, you can call the `update_effect()` method manually to update the effect.
 
-If calling the `update_effect()` method did not update the effect, you may need to call the `refresh_effect()` method. But beware, calling this effect continuously in a small interval of time can reduce the widget's performance.
+The FrostedGlass widget is designed to update the effect whenever there is a change to its properties or background properties that requires an effect update, to keep the effect in sync with the background. 
+
+But if it doesn't, you can call the `update_effect()` method manually to update the effect.
+
+If calling the `update_effect()` method did not update the effect, you may need to call the `refresh_effect()` method.
+
+<br>
 
 ---
 
 ## **API**
 
     background
 
-> Target widget/layout that will be used as a background to FrostedGlass.
+> Target widget/layout that will be used as a background to **FrostedGlass**.
 > The recomended way to pass the widget is through the widget/layout **id**.
 > 
 > `background` is defaults to `None`.
@@ -84,7 +120,7 @@ If calling the `update_effect()` method did not update the effect, you may need
 
 > Size of the gaussian blur aplied to the background.
 
-❗️*Note: Do not pass relative values such as **dp** or **sp**. FrostedGlass already
+❗️*Note: Do not pass relative values such as **dp** or **sp**. **FrostedGlass** already
     manages this automatically, according to the device's screen density.*
 
 > `blur_size` is defaults to `25`.
@@ -149,23 +185,19 @@ If calling the `update_effect()` method did not update the effect, you may need
 
 <br/>
 
-
-
     update_effect()
 
 > Updates the effect only once with each method call.
 
-❗️*Note: Use this method to update the effect only if it doesn't update automatically.*
+❗️*Note: Use this method to update the effect only if **FrostedGlass** doesn't update automatically.*
 
 <br/>
 
     refresh_effect()
 
 > Updates the effect only once with each method call. Sould be used as an alternative, when `update_effect()` doesn't update the effect totally.
 
-❗️*Note: Use this method to update the effect only if it doesn't update automatically and `update_effect()` doesn't update the effect.*
-
-❗️*Note: Unlike `update_effect()` method, `refresh_effect()` will refresh the FBO on each call, wich can lead to a performance drop if called continuously on a small interval of time.*
+❗️*Note: Use this method to update the effect only if **FrostedGlass** doesn't update automatically and `update_effect()` was not enough to update the effect.*
 
 ---
 

examples/README.MD

@@ -1,17 +1,20 @@
 # Guide:
 
-When you run the `main.py` file you will see three common types of FrostedGlass implementations: static, static with a moving background, and moving with a static background.
-In terms of performance, there is no significant difference between the first and second implementations (which have high performance). However, the third implementation may have a slight drop in FPS on some devices, as it needs to update the FBO every time the *FrostedGlass* is moved. *What can be targeted for improvement by contributors!*
+When you run the `main.py` file you will see four common types of `FrostedGlass` implementations:
+- STATIC → static `FrostedGlass` and static `background`
+- MOVING BACKGROUND → static `FrostedGlass` and moving `background`
+- MOVING FrostedGlass → `FrostedGlass` moving with a static `background`
+- INSIDE MODALVIEW → `FrostedGlass` inside `ModalView`.
 
-The main intention is to give a basic idea of how to combine FrostedGlass with the rest of the UI. These are just some of the many possible combinations you can make. *The creativity is yours!*
+The main intention is to give a basic idea of how to combine `FrostedGlass` with the rest of the UI. These are just some of the many possible combinations you can make. *The creativity is yours!*
 
-An FPS meter (`fps_monitor.py`) will also be imported and used to display the current performance of the UI. But attention, its use is indicated only for development purposes and contribution to the FrostedGlass project widget. For final product uses, perform conventional import and use as described on the project homepage: [*Import and Usage*](https://github.com/kivy-garden/frostedglass/blob/main/README.md#import)
+An FPS meter (`fps_monitor.py`) will also be imported and used to display the current FPS of the UI. But attention, its use is indicated only for development purposes and contribution to the `FrostedGlass` project widget. For final product uses, perform conventional import and use as described on the project homepage: [*Import and Usage*](https://github.com/kivy-garden/frostedglass/blob/main/README.md#import)
 
 ### For contributors:
 
-The contents of this folder are ready to be used on any operating system supported by Kivy. The FPS indicator will be imported and used automatically as mentioned above and will help you to track the performance of the UI while improving the performance, quality and usability of the FrostedGlass widget. The contents of this folder will help you improve FrostedGlass, but you don't have to limit yourself to it, of course!
+The contents of this folder are ready to be used on any platforms supported by Kivy. The FPS indicator will be imported and used automatically as mentioned above and will help you to track the performance of the UI while improving the quality, usability and performance of the `FrostedGlass` widget. The contents of this folder will help you improve `FrostedGlass`, but you don't have to limit yourself to it, of course!
 
 
 # Examples overview:
 
-https://user-images.githubusercontent.com/73297572/157085704-6fa4c48b-ba9a-4fb3-9ef1-a59088a89622.mp4
+https://user-images.githubusercontent.com/73297572/214140662-8703ef05-ff28-4712-a081-519624e3b5ba.mp4

examples/fps_monitor.py

@@ -1,4 +1,4 @@
-'''
+"""
 Monitor module
 ==============
 The Monitor module is a toolbar that shows the activity of your current
@@ -8,9 +8,9 @@
 Usage
 -----
 For normal module usage, please see the :mod:`~kivy.modules` documentation.
-'''
+"""
 
-__all__ = ('start', 'stop')
+__all__ = ("start", "stop")
 
 from kivy.uix.label import Label
 from kivy.graphics import Rectangle, Color
@@ -22,7 +22,7 @@
 
 
 def update_fps(ctx, *largs):
-    ctx.label.text = 'FPS: %f' % Clock.get_fps()
+    ctx.label.text = "FPS: %f" % Clock.get_fps()
     ctx.rectangle.texture = ctx.label.texture
     ctx.rectangle.size = ctx.label.texture_size
 
@@ -31,7 +31,7 @@ def update_stats(win, ctx, *largs):
     global _statsinput
     ctx.stats = ctx.stats[1:] + [_statsinput]
     _statsinput = 0
-    m = max(1., _maxinput)
+    m = max(1.0, _maxinput)
     for i, x in enumerate(ctx.stats):
         ctx.statsr[i].size = (4, ctx.stats[i] / m * 20)
         ctx.statsr[i].pos = (win.width - 64 * 4 + i * 4, 0)
@@ -56,29 +56,29 @@ def process(self, events):
 def start(win, ctx):
     # late import to avoid breaking module loading
     from kivy.input.postproc import kivy_postproc_modules
-    kivy_postproc_modules['fps'] = StatsInput()
+
+    kivy_postproc_modules["fps"] = StatsInput()
     global _ctx
-    ctx.label = Label(text='FPS: 0.0', font_size=40)
+    ctx.label = Label(text="FPS: 0.0", font_size=35, color=(1, 1, 1, 1))
+    ctx.label.texture_update()
     ctx.inputstats = 0
     ctx.stats = []
     ctx.statsr = []
     with win.canvas.after:
-        # ctx.color = Color(1, 0, 0, .5)
-        ctx.color = Color(0, 0, 0, .0)
-        ctx.overlay = Rectangle(pos=(0, 0),
-                                size=(win.width, 25))
-        # ctx.color = Color(1, 1, 1)
+        ctx.color = Color(0, 0, 1, 1.0)
+        ctx.overlay = Rectangle(pos=(0, 0), size=(win.width, 40))
+
         ctx.color = Color(0, 0, 0)
         ctx.rectangle = Rectangle(pos=(5, 0))
-        ctx.color = Color(1, 1, 1, .5)
+        ctx.color = Color(1, 1, 1, 0.5)
         for i in range(64):
             ctx.stats.append(0)
             ctx.statsr.append(
-                Rectangle(pos=(win.width - 64 * 4 + i * 4, 0),
-                          size=(4, 0)))
+                Rectangle(pos=(win.width - 64 * 4 + i * 4, 0), size=(4, 0))
+            )
     win.bind(size=partial(_update_monitor_canvas, win, ctx))
-    Clock.schedule_interval(partial(update_fps, ctx), .5)
-    Clock.schedule_interval(partial(update_stats, win, ctx), 1 / 60.)
+    Clock.schedule_interval(partial(update_fps, ctx), 0.5)
+    Clock.schedule_interval(partial(update_stats, win, ctx), 1 / 60.0)
 
 
 def stop(win, ctx):

examples/main.py

@@ -1,10 +1,16 @@
 import fps_monitor
 from kivy.app import App
-from kivy.lang import Builder
 from kivy.core.window import Window
+from kivy.lang import Builder
 from kivy.uix.floatlayout import FloatLayout
-from kivy.uix.screenmanager import ScreenManager, Screen
-from kivy_garden.frostedglass import FrostedGlass
+from kivy.uix.screenmanager import Screen, ScreenManager
+from kivy.utils import platform
+
+from kivy_garden.frostedglass import FrostedGlass  # FrostedGlass import
+
+if platform not in ("android", "ios"):
+    Window.size = (480, 854)
+    Window.top = 50
 
 Builder.load_file('test.kv')
 
@@ -25,6 +31,10 @@ class Screen3(Screen):
     pass
 
 
+class Screen4(Screen):
+    pass
+
+
 class FrostedGlassApp(App):
     def build(self):
         return UI()