procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve commentary in font.h

Browse source 
* src/font.h (struct font, struct font_driver): Fix typos and
wording in comments.  Document all driver methods.
This commit is contained in:
Eli Zaretskii 2019-01-05 10:28:34 +02:00
parent a058edae5b
commit 0ecff00bc1
1 changed files with 33 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
src/font.h
View file

@ -284,7 +284,7 @@ struct font
/* By which pixel size the font is opened. */
int pixel_size;
/* Height of the font. On X window, this is the same as
/* Height of the font. On X window system, this is the same as
(font->ascent + font->descent). */
int height;
@ -293,7 +293,7 @@ struct font
int space_width;
/* Average width of glyphs in the font. If the font itself doesn't
have that information but has glyphs of ASCII characters, the
have that information, but has glyphs of ASCII characters, the
value is the average width of those glyphs. Otherwise, the value
is 0. */
int average_width;
@ -576,8 +576,8 @@ struct font_driver
cons whose cdr part is the actual cache area. */
Lisp_Object (*get_cache) (struct frame *f);
/* List fonts exactly matching with FONT_SPEC on FRAME. The value
is a list of font-entities. The font properties to be considered
/* List fonts exactly matching FONT_SPEC on FRAME. The value is
a list of font-entities. The font properties to be considered
are: :foundry, :family, :adstyle, :registry, :script, :lang, and
:otf. See the function `font-spec' for their meanings. Note
that the last three properties are stored in FONT_EXTRA_INDEX
@ -593,19 +593,19 @@ struct font_driver
The `open' method of the same font-backend is called with one of
the returned font-entities. If the backend needs additional
information to be used in `open' method, this method can add any
Lispy value by the property :font-entity to the entities.
Lispy value using the property :font-entity to the entities.
This and the following `match' are the only APIs that allocate
font-entities. */
Lisp_Object (*list) (struct frame *frame, Lisp_Object font_spec);
/* Return a font-entity most closely matching with FONT_SPEC on
FRAME. Which font property to consider, and how to calculate the
closeness is determined by the font backend, thus
/* Return a font-entity most closely matching FONT_SPEC on FRAME.
Which font property to consider, and how to calculate the
closeness, is determined by the font backend, thus
`face-font-selection-order' is ignored here.
The properties that the font-entity has is the same as `list'
method. */
The properties that the font-entity has are the same as described
for the `list' method above. */
Lisp_Object (*match) (struct frame *f, Lisp_Object spec);
/* Optional.
@ -630,7 +630,7 @@ struct font_driver
void (*prepare_face) (struct frame *f, struct face *face);
/* Optional.
Done FACE for displaying characters by FACE->font on frame F. */
Done with FACE for displaying characters by FACE->font on frame F. */
void (*done_face) (struct frame *f, struct face *face);
/* Optional.
@ -662,8 +662,8 @@ struct font_driver
/* Optional.
Store bitmap data for glyph-code CODE of FONT in BITMAP. It is
intended that this method is called from the other font-driver
for actual drawing. */
intended that this method is called from other font-driver
methods for actual drawing. */
int (*get_bitmap) (struct font *font, unsigned code,
struct font_bitmap *bitmap,
int bits_per_pixel);
@ -677,13 +677,16 @@ struct font_driver
/* Optional.
Get coordinates of the INDEXth anchor point of the glyph whose
code is CODE. Store the coordinates in *X and *Y. Return 0 if
the operations was successful. Otherwise return -1. */
the operation was successful. Otherwise return -1. */
int (*anchor_point) (struct font *font, unsigned code, int index,
int *x, int *y);
/* Optional.
Return a list describing which scripts/languages FONT
supports by which GSUB/GPOS features of OpenType tables. */
supports by which GSUB/GPOS features of OpenType tables.
The list should be of the form (GSUB GPOS), where both
GSUB and GPOS are lists of the form
((SCRIPT (LANGSYS FEATURE ...) ...) ...) */
Lisp_Object (*otf_capability) (struct font *font);
/* Optional.
@ -707,17 +710,16 @@ struct font_driver
/* Optional.
Make the font driver ready for frame F. Usually this function
makes some data specific to F and stores it in F by calling
font_put_frame_data (). */
makes some data specific to F and stores it in F's font_data
member by calling font_put_frame_data. */
int (*start_for_frame) (struct frame *f);
/* Optional.
End using the driver for frame F. Usually this function free
some data stored for F. */
End using the driver for frame F. Usually this function frees
some font data stored in frame F's font_data member. */
int (*end_for_frame) (struct frame *f);
/* Optional.
Shape text in GSTRING. See the docstring of
`composition-get-gstring' for the format of GSTRING. If the
(N+1)th element of GSTRING is nil, input of shaping is from the
@ -728,19 +730,17 @@ struct font_driver
output glyphs (M) are more than the input glyphs (N), (N+1)th
through (M)th elements of GSTRING are updated possibly by making
a new glyph object and storing it in GSTRING. If (M) is greater
than the length of GSTRING, nil should be return. In that case,
this function is called again with the larger GSTRING. */
than the length of GSTRING, this method should return nil. In
that case, the method is called again with a larger GSTRING. */
Lisp_Object (*shape) (Lisp_Object lgstring);
/* Optional.
If FONT is usable on frame F, return 0. Otherwise return -1.
This method is used only for debugging. If this method is NULL,
Emacs assumes that the font is usable on any frame. */
int (*check) (struct frame *f, struct font *font);
/* Optional.
Return the number of variation glyphs of character C supported by
FONT. VARIATIONS is an array of 256 elements. If the variation
selector N (1..256) defines a glyph, that glyph code is stored in
@ -748,24 +748,27 @@ struct font_driver
int (*get_variation_glyphs) (struct font *font,
int c, unsigned variations[256]);
/* Optional.
Set attributes of FONT according to PROPERTIES.
PROPERTIES is an alist of pairs (KEY . VALUE) that specifies
font properties. This method should use font-put to set
properties of FONT supported by the font driver.
See font_filter_properties for more details. */
void (*filter_properties) (Lisp_Object font, Lisp_Object properties);
/* Optional.
Return non-zero if FONT_OBJECT can be used as a (cached) font
for ENTITY on frame F. */
bool (*cached_font_ok) (struct frame *f,
Lisp_Object font_object,
Lisp_Object entity);
/* Optional
Return non-nil if the driver support rendering of combining
/* Optional.
Return non-nil if the driver supports rendering of combining
characters for FONT according to Unicode combining class. */
Lisp_Object (*combining_capability) (struct font *font);
/* Optional
/* Optional.
Called when frame F is double-buffered and its size changes; Xft
relies on this hook to throw away its old XftDraw (which won't
work after the size change) and get a new one. */