Designing a library that's easy to use

a case study of the cairo graphics library http://cairographics.org

Carl Worth <cworth@redhat.com>

API Design

Some guiding principles

Keep the programmer's brain free

Exponential documentation lookup

Help the programmer get it right the first time

Being consistent

Help the programmer fix it quick when it's wrong

Help the programmers read their own code

Help the programmers read their own code

Rendering model of cairo

Expressive power of cairo's model

Not a lot of objects to juggle in cairo

/* cc `pkg-config --cflags --libs cairo-png` simple.c -o simple */
#include 

main (void)
{
    cairo_t *cr;
    cairo_surface_t *surface;

    surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, 500, 500);
    cr = cairo_create (surface);

    cairo_move_to (cr, 50, 50);
    cairo_curve_to (cr, 70, 700, 300, -100, 450, 400);

    cairo_set_line_width (cr, 40);
    cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND);
    cairo_set_source_rgba (cr, 1.0, 0.0, 0.0, 0.5); /* translucent red */
    cairo_stroke (cr);

    cairo_surface_write_to_png (surface, "simple.png");

    cairo_destroy (cr);
    cairo_surface_destroy (surface);

    return 0;
}

What worked well in the cairo process?

What didn't work well?

Background on cairo backends

June  2002: First commit (xlib backend)
Feb   2003: Add image backend
Oct.  2003: Add PostScript backend
Feb.  2004: Add XCB backend
April 2004: Add glitz backend
Nov.  2004: Add win32 backend
Jan.  2005: Add PDF and Quartz backends
Dec.  2005: Add SVG, BeOS, and DirectFB backends

Background on cairo committers

June  2002: First commit by Carl Worth
Aug.  2002: First commit by Keith Packard
April 2003: First commit by Owen Taylor
June  2006: 36 total committers (12 active in last 3 months)

Breakdown of cairo authorship by commits

 1288 Carl Worth
  143 Owen Taylor
  110 Kristian Høgsberg
   79 Emmanuel Pacaud
   69 David Reveman
   62 Keith Packard
   49 Billy Biggs
   40 Behdad Esfahbod
   39 Christian Biesinger
   34 Vladimir Vukicevic
   34 Dave Beckett
   33 Jeff Muizelaar
   24 Tor Lillqvist
   23 罗晶华 (Jinghua Luo)
   17 Anders Carlsson
   11 Bertram Felgenhauer
  (99 from others)

Breakdown of cairo releases

2005-08-24: Release 1.0.0
2005-10-03: Release 1.0.2
2006-03-15: Release 1.0.4
2006-06-27 16:59:00: Release 1.2.0

Sometimes it's hard to predict the future

  commit d334c8bf8f6814976ba12a31643917d0ede86088
  Author: Carl Worth 
  Date:   Tue Sep 17 13:38:55 2002 +0000

    Cleaned up polygon tessellation code. Fixes all known problems.