path: root/PaintLocking
diff options
Diffstat (limited to 'PaintLocking')
1 files changed, 102 insertions, 0 deletions
diff --git a/PaintLocking b/PaintLocking
new file mode 100644
index 0000000..0b18e1d
--- /dev/null
+++ b/PaintLocking
@@ -0,0 +1,102 @@
+Locking paint window paint attributes
+1. About this document
+2. Basic design
+3. Usage
+1. About this document
+This document is more a quick overview than an in-depth description.
+The functions are well documented in the code, please read them for more
+In this document, paint attributes are opacity, saturation and brightness.
+They also deal with CompWindow's not, for instance, cube transparancy.
+2. Basic design
+We assume there are three fundamentally diffrent ways to change paint
+attributes. These are:
+ - Human change or external program. These should get precedence.
+ - Plugin wanting a permanent change for their lifetime.
+ - Plugin wanting a temporary effect.
+To facilitate these three diffrent cases, we store paint-values two
+plces. They are stored in w->paint, which is the actual paint values
+used, and they are stored in w->opacity/saturation/brightness (I'll use
+w->opacity though all three apply from now on).
+Traditionally, w->opacity represented the atom, and did not change unless
+we changed an atom. At the same time, plugins hardly used w->paint.* at, but
+instead wrapped paintWindow() to change the opacity at each repaint of the
+The way we do things now, we use w->opacity as a default value, and
+w->paint.opacity as the real value. We try to avoid using paintWindow()
+to change the opacity.
+A plugin that wish to temporarily change the opacity, will do so by
+modifying w->paint.opacity, and when it is finished, it wil set
+w->paint.opacity to w->opacity. While it is set, it will lock w->paint.opacity.
+This lock is usually set to PL_TEMP_HELLO, which is a pseudo-lock. The
+reason we don't use PL_NO_LOCK, is to avoid overriding the temporary change
+when the default is changed.
+Now consider two plugins, trailfocus and opacify. Opacify is modifying opacity
+on 5 windows, and we change focus. This causes trailfocus to change w->opacity
+on these 5 windows, but the change isn't visible until opacify decides to reset
+the opacity.
+The assumption is that a user using trailfocus wants the opacity to be changed,
+but also wants to use opacify. The default change will live "forever" because
+trailfocus allways affects the opacity. As a fallback, when we unload
+trailfocus, core supplies a bailout function that sets w->opacity to the
+atom-defined value.
+The diffrent levels of locking allow us to override other plugins. This is
+used in state, and this is used when manually changing opacity. A user-initated
+opacity change will change w->opacity and at the same time lock it so other
+code, like trailfocus, is unable to change it. State has the ability to lock
+both the default and temporary/absoloute paint attributes. State simply
+sets default and temporary paint attributes with PL_PLUGIN_ONE. Users may
+want to use this for ensuring their mplayer-window is allways opaque for
+3. Usage
+Unless you intend the paint change to last until you unload, you want
+to use the
+setWindowOpacity(CompWindow * w, GLushort opacity, PaintLockLevels lock);
+resetWindowOpacity(CompWindow * w, PaintLockLevels lock);
+set of functions (and the respective functions for brightness/saturation).
+You should not have to worry about return-values, though setWindowOpacity()
+will return true if it successfully sets the value.
+Generally, you use PL_TEMP_HELLO as the lock, state uses PL_PLUGIN_ONE. We
+adjust lock levels on a case-by-case basis. There is really no more magic
+behind this.
+If you are writing something similar to state or trailfocus, or otherwise
+want to define the opacity the user sees on the window "all the time", you
+will have to use these:
+setDefaultWindowOpacity(CompWindow *w, GLushort opacity, PaintLockLevels lock);
+setWindowBailoutOpacity(CompWindow *w, PaintLockLevels lock);
+Here, you will use PL_NO_LOCK or PL_PLUGIN_x, (IE: Everything but PL_TEMP_HELLO
+and PL_SUPER).
+The bailout is intended for configuration changes (when a user suddenly no
+longer want state to handle a window for instance), and plugin unload. Do not
+use the Bailout* functions lightly.
+Examples of usage:
+Opacify (temp)
+Move (temp)
+Resize (temp)
+Trailfocus (default)
+State (default and temp)
+Core (mouse-wheel and atom-changes) (default)