GNOME font library RFC

[Lauris Kaplinski <lauris ariman ee>]

Hello

I am planning to start moving gnome-font code from gnome-print into
separate package (gnome-font?). The rough design idea is following:

Font server.
This should keep an eye on hot directories and update its internal font
list, if user drops/deletes some interesting (pfb, ttf) files. It acts as
central font resource, distributing fonts to clients via CORBA.
Possible additional functions:
- It can generate GhostScript fontmap
- It can act as X font server
- It can somehow handle font URL-s

Client side font library.
Maintaining local copy of fonts during client lifetime. Doing all
rendering, plus possibility to import/export raw font data (to include
fonts with documents)


The initial API draft for client (mostly copied from existing font API) is
included in end of document. I am especially interested in special needs
of pango-like multilanguage text handling.
Also - maybe specific font should have rotation parameter - but then
possibly rotation is not enough, and full affine transform would be
better.
I am not sure, how to deal with ligatures. I prefer, if font handles them
internally, as there can be fonts with huge amounts of complex ligatures -
but maybe user program should still have a way to access full
ligature list.

All ideas + critique is welcome

Lauris Kaplinski



API Draft

Problem 1. How to present available fonts in user-manageable way.

Proposal:

GnomeFontFamily
Opaque

GList * gnome_font_get_family_list (const gchar * encoding...)

Arguments: NULL-terminated list of accepted encodings. NULL or "*" if don't
care.
Returns: list of available font families, referenced

All further subclassing is done with static strings

GList * gnome_font_family_get_weights (GnomeFontFamily * family, ...)
GList * gnome_font_family_get_slants (GnomeFontFamily * family, ...)
GList * gnome_font_family_get_stretches (GnomeFontFamily * family, ...)
GList * gnome_font_family_get_variants (GnomeFontFamily * family, ...)
GList * gnome_font_family_get_encodings (GnomeFontFamily * family, ...)

Arguments: GnomeFontFamily
NULL-terminated list of additional constraints, all expressed as string
key-value pairs
"weight", "slant", "stretch", "variant", "encoding"...
Multiple pairs with same key are ANDed, except encodings, which are ORed
Scalar arguments can include extra symbols:
"+bold" - bold or thicker == ">=bold"
">book" - thicker than book
Synonyms are resolved according to current family rules - i.e. usually
"book" == "normal"
Returns: New GList of static strings

Convenience translations:

GnomeFontWeight gnome_font_string_to_weight (const gchar * weight)
GnomeFontSlant gnome_font_string_to_weight (const gchar * slant)
GnomeFontStretch gnome_font_string_to_weight (const gchar * stretch)
GnomeFontVariant gnome_font_string_to_weight (const gchar * variant)
GnomeFontEncoding gnome_font_string_to_encoding (const gchar * variant)

Opposite are family-dependent to allow correct value for synonyms

const gchar * gnome_font_weight_to_string (GnomeFontFamily * family,
	GnomeFontWeight weight)
etc...

GnomeFontMap - unsized font
Opaque

GnomeFontMap * gnome_font_find (GnomeFontFamily * family,
	GnomeFontWeight weight,
	GnomeFontSlant slant,
	GnomeFontVariant variant,
	GnomeFontStretch stretch,
	GnomeFontEncoding encoding);

Arguments: font data. Anything (including family) can be NULL, in which case
sensible default is loaded. Default values for all arguments are:
"Helvetica", "Book", "Normal", "Normal", "Normal", "iso-8859-15"
Returns: Referenced GnomeFontMap object

Accessing members:
GnomeFontFamily * gnome_font_map_get_family (GnomeFontMap * map)
Returns: Referenced font family
const gchar * gnome_font_map_get_family_as_string (GnomeFontMap * map)
Return: Family name
etc... (weight, slant, variant, stretch, encoding)

const gchar * gnome_font_map_get_ps_name (GnomeFontMap * map)
Returns: PostScript name for font

gdouble gnome_font_map_get_ascender (GnomeFontMap * map)
gdouble gnome_font_map_get_descender (GnomeFontMap * map)
gdouble gnome_font_map_get_underline_position (GnomeFontMap * map)
gdouble gnome_font_map_get_underline_thickness (GnomeFontMap * map)

Accessing glyphs

gint gnome_font_map_glyph_from_unicode (GnomeFontMap * map, gint unicode)
gint gnome_font_map_glyph_from_char (GnomeFontMap * map, gint ch)

Glyph operations (all sizes are in 0.001 units)

gdouble gnome_font_map_glyph_ascender (GnomeFontMap * map, gint glyph)
gdouble gnome_font_map_glyph_descender (GnomeFontMap * map, gint glyph)
gdouble gnome_font_map_glyph_lbearing (GnomeFontMap * map, gint glyph)
gdouble gnome_font_map_glyph_rbearing (GnomeFontMap * map, gint glyph)
ArtPoint * gnome_font_map_glyph_advance (GnomeFontMap * map, gint glyph,
	ArtPoint * advance)
ArtDRect * gnome_font_map_glyph_bbox (GnomeFontMap * map, gint glyph,
	ArtDRect * bbox)
const ArtBpath * gnome_font_map_glyph_outline (GnomeFontMap * map,
	gint glyph)

Text operations

