Debian Codegraph @

CorsixTH/Src/th_gfx_font.h

raw
1 /*
2 Copyright (c) 2010 Peter "Corsix" Cawley
3
4 Permission is hereby granted, free of charge, to any person obtaining a copy of
5 this software and associated documentation files (the "Software"), to deal in
6 the Software without restriction, including without limitation the rights to
7 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
8 of the Software, and to permit persons to whom the Software is furnished to do
9 so, subject to the following conditions:
10
11 The above copyright notice and this permission notice shall be included in all
12 copies or substantial portions of the Software.
13
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 SOFTWARE.
21 */
22
23 #ifndef CORSIX_TH_TH_GFX_FONT_H_
24 #define CORSIX_TH_TH_GFX_FONT_H_
25 #include "config.h"
26
27 #include <SDL_render.h>
28 #include <ft2build.h> // IWYU pragma: keep
29 // IWYU pragma: no_include "freetype/config/ftheader.h"
30
31 #include <climits>
32
33 #include "th_gfx_sdl.h"
34 #include FT_FREETYPE_H
35 #include FT_IMAGE_H
36 #include FT_TYPES_H
37
38 enum class text_alignment {
39 left = 0,
40 center = 1,
41 right = 2,
42 };
43
44 enum class bitmap_font_character_set { cp437, mik };
45
46 /** Structure for the bounds of a text string that is rendered to the screen. */
47 struct text_layout {
48 //! Number of rows the rendered text spans
49 int row_count;
50
51 //! Left X-coordinate for the start of the text
52 int start_x;
53
54 //! Right X-coordinate for the right part of the last letter rendered
55 int end_x;
56
57 //! Top Y-coordinate for the start of the text
58 int start_y;
59
60 //! Bottom Y-coordinate for the end of the text
61 int end_y;
62
63 //! Width of the widest line in the text
64 int width;
65 };
66
67 struct font_shadow_options {
68 //! Whether to draw a shadow
69 bool enabled{false};
70
71 //! Horizontal offset of the shadow, in pixels
72 int offset_x{1};
73
74 //! Vertical offset of the shadow, in pixels
75 int offset_y{1};
76
77 //! Colour of the shadow
78 argb_colour color{0xFF000000u};
79 };
80
81 class font {
82 public:
83 virtual ~font() = default;
84
85 //! Get the size of drawn text.
86 /*!
87 If iMaxWidth is specified the text will wrap, so that the height can
88 span multiple rows. Otherwise gets the size of a single line of text.
89 @param sMessage A UTF-8 encoded string containing a single line of text
90 to measure the width and height of.
91 @param iMessageLength The length, in bytes (not characters), of the
92 string at sMessage.
93 @param iMaxWidth The maximum length, in pixels, that the text may
94 occupy. Default is INT_MAX.
95 */
96 virtual text_layout get_text_dimensions(const char* sMessage,
97 size_t iMessageLength,
98 int iMaxWidth = INT_MAX) const = 0;
99
100 //! Draw a single line of text
101 /*!
102 @param pCanvas The render target to draw onto.
103 @param sMessage A UTF-8 encoded string containing a single line of text
104 to draw.
105 @param iMessageLength The length, in bytes (not characters), of the
106 string at sMessage.
107 @param iX The X coordinate of the top-left corner of the bounding
108 rectangle for the drawn text.
109 @param iY The Y coordinate of the top-left corner of the bounding
110 rectangle for the drawn text.
111 */
112 virtual void draw_text(render_target* pCanvas, const char* sMessage,
113 size_t iMessageLength, int iX, int iY) const = 0;
114
115 //! Draw a single line of text, splitting it at word boundaries
116 /*!
117 This function still only draws a single line of text (i.e. any line
118 breaks like `\r` and `\n` in sMessage are ignored), but inserts line
119 breaks between words so that no single line is wider than iWidth pixels.
120 If iMaxRows is specified it will simply cut after that many rows.
121 @param pCanvas The canvas on which to draw. Can be nullptr, in which
122 case nothing is drawn, but other calculations are still made.
123 @param sMessage The line of text to draw, encoded in CP437.
124 @param iMessageLength The length (in bytes) of sMessage.
125 @param iX The X position to start drawing on the canvas.
126 @param iY The Y position to start drawing on the canvas.
127 @param iWidth The maximum width of each line of text.
128 @param iMaxRows The maximum number of rows to draw. Default is INT_MAX.
129 @param iSkipRows Start rendering text after skipping this many rows.
130 @param eAlign How to align each line of text if the width of the line
131 of text is smaller than iWidth.
132 */
133 virtual text_layout draw_text_wrapped(
134 render_target* pCanvas, const char* sMessage, size_t iMessageLength,
135 int iX, int iY, int iWidth, int iMaxRows = INT_MAX, int iSkipRows = 0,
136 text_alignment eAlign = text_alignment::left) const = 0;
137 };
138
139 class bitmap_font final : public font {
140 public:
141 bitmap_font();
142
143 //! Set the character glyph sprite sheet
144 /*!
145 The sprite sheet should have the space character (ASCII 0x20) at sprite
146 index 1, and other ASCII characters following on in simple order (i.e.
147 '!' (ASCII 0x21) at index 2, 'A' (ASCII 0x41) at index 34, etc.)
148 \param pSpriteSheet The sprite sheet to use for the font.
149 \param character_set The character set to use when mapping unicode to
150 sprite indexes.
151 */
152 void set_sprite_sheet(sprite_sheet* pSpriteSheet,
153 bitmap_font_character_set character_set);
154
155 void set_scale_factor(int factor);
156
157 sprite_sheet* get_sprite_sheet() { return sheet; }
158
159 //! Set the separation between characters and between lines
160 /*!
161 Generally, the sprite sheet glyphs will already include separation, and
162 thus no extra separation is required (set iCharSep and iLineSep to 0).
163 */
164 void set_separation(int iCharSep, int iLineSep);
165
166 text_layout get_text_dimensions(const char* sMessage, size_t iMessageLength,
167 int iMaxWidth = INT_MAX) const override;
168
169 void draw_text(render_target* pCanvas, const char* sMessage,
170 size_t iMessageLength, int iX, int iY) const override;
171
172 text_layout draw_text_wrapped(
173 render_target* pCanvas, const char* sMessage, size_t iMessageLength,
174 int iX, int iY, int iWidth, int iMaxRows = INT_MAX, int iSkipRows = 0,
175 text_alignment eAlign = text_alignment::left) const override;
176
177 private:
178 sprite_sheet* sheet{nullptr};
179 int letter_spacing{};
180 int line_spacing{};
181 int scale_factor{1};
182 bitmap_font_character_set character_set{bitmap_font_character_set::cp437};
183 };
184
185 //! Adaptor around the FreeType2 library to a THFont.
186 /*!
187 Due to the relatively high cost of rendering a message with FreeType, this
188 class implements internal caching of messages, so rendering a message once
189 will be quite expensive, but subsequently rendering the same message again
190 will be quite cheap (provided that it hasn't fallen out of the cache).
191
192 Unlike THBitmapFont which sits entirely on top of existing interfaces, some
193 of the internal methods of this class are implemented by each individual
194 rendering engine (said methods are roughly for the equivalent of the
195 THRawBitmap class, but with an alpha channel, and a single colour rather
196 than a palette).
197 */
198 class freetype_font final : public font {
199 public:
200 freetype_font();
201 ~freetype_font() override;
202
203 //! Get the copyright notice which should be displayed for FreeType2.
204 /*!
205 To comply with the FreeType2 license, the string returned by this
206 function needs to be displayed at some point.
207 @return A null-terminated UTF-8 encoded string.
208 */
209 static const char* get_copyright_notice();
210
211 //! Initialise the FreeType2 library.
212 /*!
213 This will be called automatically by setFace() as required.
214 */
215 FT_Error initialise();
216
217 //! Remove all cached strings, as our graphics context has changed
218 void clear_cache();
219
220 //! Set the font face to be used.
221 /*!
222 @param pData Pointer to the start of a font file loaded into memory.
223 This block of memory must remain valid for at least the lifetime
224 of the THFreeTypeFont objcect.
225 @param iLength The size, in bytes, of the font file at pData.
226 */
227 FT_Error set_face(const uint8_t* pData, size_t iLength);
228
229 //! Find colour and size to best match a bitmap font.
230 /*!
231 Note that the matching is done on a best-effort basis, and will likely
232 not be perfect. This must be called after setFace().
233
234 @param font_spritesheet The sprite sheet of the bitmap font.
235 @param color [out] Colour to use for the font. Colour 0 falls back to
236 deriving the colour from the sprite sheet.
237 @param width [out] Width of each character in pixels.
238 @param height [out] Height of each character in pixels.
239 */
240 FT_Error match_bitmap_font(sprite_sheet* font_spritesheet, argb_colour* color,
241 int* width, int* height);
242
243 //! Set the ideal character size using pixel values.
244 /*!
245 Note that the given size might be changed a small amount if doing so
246 would result in a much nicer rendered font. This must be called after
247 setFace().
248 */
249 FT_Error set_ideal_character_size(int iWidth, int iHeight);
250
251 void set_font_color(argb_colour color);
252
253 void set_shadow_options(const font_shadow_options& options);
254
255 text_layout get_text_dimensions(const char* sMessage, size_t iMessageLength,
256 int iMaxWidth = INT_MAX) const override;
257
258 void draw_text(render_target* pCanvas, const char* sMessage,
259 size_t iMessageLength, int iX, int iY) const override;
260
261 text_layout draw_text_wrapped(
262 render_target* pCanvas, const char* sMessage, size_t iMessageLength,
263 int iX, int iY, int iWidth, int iMaxRows = INT_MAX, int iSkipRows = 0,
264 text_alignment eAlign = text_alignment::left) const override;
265
266 private:
267 struct cached_text {
268 //! The text being converted to pixels
269 char* message;
270
271 //! Raw pixel data in row major 8-bit greyscale
272 uint8_t* data;
273
274 //! Generated texture ready to be rendered
275 SDL_Texture* texture;
276
277 //! The length of sMessage
278 size_t message_length;
279
280 //! The size of the buffer allocated to store sMessage
281 size_t message_buffer_length;
282
283 //! Width of the image to draw
284 int width;
285
286 //! Height of the image to draw
287 int height;
288
289 //! The width of the longest line of text in in the textbox in pixels
290 int widest_line_width;
291
292 //! X Coordinate trailing the last character in canvas coordinates
293 int last_x;
294
295 //! Number of rows required
296 int row_count;
297
298 //! Alignment of the message in the box
299 text_alignment alignment;
300
301 //! True when the data reflects the message given the size constraints
302 bool is_valid;
303 };
304
305 //! Render a FreeType2 monochrome bitmap to a cache canvas.
306 void render_mono(cached_text* pCacheEntry, FT_Bitmap* pBitmap, FT_Pos x,
307 FT_Pos y) const;
308
309 //! Render a FreeType2 grayscale bitmap to a cache canvas.
310 void render_gray(cached_text* pCacheEntry, FT_Bitmap* pBitmap, FT_Pos x,
311 FT_Pos y) const;
312
313 static FT_Library freetype_library;
314 static int freetype_init_count;
315 static constexpr int cache_size_log2{7};
316 FT_Face font_face{nullptr};
317 argb_colour font_color{0};
318 font_shadow_options shadow_opts{};
319 bool is_done_freetype_init{false};
320 mutable cached_text cache[1 << cache_size_log2]{};
321
322 // The following five methods are implemented by the rendering engine.
323
324 //! Query if 1-bit monochrome or 8-bit grayscale rendering should be used.
325 /*!
326 @return true if 1-bit monochrome rendering should be used, false if
327 8-bit grayscale rendering should be used (though in the latter
328 case, 1-bit rendering might still get used).
329 */
330 bool is_monochrome() const;
331
332 //! Convert a cache canvas containing rendered text into a texture.
333 /*!
334 @param pEventualCanvas A pointer to the rendertarget we'll be using to
335 draw this.
336 @param pCacheEntry A cache entry whose pData field points to a pixmap
337 of size iWidth by iHeight. This method will convert said pixmap to
338 an object which can be used by the rendering engine, and store the
339 result in the pTexture or iTexture field.
340 */
341 void make_texture(const render_target* pEventualCanvas,
342 cached_text* pCacheEntry) const;
343
344 static void copy_pixel_data(const cached_text* cacheEntry, argb_colour color,
345 int offsetX, int offsetY,
346 std::vector<argb_colour>::iterator outIter);
347
348 //! Free a previously-made texture of a cache entry.
349 /*!
350 This call should free all the resources previously allocated by a call
351 to _makeTexture() and set the texture field to indicate no texture.
352
353 @param pCacheEntry A cache entry previously passed to _makeTexture().
354 */
355 void free_texture(cached_text* pCacheEntry) const;
356
357 //! Render a previously-made texture of a cache entry.
358 /*!
359 @param pCanvas The canvas on which to draw.
360 @param pCacheEntry A cache entry containing the texture to draw, which
361 will have been stored in the pTexture or iTexture field by a prior
362 call to _makeTexture().
363 @param iX The X position at which to draw the texture on the canvas.
364 @param iY The Y position at which to draw the texture on the canvas.
365 */
366 void draw_texture(render_target* pCanvas, cached_text* pCacheEntry, int iX,
367 int iY) const;
368 };
369
370 #endif // CORSIX_TH_TH_GFX_FONT_H_