[Cairo] Text API proposal

[Carl Worth]

OLS was a lot of fun, and Keith and I were able to put some good time
into the Cairo API and implementation.

We audited the API for warts[*], fixed a few numerical problems in the
implementation, and sketched out a plan for text.

My current tree is still churning as I prepare the new backend
abstraction framework. While I'm doing that, I thought I'd let
everyone take a look at the text API and give feedback.

Here's the proposed primary Cairo text functionality which fits in 7
functions. There's a "toy" API here so people like me can succeed in
getting a string on the screen. Then there's a real API for placing
individual glyphs at absolute locations so that people like Pango/OOo
developers can get their work done:

	/* Font/Text functions */

	void
	cairo_select_font (cairo_t *ct, char *name);

	void
	cairo_set_font (cairo_t *ct, cairo_font_t *font);

	void
	cairo_show_text (cairo_t *ct, const unsigned char *utf8);

	void
	cairo_text_extents (cairo_t *ct,
	                    const unsigned char *utf8,
	                    double *x, double *y,
	                    double *width, double *height,
	                    double *dx, double *dy);

	typedef struct cairo_glyph {
	    cairo_font_t *font;
	    FT_UInt      id;
	    double x;
	    double y;
	} cairo_glyph_t;

	void
	cairo_show_glyphs (cairo_t *ct, cairo_glyph_t *glyphs, int num_glyphs);

	void
	cairo_text_path  (cairo_t *ct, const unsigned char *utf8);

	void
	cairo_glyph_path (cairo_t *ct, cairo_glyph_t *glyphs, int num_glyphs);

	/* XXX: Does anyone really need a cairo_glyph_extents function? */

Notice that a Freetype datatype is exposed, (and fontconfig is
implicit in that the "name" parameter will be interpreted as a
fontconfig pattern string). That theme continues in the remaining new
cairo_font_t functions. Most of these just exist to let users get at
what they need in order to be able to call fontconfig/Freetype
directly:

	/* Font manipulation */

	cairo_font_t *
	cairo_font_create (FcPattern *pattern);

	cairo_font_t *
	cairo_font_create_scale (FcPattern *pattern, double scale);

	cairo_font_t *
	cairo_font_create_transform (FcPattern *pattern, cairo_matrix_t *transform);

	cairo_font_t *
	cairo_font_create_for_ft_face (FT_Face face);

	void
	cairo_font_destroy (cairo_font_t *font);

	cairo_font_t *
	cairo_font_scale (cairo_font_t *font, double scale);

	cairo_font_t *
	cairo_font_transform (cairo_font_t *font, cairo_matrix_t *transform);

	FT_Face
	cairo_font_ft_face (cairo_font_t *font);

	FcPattern *
	cairo_font_pattern (cairo_font_t *font);

	FcCharSet *
	cairo_font_char_set (cairo_font_t *font);

	double
	cairo_font_ascent (cairo_font_t *font);

	double
	cairo_font_descent (cairo_font_t *font);

	double
	cairo_font_height (cairo_font_t *font);

	double
	cairo_font_max_advance_width (cairo_font_t *font);

So let us know what you think. Especially if you have a real
application that needs something that's not here.

-Carl

[*] This is buried here in the vain hope that I can slip a couple of
API changes past without anyone complaining, (we'll see who actually
reads this far):

1) Right now, there are a bunch of "cairo_get_*" functions which is a
   gratuitous deviation from the PostScript current* operator
   names. The biggest wart is the function "cairo_get_current_point"
   which can't make up its mind which convention to follow. And, since
   "cairo_get_point" doesn't work, we propose to use
   "cairo_current_point" and change all other "cairo_get_*" functions
   to "cairo_current_*". So sorry that the function names get
   longer. Some of you might need to save up and buy new terminal
   emulators with more columns.

2) After an initial idea from my wife, Keith had the idea to rename
   "cairo_surface_*" to "cairo_papyrus_*". The metaphor is more direct
   in addition to being thematic. But of course, the coolest part of
   that is that the number of characters doesn't change at all.

-- 
Carl Worth                                        
USC Information Sciences Institute                      cworth at isi.edu