README

-----------------------------------< SFont >------------------------------------

License: GPL or LGPL (at your choice)
Author: Karl Bartel <karl@karl.berlin>
WWW: http://www.linux-games.com/sfont/ or https://github.com/karlb/sfont/

This library has been originally developed for SDL1. The examples have been
updated to work with SDL2, but are still using the SDL_Surface API. Changing it
to use SDL_Textures should not be hard, but I have not tried it myself.

Usage:
    1. Load a font and place it in an SDL_Surface *. If your are using the 
       SDL_image library you can do this with Font = IMG_Load("filename");
    2. Initialize the font by using InitFont(surface *Font);
    3. Now you can use the font in you SDL program.
       Please take a look at SFont.h to get info about the funtions.

    For more usage examples, have a look at the included example files.

File Format:
    The font file can be any type image file. The characters start with
    ASCII symbol #33. They are seperated by pink(255,0,255) lines at the top
    of the image. The space between these lines is the width of the caracter.
    Just take a look at the font, and you'll be able to understand what I tried
    to explain here.

Example for the font file format:

____       _____      _____     _____     <- This is the pink line at the top

       #        #####       ####
      # #       #    #     #
      # #       #    #     #
     #   #      #####      #
     #####      #    #     #
    #     #     #    #     #
    #     #     #####       ####

		|----|
	Width of the character
             
	     |----------|
Part of the font surface that is beeing blitted


How to create Fonts:
    The easiest way to create a new font is to use the GIMP's Logo function.
    Use the following string as text (ASCII 33-127 with escape sequences and
    spaces between the letters):

    ! \" # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \\ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~

    In most other applications, you can just use the ASCII charakters without
    escape sequences:

    ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~

    Now you have to add the pink line above the font. You can either do this 
    manually, or let SFontMaker (http://nostatic.org/sfont/) do the work for
    you. SFontMaker doesn't always generate the optimal soultion, but it's 
    usually good enough, and it provides a great starting point for manual 
    font tweaking.


ChangeLog:

2.10 (2023-01)
    Update to use SDL2

2.03
    Changes in C++ Wrapper by Lion Vollnhals:
	fixed typo in "SFont_TextHeighT" call
	fixed forgotten ',' in function Write
	fixed parameter order in function Write
	changed exception class to std::runtime_error which is derived from std::exception because of
	    - standard conformance
	    - the additional functionality of class Exception isn't used in the code
	    - the code of class Exception uses non-C++ C code facilities, which are type unsafe and potentially dangerous
	    - to remove the .cpp (object) file
	added overloaded functions to support the standard std::string class
    Also the class name has been changed to SFont and the Write method has been renamed to write

2.02
    Readded GPL/LGPL license choice (it got lost somehow when I put out the 2.0 version)
    Changes by Florian Hufsky <fhufsky@phorus.at> (http://jnrdev.weed-crew.net)
:
	Added a character list without escape sequences to the readme.
	added link to SFontMaker
        removed some confusing, outdated comments SFont.h


2.01
    Fixed a compilation problem with older gcc versions (parse error before cyan)
    Added a SFont_Font cast before malloc, to make more compilers happy.

2.0
    All changes in this version were done by Matthias Braun.
    Yhis version breaks compatability in favor of a cleaner API!
    Changes in detail:
    	-   SDL.h is an external library so we should do #include <SDL.h> 
	    (same goes for string.h)
 	-   prefixed all functions with SFont_, this is good style to avoid 
	    naming conflicts with other packages which might already have 
	    functions with same name.
 	-   Changed FontInit procedure: You now call InitFont and get a 
	    SFont_FontInfo back. YOu have to call SFont_FreeFont later to 
	    release the memory. Removed all the functions which draw the 
	    default font. Keep it simple by only having 1 version which draws 
	    a specified font. (User can easily create their own global font)
 	-   changed text parameter in several functions from char* to const 
	    char*, We're not changing the text anyway
 	-   renamed PutString to Write
	-   renamed XCenteredString to WriteCenter
	-   added a SFont_TextHeight function
	-   removed input function from SFont, because:
    	    a) it wasn't user friendly (no cursor keys, no begin/end key, ...)
	    b) it's of no use for most projects since the function totally
		blocks your app. (for an ingame chat I want the game to 
		continue running, for a menu. I want the OK/Cancel buttons to 
		still work, ...)
	    c) it wasn't safe for buffer overflows (evil hacker creates a font 
		with width of 1 pixel and can input very long strings then...)
	    d) a lib is best when it only does 1 thing (in this case handling 
		fonts) and does this well. This keeps code small and bug free.
	
	-   declared internal function GetPixel static to avoid clashes with 
	    other packages
	-   made the functions save to not crash on unknown characters
	-   I also converted the testapps to the new interface
	-   A C++ wrapper is included!
    

1.71
    really fixed serious bug

1.7
    removed one warning by adding #include <stdlib.h>
    added license info at the top of sfont.c/.h
    fixed serious bug (thanks Sulaiman)

1.6
    added #ifndef SFONT_H etc to SFont.h to allow it to be
	included multiple times with causing errors
    To handle larger charsets (>127 chars) the type of
	the 'text[i]' variable has been changed in
	PutString2 and TextWidth2

1.5 
    fixed a bug in xcenteredstring2
    added return on error in GetPixel in SoFont.cpp
    SFont can be used either under the GPL or LGPL
    unicode state is restored at the end of SFont_Input
    added extern "C" defines for usage in C++ programs
    Added lock and unlock for hardware surfaces
    Added blinking cursor to SFont_Input
    Added check for ASCII<33 in SFont_Input
    TextWidth returned a too high value -> fixed

1.4
    Added support for multiple fonts in one program
    Add a missing "*" in the SFont.h file
    Proper '\0' at the end of stings produced by SFont_Input
    Fixed problems in SFont_Input, which were creating '\b' in the string
    Fixed two other bugs in SFont_Input
    Added the SFontViewer and new test programs

1.3
    Fixed three wrong interpretations of the file format
	o wrong division (float had to be used)
	o detection of right ends of pink lines (were one pixel too far right)
	o blit destination (all blits were too far right)
    support for non-alpha mapped fonts
    some fonts updated
    
1.2
    added XCenteredString

1.1
    renamed font.c to SFont.c and font.h to SFont.h
    better Makefile
1.0
    Added the Input function
    Added a check whether the Font has been loaded
0.9
    better Makefile for the example (using sdl-config)
    better Neon Font
0.8 
    First Release

If you have any questions please write a mail!

-- Karl