From 0ecff00bc19c0f8e1b2c0b552a7a686525377dad Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 5 Jan 2019 10:28:34 +0200 Subject: Improve commentary in font.h * src/font.h (struct font, struct font_driver): Fix typos and wording in comments. Document all driver methods. --- src/font.h | 63 ++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/src/font.h b/src/font.h index d358110ce9a..bb468333e85 100644 --- a/src/font.h +++ b/src/font.h @@ -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. */ -- cgit v1.2.1