Differential D17493 Diff 47361 kcms/fonts/freetype-renderer.h

Changeset View

Standalone View

View Options

kcms/fonts/freetype-renderer.h

  • This file was added.
1​/*
2​ * Copyright 2018 Max Harmathy
3​ *
4​ * This program is free software; you can redistribute it and/or modify it under
5​ * the terms of the GNU General Public License as published by the Free Software
6​ * Foundation; either version 2 of the License, or (at your option) any later
7​ * version.
8​ *
9​ * This program is distributed in the hope that it will be useful, but WITHOUT
10​ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11​ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
12​ * details.
13​ *
14​ * You should have received a copy of the GNU General Public License along with
15​ * this program; if not, see <http://www.gnu.org/licenses/>.
16​ */
17​
18​#ifndef FREETYPE_RENDERER_H
19​#define FREETYPE_RENDERER_H
20​
21​#include "kxftconfig.h"
22​
23​extern "C" {
24​#include <ft2build.h>
25​#include FT_FREETYPE_H
26​#include <fontconfig/fontconfig.h>
27​#include <hb.h>
28​}
29​
30​#include <QBitArray>
31​#include <QByteArray>
32​#include <QColor>
33​#include <QImage>
34​#include <QRect>
35​
36​/**
37​ * @brief The FontManagement class is a wrapper around the Fontconfig library.
38​ *
39​ * Fontconfig is commonly used to manage font files on the system and has a complex configuration
40​ * system. In particular it handles font substitution. It therefore can provide a font file for a
41​ * given font specification, which is used in the retrievePath method.
42​ */
43​class FontManagement
44​{
45​public:
46​ /**
47​ * FontManagement constructor initializes the Fontconfig library.
48​ */
49​ FontManagement();
50​
51​ ~FontManagement();
52​
53​ FontManagement& operator=(const FontManagement&) = delete;
54​ FontManagement(const FontManagement&) = delete;
55​
56​ /**
57​ * @brief retrievePath fetches the path of a specified font.
58​ *
59​ * Here the Fontconfig library is used to substitute the font according to the system settings
60​ * and to locate the font file. The font file path can be used to load the font in FreeType. The
61​ * path is copied from the Fontconfig data structures which are destroyed after this method
62​ * call.
63​ *
64​ * @param font name to specify the font
65​ * @return path to the font file
66​ */
67​ const char* retrievePath(const char* font);
68​
69​ /**
70​ * @brief copyFcString helper method to retrieve the font path from Fontconfig data structures
71​ * @param fcString pointer to the path in the data structure
72​ * @return string copy of the path
73​ */
74​ static inline const char* copyFcString(const FcChar8* fcString);
75​
76​private:
77​ FcConfig* fontConfig;
78​};
79​
80​/**
81​ * Hold parameters for FreeType, which influence the rendering result.
82​ */
83​class FreeTypeParameters
84​{
85​public:
86​ /**
87​ * Convert rendering options from the commonly used Fontconfig style into parameters for
88​ * FreeType. FreeTypeParameters does not take ownership of the KXftConfig object.
89​ */
90​ FreeTypeParameters(KXftConfig* options);
91​
92​ int loadFlags;
93​ FT_Render_Mode renderMode;
94​ // FT_Library_SetLcdFilter
95​};
96​
97​/**
98​ * @brief The FreeTypeLibrary class
99​ */
100​class FreeTypeLibrary
101​{
102​private:
103​ FT_Library freetypeLib;
104​
105​public:
106​ FreeTypeLibrary();
107​ virtual ~FreeTypeLibrary();
108​
109​ FT_Face getFontFace(const char* path);
110​
111​ /**
112​ * This inline function converts point size from float to internal integer representation used
113​ * by FreeType. Keep in mind that point size isn't a discrete measure and therefore a float.
114​ * @param pointSize size in typographic units
115​ * @return internal integer representation used by FreeType
116​ */
117​ static inline long convertPointSize(double pointSize);
118​};
119​
120​/**
121​ * @brief The RasteredGlyph class is the base class for rasters glyph data from FreeType.
122​ *
123​ * This class is an abstract class to provide a common interface to the different format of glyph
124​ * data provided by FreeType. Depending on the parameters for font rendering FreeType uses different
125​ * approached for storing the data, e.g. if anti-aliasing is turned off, glyphs are rendered in
126​ * monochrome (handles by subclass MonochromeGlyph) using only one bit per pixel.
127​ */
128​class RasteredGlyph
129​{
130​
131​protected:
132​ /**
133​ * @brief pitch is the length of one row of glyph data in bytes and signedness encoding
134​ * direction.
135​ *
136​ * The pitch is copied from the FreeType glyph data structure. It can be positive or negative
137​ * depending on the direction, in which the glyph is renders. See also FT_Bitmap in the FreeType
138​ * documentation. An always positive length value is stored in rowLength.
139​ */
140​ const int pitch;
141​
142​ /**
143​ * @brief rowLength is the length of one row of glyph data in bytes.
144​ *
145​ * In contrast to pitch this value is always positive and can be used to compute the required
146​ * space of the glyph.
147​ */
148​ const unsigned int rowLength;
149​
150​ /**
151​ * @brief width of the glyph in pixels.
152​ */
153​ const unsigned int width;
154​
155​ /**
156​ * @brief height of the glyph in pixels.
157​ */
158​ const unsigned int height;
159​
160​public:
161​ /**
162​ * @brief RasteredGlyph constructor
163​ *
164​ * The bitmap data structure has also a width and height (rows) field, however for sub-pixel
165​ * rendered bitmaps the respective value will be in sub-pixels, i.e. three times larger. This
166​ * should be handled by the constructor of the specialized sub-class.
167​ * @param bitmap the rendering result from FreeType
168​ * @param width the actual width in pixels
169​ * @param height the actual height in pixels
170​ */
171​ RasteredGlyph(FT_Bitmap* bitmap, uint width, uint height);
172​
173​ virtual ~RasteredGlyph() = default;
174​
175​ /**
176​ * @brief paint method will paint the glyph to the canvas given at position (x,y).
177​ *
178​ * The rendering slightly differs depending on the given font rendering options. Therefore this
179​ * is an abstract method, which has to be implemented by inheriting classes. For anti-aliased
180​ * and sub-pixel based rendering the glyph has to be painted using alpha blending, since the
181​ * FreeType data yields the coverage of a (sub-)pixel.
182​ * @param canvas where the glyph is to be painted on.
183​ * @param x leftmost coordinate where to start painting the glyph.
184​ * @param y upmost coordinate where to start painting the glyph.
185​ * @param pen color, in which the glyph will be painted.
186​ */
187​ virtual void paint(QImage* canvas, int x, int y, const QColor& pen) = 0;
188​
189​ /**
190​ * @return the pixel height.
191​ */
192​ unsigned int getHeight() const;
193​
194​ /**
195​ * @return the pixel width.
196​ */
197​ unsigned int getWidth() const;
198​};
199​
200​/**
201​ * @brief The MonochromeGlyph class handles glyph data rendered without anti-aliasing.
202​ *
203​ * For every pixel there are only two possible states: either the glyph covers it, or not. Therefore
204​ * the data is stored in a bitmap, where one bit denotes one pixel.
205​ */
206​class MonochromeGlyph : public RasteredGlyph
207​{
208​protected:
209​ /**
210​ * @brief bitmap holds the pixel data of a rendered glyph, where every bit denotes a pixel.
211​ */
212​ unsigned char* bitmap;
213​
214​public:
215​ /**
216​ * @brief MonochromeGlyph constructor.
217​ *
218​ * The width and height are passed from the FT_Bitmap input to the base constructor (@ref
219​ * RasteredGlyph::RasteredGlyph). Side note: the width field in FT_Bitmap for monochrome glyph
220​ * data gives the width in pixels (in contrast sub-pixel rendered glyph data).
221​ * @param bitmap the rendering result from FreeType
222​ */
223​ MonochromeGlyph(FT_Bitmap* bitmap);
224​
225​ /**
226​ * @brief ~MonochromeGlyph frees private bitmap data copied from FreeType bitmap.
227​ */
228​ virtual ~MonochromeGlyph();
229​
230​ /**
231​ * @copydoc RasteredGlyph::paint
232​ *
233​ * This will paint the monochrome glyph to the canvas. Since there is no anti-aliasing involved
234​ * no alpha blending is needed.
235​ */
236​ virtual void paint(QImage* canvas, int x, int y, const QColor& pen) override;
237​
238​ /**
239​ * @brief pixelAt is a helper function to access the bit data of a single pixel.
240​ *
241​ * This is necessary since not only one byte holds the data of eight pixels but also they are
242​ * stored in most-significant bit order.
243​ * @param x horizontal pixel position in the glyph bitmap
244​ * @param y vertical pixel position in the glyph bitmap
245​ * @param pitch see @ref RasteredGlyph::pitch
246​ * @param buffer see @ref bitmap
247​ * @return 1 if the pixel is covered by the glyph and 0 otherwise
248​ */
249​ inline int pixelAt(uint x, uint y, int pitch, const unsigned char* buffer);
250​};
251​
252​/**
253​ * @brief The ByteDataGlyph class is an abstract class for glyph data, where pixel data is stored in
254​ * bytes.
255​ *
256​ * This is the base class for anti-aliased and sub-pixel rendered glyph data.
257​ */
258​class ByteDataGlyph : public RasteredGlyph
259​{
260​protected:
261​ /**
262​ * @brief bytemap stores the glyph data copied from the FreeType bitmap.
263​ */
264​ QByteArray* bytemap;
265​
266​public:
267​ /**
268​ * @brief ByteDataGlyph constructor.
269​ * @param bitmap see @ref RasteredGlyph::RasteredGlyph
270​ * @param bytesPerPixel number of bytes used to store one pixel. For gray scale glyphs it would
271​ * be set to 1, for sub-pixel rendered glyphs it would be 3 (one for each sub-pixel).
272​ * @param width see @ref RasteredGlyph::RasteredGlyph
273​ * @param height see @ref RasteredGlyph::RasteredGlyph
274​ */
275​ ByteDataGlyph(FT_Bitmap* bitmap, uint bytesPerPixel, uint width, uint height);
276​
277​ /**
278​ * @brief ~ByteDataGlyph frees private byte array with data copied from FreeType bitmap.
279​ */
280​ virtual ~ByteDataGlyph();
281​
282​ /**
283​ * @copydoc RasteredGlyph::paint
284​ */
285​ virtual void paint(QImage* canvas, int x, int y, const QColor& pen) override = 0;
286​};
287​
288​/**
289​ * @brief The GrayScaleGlyph class represents anti-aliased glyphs, rendered on pixel level.
290​ */
291​class GrayScaleGlyph : public ByteDataGlyph
292​{
293​public:
294​ /**
295​ * @brief GrayScaleGlyph constructor. Parameters for base classes are initialized.
296​ * @param bitmap see @ref RasteredGlyph::RasteredGlyph
297​ */
298​ GrayScaleGlyph(FT_Bitmap* bitmap);
299​
300​ /**
301​ * @copydoc RasteredGlyph::paint
302​ *
303​ * Pen color will be alpha blended onto the background.
304​ */
305​ virtual void paint(QImage* canvas, int x, int y, const QColor& pen) override;
306​};
307​
308​/**
309​ * @brief The AbstractSubPixelGlyph class is an abstract class for sub-pixel rendered glyphs.
310​ *
311​ * FreeType can render glyphs for utilizing sub-pixels of the displays panel to increase resolution.
312​ * FreeType assumed a pixel geometry of three sub-pixels (stripes). The rendering result from
313​ * FreeType is independent from the actual the sub-pixel color order. Usually LCD-Panels are
314​ * oriented in a way, that sub-pixels have the order Red, Green, Blue from left to right. If a
315​ * display is used in a turned position, the orientation and order of the sub-pixels change and
316​ * glyphs have to be rendered and displayed differently.
317​ *
318​ * This class implements the common per sub-pixel alpha blending in the paint method. Since
319​ * horizontal and vertical sub-pixel rendered glyphs are stored differently by FreeType the access
320​ * is encapsulated in the sub-classes SubPixelGlyph and VerticalSubPixelGlyph, which implement the
321​ * getValue method.
322​ */
323​class AbstractSubPixelGlyph : public ByteDataGlyph
324​{
325​protected:
326​ /**
327​ * @brief This indicates if the sub-pixel order is turned around, i.e. BGR instead of RGB.
328​ *
329​ * Setting this to true will swap the offset for accessing red and blue sub-pixel information.
330​ */
331​ bool reverse;
332​
333​ /**
334​ * @brief getValue retrieve the sub-pixel value of a pixel in the rendered glyph image.
335​ * @param row in rendered glyph, y coordinate
336​ * @param column in rendered glyph, x coordinate
337​ * @param offset selector for sub-pixel is one out of 0, 1 or 2.
338​ * Depending on the orientation 0 selects the left or top sub-pixel, 1 selects the middle
339​ * sub-pixel and 2 selects the right or bottom sub-pixel.
340​ * @return the area of the sub-pixel covered by the glyph in a range from 0 to 255, where 0 is
341​ * not covered and 255 is fully covered.
342​ */
343​ virtual unsigned char getValue(int row, int column, int offset) = 0;
344​
345​public:
346​ AbstractSubPixelGlyph(
347​ FT_Bitmap* bitmap, uint bytesPerPixel, uint width, uint height, bool reversed);
348​
349​ /**
350​ * @copydoc RasteredGlyph::paint
351​ *
352​ * Pen color will be alpha blended separately for every sub-pixel onto the background.
353​ */
354​ virtual void paint(QImage* canvas, int x, int y, const QColor& pen) override;
355​};
356​
357​/**
358​ * @brief The SubPixelGlyph class represents sub-pixel rendered glyphs for horizontal sub-pixel
359​ * orientation.
360​ */
361​class SubPixelGlyph : public AbstractSubPixelGlyph
362​{
363​protected:
364​ virtual inline unsigned char getValue(int row, int, int offset) override;
365​
366​public:
367​ SubPixelGlyph(FT_Bitmap* bitmap, bool reversed);
368​};
369​
370​/**
371​ * @brief The VerticalSubPixelGlyph class represents sub-pixel rendered glyphs for vertical
372​ * sub-pixel orientation.
373​ */
374​class VerticalSubPixelGlyph : public AbstractSubPixelGlyph
375​{
376​protected:
377​ virtual inline unsigned char getValue(int row, int column, int offset) override;
378​
379​public:
380​ VerticalSubPixelGlyph(FT_Bitmap* bitmap, bool reversed);
381​};
382​
383​/**
384​ * @brief The GlyphData class holds metadata together with rendered glyph data.
385​ *
386​ * With the paint method it ca be used to directly put the rendered glyph on a QImage.
387​ */
388​class GlyphData
389​{
390​private:
391​ const int offsetX;
392​ const int offsetY;
393​ const int advanceX;
394​ const int advanceY;
395​ const int bearingLeft;
396​ const int bearingTop;
397​
398​ RasteredGlyph* pixelData;
399​
400​public:
401​ /**
402​ * @brief GlyphData constructor
403​ * @param glyphPos is a Harfbuzz position data structure from a Harfbuzz font shaping run.
404​ * @param glyphData is the data structure from FreeType containing the render results of a
405​ * glyph.
406​ * @param reversedSubpixel This is only relevant for sub-pixel rendered glyphs. Set this to true
407​ * for bgr and vbgr sub-pixel order. See also @ref AbstractSubPixelGlyph::reverse.
408​ */
409​ GlyphData(hb_glyph_position_t* glyphPos,
410​ FT_GlyphSlotRec* glyphData,
411​ bool reversedSubpixel = false);
412​ int getOffsetX() const;
413​ int getOffsetY() const;
414​ int getBearingLeft() const;
415​ int getBearingTop() const;
416​ int getAdvanceX() const;
417​ int getAdvanceY() const;
418​ unsigned int getWidth() const;
419​ unsigned int getHeight() const;
420​ void paint(QImage* canvas, int x, int y, const QColor& pen);
421​};
422​
423​/**
424​ * @brief The FontShaping class contains all data provided by a font shaping run using Harfbuzz.
425​ *
426​ * In order to estimate the space needed by the text the actual rendering, i.e. the rasterization
427​ * but not the painting to a surface, is conducted.
428​ */
429​class FontShaping
430​{
431​private:
432​ const char* path;
433​
434​ unsigned int glyphCount;
435​ GlyphData** glyphs;
436​ unsigned int baseLineOffset;
437​ QRect boundingBox;
438​
439​public:
440​ /**
441​ * @brief FontShaping constructor conducts the shaping and the rendering steps.
442​ * @param freetypeLib a FreeTypeLibrary object
443​ * @param fontManagement a FontManagement object
444​ * @param text see @ref FreeTypeFontPreviewRenderer::renderText
445​ * @param font see @ref FreeTypeFontPreviewRenderer::renderText
446​ * @param pointSize see @ref FreeTypeFontPreviewRenderer::renderText
447​ * @param options see @ref FreeTypeFontPreviewRenderer::renderText
448​ */
449​ FontShaping(FreeTypeLibrary* freetypeLib,
450​ FontManagement* fontManagement,
451​ const char* text,
452​ const char* font,
453​ double pointSize,
454​ KXftConfig* options);
455​
456​ ~FontShaping();
457​
458​ unsigned int getGlyphCount() const;
459​ GlyphData** getGlyphs() const;
460​ unsigned int getBaseLineOffset() const;
461​ QRect getBoundingBox() const;
462​};
463​
464​/**
465​ * The FreeTypeFontPreviewRenderer class provides the possibility to render Text with FreeType
466​ * offside.
467​ */
468​class FreeTypeFontPreviewRenderer
469​{
470​private:
471​ FreeTypeLibrary* freeTypeLibrary;
472​ FontManagement* fontManagement;
473​
474​public:
475​ /**
476​ * @brief FreeTypeFontPreviewRenderer
477​ *
478​ * The constructor initializes the library classes for Harfbuzz, FreeType and Fontconfig.
479​ */
480​ explicit FreeTypeFontPreviewRenderer();
481​ virtual ~FreeTypeFontPreviewRenderer();
482​
483​ /**
484​ * @brief Render text independent from render settings of the running session.
485​ *
486​ * The given text will be rendered offside using the options provided as parameters. This is
487​ * intended to be presented to a user to give an impression, what rendering with the given
488​ * parameters would look without the need to change the actual setting for the session.
yurchorUnsubmitted
Done

Typo: imperssion -> impression

yurchor: Typo: imperssion -> impression
489​ * @param text string to render
yurchorUnsubmitted
Done

Typo: parametrs -> parameters

yurchor: Typo: parametrs -> parameters
490​ * @param font in which the text should be rendered
491​ * @param pointSize is the font size in typographic points
492​ * @param options config object which contains anti-aliasing, hinting and sub-pixel settings
493​ * @param background color
yurchorUnsubmitted
Done

Typo: anti-alising -> anti-aliasing

yurchor: Typo: anti-alising -> anti-aliasing
494​ * @param pen writing color
495​ * @return rendered text as QImage
496​ */
497​ QImage renderText(const char* text,
498​ const char* font,
499​ double pointSize,
500​ KXftConfig* options,
501​ QColor background,
502​ QColor pen);
503​};
504​
505​#endif // FREETYPE_RENDERER_H