summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKristian Lyngstol <kristian@bohemians.org>2007-06-22 14:43:10 +0200
committerKristian Lyngstol <kristian@bohemians.org>2007-06-22 14:43:10 +0200
commiteb193e158d25c1707a0b63e91122780400d69d44 (patch)
tree15dba9d2f852546715ccb0f77f6612d4b3668f6e
parent547f5f004bdc2ccbf8b323eb5c07827d01ee547d (diff)
downloadDocumentation-eb193e158d25c1707a0b63e91122780400d69d44.tar.gz
Documentation-eb193e158d25c1707a0b63e91122780400d69d44.tar.bz2
Update for Compiz Fusion
-rw-r--r--CoreStructures84
1 files changed, 57 insertions, 27 deletions
diff --git a/CoreStructures b/CoreStructures
index 736c887..7c859d6 100644
--- a/CoreStructures
+++ b/CoreStructures
@@ -1,5 +1,6 @@
Beryl's core structures - version this-is-not-complete-yet
=======================
+0. State of this document - Compiz Fusion
1. Scope of this document
2. CompDisplay vs CompScreen
3. CompDisplay
@@ -7,15 +8,20 @@ Beryl's core structures - version this-is-not-complete-yet
5. CompWindow
6. Regions
+0. State of this document - Compiz Fusion
+=========================================
+This document was written for the Beryl project, so not all of this applies
+to Compiz Fusion. Most of it does.
+
1. Scope of this document
=========================
-With this document I will attempt to clear up some confusion about the most
-important data structures in Beryl. I will not describe every part of the
-structures, but rather clear up some trickier parts.
+This document attempts to clear up some confusion about the most important data
+structures in Compiz Fusion. I will not describe every part of the structures,
+but rather clear up some trickier parts.
-A good way to get to know these structures is to use the debug plugin. It
-allows you to easily view the CompScreen and CompWindow structure(s) with
-some of the sub-structures.
+The Beryl project had a debug plugin which was capable of displaying the
+content of many of these structures on the fly. It might get ported for Compiz
+Fusion.
2. CompDisplay vs CompScreen
============================
@@ -23,10 +29,10 @@ If you've seen the DISPLAY variable, it'll look something like this for most
people: DISPLAY=:0.0 . The first 0 here is the display, and the second 0
is the screen. Each X server has ONE display, but can have multiple screens.
-Do not confuse a screen with a monitor, though. In a xinerama-hinted
-environment (the most common multihead setup), the X server presents just one
-screen to the programs, but gives us hints about where the head/monitor
-stops and starts.
+Do not confuse a screen with a monitor, though. In bigscreen multihead
+environment (the most common multihead setup, xinerama, xrandr, twinview,
+mergedfb, they all supply this), the X server presents just one screen to the
+programs, but gives us hints about where the head/monitor stops and starts.
Usually, there isn't any real work needed in a plugin to support multiscreen.
All you need to do is make sure you deal with CompScreen and never assume
@@ -39,6 +45,9 @@ but make sure you find the right screen if you want your binding to only
affect one screen. Take a look at rotate.c to see how this is done as an
example.
+The rule of thumb is that input is display scope, and output is screen-scope:
+You can only input to one screen at the time, but output to multiple.
+
3. CompDisplay
==============
@@ -72,7 +81,7 @@ words, one per monitor. It also has a convenient currentOutputDev which core
tries to set, but is not always accurate.
Luckily, the CompOutput struct is very simple. It has a width, height, region
-and workRegion variable that we care about. The region helps us establish
+and workArea variable that we care about. The region helps us establish
where an outputDev starts in the screen. region.x1 defines where the X-coordinate
of that specific window starts, and region.x2 describes where it ends. The same
with region.y1/y2 respectively for the Y coordinate.
@@ -84,37 +93,56 @@ y2: 767
Keep in mind that x + width puts you 1 pixel beyond the device. (0-1023 is 1024
numbers. A classic programming error is to forget that 0 is a valid number).
-Currently, we don't really use the rects of the regions, so for nowe we can
+Currently, we don't really use the rects of the regions, so for now we can
ignore those.
-workRegion is identical to region, but is supposed to take struts into
-consideration. This code has undergone some changes, and is likely to change
-in the future. The problem is that we never used the region nature of the
-workRegion so it was still just a rect. That discussion is beyond the scope
-of this text, however. Just keep it in mind if you want a simple but imperfect
-way of avoiding panels.
+workArea is the extents of the head, but is supposed to take struts into
+consideration. Just like s->workArea. There have been changes in this area in
+the past, Beryl and Compiz diverge somewhat as two different solutions were
+initially used to solve multihead struts and floating struts. A strut is an
+area of the screen that should not be covered by windows, usually because it
+is covered by a panel.
-So when do you use s->width and when do you use
+So when do you use s->width and when do you use
s->outpudDev[s->currentOutputDev].region.x1/x2 ? There is no universal answer
to this, but the simple answer is to use s->width when you are concerned with
the entire screen, and the outputDev when you want to constrain yourself to the
monitor. Examples are maximization, which deals with outputDev, and edge-
detection, which wants to find the edge of the screen, not the monitor.
+Snapping wants to snap to the edge of the head, and so on.
More obvious variables are hsize and vsize, which define the horisontal
and vertical size, x and y, which define which of these you are currently on,
screenNum, which defines which screen you are on (usually 0), and the WorkArea
rectangle, which defines the work area for the screen (avoid using this, as
-it will be quite strange on xinerama-hinted multihead.)
+it will be quite strange on bigscreen-hinted multihead, specially for
+asymetric resolutions)
+
+Here's a drawing of an asymetric multihead setup:
++--------+-------------+
+| | |
+| A | |
+| | B |
++--------+ |
+| C | |
++--------+-------------+
+
+A and B are monitors, C is part of the screen, but is not visible (The screen
+has to be rectangular). If you have a strut on the bottom of A, This will mean
+that s->workArea cuts off everything on B that's below that strut too, which
+we obviously don't want to use too much.
Each CompScreen also has a list of windows (s->windows) and the reversed
version. Windows are stored in a bottom-up fashion, so the first window in
s->windows will be the bottommost window.
-The projectionStyle sets how the projection matrix should be set up. This
-is mostly just relevant for xinerama multihead at the moment. See the multihead
-documentation for details. In the future, this might be used to set orthographic
-projection instead of perspective.
+TODO: Window walking interface.
+
+During drawing, you also have to deal with which output device is being drawn
+to. This is very important for multihead, and there is a special device called
+s->fullscreenOutput which sets the OpenGL viewport to the entire screen,
+unlike the normal operation which draws each head separately. This is
+discussed further in the multihead documentation.
5. CompWindow
=============
@@ -123,8 +151,10 @@ unless you also make sure you listen for events which would destroy it and
update your version accordingly. If you want your plugin to remember a window,
it is often wise to use the w->id instead, and locate the CompWindow when you
need it, but this depends on how you use the CompWindow. Storing the CompWindow
-pointer is faster, but slightly more complex.
-
-
+pointer is faster, but slightly more complex. Keep in mind that the CompWindow
+pointer can become invalid if you do not pay attention to window destruction
+events, while the w->id will never become invalid, it will just stop
+identifying the window. That's the difference between a SIGSEG and not finding
+the window.
6. Regions