| 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_ |