GnomeGlyphList * gnome_font_map_translate (GnomeFontMap * map,
	const gchar * text)
Returns: List (array?) of glyphs, corresponding to given character. This
function resolves all ligatures that font support

ArtPoint * gnome_font_map_text_advance (GnomeFontMap * map,
	const gchar * text, ArtPoint * advance)
ArtDRect * gnome_font_map_text_bbox (GnomeFontMap * map, const gchar * text,
	ArtDRect * bbox)
gdouble gnome_font_map_text_position (GnomeFontMap * map,
	const gchar * text, gint position, gboolean inside_ligature)
gdouble gnome_font_map_glyph_kerning (GnomeFontMap * map, gint glyph1,
	gint glyph2)

Misc

gchar * gnome_font_map_get_ps_font (GnomeFontMap * map, gint * length)
Returns: PostScript (type?) font, suitable for sending to printer


GnomeFont - sized font variant, suitable for rendering
Opaque

GnomeFont * gnome_font_find (GnomeFontFamily * family, gdouble size,
	GnomeFontWeight weight,
	GnomeFontSlant slant,
	GnomeFontVariant variant,
	GnomeFontStretch stretch,
	GnomeFontEncoding encoding);
GnomeFont * gnome_font_get_from_map (GnomeFontMap * map, gdouble size)

Accessing members:

GnomeFontFamily * gnome_font_map_get_family (GnomeFont * font)
Returns: Referenced font family
const gchar * gnome_font_get_family_as_string (GnomeFont * font)
Return: Family name
etc... (weight, slant, variant, stretch, encoding)
GnomeFontMap * gnome_font_get_map (GnomeFont * font)

const gchar * gnome_font_get_ps_name (GnomeFont * font)
Returns: PostScript name for font
const gchar * gnome_font_get_x_name (GnomeFont * font)
gdouble gnome_font_get_size (GnomeFont * font)

gint gnome_font_get_ascender (GnomeFont * font)
gint gnome_font_get_descender (GnomeFont * font)
gint gnome_font_get_underline_position (GnomeFont * font)
gint gnome_font_get_underline_thickness (GnomeFont * font)

Accessing glyphs

gint gnome_font_glyph_from_unicode (GnomeFont * font, gint unicode)
gint gnome_font_glyph_from_char (GnomeFont * font, gint ch)

Glyph operations (all sizes are in units (usually pixels))

gint gnome_font_glyph_ascender (GnomeFont * font, gint glyph)
gint gnome_font_glyph_descender (GnomeFont * font, gint glyph)
gint gnome_font_glyph_lbearing (GnomeFont * font, gint glyph)
gint gnome_font_glyph_rbearing (GnomeFont * font, gint glyph)
GdkPoint * gnome_font_glyph_advance (GnomeFont * font, gint glyph,
	GdkPoint * advance)
ArtIRect * gnome_font_glyph_bbox (GnomeFont * font, gint glyph,
	ArtIRect * bbox)

Text operations

GnomeGlyphList * gnome_font_translate (GnomeFont * font,
	const gchar * text)
Returns: List (array?) of glyphs, corresponding to given character. This
function resolves all ligatures that font support

GdkPoint * gnome_font_text_advance (GnomeFont * font,
	const gchar * text, GdkPoint * advance)
ArtIRect * gnome_font_text_bbox (GnomeFont * font, const gchar * text,
	ArtIRect * bbox)
gint gnome_font_text_position (GnomeFont * font,
	const gchar * text, gint position, gboolean inside_ligature)
gint gnome_font_glyph_kerning (GnomeFont * font, gint glyph1,
	gint glyph2)

Rendering

gnome_font_render_glyph_graymap (GnomeFont * font, gint glyph,
	guchar * pixels, gint width, gint height, gint rowstride)
gnome_font_render_glyph_rgb (GnomeFont * font, gint glyph,
	guchar * pixels, gint width, gint height, gint rowstride,
	guint32 color)
gnome_font_render_glyph_rgba (GnomeFont * font, gint glyph,
	guchar * pixels, gint width, gint height, gint rowstride,
	guint32 color)
gnome_font_render_glyph_pixmap_and_mask (GnomeFont * font, gint glyph,
	GdkWindow * window, GdkPixmap ** pixmap, GdkBitmap ** bitmap)

gnome_font_render_text_graymap (GnomeFont * font, const gchar * text,
	guchar * pixels, gint width, gint height, gint rowstride)
gnome_font_render_glyph_rgb (GnomeFont * font, const gchar * text,
	guchar * pixels, gint width, gint height, gint rowstride,
	guint32 color)
gnome_font_render_text_rgba (GnomeFont * font, const gchar * text,
	guchar * pixels, gint width, gint height, gint rowstride,
	guint32 color)
gnome_font_render_text_pixmap_and_mask (GnomeFont * font, const gchar * text,
	GdkWindow * window, GdkPixmap ** pixmap, GdkBitmap ** bitmap)

Misc

GdkFont * gnome_font_get_gdk_font (GnomeFont * font)
NB! this function should invoke X font lookup, to which (hopefully)
server-side XFS responds, rendering to X exact representation of given
font.

const gchar * gnome_font_get_uri (GnomeFont * font)
Returns URI, if present, from where client can fetch that font