Add fontlib_LoadFont to replace fontlib_SetFont

Author: ZERICO2005

docs/libraries/fontlibc.rst

@@ -163,13 +163,13 @@ This file will get generated by your makefile, which will need to be modified to
     $(SRCDIR)/myfont2.inc: $(SRCDIR)/myfont2.fnt
     	convfont -o carray -f $(SRCDIR)/myfont2.fnt $(SRCDIR)/myfont2.inc
 
-Finally, somewhere else in your program, you can use :code:`fontlib_SetFont`:
+Finally, somewhere else in your program, you can use :code:`fontlib_LoadFont`:
 
 .. code-block:: c
 
     void main() {
         . . .
-        fontlib_SetFont(my_font_1, 0);
+        fontlib_LoadFont(my_font_1, 0);
         . . .
     }
 
@@ -211,7 +211,7 @@ Create a new folder, place your :code:`.fnt` files in it, and then create a :cod
 Using Font Packs
 ----------------
 
-While using an embedded font is easy—just call :code:`fontlib_SetFont` directly on the pointer to the font data—,
+While using an embedded font is easy—just call :code:`fontlib_LoadFont` directly on the pointer to the font data—,
 using a font pack is a bit more involved.
 
 **WARNING: FontLibC caches a pointer to the font's data when you use** :code:`SetFont`.
@@ -243,7 +243,7 @@ If you require a specific font pack with a specific appvar name, then opening a
             return;
         }
         /* Use font for whatever */
-        fontlib_SetFont(my_font, 0);
+        fontlib_LoadFont(my_font, 0);
         . . .
     }
 
@@ -299,7 +299,7 @@ for a font pack by typeface name:
            Note that a direct pointer to the name is returned, which may be archived,
            so you cannot write to the string. */
         if (!strcmp(typeface_name, "My Font")) {
-            fontlib_SetFont(fontlib_GetFontByIndex(var_name, 0), 0);
+            fontlib_LoadFont(fontlib_GetFontByIndex(var_name, 0), 0);
             break;
         }
     }
@@ -346,7 +346,7 @@ The :code:`GetFontByStyle` routines help you automatically select a font given a
     /* Get a 9 or 10 pixel tall bold, serif font that isn't monospaced and isn't italic. */
     font = fontlib_GetFontByStyleRaw(font_pack, 9, 10, FONTLIB_BOLD, FONTLIB_BOLD, FONTLIB_SERIF, FONTLIB_MONOSPACED | FONTLIB_ITALIC);
     if (font)
-        fontlib_SetFont(font, 0);
+        fontlib_LoadFont(font, 0);
 
 API Usage Notes
 ---------------
@@ -404,9 +404,9 @@ on normal wrapping with :code:`fontlib_SetNewlineOptions`.
 
 Additional blank vertical space around text can improve readability in large blocks of text.
 :code:`fontlib_SetLineSpacing` allows you to set this behavior.
-Fonts may specify default additional spacing that is automatically applied when calling :code:`fontlib_SetFont`.
+Fonts may specify default additional spacing that is automatically applied when calling :code:`fontlib_LoadFont`.
 In GUIs and games where the benefits of legibility are outweighed by more aggressive use of vertical space,
-you can force the default spacing to zero after using :code:`fontlib_SetFont` with :code:`fontlib_SetLineSpacing`.
+you can force the default spacing to zero after using :code:`fontlib_LoadFont` with :code:`fontlib_SetLineSpacing`.
 
 API Documentation
 -----------------

examples/library_examples/fontlibc/example/src/main.c

@@ -17,7 +17,7 @@ int main(void)
     gfx_ZeroScreen();
 
     /* Set a font to use.  DrawString will display garbage if you don't give it a font! */
-    fontlib_SetFont(test_font, 0);
+    fontlib_LoadFont(test_font, 0);
 
     /* First, we'll display centered text in a window */
     /* Add some vertical padding around our text */

examples/library_examples/fontlibc/font_pack/src/main.c

@@ -26,7 +26,7 @@ int main(void)
     /* Set a font to use. */
     font_pack = fontlib_GetFontByIndex(font_pack_name, 1);
     if (font_pack) {
-        fontlib_SetFont(font_pack, 0);
+        fontlib_LoadFont(font_pack, 0);
         fontlib_DrawString(test_str);
     }
     else
