Progress on generating Python API docs from introspection

The Docs hackfest in Brno is nearing to an end and I think enough progress has happened on generating API reference from introspection to warrant a report.

To see the current state, check the Telepathy-GLib reference generated here for Python.

Tomorrow morning will work on fixing some issues in the GIR files such as enum docs not making to it and then I will head home.

I'm not likely to work further on this, so if you think it can be of use to you, please consider lending a hand and contribute bugfixes and features. And if you don't like the design or the layout, just change it :)

Hope you have as much fun with this as I have had!

Once more, thanks to the GNOME Foundation, Red Hat and Collabora for sponsoring this work.

Below you can get a glance of what has been progressed on during these days, here is the changelog:

• Add some more stuff to Enum pages
• Display the hierarchy tree for classes
• Install the Mako template files
• Add AM_CHECK_PYMOD macro and use it to check for Mako
• Remove stale DocBook files
• Properly link to property pages
• Fix names of xref links
• Move constructor example to follow the class doc body
• Properly link to signal pages
• Fix the id of signal pages for Python
• Qualify the class name in the constructor with the module name
• Add links to properties in the constructor
• Fix link
• Show how to construct instances in the Class page
• Add details for properties in Python
• Add param information to signal pages in Python
• Implement intra-namespace cross references
• Use instances of MallardFormatter* instead of class methods
• Remove some occurrences of empty Returns: lines
• use True and False instead of %TRUE and %FALSE
• Remove module and class from the function signature
• Use template caching
• Use None instead of %NULL
• Use the ctype for the return type in signatures
• Display Returns: even if there's no args
• Update expected, some whitespace was removed
• Add Since: tag to classes
• Add Since: tag to mallard docs
• Add function argument docs to the C template
• Add argument docs to the Python template
• Don't instantiate MallardFormatter for unknown languages
• Update expected mallard for the doc tests

Docs hackfest: starting point

Have spent my trip to Brno undusting and rebasing the branch in gobject-introspection that uses to Mako templates to generate Mallard code from GIR files.

Here you can see how looks like the generated documentation for the Account class in the TelepathyGLib typelib for Python, and here is the one generated with gtk-doc.

As can be seen, there's still a long way to get even close to the gtk-doc level, but it's a very promising start.

Documentation hackfest in Brno 2012

Tomorrow I'm taking the train to Brno to participate in the documentation hackfest, with plans to continue the work on generating API documentation from the GIR files that are generated by GObject Introspection.

I will be continuing the work that a bunch of us started in Berlin during the GObject Introspection hackfest last year.

Will be giving as well a workshop on GNOME application development with Python and GObject Introspection as part of the Developer Conference 2012 that Red Hat is organizing there.

Thanks to the GNOME Foundation for sponsoring my accommodation, to my employer Collabora for sponsoring my time there and Red Hat for sponsoring the venue and the food.

PyGObject gets a splash of new blood

Things as they are, few hackers get to work on the same project their whole life. No matter how deep one has been involved in a project, and how much effort was put in, there are many reasons why at some point one may decide to distance from it.

For different reasons, the people who have been maintaining PyGObject for the last couple of years (since the move to introspection) aren't currently using it much any more, which isn't ideal because it means they can allocate less time to maintenance and also lack the guidance of their own motivation.

Fortunately for PyGObject, a bunch of heroic hackers have stepped forward to take the responsibility of maintaining it:

• Martin Pitt
• Paolo Borelli
• Ignacio Casal Quintero
• Sebastian Pölsterl

For now I remain listed in the .doap file, but as I'm not using PyGObject myself any more (even though Collabora sponsors some of my time working on PyGObject), my involvement will be limited to occasional patches and code reviews as I find time.

My thanks and admiration to those who have maintained PyGObject in the past:

• Johan Dahlin
• James Henstridge
• John (J5) Palmieri
• Simon van der Linden
• Zach Goldberg
• Gustavo J Carneiro
• Paul Pogonyshev
• Gian Mario Tagliaretti

To end, just note that Martin is using his canonical.com address, so I assume that Canonical is sponsoring his work as maintainer upstream, so kudos to them as well.

WebGL support in WebKit-Clutter

In a previous post I wrote about how we can use accelerated compositing in the Clutter port of WebKit in order to take advantage of the graphics hardware when merging media elements into the finalized web page, which can be very dynamic (read: several updates per second) due to JavaScript usage and also because of CSS3 animations.

