FontLib v1.0 by Philippe Gervaise aKa CandyMan
----------------------------------------------



  First sorry about my bad english, you will see ...




Summary :
---------

  What's this ?
  Why this library ?
  How it's work ?
  How to use a font in a file ?
  How to use a font without a file ?
  How to use Italic property ?
  How to use Invert property ?
  How to write char/string on memory, not screen ?
  How to get Font informations (as X, Y) ?
  How to add spaces between chars ?
  How to make my font ?
  How to edit an font ?
  Files included with this version
  History
  To contact me



What's this ?
-------------
  As the name suggest, this is a font library, it allow to use fonts.
  It work with DoorsOS and plusshell (I think ...), and work on TI89
(TI92 work, I think ... but fonts are 89s files).



Why this library ?
------------------
  Well, I think that TI89 fonts have some problems :
    - There is only 3 fonts
    - Little font is not an proportionnal font
    - No italic feature
    - A bit slower (for little font)
    - Little font don't delete background
    - Can't really use fonts in gray mode (only in the first plane)

  Then I've decided to make my owns fonts, there is :
    - More than 3 fonts (with this library there is >30 fonts)
    - All fonts are proportionnals fonts (an advantage ?)
    - Italic feature
    - Faster ?
    - Font background can be deleted
    - Fonts could be use in Gray mode (with effects as shadow)
    - Invert feature
    - Font files or InAsm fonts
    - Variable chars numbers in a font
    - An font maker (from an BMP, to convert Windows font into TI fonts)
    - An font Editor (To edit font, in the TI89 latter ?)
    - Some examples to learn how to use this library
    - etc ... (I'm sure to forgot something)

For example you can make an numerical font (with 10 chars -> number 0 to
number 9) and use it to draw a score.



How it works ?
--------------
  The main thing is the fontlib library (fontlib.h). With this file
you can use fonts.
  To use this library put this line in your asm file (at the begining):

    include "fontlib.h"

  This mean that the compiler include the file fontlib.h in you asm source.
Take care that fontlib.h is in your source directory else put :

    include "<directory>\fontlib.h"

  <directory> is the directory where file fontlib.h can be found.

  Now you can use fontlib functions. See fontlib.h to see all available
functions and properties.



How to use a font in a file ?
-----------------------------
  To use a font in a file you must give the file adress + 2
to the fontlib::InitFont function (in a0). Then you must search
a file yourself (see example1.asm).

  Example (d0 is the font file handle that you have found) :

	DEREF d0,a0                 ;Get the file address in a0
	addq #2,a0                  ;Skip file size (Word, 2 bytes)
	jsr fontlib::InitFont       ;Now initialize the font (at a0)

  After this font is ready to use.



How to use a font without a file ?
----------------------------------
  There is another way to use fonts and it does not require an file.
Useful because it does not require filelib and it safe (font already
exist and always valid). See example3.asm.
  To do this just give adress of the font in a0, example :

    move.l #Font_Data,a0
    jsr fontlib::InitFont

    ...

    Font_Data:
     dc.l "_Fnt"
     ...

  To do a such font see "How to make my font ?".



How to use Italic property ?
----------------------------
  (see example4.asm and example6.asm)
  In the library there is an variable named : fontlib::Italic (Word).
  If this variable is 0, font is normal else font will be in Italic.
  Note that calling fontlib::InitFont function clear this property.



How to use Invert property ?
----------------------------
  (see example5.asm and example6.asm)
  In this library there is an variable named : fontlib::Invert (Word).
  If this variable is 0, font will be normal else font will be inverted.
  Note that calling fontlib::InitFont function clear this property.



How to write char/string on memory, not screen ?
------------------------------------------------
  (See exemple2.asm)
  In this library there is an variable named : fontlib::WriteAddr (Long).
  This variable is the address where chars/strings are written, calling
fontlib::InitFont function set this variable to LCD_MEM (LCD screen). To
change address just do this :

    move.l a2,fontlib::WriteAddr

  a2 could be the screen address or plane address (for gray use). Note that
destination must be the same format as the screen (30 bytes for each line).



How to get Font informations (as X, Y) ?
----------------------------------------
  For this there is other variables :
    fontlib::FontX   ;Horizontal size for each char (Byte)
    fontlib::FontY   ;Vertical size for each char (Byte)

  BE CAREFUL !! fontlib::FontX and fontlib::FontY properties are BYTES
not words !! For example don't do this :

    move.w fontlib::FontX,d0

  but do this :

    clr.w d0                 ;Because only lower byte of d0 will be changed
    move.b fontlib::FontX,d0



How to add spaces between chars ?
---------------------------------
  The property : fontlib::SpaceX (Word) is the number of pixels between each
chars (use with fontlib::WriteString function).
  BUT if you use Invert property spaces will be white not black (it will be
ugly).

  Note that fontlib::InitFont function set this variable to 0.



How to make my font ?
---------------------
  With this library there is an DOS program : FontMake.
  It's Font Maker V1.0, it allow to create fonts from a Bitmap (graphic with
BMP extension) or to create an empty font (to use Font Edit v1.0).

  First the program ask you if you want to create a font from an Bitmap or