@@ -38,7 +38,7 @@ int main(void)
     font_pack = fontlib_GetFontByStyle(font_pack_name, 9, 10, FONTLIB_NORMAL, FONTLIB_NORMAL, 0, FONTLIB_SERIF);
     if (font_pack)
     {
-        fontlib_SetFont(font_pack, 0);
+        fontlib_LoadFont(font_pack, 0);
         fontlib_DrawString(test_str);
     }
     else
@@ -50,7 +50,7 @@ int main(void)
     font_pack = fontlib_GetFontByStyle(font_pack_name, 30, 50, FONTLIB_NORMAL, FONTLIB_NORMAL, FONTLIB_SERIF, 0);
     if (font_pack)
     {
-        fontlib_SetFont(font_pack, 0);
+        fontlib_LoadFont(font_pack, 0);
         fontlib_DrawString(test_str);
     }
     else

src/fontlibc/fontlibc.asm

@@ -3,7 +3,7 @@ include '../include/library.inc'
 include '../include/include_library.inc'
 ;-------------------------------------------------------------------------------
 
-library FONTLIBC,2
+library FONTLIBC,3
 
 ;-------------------------------------------------------------------------------
 ; Dependencies
@@ -78,7 +78,11 @@ include_library '../graphx/graphx.asm'
 	export fontlib_ScrollWindowUp
 	export fontlib_Home
 	export fontlib_HomeUp
-
+;-------------------------------------------------------------------------------
+; v3 functions
+;-------------------------------------------------------------------------------
+	; replacement for fontlib_SetFont
+	export fontlib_LoadFont
 
 ;-------------------------------------------------------------------------------
 CurrentBuffer	:= ti.mpLcdLpbase
@@ -140,6 +144,11 @@ virtual at 0
 strucFontPackHeader strucFontPackHeader
 end virtual
 
+;-------------------------------------------------------------------------------
+; fontlib_load_options_t
+
+bLoadOption_IgnoreLineSpacing := 0
+mLoadOption_IgnoreLineSpacing := 1 shl bLoadOption_IgnoreLineSpacing
 
 ;-------------------------------------------------------------------------------
 macro mIsHLLessThanDE?
@@ -405,6 +414,17 @@ fontlib_Home:
 
 ;-------------------------------------------------------------------------------
 fontlib_SetFont:
+	; performs fontlib_LoadFont(font_data, FONTLIB_IGNORE_LINE_SPACING)
+	ld	hl,arg1
+	add	hl,sp
+	ld	bc,mLoadOption_IgnoreLineSpacing
+	ld	(hl),bc
+
+; Fall through to fontlib_LoadFont
+assert $ = fontlib_LoadFont
+
+;-------------------------------------------------------------------------------
+fontlib_LoadFont:
 ; Sets the current font to the data at the pointer given
 ; Arguments:
 ;  arg0: Pointer to font
@@ -435,12 +455,12 @@ fontlib_SetFont:
 	or	a,a
 	ret	z			; Also unreasonable: a zero-height font
 	and	a,$80
-	jr	nz,.false
+	jr	nz,.failure
 	ld	a,63
 	cp	a,(iy + strucFont.spaceAbove)
-	jr	c,.false
+	jr	c,.failure
 	cp	a,(iy + strucFont.spaceBelow)
-	jr	c,.false
+	jr	c,.failure
 .validateOffsets:
 ; Now convert offsets into actual pointers
 ; Validate that offset is at least semi-reasonable
@@ -459,21 +479,20 @@ fontlib_SetFont:
 	add	hl,bc
 	ld	(iy + strucFont.bitmapsTablePtr),hl
 ; Check for the ignore line spacing flag
-; Due to a bug, flags must be ignored, and treated as FONTLIB_IGNORE_LINE_SPACING
-	; ld	hl,arg1
-	; add	hl,sp
-	; ld	a,(hl)
-	; or	a,a
-	; jr	z,.true
+	ld	hl,arg1
+	add	hl,sp
+	bit	bLoadOption_IgnoreLineSpacing,(hl)
+	jr	z,.finish_load
 	lea	hl,iy + strucFont.spaceAbove
 	xor	a,a
 	ld	(hl),a
 	inc	hl
 	ld	(hl),a
-.true:
+.finish_load:
 	ld	a,1
 	ret
