[Cairo] Text API proposal

Carl Worth cworth at east.isi.edu
Mon Jul 28 17:51:30 PDT 2003

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 */

	cairo_select_font (cairo_t *ct, char *name);

	cairo_set_font (cairo_t *ct, cairo_font_t *font);

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

	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;

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

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

	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

	/* 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);

	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);

	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);

	cairo_font_ascent (cairo_font_t *font);

	cairo_font_descent (cairo_font_t *font);

	cairo_font_height (cairo_font_t *font);

	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.


[*] 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

More information about the cairo mailing list