From a8466a16f73d22373002b725e81b020d746a5a26 Mon Sep 17 00:00:00 2001 From: Simon Schneegans Date: Sat, 19 Aug 2023 08:00:54 +0200 Subject: [PATCH] :memo: Update effect creation guide --- docs/how-to-create-new-effects.md | 321 +++--------------------------- 1 file changed, 30 insertions(+), 291 deletions(-) diff --git a/docs/how-to-create-new-effects.md b/docs/how-to-create-new-effects.md index ddbdb03..9a17254 100644 --- a/docs/how-to-create-new-effects.md +++ b/docs/how-to-create-new-effects.md @@ -38,7 +38,7 @@ journalctl -f -o cat | grep -E 'burn-my-windows|' For the sake of this tutorial, we will create a **"Simple Fade"** effect. Of course, you can replace any occurrence of this name and its nick `simple-fade` with your custom effect name. -Three simple steps are required to create a new effect. +Three simple steps are required to create a new effect. You will have to ... 1. add preferences keys for enabling the effect, @@ -103,13 +103,14 @@ Please study this code carefully, all of it is explained with inline comments. // The content from common.glsl is automatically prepended to each shader effect. This // provides the standard input: -// vec2 iTexCoord: Texture coordinates for retrieving the window input color. -// bool uForOpening: True if a window-open animation is ongoing, false otherwise. -// float uProgress: A value which transitions from 0 to 1 during the animation. -// float uDuration: The duration of the current animation in seconds. -// vec2 uSize: The size of uTexture in pixels. -// float uPadding: The empty area around the actual window (e.g. where the shadow -// is drawn). For now, this will only be set on GNOME. +// vec2 iTexCoord: Texture coordinates for retrieving the window input color. +// bool uIsFullscreen: True if the window is maximized or in fullscreen mode. +// bool uForOpening: True if a window-open animation is ongoing, false otherwise. +// float uProgress: A value which transitions from 0 to 1 during the animation. +// float uDuration: The duration of the current animation in seconds. +// vec2 uSize: The size of uTexture in pixels. +// float uPadding: The empty area around the actual window (e.g. where the shadow +// is drawn). For now, this will only be set on GNOME. // Furthermore, there are two global methods for reading the window input color and // setting the shader output color. Both methods assume straight alpha: @@ -162,16 +163,13 @@ void main() { // SPDX-FileCopyrightText: Your Name // SPDX-License-Identifier: GPL-3.0-or-later -'use strict'; +"use strict"; const GObject = imports.gi.GObject; -const _ = imports.gettext.domain('burn-my-windows').gettext; +const _ = imports.gettext.domain("burn-my-windows").gettext; -const ExtensionUtils = imports.misc.extensionUtils; -const Me = imports.misc.extensionUtils.getCurrentExtension(); -const utils = Me.imports.src.utils; -const ShaderFactory = Me.imports.src.ShaderFactory.ShaderFactory; +import { ShaderFactory } from "../ShaderFactory.js"; ////////////////////////////////////////////////////////////////////////////////////////// // This effect ... // @@ -181,21 +179,21 @@ const ShaderFactory = Me.imports.src.ShaderFactory.ShaderFactory; // The effect class can be used to get some metadata (like the effect's name or supported // GNOME Shell versions), to initialize the respective page of the settings dialog, as // well as to create the actual shader for the effect. -var SimpleFade = class { - +export default class Effect { // The constructor creates a ShaderFactory which will be used by extension.js to create // shader instances for this effect. The shaders will be automagically created using the // GLSL file in resources/shaders/.glsl. The callback will be called for each // newly created shader instance. constructor() { this.shaderFactory = new ShaderFactory(this.getNick(), (shader) => { - // Store uniform locations of newly created shaders. - shader._uFadeWidth = shader.get_uniform_location('uFadeWidth'); + shader._uFadeWidth = shader.get_uniform_location("uFadeWidth"); // Write all uniform values at the start of each animation. - shader.connect('begin-animation', (shader, settings) => { - shader.set_uniform_float(shader._uFadeWidth, 1, [settings.get_double('simple-fade-width')]); + shader.connect("begin-animation", (shader, settings) => { + shader.set_uniform_float(shader._uFadeWidth, 1, [ + settings.get_double("simple-fade-width"), + ]); }); }); } @@ -213,13 +211,13 @@ var SimpleFade = class { // (e.g. '*-animation-time'). Also, the shader file and the settings UI files should be // named likes this. getNick() { - return 'simple-fade'; + return "simple-fade"; } // This will be shown in the sidebar of the preferences dialog as well as in the // drop-down menus where the user can choose the effect. getLabel() { - return _('Simple Fade Effect'); + return _("Simple Fade Effect"); } // -------------------------------------------------------------------- API for prefs.js @@ -236,7 +234,7 @@ var SimpleFade = class { // animation. This is useful if the effect requires drawing something beyond the usual // bounds of the actor. This only works for GNOME 3.38+. getActorScale(settings) { - return {x: 1.0, y: 1.0}; + return { x: 1.0, y: 1.0 }; } } ``` @@ -250,15 +248,17 @@ Both, [`extension.js`](../extension.js) and [`prefs.js`](../prefs.js) define an Like this: ```javascript +import SimpleFade from './src/effects/SimpleFade.js'; + +... + const ALL_EFFECTS = [ ... - new Me.imports.src.effects.SimpleFade.SimpleFade(), + new SimpleFade(), ... ]; ``` - - ### Testing your Effect Now you can call `make install` and restart GNOME Shell with Alt + F2, r + Enter. @@ -274,272 +274,11 @@ gnome-extensions prefs burn-my-windows@schneegans.github.com ## Adding a Preferences Page There should be two sliders in this example: The animation duration and the width of the fading gradient. - -If your effect supports GNOME Shell 3.3x _and_ GNOME Shell 40+, you will have to provide three `*.ui` files for this. -This is because starting with GNOME Shell 40, the preference dialog uses GTK4, before it used to use GTK3. -Starting with GNOME Shell 42, it uses `libadwaita` which requires different UI files again. - -_:information_source: If you do not have the means to test your effect on different versions of GNOME, feel free to submit a pull request for one GNOME version only, I may then port your effect to other GNOME versions!_ - -Just save the code below to `resources/ui/gtk3/simple-fade.ui`, `resources/ui/gtk4/simple-fade.ui`, and `resources/ui/adw/simple-fade.ui` respectively. +Just save the code below to `resources/ui/adw/simple-fade.ui`. Remember to replace any occurrence of `simple-fade` with your effect's nick-name!
- Expand this to show the GTK3 code. - -```xml - - - - - - - - 5000 - 100 - 10 - 100 - - - - 1 - 0 - 0.01 - 0.1 - - - - - - - none - - - - 0 - - - - - Animation Time [ms] - 0 - start - center - 1 - - - - - end - center - 1 - 0 - left - 300 - simple-fade-animation-time - - - - - - - edit-clear-symbolic - 1 - - - Reset to Default Value - - - - - - - - - - - 0 - - - - - Fade Width - 0 - start - center - 1 - - - - - end - center - 1 - 2 - left - 300 - simple-fade-width - - - - - - - edit-clear-symbolic - 1 - - - Reset to Default Value - - - - - - - - - - - - - -``` - -
- - - - -
- Expand this to show the GTK4 code. - -```xml - - - - - - - - 5000 - 100 - 10 - 100 - - - - 1 - 0 - 0.01 - 0.1 - - - - - - - none - - - - 0 - - - - - Animation Time [ms] - 0 - start - center - 1 - - - - - end - center - 1 - 0 - left - 300 - simple-fade-animation-time - - - - - edit-clear-symbolic - Reset to Default Value - - - - - - - - - - - 0 - - - - - Fade Width - 0 - start - center - 1 - - - - - end - center - 1 - 2 - left - 300 - simple-fade-width - - - - - edit-clear-symbolic - Reset to Default Value - - - - - - - - - - - - - -``` - -
- - -
- Expand this to show the libadwaita code. + Expand this to show the UI code. ```xml @@ -628,7 +367,7 @@ SPDX-License-Identifier: GPL-3.0-or-later ### Loading the Preferences Page -In order to load the above `*.ui` files, add the following code to your effect's `bindPreferences()` method. +In order to load the above `*.ui` file, add the following code to your effect's `bindPreferences()` method. ```javascript bindPreferences(dialog) { @@ -651,4 +390,4 @@ make install && pkill -f '.Extensions' && sleep 2 ; gnome-extensions prefs burn- That's it! If you have any questions, feel free to [ask them on the discussions board](https://github.com/Schneegans/Burn-My-Windows/discussions). -If you are happy with your effect, submit a pull request, and it may get included in the next version! \ No newline at end of file +If you are happy with your effect, submit a pull request, and it may get included in the next version!