API Design

• API design is hard stuff
  • You won't get it all right
  • You get to live with the mistakes for a long time
  • Few tasks are harder than inventing names
• API design is worth doing
  • Look at the time we spend rewriting garbage interfaces
  • Less distance between developers and users is an advantage when doing library work
• So remember that there's more to coding a library than just getting it working

Some guiding principles

• Keep the programmer's brain free
• Help the programmer get it right the first time
• Help the programmer fix it quick when it's wrong
• Help the programmers read their own code

Keep the programmer's brain free

As much as we'd like for the programmer to just sit and admire our lovely library---there's usually some other motive for the coding session
• Prevent exponential documentation lookup
• The name of the game is elegance:

  Elegance == Expressive Power:Complexity

  (Limiting the library's scope helps)

Exponential documentation lookup

int XDrawLine(Display *display, Drawable d, GC gc,
              int x1, int y1, int x2, int y2);

Display *XOpenDisplay(char *display_name);

$ man -k Drawable
Drawable: nothing appropriate.

Window XCreateWindow(Display *display, Window parent,
       int x, int y, unsigned int width, unsigned int height,
       unsigned int border_width, int depth, unsigned int class,
       Visual *visual, unsigned long valuemask,
       XSetWindowAttributes *attributes);

Window XCreateSimpleWindow(Display *display, Window parent,
       int x, int y, unsigned int width, unsigned int height,
       unsigned int border_width, unsigned long border,
       unsigned long background);

#xorg poor_coder: After a week, I finally got it to
      compile, but I still can't see anything! *&@#$

Help the programmer get it right the first time

• Be consistent
• Be careful of abbreviations
• Reduce number of function arguments

  cairo_pattern_add_color_stop_rgba (cairo_pattern_t *,
                double, double, double, double, double);
  

Being consistent

• Use terms consistently (beware subtle distinctions)
  • XFreePixmap vs. XDestroyWindow
  • cairo_get_target vs. cairo_current_operator vs. cairo_get_current_point
• Be careful with StudlyCaps:
  • GSList GdkRgbCMap GdkXEvent GdkWChar
• And stay away from Studly_Caps!
  • Bonobo_RegistrationResult vs. BonoboActivationPlugin
  • FT_GlyphSlot vs. FT_Face_Internal

Help the programmer fix it quick when it's wrong

• Let the compiler help the programmer when possible (catching bugs sooner helps everybody)
• enum can be much better than char* for example
  • Extensibility doesn't always justify delaying checks until run-time
  • We can often get extensibility via a free software license or dynamic linking
• Embrace the type system rather than actively subverting it:

  FcPatternAddInteger (FcPattern*, const char*, int)
  FcPatternAddDouble (FcPattern*, const char*, double)
  FcPatternAddString (FcPattern*, const char*, const FcChar8*)
  FcPatternAddMatrix (FcPattern*, const char*, const FcMatrix*)
  FcPatternAddBool (FcPattern*, const char*, FcBool)
  

Help the programmers read their own code

• A nice readable prototype:

  gtk_box_pack_start (GtkBox *box, GtkWidget *child,
                      gboolean expand, gboolean fill,
                      guint padding)
  

Help the programmers read their own code

• Can result in inscrutable code:

  gtk_box_pack_start (box, child, TRUE, FALSE, 0);
  

• enum instead of Boolean can help, (some open opportunities for static checks here)
• Another approach is to move the helpful names from the arguments in the prototype to the function name where they will appear in the final code.

Rendering model of cairo

• 1 fundamental rendering operation
• 5 variations differing only in mask construction:

cairo_paint();
cairo_stroke();
cairo_fill();
cairo_show_glyphs(); cairo_show_text();
cairo_mask(); cairo_paint_with_alpha ();

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?

• We took a lot of time before 1.0, (not always possible in practice of course)
• Before the 1.0 release, but after everything was "working" we distilled the new imaging model
• This process removed some major flaws---the old implementation had no consistent model. It would have been a nightmare to ever explain it.
• Extremely valuable to have the core "architectural team" meet in person (for the first time) for about a week to hash it all out, (Carl Worth, Keith Packard, Owen Taylor, David Reveman, Kristian Høgsberg)

What didn't work well?

• We took a lot of time before 1.0...
• The cairo maintainer can be a bit too picky sometimes.

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.