1 [15:59] <dholbach> smspillaz, also known as Sam Spilsbury graciously agreed to give a session, and he'll talk to you about bringing more bling to compiz by writing spiffy plugins
2 [15:59] <dholbach> smspillaz, the stage is yours!
3 [15:59] <smspillaz> horray!
4 [16:00] <smspillaz> ok, awesome, so yes, here I am, I am the maintainer of the Compiz 0.9 series, i.e the version of compiz that will be used in Ubuntu 11.04 and Unity as well as most upcoming distros
5 [16:00] <smspillaz> first things' first, because I overprepare for everything, I made some documents that you all might find useful (and me too!) when following me
6 [16:00] <smspillaz> so the first one is the internal architecture of compiz
7 [16:00] <smspillaz> which can be found here:
8 [16:00] <smspillaz> http://smspillaz.ucc.asn.au/unity/compiz_arch/compiz_arch.pdf
9 === ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - https://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Questions in #ubuntu-classroom-chat || Event: Ubuntu Developer Week - Current Session: How to write a compiz plugin - Instructors: smspillaz
10 [16:01] <smspillaz> and the second is a 7 page guide on writing compiz plugins, which is half-finished, since I've been quite busy this week
11 [16:01] <ClassBot> Logs for this session will be available at http://irclogs.ubuntu.com/2011/03/01/%23ubuntu-classroom.html following the conclusion of the session.
12 [16:01] <smspillaz> http://smspillaz.ucc.asn.au/unity/compiz_arch/writing.odt
13 [16:01] <smspillaz> so feel free to grab those :)
14 [16:01] <smspillaz> alrighty, so starting from the beginning
15 [16:02] <smspillaz> first of all, a quick introduction to how compiz works, and what exactly its function is
16 [16:02] <smspillaz> and then how to get and compile a development version of compiz, or just develop for it on ubuntu
17 [16:02] <smspillaz> and then I'll do a quick walkthrough of the basic structure of a plugin and some commonly done things in plugins
18 [16:03] <smspillaz> ok, so as for how compiz works, and what exactly it does
19 [16:04] <smspillaz> to take a page from the compiz wiki, compiz is basically what we call a "Compositing Window Manager" in X land, which means that as well as managing windows on screen, it also is in charge of drawing those windows. This technology came about in around 2005ish when XComposite came about
20 === m4n1sh is now known as manish
21 [16:04] <smspillaz> so this means that in terms of your scope of compiz plugins, you can affect how windows are actually managed, affect how they are drawn, and affect how the entire scene is drawn
22 [16:05] <smspillaz> along with its plugin interface, this makes it pretty much possible to do any bling that you want
23 === manish is now known as manish__
24 [16:05] <smspillaz> so, now moving on to exactly how to set up a development environment
25 [16:05] <smspillaz> luckly, ubuntu makes this pretty easy
26 [16:06] <smspillaz> just sudo apt-get install compiz-dev and compiz-plugins-main-dev and you're done
27 [16:06] <smspillaz> (On maverick, it is compiz-fusion-plugins-main)
28 === manish__ is now known as manish_
29 [16:06] <smspillaz> but, if you want to do development in a little more, I usually suggest having a local build of compiz handy.
30 [16:07] <smspillaz> Luckily, most of that is relatively straightforward these days, since there are scripts to do that
31 [16:07] <smspillaz> http://git.compiz.org/~soreau/scripts/ <- like these fantastic ones
32 [16:08] <smspillaz> just clone the git repo there and with the script you'll have a full working installation from source.
33 [16:08] <smspillaz> This helps if, for example, some plugin does something similar to what you want to do, and you can start hacking on that plugin first.
34 [16:08] <smspillaz> so, a quick question I've recieved
35 [16:09] <smspillaz> QUESTION: What about Ubuntu 11.04
36 [16:09] <smspillaz> so, this tutorial here, as I probably should have explained will be for Ubuntu 11.04
37 [16:09] <smspillaz> since compiz was re-written in between the 0.8 and 0.9 series (maverick and natty)
38 [16:09] <smspillaz> however, those git scripts about should also work on maverick
39 [16:10] <smspillaz> Now on to the nitty gritty of writing your first plugin
40 [16:10] <smspillaz> Compiz plugins are written in C++. We don't really use very many advanced features of the languages or external libraries that heavily, so if you have a basic knowledge of that, then you should be good
41 [16:11] <smspillaz> we only use boost to a small extent, glib more recently and sigc
42 [16:11] <smspillaz> CMake is also used for building rather than automake
43 [16:11] <smspillaz> to answer another quick question
44 [16:11] <smspillaz> QUESTION:Is it possible to do some type of local build using the ubuntu packaging and pbuilder or something like that so that you can remove it easily?
45 [16:12] <smspillaz> So, the answer to this is is that you can indeed clone lp:compiz , however, this is the packaging branch of compiz core, and doesn't get all the modules
46 [16:12] <smspillaz> in addition, I'm not sure about how to make it build and install locally
47 [16:12] <smspillaz> (plus, adding extra stuff to it is a pain since you need to rebuild the whole thing all the time using bzr bd)
48 [16:12] <smspillaz> so I'd suggest you stick to the scripts or to the master source
49 [16:13] <smspillaz> (A link to the build tutorial is in the documents I linked to earlier)
50 [16:13] <smspillaz> so now back to writing plugins
51 [16:13] <smspillaz> so the basic knowledge, you will need once again, is C++, boost or CMake
52 [16:14] <smspillaz> note that OpenGL isn't really a strict requirement, since a lot of the graphics functions that are commonly used are abstracted through the API of compiz
53 [16:14] <smspillaz> it's just that if you want to go down the road of bling-bling, then OpenGL is nice
54 [16:14] <smspillaz> ok, so now for creating your plugin project
55 [16:14] <smspillaz> so to start off with, say you want to create a plugin called "moveleft" which, every time a window is opened, if moves every other window to the left
56 [16:15] <smspillaz> so, your directory structure would be
57 [16:15] <smspillaz> moveleft
58 [16:15] <smspillaz> -
59 [16:15] <smspillaz> -> src
60 [16:15] <smspillaz> ---> moveleft.cpp
61 [16:15] <smspillaz> ---> moveleft.h
62 [16:15] <smspillaz> -> moveleft.xml.in
63 [16:15] <smspillaz> -> CMakeLists.txt
64 === qwebirc46515 is now known as geco2
65 [16:16] <smspillaz> now to explain each component of that
66 [16:16] <smspillaz> basically, the .cpp and .h files are the implementation of your plugin, eg the loadable object code
67 [16:16] <smspillaz> the .xml.in describes information about your plugin for CCSM and also its options
68 [16:16] <smspillaz> and the CMakeLists.txt is the buildsystem
69 [16:16] <smspillaz> now, lucky for plugin authors, the buildsystem for compiz plugins is insanely easy
70 [16:17] <smspillaz> all you need is three lines
71 [16:17] <smspillaz> find_package (Compiz REQUIRED)
72 [16:17] <smspillaz> include (CompizPlugin)
73 [16:17] <smspillaz> compiz_plugin (moveleft PLUGINDEPS foo bar PKGDEPS baz)
74 [16:17] <smspillaz> so now on to what each line dos
75 [16:17] <smspillaz> *does
76 [16:18] <smspillaz> the first basically finds compiz with pkgconfig
77 [16:18] <smspillaz> the second imports all the plugin buildsystem
78 [16:18] <smspillaz> the third sets up a new "compiz plugin" project in CMake with the name "moveleft" depending on other plugins "foo" and "bar" and depending on external packages "baz"
79 [16:18] <smspillaz> so to disect that further
80 [16:19] <smspillaz> now that you've called your plugin "moveleft" you must stick with that shortname everywhere
81 [16:19] <smspillaz> so for example, the .xml.in must be named "moveleft"
82 [16:19] <smspillaz> However in the src/ tree, you don't need to worry about that
83 [16:19] <smspillaz> another interesting thing is that you can depend on other plugins
84 [16:20] <smspillaz> compiz 0.9 was designed in mind with inter-plugin dependency with each plugin providing objects to other plugins
85 [16:20] <smspillaz> so, a common example of this is the fact htat the opengl and composite bits of compiz are in fact plugins themselves
86 [16:20] <smspillaz> so most plugins that need to access this functionality will set those as their PLUGINDEPS
87 [16:21] <smspillaz> now on to the metadata file
88 [16:21] <smspillaz> I've explained this in more detail in the documents I linked to earlier
89 [16:21] <smspillaz> but basically, here you need to define your plugin name too
90 [16:21] <smspillaz> so <compiz>
91 [16:21] <smspillaz> <plugin name="myplugin" useBcop="true">
92 [16:22] <smspillaz> the useBcop is crucial if you want your life to be easier with autogenerated options code
93 [16:22] <smspillaz> you can also define some options there
94 [16:22] <smspillaz> but we will get back to that later
95 [16:22] <smspillaz> so close all the tags and save it
96 [16:22] <smspillaz> next, you need to define the classes of your plugin
97 [16:23] <smspillaz> so the way things work in compiz is that each plugin is responsible for one or both of two things
98 [16:23] <smspillaz> 1) attaching their own information and hooks to existing objects
99 [16:23] <smspillaz> 2) creating their own objects
100 [16:23] <smspillaz> the vast majority of plugins only do 1)
101 [16:23] <smspillaz> and they usually hook two very important existing object
102 [16:23] <smspillaz> CompWindow and CompScreen
103 [16:24] <smspillaz> so, starting with the second
104 [16:24] <smspillaz> compiz runs per X-screen
105 [16:24] <smspillaz> so, this means that CompScreen is kind of like the "master class" where everything relating to everything going on on screen happens
106 [16:24] <smspillaz> CompWindow is a representation of some managed X11 window
107 [16:25] <smspillaz> (and believe me, there are a lot of them, see xwininfo -root -tree for how much there is to manage)
108 [16:25] <smspillaz> now each plugin works by attaching their own structures to those core objects
109 [16:25] <smspillaz> so if you defined a MoveLeftScreen as attaching to CompScreen
110 [16:25] <smspillaz> there would be one MoveLeftScreen per CompScreen
111 [16:26] <smspillaz> same thing with MoveLeftWindow
112 [16:26] <smspillaz> this allows you to store data and functions on those core structures
113 [16:26] <smspillaz> so, for moveleft, you might want to track if you've moved a window already, and if it has moved since you've moved it
114 [16:26] <smspillaz> so you would store that information in MoveLeftWindow
115 [16:27] <smspillaz> the actual attaching
116 [16:27] <smspillaz> ok
117 [16:27] <smspillaz> so the actual attaching is done by a special class called PluginClassHandler
118 [16:27] <smspillaz> it's basically a template class that sets up some special indexes in the base object and attaches your class to it
119 [16:28] <smspillaz> so that, whenever you want to get your own data for the base object, you just call MoveLeftWindow::get (CompWindow *)
120 [16:28] <smspillaz> so in constructing your MoveLeftWindow, you'll get something like:
121 [16:28] <smspillaz> class MoveLeftWindow :
122 [16:28] <smspillaz> public PluginClassHandler <MoveLeftWindow, CompWindow>,
123 [16:28] <smspillaz> public WindowInterface
124 [16:28] <smspillaz> {
125 [16:28] <smspillaz> }
126 [16:28] <smspillaz> etc
127 [16:28] <smspillaz> (See the handout)
128 [16:29] <smspillaz> the WindowInterface is for interfacable functions and will be explained in a bi
129 [16:29] <smspillaz> so now that you've got your MoveLeftScreen and MoveLeftWindow defined as classes attaching to the relevant core structures
130 [16:29] <smspillaz> there are a few final things to do
131 [16:29] <smspillaz> the first is to define a VTable for your plugin
132 [16:30] <smspillaz> this tells core how to load and what "attaching classes" to initialize when objects are created
133 [16:30] <smspillaz> we have templates for the most common usecases
134 [16:30] <smspillaz> so, you'd have
135 [16:30] <smspillaz> class MoveLeftPluginVTable :
136 [16:30] <smspillaz> public CompPlugin::VTableForScreenAndWindow <MoveLeftScreen, MoveLeftWindow>
137 [16:31] <smspillaz> {
138 [16:31] <smspillaz> public
139 [16:31] <smspillaz> bool init ();
140 [16:31] <smspillaz> }
141 [16:31] <smspillaz> the only thing yout need to put in your init function for now is a core ABI version check
142 [16:31] <smspillaz> eg
143 [16:31] <smspillaz> if (CompPlugin::checkPluginABI ("core", CORE_ABIVERSION)) return true; else return false;
144 [16:32] <smspillaz> and finally, a extern C object definition for core to look up the VTable on plugin load
145 [16:32] <smspillaz> and like all good things, we have a macro for that
146 [16:33] <smspillaz> COMPIZ_PLUGIN_20090315 (MoveLeftPluginVTable, moveleft);
147 [16:33] <smspillaz> note the use of "moveleft" again
148 [16:33] <smspillaz> that is *crucial*
149 [16:33] <smspillaz> since the library is going to be named "moveleft" and core will be loading a plugin called "moveleft"
150 [16:33] <smspillaz> so its going to be looking for the right symbol
151 [16:33] <smspillaz> As a quick aside, I've been asked to explain what CCSM is
152 [16:34] <smspillaz> in fact, I should probably explain some of the other compiz modules
153 [16:34] <smspillaz> so "compizconfig" == our library to handle configuration and desktop integration amongst different settings backends (eg ini, dconf, gconf, kconfig4)
154 [16:35] <smspillaz> "ccsm" == "compizconfig-settings-manager" which is a tool to adjust all the settings in compiz (seriously, there are tons)
155 [16:35] <smspillaz> "core" == the core executable of compiz, where the base window management logic and API comes from
156 [16:35] <smspillaz> ok, so back to plugins
157 [16:36] <smspillaz> once you have checked off implementing your MoveLeftScreen, MoveLeftWindow, MoveLeftPluginVTable, COMPIZ_PLUGIN_20090315 etc
158 [16:36] <smspillaz> and #included <core/core.h>
159 [16:36] <smspillaz> you now have an installing plugin!
160 [16:36] <smspillaz> however, it doesn't really do all that much
161 [16:36] <smspillaz> so lets get on to something more interesting
162 [16:37] <smspillaz> what about being able to "plug-in" to things that core or other plugins do
163 [16:37] <smspillaz> ah, QUESTION: how can we make sure there isn't another plugin called "moveleft"
164 [16:37] <smspillaz> well, the simple answer to that is, you don't
165 [16:37] <smspillaz> there aren't too many compiz plugins around, but if a plugin with the same name is already loaded then yours fails to load
166 [16:38] <smspillaz> ok, back to being able to plugin-in to things
167 [16:38] <smspillaz> so, as I was saying a bit before, we have another special thing in compiz called "wrapable interfaces"
168 [16:39] <smspillaz> these are basically just call chains of function objects in doubly linked lists
169 [16:40] <smspillaz> when you thing you are calling some core function that was implemented in an "interfacable way" you are actually just calling a function which increments the linked list counter by 1 and calls the next function in the list
170 [16:40] <smspillaz> the convention is that at the end of each of the plugin's function calls, they will call the same core function again, which increases the function counter, calls the next function and so forth
171 [16:41] <smspillaz> this allows us to, on each core function call, call lots of other functions at the same time
172 [16:41] <smspillaz> So the first thing you would have seen in the MoveLeftWindow definition was that we inherited a class called "WindowInterface"
173 [16:42] <smspillaz> this is the "Interface class" to all of these Intefacable functions
174 [16:42] <smspillaz> so if you have a look in core/include/window.h, you will see all the functions that plugins can hook
175 [16:42] <smspillaz> by inheriting this class you are said to be "implementing" this interface
176 [16:43] <smspillaz> by default, the functions in WindowInterface all do nothing, but that is because they are all virtual!
177 [16:43] <smspillaz> so to change that, you overload one of the functions
178 [16:43] <smspillaz> for example, void moveNotify (int, int, bool); is a function that tells us when a window has moved and by how much
179 [16:44] <smspillaz> so if we implement a function like that in our MoveLeftWindow class which inherits WindowInterface, we will have implemented that
180 [16:44] <smspillaz> next, in the MoveLeftwindow constructor, we have a call to WindowInterface::setHandler (window);
181 [16:45] <smspillaz> what this does, is set the handler of the interface class that we inherited to the base class that owns the function
182 [16:45] <smspillaz> so that now whenever we call the base class function
183 [16:45] <smspillaz> our function will be called first
184 [16:46] <smspillaz> then functions from the previously loaded plugin
185 [16:46] <smspillaz> etc etc
186 [16:46] <smspillaz> until you get to the main function in the class
187 [16:46] <smspillaz> ok, another question!
188 [16:46] <smspillaz> QUESTION: so, can i write a separate MoveLeft function, embed in Window.h, and then call n override it whenever n wherever i want?
189 === dholbach_ is now known as dholbach
190 [16:47] <smspillaz> So, I'm not too sure what is meant by this, but if you mean adding a new wrapable function to core, I am afraid that is out of the scope of this tutorial
191 [16:47] <smspillaz> plugins should generally only overload the functions in the interface classes
192 [16:48] <smspillaz> anyways, interfaces are explained a bit more in the document I posted
193 [16:48] <smspillaz> next up: options
194 [16:48] <smspillaz> so say you've interfaced CompWindow::windowNotify from WindowInterface
195 [16:48] <smspillaz> so now whenever someone else calls window->windowNotify (), MoveLeftWindow::windowNotify is also called
196 [16:49] <smspillaz> and you've handled the CompWindowNotifyMap there to loop over all windows in screen->windows () (eg, loop over an std::list) and call w->move (x, y, immediate) to move them to the left
197 [16:50] <smspillaz> but now, you want to play with an option whereby it actually moves windows to the right instead of the left!
198 [16:50] <smspillaz> so you need to go back into your moveleft.xml.in and add some information about this option
199 [16:50] <smspillaz> so <option name="right" type="bool">
200 [16:50] <smspillaz> <_short>Move right</_short>
201 [16:50] <smspillaz> <_long>Do the wrong thing </_long>
202 [16:51] <ClassBot> There are 10 minutes remaining in the current session.
203 [16:51] <smspillaz> <default>false</default>
204 [16:51] <smspillaz> </option>
205 [16:51] <smspillaz> that defines the option, with the default value of false
206 [16:51] <smspillaz> now, in your MoveLeftScreen make sure you inherit MoveleftOptions (note the small case l) to get access to autogenerated code from this option
207 [16:52] <smspillaz> ok, so now here is where it gets funky
208 [16:52] <smspillaz> that options code is owned by MoveLeftScreen
209 [16:52] <smspillaz> so you need to MoveLeftScreen *mls = MoveLeftScreen::get (screen) in your ::windowNotify
210 [16:53] <smspillaz> then, you want to read the option to see what it says
211 [16:53] <smspillaz> so for "right" that would be
212 [16:53] <smspillaz> mls->optionGetRight ()
213 [16:53] <smspillaz> and it returns true or false depending on the option value
214 [16:53] <smspillaz> now, here is how the generation code works
215 [16:53] <smspillaz> first you have optionGet, which is prepended to call getters
216 [16:54] <smspillaz> then you have "Right" right came from "right" in the xml file
217 [16:54] <smspillaz> so the parser replaces underscores with CamelCase
218 [16:54] <smspillaz> so if you had right_foo
219 [16:54] <smspillaz> it would be come
220 [16:54] <smspillaz> optionGetRightFoo ()
221 [16:54] <smspillaz> Ok, cool so now you've read the option
222 [16:54] <smspillaz> so with some simple math
223 [16:54] <smspillaz> and that skeleton
224 [16:55] <smspillaz> you should be able to make everything go to the left when a new window is mapped
225 [16:55] <smspillaz> or at your choosing
226 [16:55] <smspillaz> go to the right
227 [16:55] <smspillaz> I'll open the floor to questions
228 [16:55] <smspillaz> ok
229 [16:55] <smspillaz> QUESTION: since you mentioned compiz 0.9 written for Ubuntu, do you use any distro specific API implementations which may break if I write a plugin for, say, Arch?
230 [16:55] <smspillaz> Good question
231 [16:55] <ClassBot> There are 5 minutes remaining in the current session.
232 [16:55] <smspillaz> so, compiz 0.9 was written independently, and has only been started to be used for unity until early this year
233 [16:56] <smspillaz> so it is still an upstream project
234 [16:56] <smspillaz> and as such I keep the API consistent between all version
235 [16:56] <smspillaz> there used to be an API inconsistency with the glib mainloop stuff, but that has been upstreamed
236 [16:56] <smspillaz> any other questions?
237 [16:57] <smspillaz> (I might just paste again those documents I'm referring to in case you missed them)
238 [16:57] <smspillaz> http://smspillaz.ucc.asn.au/unity/compiz_arch/compiz_arch.pdf
239 [16:57] <smspillaz> and
240 [16:57] <smspillaz> http://smspillaz.ucc.asn.au/unity/compiz_arch/writing.odt
241 [16:57] <smspillaz> QUESTION: What happened to the compiz mindcontrol?
242 [16:57] <smspillaz> I love it
243 [16:58] <smspillaz> that project would be cool, except that the developer with that idea didn't cobble together the funds to buy a headset for that
244 [16:58] <smspillaz> plus it requires shaving your head
245 [16:58] <smspillaz> which I would never do since I have awesome hair
246 [16:58] <smspillaz> any more questions before I wrap it up?
247 [16:59] <smspillaz> ok, well it is 16:59, I should probably wrap it up
248 [16:59] <smspillaz> thanks for attending!
249 [16:59] <smspillaz> now go write some awesome plugins!