[Cairo] Text API proposal

[Kai Wetzel]

Hi,

have you considered to get in touch with Raph Levien, David Turner,
Werner Lemberg regarding the font API and maybe forward to
the gs-devel mailing list ?

On Tuesday 29 July 2003 02:51, Carl Worth wrote:
[...]
> 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.

That's one of my main itches with the API proposal: What is the
seperation between the low-level drivers' responsibilities and the
"shared", high(er)-level parts of the API, e.g. is "show_text" implemented
by the driver and defined to mean exactly what the PostScript "show" operator
does (allowing pass-through) or is it a high-level convenience function which
the driver will see as a call to "show_glyphs" ?

Will exposing the FontConfig pattern (name) in select_font require a
PostScript driver to know (and use, I guess) FontConfig to resolve the
pattern and find a "good match" to use in the PostScript stream ?
This approach seems both underspecified (in terms of how drivers
agree on using the "same" font that was used in layout) as well
as too broad (requiring a lot of work on the side of an individual
driver).

Did you consider adding "display list" support to Cairo ? I think
display lists (in OpenGL, or user-defined operators/words in PostScript,
stored procedures or how you want to call them) are very useful to
allow some optimizations to be performed by the drivers which are
otherwise hard or impossible to do (such as writing dense PostScript or SVG,
caching paths or composits, preserving network bandwidth, etc.)

example display lists functions:

uint (tag) cairo_list_start (CAIRO_ARG); /* start "recording" */
/* operators beeing called on CAIRO_ARG are recorded,
operators that return a value are not allowed here */
void cairo_list_end (CAIRO_ARG); /* end recording */
/* ... */
void call_list (CAIRO_ARG, uint tag); /* execute list */

Any chance ?

> Here's the proposed primary Cairo text functionality which fits in 7
> functions. There's a "toy" API

"convenience functions" :)

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

Where "name" is a Xft pattern including scale/matrix, etc. ?

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

I personally think that only one of the above schemes should
be required at the driver-level (possible ?).

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

This function, along with the "current*" functions, shouldn't
be expected from all drivers, making it possible to have "write-only"
drivers (PostScript, PDF, etc.). Actually it looks like it belongs
to high-level layout, not the rendering part of the API, maybe it
should be provided in the "object-oriented" CairoFont interface
only. 

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

I'd suggest to strip "font", make id a uint32 or even uint, and
get rid of the struct.

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

void
cairo_show_glyphs (CAIRO_ARG, uint*, double*, int num_glyphs);

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

driver-level yes/no ?

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

Is there any chance to change the naming
convection of structs due to popular request at this point (CairoFont) ? 

How will drivers and the high-level layout layer communicate
fonts and font-metrics to match ? Other then that Idon't think Cairo
is the right place for a high-level "object-oriented" font API like
you propose. (But if the seperation of concerns is done well, it
wouldn't hurt, I guess). E.g. I could just use FreeType directly
or let Pango use FreeType directly, no need to go through Cairo
in the layout phase, right ?
[...]
> 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.

Nice! But please consider the driver-issue mentioned above.

Best regards,
kai