Tutorial on writing compiz plugins for Ubuntu 12.04?

Asked by Robert Brais

Does there exist a basic up to date tutorial on writing compiz plugins? Smspillaz wrote a great tutorial on the subject, but it is getting out of date as both ubuntu compiz move on to newer versions. What are the latest compiz packages to install? (I've seen a lot of tutorials on installing compiz, but I have yet to find a development version that will install without running into an error because it is missing a package.)

Question information

English Edit question
Compiz Edit question
No assignee Edit question
Solved by:
Robert Brais
Last query:
Last reply:
Revision history for this message
Micheal Hsu (mkhu) said :

to write a plugin you don't need to build compiz from source,
you just need to install compiz-dev
(i assume you use ubuntu here)-
> sudo apt-get install compiz-dev
you can find the headers in /usr/include/compiz
these are the compiz APIs you can use in your plugin
it's advisable to keep compiz source around (for reference)
> apt-get source compiz

most plugins depend on the following plugins:
1. core
2. composite
3. opengl

read the APIs (see corresponding headers) to get a general idea of the functionality at your disposal.
most of the APIs are apparent from their names and some non-trivial functions are documented.
if you're still not sure about something, read its implementation.
som plugins also export their functionality to be consumed by other plugins.

to write a plugin, you need some knowledge of Xlib and OpenGL.

basic instructions.
1. understanding compiz option system
    xml description files and the generated accessors.
2. screen and window interfaces
     core rendering hooks.
3. event handling
     see screen interface handleEvent method

pick up a simple plugin and study it piece by piece.
the splash plugin is a good start.
here's is a simple hacking guide to get yourself aquainted with the rendering APIs.
1. cp out splash plugin to a separate to directory.
2. change the plugin name to avoid clash.
3. read splash.cpp to understand how the rendering hooks work.
4. now remove splash rendering code.
    draw a triangle for yourself using opengl
5. build it and install it. (or directly copy the libXXX.so to /usr/lib/compiz)
you need to enable it by change compiz gsettings value
or run compiz from command line with the plugin name.

(sorry for my english)

Revision history for this message
Robert Brais (rbrais) said :

Thank you for the help! I successfully installed the modified 'splash' plugin using 'make' and 'make install'. I restarted my system, but the plug-in does not appear in ccsm. I am unsure as to which gsettings value I must change to enable the plug-in. (Your English is very good).

Revision history for this message
Micheal Hsu (mkhu) said :

the plugin should appear in ccsm.

if you build your plugin out of the compiz source tree,
'make install' will install the plugin in $HOME/.compiz-1/plugins
compiz and ccsm both search from this directory before the plugins in system plugin directory (/usr/share/compiz)
so its OK even if your plugin has the same name as a plugin in system directory.

how to enable your plugin?
there're three ways AFAIK:
1. ccsm should show the plugin with a question icon.
     (you may install a icon for your plugin into /usr/share/ccsm/icons/hicolors/scalable/apps/plugin-xxxxx.svg)
2. change gsettings value:
    (actually compiz has three configuration backend: ini, gconf, gsettings. but nowadays gsettings is most common)
    > sudo apt-get install dconf-tools (command line tool is OK)
    open dconf-editor: see path
    org.compiz: current-profile = XXXX
    then see org.compiz.profiles:/XXXX: plugins-with-set-keys: add it here.
    another way is to change your profile file in /etc/compizconfig/... or .config/compizconfig/ (see config and unity.ini)
3. run you plugin with command line (this does not change any settings)
    1' compiz --replace <your_plugin_name> (if you're using system-installed compiz, it's patched so ccp plugin is started by default)
    2' compiz --replace ccp <your_plugin_name> (if your'e using custom built compiz)

to see if your plugin is actually loaded, run previous compiz command with --debug option.
(this also prints your settings backend and profile name).

1. you don't need to restart to test a plugin.
2. you don't need to ask another question just comment here is Ok
3. i suggest you build your plugin out of the compiz source tree (play safe).
     most of the time your system hangs, you just need to change to another VT and
     > sudo restart lightdm
     you still have a working compiz.

I don't know why ccsm don't show your plugin.
please check ( I assume you build your plugin out of compiz source tree)
0. run ccsm from gnome-terminal to see its console output is consistent with your compiz settings.
1. your plugin should in $HOME/.compiz-1/plugins
2. run compiz --debug --replace ccp <youor_plguin_nam> to see how compiz try to load your plugin,
     does compiz find it? does compiz load it successfully?

Revision history for this message
Robert Brais (rbrais) said :

Thank you Hu Kang,
I managed to load my plugin succesfully.