-.false:
+
+.failure:
 	xor	a,a
 	ret
 

src/fontlibc/fontlibc.h

@@ -49,9 +49,8 @@ typedef enum {
 } fontlib_newline_options_t;
 
 /**
- * @warning Flags are currently ignored due to a bug, and treated as FONTLIB_IGNORE_LINE_SPACING
  * Options for controlling how SetFont functions.
- * @see fontlib_SetFont
+ * @see fontlib_LoadFont
  */
 typedef enum {
     /**
@@ -162,7 +161,7 @@ typedef struct fontlib_metadata_t {
  *  unsigned char baseline;
  *  fontlib_font_t *my_font = fontlib_GetFontByStyle("FONTPACK", 12, 12,
  *      FONTLIB_NORMAL, FONTLIB_NORMAL, FONTLIB_SERIF, 0);
- *  if (!my_font || !fontlib_SetFont(my_font))
+ *  if (!my_font || !fontlib_LoadFont(my_font, 0))
  *      return;
  *  baseline = my_font->baseline_height;
  * @endcode
@@ -382,16 +381,24 @@ void fontlib_HomeUp();
  */
 void fontlib_Home();
 
+/**
+ * @warning fontlib_SetFont is deprecated, use fontlib_LoadFont instead.
+ * @note due to a bug, fontlib_SetFont ignores flags and assumes
+ * FONTLIB_IGNORE_LINE_SPACING. This has been fixed with fontlib_LoadFont
+ */
+bool fontlib_SetFont(const fontlib_font_t *font_data, fontlib_load_options_t flags);
+
+#define fontlib_SetFont _Pragma("GCC warning \"'fontlib_SetFont' is deprecated, use 'fontlib_LoadFont' instead\"") fontlib_SetFont
+
 /**
  * Sets the current font
  * @param[in] font_data Pointer to font data
- * @param[in] Unused and treated as FONTLIB_IGNORE_LINE_SPACING
+ * @param[in] flags Information about how to process the font
  * @return Returns false if the font seems invalid for any reason
  * @warning If false is returned, no valid font is currently loaded and trying
- * @note Flags are currently ignored due to a bug, and treated as FONTLIB_IGNORE_LINE_SPACING
  * to print will print garbage!
  */
-bool fontlib_SetFont(const fontlib_font_t *font_data, fontlib_load_options_t flags);
+bool fontlib_LoadFont(const fontlib_font_t *font_data, fontlib_load_options_t flags);
 
 /**
  * Sets the current foreground color FontLibC will use for drawing.

test/fontlibc/glyph_width/src/main.c

@@ -15,7 +15,7 @@
 int run_tests(void) {
 
     /* 256 glyph test */
-    fontlib_SetFont(test_font, 0);
+    fontlib_LoadFont(test_font, 0);
     C(fontlib_GetFirstGlyph() == 0);
     C(fontlib_GetTotalGlyphs() == 256);
     C(fontlib_GetTotalGlyphs() == 256);
@@ -27,7 +27,7 @@ int run_tests(void) {
     /* 255 glyph test */
     test_font->first_glyph = 1;
     test_font->total_glyphs = 255;
-    fontlib_SetFont(test_font, 0);
+    fontlib_LoadFont(test_font, 0);
     C(fontlib_GetFirstGlyph() == 1);
     C(fontlib_GetTotalGlyphs() == 255);
     C(fontlib_GetGlyphWidth(0) == 0);
@@ -39,7 +39,7 @@ int run_tests(void) {
     /* 128 glyph test */
     test_font->first_glyph = 0;
     test_font->total_glyphs = 128;
-    fontlib_SetFont(test_font, 0);
+    fontlib_LoadFont(test_font, 0);
     C(fontlib_GetFirstGlyph() == 0);
     C(fontlib_GetTotalGlyphs() == 128);
     for (unsigned i = 0; i <= 127; i++) {
@@ -54,7 +54,7 @@ int run_tests(void) {
     /* 64 glyph test */
     test_font->first_glyph = 32;
     test_font->total_glyphs = 64;
-    fontlib_SetFont(test_font, 0);
+    fontlib_LoadFont(test_font, 0);
     C(fontlib_GetFirstGlyph() == 32);
     C(fontlib_GetTotalGlyphs() == 64);
     for (unsigned i = 0; i <= 31; i++) {