Another advantage of having the composition happening in the GPU is that whatever elements we render there (hw-accelerated video decoding or WebGL) doesn't need to be brought back to the CPU for composition, which would be very expensive.

For the last few weeks I have been working on a proof of concept of how we could implement the WebGL specification in our port, using Clutter. We cannot take the WebGL implementation that is already in use by the Gtk+, Qt and OSX ports because direct GL access isn't possible with Clutter, so it has taken quite a bit more of work than that. Here you can see the code in action, it's a WebGL canvas being rotated with CSS3:



What I ended up doing was adding a mechanism to Cogl (Clutter's graphics backend that abstracts OpenGL) so that applications could use raw GL to draw into an offscreen framebuffer without disturbing the rest of the application's graphics state, that is managed by Cogl. The branch that implements this is here.

Note that this is a proof of concept, in order to upstream this work we would need to find a way to share more code with the existing WebGL implementation in WebKit and also fix all the hackiness on the Cogl branch.

Other further work includes reducing the frequency with which GL contexts are switched, which should help enormously in GPUs such as Imagination's PVR and ARM's Mali.

To finish, I would like to thank my employer Collabora for allowing me to work on this and share the results, and to the Clutter guys that patiently answered my questions and showed me the right way, specially Robert Bragg and Neil Roberts.

If your company is interested in this, we'll be pleased in working with you, just drop an email to sales@collabora.com.

PyGObject 3.0.3 Released

The Sugar guys are doing great progress porting their code from PyGTK+ to GObject Introspection and they have requested a new stable release, which comes with these goodies:

- Convert all modifier constants to Gdk.ModifierType (Manuel Quiñones)

- Convert all strings to utf-8 encoding when retrieving from TreeModel (Sebastian Pölsterl)

- add test for bytearray variants (John (J5) Palmieri)

- handle NULL arrays correctly for each array type (John (J5) Palmieri)

- Revert "Revert "Fix array termination and size calculation"" (John (J5) Palmieri)

- pygmainloop: avoid lockups if multiple glib.MainLoop exist (Owen W. Taylor)

- Properly chain up to the class that implements a given vfunc. (Tomeu Vizoso)

- Revert "Fix array termination and size calculation" (Tomeu Vizoso)

- Fix array termination and size calculation (Holger Berndt)

- pygi-convert: fix for Pango.Alignment (Daniel Drake)

- pygi-convert: fix for Gtk.Orientation (Daniel Drake)

- Add tests for calling closures (Martin Pitt)

- fix marshaling of arrays of GVariants (Mikkel Kamstrup Erlandsen)

Thanks all for your hard work!

More acceleration support for video in webkit-clutter

The last few days I have been working on reworking how video gets rendered inside a web page in the Clutter port of WebKit, using Clutter-GStreamer. This work is contributed by Collabora and sponsored by Bosch.

Previously, we were doing the same as the Gtk+ port, that is, rendering each frame to a Cairo texture (with whatever format conversion that was needed) which would be then composited along the rest of the page (with Cairo as well). On the Clutter port that big surface would be uploaded to a texture in the GPU side of things and composed along the rest of the stage.

Joone and Gustavo have been working lately on adding accelerated compositing support to the Clutter port (and both will be blogging in the next few days about this work), which means that the page gets split in layers that get sent individually to the GPU where they get composited. Layers can be cached so only the ones that changed need to be re-rendered and re-uploaded.

This reduces dramatically the amount of work that happens on the CPU, so that animations with complex pages are feasible, even those involving video elements during playback, such as this:



Because page composition happens now in the GPU instead of in Cairo, we don't need to copy each frame to a Cairo surface (saving a copy) and don't need either to change the pixel format from whatever GStreamer gave us to whatever Cairo wants.

Another benefit of using Clutter-GStreamer is that alpha pre-multiplication can happen in the GPU (implemented as a shader), saving more CPU.

Furthermore (and more importantly), we can use standard GStreamer elements that use the hardware for decoding. Given the proper hardware and driver support, frames could be placed directly where the GPU can find them when compositing the page.

Hopefully this will make the Clutter port of WebKit more appealing for mobile platforms, where low-power GPUs are commonly available but the CPU is often taxed by other tasks.

All the code is here: https://gitorious.org/webkit-clutter/webkit-clutter/commits/ac2

Thanks to Bosch and Collabora for allowing me working on this. To know more about Collabora's involvement in WebKit: http://www.collabora.com/projects/webkit/