[Cairo] Text APIs round 2

[Owen Taylor]

On Wed, 2003-08-13 at 19:49, Keith Packard wrote:
> I think we've converged on the class of acceptable solutions for cairo 
> text.  Here's a specific example of both the FreeType/Fontconfig APIs and 
> the generic (aka 'toy') APIs:
> 
> OS-independent functions:
> 
> 	/* "toy" API to select a font */
> 	void
> 	cairo_select_font (cairo_t *ct, char *family, int slant, int weight);
>
> 	void
> 	cairo_set_font (cairo_t *ct, cairo_font_t *font);
> 
> 	void
> 	cairo_show_text (cairo_t *ct, const unsigned char *utf8);

Is the lack of a 'scale_font' or a size in select_font intentional?

You could say that text is always 1 unit high, but I think that's less
than convenient - people in the simplest way of using Cairo will
probably want to leave the matrix untouched and work with the
default transform.

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

I think you might want to reduce the set of out parameters here
with a judicious structure or two. E.g. the XGlyphInfo
structure of XftTextExtents, or pango_*_extents() pair
of &ink_rect, &logical_rect.

For Pango, my plan for vertical writing is that dy == 0 by
definition, but I guess the convention for Postscript is
that dx == 0 for vertical writing. Doesn't really matter much
for my purposes. I suppose applying a matrix with rotation
in it to a font also gives you dy != 0.

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

I tend to agree with others that the inclusion of the font here
is vaguely annoying. It's not necessary for efficiency, and
not really necessary for correctness. 

(You aren't going to have delicately joined together glyphs in 
different fonts in almost any circumstance. You don't actually 
have delicately joined together glyphs in the *same* font in most 
cases; Script fonts join with overlaps)

Pango uses the position-but-no-font variant of the Xft API.

But not really a huge deal, and a small API without a million
premature variations is definitely good.

> Fontconfig/FreeType API:
> 
> 	cairo_ft_font_t *
> 	cairo_ft_font_create (FcPattern *pattern);
> 
> 	cairo_ft_font_t *
> 	cairo_ft_font_create_scale (FcPattern *pattern, double scale);

What's the relationship between the size in the FcPattern
and the scale parameter?

> 	cairo_ft_font_t *
> 	cairo_ft_font_create_transform (FcPattern *pattern, cairo_matrix_t *transform);

If this a transform that is composed with the current user=>device
transform, like in Postscript's makefont?

> 	cairo_ft_font_t *
> 	cairo_ft_font_create_for_ft_face (FT_Face face);
> 
> 	FT_Face
> 	cairo_ft_font_face (cairo_ft_font_t *ft_font);

I'm not sure that the treatment of sizing here is coherent. 
A FT_Face is tied to the pixel grid, So, I don't really see
how we obtain one independent of a cairo_context_t.

In order to propose something better, I'll need to work through
how Pango would interact with Cairo in detail, an excercise
this margin is too small to contain.

> 	void
> 	cairo_ft_font_destroy (cairo_ft_font_t *ft_font);
> 
> 	cairo_font_t *
> 	cairo_font_from_ft_font (cairo_ft_font_t *ft_font);

[...]

> 	FcPattern *
> 	cairo_ft_font_pattern (cairo_ft_font_t  *ft_font);


[ Win32 font proposal skipped for the moment; I don't know 
  the Win32 API's enough to comment on them in the abstract ]

> 	Should the os-dependent code be limited to functions accepting 
> 	pre-generated font objects?  This would make those APIs much 
> 	simpler.
> 
> 	Should the various scale/transform functions be os-independent and
> 	take a cairo_font_t and manipulate it?  That could reduce 
> 	os-dependent code a bit, or it might just make applications mix
> 	up the calls and confuse everyone.

I'd definitely have the feeling that scale/transform should
be in the generic API. Since they are presumably relative
to the current transform not to the pixel grid, I'm not sure
it's even *possible* to implement them at the font-system
specific layer.

_destroy() as well. The toy API is going to need a generic
way to destroy a cairo_font_t, so it might as well be part
of the public API.

> 	Should we support bitmap fonts at all?

I don't think there is any particular harm API-wise 
in having fonts where calling the get_outline() function gives 
you an empty path. I wouldn't complicate the API for the sake
of bitmap fonts, though. I'd just consider them incredibly
badly behaved, ugly outline fonts.

Regards,
					Owen