an empty font.



  
  _ For bitmap font, you must use an graphic editor (for example
  Paint Shop Pro). First, create an white bitmap (new file). Sizes are :

    Horizontal size = (FontX) * (Number of Chars)
      FontX is the horizontal size for ONE char (identical to all chars).
      Number of chars is the number of chars in the final font.
      -> Then there is no space between each chars

    Vertical size = FontY
      FontY is the vertical size for each char.

    The bitmap must have 16 millions of colors (24 bits).

    Then edit your new file. A useful thing is to draw a string with the editor,
  then you do nothing ! After save you file (BMP format, uncompressed).
  
  Once you have created the BMP file, launch Font Maker. Use file selector to
use you BMP file. Then the program ask you to enter the horizontal size of a
char (FontX).
  After is ask for first char code. Check Ascii table (TI doc for example) to
find the char code (for example space code is 32, 'A' code is 65).
  After you have to choose to store the font in a 89s file (ready to send to
the TI, for external fonts, fonts in files) or in an ASM file (to use in an
asm source, internal font, don't require any font file).
  For asm files, in you source write :
    include "fontname.asm"
    
    fontname is the name of the font created by Font Maker.




  _ For empty font, it's useful if you want to use Font Editor v1.0 to make
chars. The program ask you to enter a file name.
    The program ask you to enter the horizontal size of a char (FontX) and
the vertical size of a char (FontY).
    After is ask for first char code and the last char code. Check Ascii
table (TI doc for example) to find the char code (for example space code
is 32, 'A' code is 65).




How to edit an font ?
---------------------
  Launch FontEdit and use file selector to edit an existing font (font
ready to send to the TI). Very simple !
  When editing font don't forget to save you work before quit !
  (Keys to use are written on the File Editor screen).



Files included with this version
--------------------------------
  Fontlib.txt   : This text
  DoorsOS.h  \
  Filelib.h   \
  Fontlib.h    |  Include files, used by asm sources
  Graphlib.h  /
  Userlib.h  /

  Fontlib.89z   : Library ready to send to the TI89
  Fontlib.9xz   : Library ready to send to the TI92+ (TI92 II ?)

  \examples\    : All examples to learn how to use font library
  \FontEdit\    : Font Editor v1.0, to edit fonts (89s)
  \FontMake\    : Font Maker v1.0, to create fonts from BMP or nothing
  \Plusshell\   : Font library compiled with plusshell
  \Sources\     : Font Editor, Font Maker and MakeData source

  \Fonts\       : 35 fonts !! (with BMP, 89S and TXT files)



History :
---------
v1.0  : Lastest version with Invert, documentation, new examples, etc ...
        Official release (not a beta)
v0.9c : Included Font Maker and File Editor, more fonts, Italic ...
v0.9b : First good version with examples, fonts (30).
v0.9a : First version, only one example, only one font.



To contact me :
---------------
  E-Mail :
    candyman@i-france.com

  Web page for latest updates and programs :
    http://www.i-france.com/candyman