Michael's Weblog

PECL/Cairo 0.3.0 released!

As I'm sure you've all been longing to hear, we've finally got around to releasing a new version of PECL/Cairo! This version fixes some bugs, and adds support for some new features available since Cairo 1.10 — notably, support for subsurfaces, which are surfaces that draw onto a part of a larger surface, and for recording surfaces, which record all drawing operations and can then be used as the source for other drawing operations. Also, Mark Skilbeck has added support for Win32 fonts. Also, the FreeType font handling has been improved, and should now give more informative messages when errors occur.

Any questions, comments, bug reports, or contributed code are welcome. Drop us a line on the PECL mailing list, or try #php.pecl on EFNet.

FrOSCon 2011

I'm very pleased to be able to announce that I'll be giving two talks at this year's FrOSCon conference in St Augustin near Bonn in Germany, on the 20th and 21st of August. The first is on the PHP track, and is an overview of the PECL/Cairo extension for PHP.

The second talk is on the main track, and is about Making Software See, where I'll give an introduction to the OpenCV image processing library, including some examples in various popular programming languages.

I'm extremely happy to have been selected both by the main FrOSCon organisers and the PHP track, organised by the PHP Usergroup Dortmund. I hope to see some of you there!

Pango for PHP PECL channel

It occurs to me that though I wrote an introduction post about Pango for PHP, I forgot to mention that it's actually installable using the PECL installer.

 pecl channel-discover pecl.mgdm.net
 pecl install channel://pecl.mgdm.net/Pango-0.1.0

Assuming you have the required development packages installed, it should go off and install it. You may still need to add the

extension=pango.so

line to your php.ini. Hope this helps someone give it a go! As ever, any feedback is welcome.

Android: LinearLayouts, WebViews and black screens

Just making a quick note in case anyone else is searching for the same problem.

I have an app with an activity which previously was just a WebView, but I wanted to add some other widgets above the WebView as well, so I made an XML layout and wrapped the WebView in a LinearLayout. Upon using this as the content view, my WebView went black. Completely. This resulted in a bit of frantic Googling, whereupon I discovered that it wasn't an unusual problem. Most of the solutions revolved around making sure the LinearLayout's width and height were both set to fill_parent — this didn't work for me. A little bit of investigation then lead me to discover that I'd forgotten to set the orientation on the LinearLayout. Once I'd set that, everything started working fine. A silly problem, but quite often it's the silly ones that take the most time to figure out.

Using Pango for PHP: a taster

The PECL/Cairo library is pretty good at drawing vector graphics (in our opinion, as the developers, at least!), but one thing it's not able to do by itself is draw text with mildly advanced layout. It has the CairoContext::showText() function, but that doesn't really let you do anything GD can't. That's because the developers of the Cairo library decided to let another more specialised library handle the job of text layout. Much of the time, the library that gets used for this is Pango. It has several bindings already for most popular languages on Unix-like platforms. It's quite capable, and able to lay out text while taking care of things such as paragraph alignment, line breaking, bold/italic text, justification, and various other features. In this post, I intend to give a little tour of some of its features.

Quite a while ago now, I wrote an extension to wrap Pango for PHP. It's available on its Github repository. It's not available on PECL right now, but you can check it out from there and install it using the normal method. (Sorry Windows users, I've not had time to test it out on there, and likely won't any time soon. Patches are welcome, though...). It requires that the Pango headers are installed, and that PECL/Cairo is already installed into PHP.

Once installed, you can use it with Cairo. The best way to show it off is probably some example code:

 
<?php
header("Content-Type: image/png");
/* Make a 300x300px image surface */
$s = new CairoImageSurface(CairoFormat::ARGB32, 300, 300);
$c = new CairoContext($s);
 
/* Set the background to white */
$c->setSourceRGB(1, 1, 1); 
$c->paint();
 
/* Let's draw using black 'ink' */
$c->setSourceRGB(0, 0, 0); 
 
/* Make a Pango layout, set the font, then set the layout size */
$l = new PangoLayout($c);
$desc = new PangoFontDescription("Bitstream Charter 28");
$l->setFontDescription($desc);
$l->setWidth(250 * PANGO_SCALE);
 
/* Here, we use Pango markup to make part of the text bold */
$l->setMarkup("Hello <b>world!</b> Here is a rather long paragraph which should get wrapped");
 
/* Draw the layout on the surface */
$l->showLayout($c);
 
/* Output the PNG to the browser */
$s->writeToPng("php://output");
 

If all goes to plan, you should see a PNG in your browser with the above text.

Going through each step, firstly we set up the Cairo surface to draw on, and the context we use to draw with. Once we have done that, we can create a PangoLayout object which lets us draw the text we require. The PangoLayout is passed a context, so it can invoke the drawing methods itself to draw the text. We pass the PangoLayout a PangoFontDescription object, which lets us choose from the fonts already installed on the machine. This means that we don't need to concern ourselves with the paths to actual TrueType font files, or similar - the fonts are resolved by Fontconfig or whatever system is available on your machine.

Next, we set the width of the layout. We can also set a height, but I haven't bothered on this occasion. This lets Pango know where to wrap the text - if we don't set this, it won't bother, which may result in text falling off the edge of the image. You may note that the width is multiplied by the PANGO_SCALE - this is because Pango deals in units which are a tiny fraction (1/1024, in fact) of a pixel, in order to handle antialiasing properly. Because we're using a CairoImageSurface, this means that they layout will be 250 pixels wide.

Next up, we set the text to be drawn. There are two methods available to do this; PangoLayout::setText() is used when we just want to render text with no formatting instructions. In this case, I've opted for the PangoLayout::setMarkup() method, which lets me use Pango's markup language to make part of the text bold. Many other attributes can be changed using this markup, which has shortcuts that somewhat resemble HTML.

Finally, the call to showLayout() renders the layout onto the surface. You can also render just a path, using layoutPath(), which sets the path on the surface so you can then use more advanced effects with Cairo. The layout is drawn using whatever the current source is on the Cairo context, so you can render using flat colours, gradients, other source images, or whatever takes your fancy. Additionally, this means that any transformations you have set on the Cairo context also take effect, allowing you to rotate, scale, shear and otherwise distort the text.

It probably looks a little complex just to write some text on an image, but it is rather flexible. This flexibility is handy when you consider that Cairo can render more than just PNG images; PDFs, PostScript and SVG are also easy to create. I hope that this post may inspire someone else to give it a try. Feedback and reports of issues are always welcome.