2011-11-05 02:52:05 +08:00
# Compton
__Compton__ is a compositor for X, and a fork of __xcompmgr-dana__ .
I was frustrated by the low amount of standalone lightweight compositors.
Compton was forked from Dana Jansens' fork of xcompmgr and refactored. I fixed
whatever bug I found, and added features I wanted. Things seem stable, but don't
quote me on it. I will most likely be actively working on this until I get the
features I want. This is also a learning experience for me. That is, I'm
partially doing this out of a desire to learn Xlib.
## Changes from xcompmgr:
* __inactive window transparency__ (specified with `-i` )
2011-11-06 11:33:50 +08:00
* __titlebar/frame transparency__ (specified with `-e` )
2011-11-07 09:29:23 +08:00
* menu transparency (thanks to Dana)
2011-11-05 02:52:05 +08:00
* shadows are now enabled for argb windows, e.g. terminals with transparency
* removed serverside shadows (and simple compositing) to clean the code,
the only option that remains is clientside shadows
2012-10-22 20:41:24 +08:00
* configuration files (specified with `--config` )
* colored shadows (with `--shadow-[red/green/blue] value` )
* a new fade system
* vsync (still under development)
* several more options
2011-11-06 11:33:50 +08:00
2011-11-05 02:52:05 +08:00
## Fixes from the original xcompmgr:
* fixed a segfault when opening certain window types
* fixed a memory leak caused by not freeing up shadows (from the freedesktop
repo)
2012-10-22 20:41:24 +08:00
* fixed the conflict with chromium and similar windows
* [many more ](https://github.com/chjj/compton/issues )
2011-11-05 02:52:05 +08:00
## Building
### Dependencies:
2012-03-18 09:17:08 +08:00
__B__ for build-time
__R__ for runtime
* libx11 (B,R)
* libxcomposite (B,R)
* libxdamage (B,R)
* libxfixes (B,R)
2012-09-11 21:33:03 +08:00
* libXext (B,R)
2012-03-18 09:17:08 +08:00
* libxrender (B,R)
Feature: #7: VSync
- Add VSync feature. 3 possible VSync methods available: "sw" (software,
not too reliable, but at least you have something to fallback to),
"drm" (using DRM_IOCTL_WAIT_VBLANK, should work only on DRI drivers),
"opengl" (using SGI_swap_control extension OpenGL, might work on more
drivers than the DRM method). "sw" and "opengl" are briefly tested,
"drm" received utterly no test (because I use the nVidia binary blob).
They are enabled with "--vsync sw" / "--vsync drm" / "--vsync opengl".
- Add --refresh-rate to let user specify a refresh rate for software
VSync, in case the automatic refresh rate detection does not work
well.
- Seemingly the automatic refresh rate detection using X RandR in
software VSync detects refresh rate incorrectly. Need further investigation.
- Fix a few bugs in fading timing.
- Add a workaround for client window detection on Fluxbox, as Fluxbox
(incorrectly?) sets the override-redirect flag upon all frame
windows.
- Software VSync adds dependency on librt (a part of glibc) for
nanosecond-level timing functions, and libXrandr for automatic refresh
rate detection; DRM VSync adds dependency on libdrm to use its drm.h,
but does not link to libdrm; OpenGL VSync adds dependency on libGL.
- Print timing information on DEBUG_REPAINT.
2012-10-08 10:20:01 +08:00
* libXrandr (B,R)
2012-03-18 09:17:08 +08:00
* pkg-config (B)
* make (B)
* xproto / x11proto (B)
* bash (R)
* xprop,xwininfo / x11-utils (R)
Feature: Issue #29: Alternative shadow blacklist implementation
- Add shadow blacklist feature, but a different implementation from
nicklan's. 5 matching modes (exact, starts-with, contains, wildcard,
PCRE) and 3 matching targets (window name, window class instance,
window general class). Not extensively tested, bugs to be expected.
It's slower for exact matching than nicklan's as it uses linear search
instead of hash table. Also, PCRE's JIT optimization may cause issues
on PaX kernels.
- Add dependency to libpcre. Could be made optional if we have a
graceful way to handle that in Makefile.
- Some matching functions are GNU extensions of glibc. So this version
may have troubles running on platforms not using glibc.
- Fix a bug that access freed memory blocks in set_fade_callcack() and
check_fade_fin(). valgrind found it out.
- Use WM_CLASS to detect client windows instead of WM_STATE. Some client
windows (like notification windows) have WM_CLASS but not WM_STATE.
- Mark the extents as damaged if shadow state changed in
determine_shadow().
- Rewrite wid_get_name(). Code clean-up.
- Two debugging options: DEBUG_WINDATA and DEBUG_WINMATCH.
- As the matching system is ready, it should be rather easy to add other
kinds of blacklists, like fading blacklist.
2012-09-22 11:42:39 +08:00
* libpcre (B,R) (Will probably be made optional soon)
2012-09-25 10:19:20 +08:00
* libconfig (B,R) (Will probably be made optional soon)
Feature: #7: VSync
- Add VSync feature. 3 possible VSync methods available: "sw" (software,
not too reliable, but at least you have something to fallback to),
"drm" (using DRM_IOCTL_WAIT_VBLANK, should work only on DRI drivers),
"opengl" (using SGI_swap_control extension OpenGL, might work on more
drivers than the DRM method). "sw" and "opengl" are briefly tested,
"drm" received utterly no test (because I use the nVidia binary blob).
They are enabled with "--vsync sw" / "--vsync drm" / "--vsync opengl".
- Add --refresh-rate to let user specify a refresh rate for software
VSync, in case the automatic refresh rate detection does not work
well.
- Seemingly the automatic refresh rate detection using X RandR in
software VSync detects refresh rate incorrectly. Need further investigation.
- Fix a few bugs in fading timing.
- Add a workaround for client window detection on Fluxbox, as Fluxbox
(incorrectly?) sets the override-redirect flag upon all frame
windows.
- Software VSync adds dependency on librt (a part of glibc) for
nanosecond-level timing functions, and libXrandr for automatic refresh
rate detection; DRM VSync adds dependency on libdrm to use its drm.h,
but does not link to libdrm; OpenGL VSync adds dependency on libGL.
- Print timing information on DEBUG_REPAINT.
2012-10-08 10:20:01 +08:00
* libdrm (B) (Will probably be made optional soon)
* libGL (B,R) (Will probably be made optional soon)
2012-11-01 12:44:09 +08:00
* asciidoc (B) (if you wish to run `make docs` )
Improvement #74: Use libevent for main loop
- Use libevent for main loop. I will explain the reasons in #56 later.
The preferred libevent version is 2.x, yet 1.4.x should work as well.
- As a result, compton now should build fine on *BSD. Thanks to
DachiChang for the FreeBSD build issue report.
- Another consequence is we now use microsecond-level timing all the
way. Nanosecond-level code will be dropped soon. Start using long
instead of unsigned long to represent time in milliseconds, as both
can't hold the full epoch time in ms, anyway, and a signed type
requires less care in subtraction. Wrap the epoch time in ms to 15
days.
- Fix broken NO_VSYNC_DRM and NO_VSYNC_OPENGL compile-time options.
- Use git revision number for versioning in Makefile, and other small
improvements.
- Reorganize struct _win. Drop unused w->damaged_sequence. w->damaged is
turned to bool.
- Add type and format to winprop_t, as preparation for the new condition
format.
- Add w->shadow_force and w->focus_force, to prepare for D-Bus support.
- Rename wid_get_prop() to wid_get_prop_adv() with more options. Add
wrapper function wid_get_prop().
- Add some extra helper functions, for D-Bus support later.
- Make some functions return a bool value to indicate if it's
successful.
- Modify add_win(), use a static const structure to initialize the new
struct _win.
- Add some helper macros, like printf_err(f)(q). Make some errors fatal.
- Rename some types, constants, and functions. Code clean-up.
- Check for time disorder in paint_preprocess() when calculating fading
steps.
- Rename evpoll() to swopti_handle_timeout(), and partially rewrite it.
- Make -h / --help legal.
- Known issue: compton segfaults on FreeBSD with nvidia-drivers, unless
NO_VSYNC_OPENGL is used. Will look into it later. Thamls to DachiChang
for reporting.
2013-01-08 08:50:58 +08:00
* libevent (B,R)
2011-11-05 02:52:05 +08:00
2012-11-14 18:42:09 +08:00
### How to build
To build, make sure you have the dependencies above:
2011-11-05 02:52:05 +08:00
``` bash
2012-11-14 18:42:09 +08:00
# Make the main program
2011-11-05 02:52:05 +08:00
$ make
2012-11-14 18:42:09 +08:00
# Make the newer man pages
$ make docs
# Install
2011-11-07 08:20:45 +08:00
$ make install
2011-11-05 02:52:05 +08:00
```
2012-11-14 18:42:09 +08:00
(Compton does include a `_CMakeLists.txt` in the tree, but we haven't decided whether we should switch to CMake yet. The `Makefile` is fully usable right now.)
2012-11-14 20:44:31 +08:00
## Known issues
2011-11-05 02:52:05 +08:00
2012-11-14 20:44:31 +08:00
* VSync does not work too well. It's widely reported that tearing still happens on the top of the screen. I do not know how to fix the issue.
2012-10-22 20:41:24 +08:00
2012-11-14 20:44:31 +08:00
* If `--unredir-if-possible` is enabled, when compton redirects/unredirects windows, the screen may flicker. Using `--paint-on-overlay` minimizes the problem from my observation, yet I do not know if there's a cure.
2012-10-22 20:41:24 +08:00
2012-11-14 20:44:31 +08:00
* compton may not track focus correctly in all situations. The focus tracking code is experimental. `--use-ewmh-active-win` might be helpful.
2012-10-22 20:41:24 +08:00
2012-11-14 20:44:31 +08:00
* Compton may give ugly shadow to windows with ARGB background if `-z` is enabled, because compton cannot determine their real shapes. One may have to disable shadows on those windows with window-type-specific settings in configuration file or `--shadow-exclude` .
2012-10-22 20:41:24 +08:00
2012-11-14 20:44:31 +08:00
* There are two sets of man pages in the repository: the man pages in groff format (`man/compton.1` & `man/compton-trans.1` ) and the man pages in Asciidoc format (`man/compton.1.asciidoc` & `man/compton-trans.1.asciidoc` ). The Asciidoc man pages are much more up-to-date than the groff ones, and it is viewable online. As chjj has not yet expressed his attitude towards switching to Asciidoc man pages, I kept both versions. By default the groff version is installed, unless you run `make docs` .
2012-10-22 20:41:24 +08:00
2012-12-18 22:04:22 +08:00
* The performance of blurring is terrible, probably because of a problem in the X Render implementation. Its behavior is driver-dependent: With nvidia-drivers it works but there are strange 1px lines remaining when you operate on windows (not sure if it's a bug in compton or in the driver); with nouveau it's utterly broken.
2012-11-14 20:44:31 +08:00
## Usage
2012-10-22 20:41:24 +08:00
2012-11-14 20:44:31 +08:00
Please refer to the Asciidoc man pages (`man/compton.1.asciidoc` & `man/compton-trans.1.asciidoc` ) for more details and examples.
2011-11-07 12:03:18 +08:00
2012-11-14 20:44:31 +08:00
Note a sample configuration file `compton.sample.conf` is included in the repository.
2012-10-22 20:41:24 +08:00
2012-11-14 20:44:31 +08:00
## Support
* Bug reports and feature requests should go to the "Issues" section above.
* Our (semi?) official IRC channel is #compton on FreeNode.
* Some information is available on the wiki, including (and presently, only includes) a FAQ.
2011-11-16 14:04:38 +08:00
2011-11-07 12:03:18 +08:00
## License
2012-10-22 20:41:24 +08:00
Although compton has kind of taken on a life of its own, it was originally
an xcompmgr fork. xcompmgr has gotten around. As far as I can tell, the lineage
for this particular tree is something like:
2011-11-07 12:03:18 +08:00
* Keith Packard (original author)
* Matthew Hawn
* ...
* Dana Jansens
2012-10-22 20:41:24 +08:00
* chjj and richardgv
2011-11-07 12:03:18 +08:00
Not counting the tens of people who forked it in between.
2012-11-14 20:44:31 +08:00
Compton is distributed under MIT license, as far as I (richardgv) know. See LICENSE for more info.
