* DISABLE WORD WRAP!

****************************************************************
* Custom Font Printing Routines ver.3 for FreeBASIC and GFXlib *
****************************************************************
* by Lachie Dazdarian(Dean Janjic)  September, 2011.  *
******************************************************* 

       Table Of Contents
[-----------------------------]
[ 1. General information      ]
[ 2. Usage                    ]
[ 3. About the fonts          ]
[ 4. Creating your own fonts  ]
[ 5. Credits                  ]  
[ 6. Updates                  ]   
[ 7. Contact                  ] 
[ ----------------------------]


1. General information
======================

These routines allow you to manage and print text with 
custom made fonts (loaded from BMP images) onto the screen 
by using simple and user-friendly subroutines. 8 bit as 
well as 16, 24 and 32 bit color depth modes are supported.

I was motivated to create these routines due the lack of
similar in the FreeBASIC community, especially those for 
16 bit color depth mode.

Printing with these routines is almost easy as using the
PRINT statement.

This package includes 5 already made fonts of smaller 
size and 1 extra large. You can create your own fonts but 
about that in one of the following sections.

The routines were developed for GFXlib 2, but only 3 GFXlib
statements that are necessary are used in them: BLOAD, GET
and PUT. So converting these routines to some other graphics 
library is easy as much as this library features appropriate 
substitutes for these statements. I'm aware that SDL uses
a really unintelligent way to store and display graphics
so a "quick conversion" to SDL is not an option. Anyway, if
anyone manages to port these routines to some other graphics
library, let me know.


2. Usage
========

First, 3 demos present in this package are more than
illustrative so the following explanation is not necessary 
for you to know how to use these routines. Still, I think 
the readme file should contain some basic info.

To use these routines first you need to attach "customfont.bi" 
or "24bitcustomfont.bi" onto your source code (depends on the
color depth you'll be using) with:

#include "customfont.bi"

Then you need to declare one or more font arrays where the 
font you'll load will be stored. Example:

DIM SHARED MyFont AS FontType 

Before loading a font you need to initiate a graphic mode.
You load fonts with the LoadFont sub (fonts saved in a grid 
consisted of 22*22 large blocks) or the LoadBFont sub (fonts 
saved in a grid consisted of 48*48 large blocks). If you
are using LoadFont you need to initiate a screen mode with
a minimum width of 320 and a minimum height of 200. If you 
are using LoadBFont you need to initiate a screen mode with 
a minimum width of 640 and a minimum height of 400. Example:

SCREEN 13,8,2,0

LoadFont "Fonts/FNT3PAL2.bmp", FontArray, 1

With the last parameter you set if every font characters will 
feature its own width (parameter equals 1; load most of the 
fonts on this way) or all characters will feature a unique
width (parameter equals 2) which is preset in the font BMP 
images (inside the refence box). The second mode is to be used 
only with fonts that are drawn on a specific way, like the 
standard ASCII font (check the BMP files). FontArray should 
equal to some font array you previously declared like MyFont 
in our example.

To print text in the loaded font you need to use PrintFont. 
Example:

PrintFont xpos, ypos, YourString, FontArray, spacing, PMode

xpos and ypos are the starting coordinates of the string and
FontArray is the name of the array where your font in stored.
spacing sets the spacing between characters and PMode sets
the mode of printing/pasting (1 for TRANS; 2 for PSET). 
YourString is the string you want to print. You can input 
some text directly like "Print this!" or pass it with a 
STRING variable.

In 16 and higher bit color depth mode you also have the 
PrintAlphaFont subroutine which allows you to print text 
with translucency. It works the same as PrintFont but instead 
of PMode the last parameter sets the alpha blender (a number 
from 0 to 255; ratio of translucency).

Next is a simple example code that summarizes all of this:

#include "customfont.bi"

DIM SHARED MyFont AS FontType 

SCREEN 13,8,2,0

LoadFont "Fonts/FNT3PAL2.bmp", MyFont, 1

PrintFont 20, 100, "Hello! My name is Bush, George Bush.", MyFont, 1, 1

SCREENCOPY
SLEEP

Copy and paste, and compile if you want.

Both LoadFont and LoadBFont subs set the page 1 as the working 
page and page 0 as the visible page before loading the font 
so I need to use SCREENCOPY or SCREENSET to display the text from 
this example. You can reset the work pages on any way you want 
after using these subs. Just have in mind how they are originally 
set in these subs.

If you don't like including .bi files into your source you can 
copy and paste the variable and subroutine declarations from it, 
as well as the very subroutines. I'm sure you don't need 
instructions for this.


3. About the fonts
==================

The original package comes with 5 "normal" sized fonts and 
one extra large. Most of them were extracted from PP256s 
PUT files.

You will notice that the fonts are saved in grids consisted 
of 12*8 blocks. 5 fonts are saved in grids consisted of 22*22
pixels large blocks (boxes) while the extra large font is 
saved in a grid consisted of 48*48 pixels large blocks. 
The fonts that are saved in 8 bit color depth mode are 
available in two palettes, standard and gradient. Converting 
them to the palette your 8 bit color depth program will use 
should be easy and depends on your ability to use specific 
drawing programs. I can't provide specific help in this 
area.

Not all fonts feature all 96 characters supported by these 
routines. If you try to print any of the un-existing characters 
it simply won't be printed while the others in the string 
will be.

Each font BMP file features an reference box, placed in the
13th column (the box most to the right). I'll refer to this
box in the next section since it's important only if you
want to edit the existing fonts or create your own.

When I was converting some fonts from their original 
palette to the second one I was unable to find the best
color alternatives so I will point out the
original palette of each font.

The fonts present in the package are as follows:

Fonts saved in 22*22 pixels large blocks:
-----------------------------------------

FNT1PAL1.BMP : Ball Blazing Fantasy font by Lachie 
               Dazdarian saved in 8 bit color depth 
               and standard palette. 8 pixels high 
               characters with maximum of 9 pixels 
               in width. 

FNT1PAL2.BMP : Ball Blazing Fantasy font by Lachie
               Dazdarian saved in 8 bit color depth
               and gradient palette (original).

FNT2PAL1.BMP : Chris Chadwick's CHARSET1 font which
               was extracted from Pixel Plus 256, his
               sprite editing program for QuickBasic.
               8*8 pixels large characters(all characters 
               feature equal width). Saved in 8 bit color
               depth and standard palette (original).

FNT2PAL2.BMP : Chris Chadwick's CHARSET1 font saved in
               8 bit color depth and gradient palette.

FNT3PAL1.BMP : Chris Chadwick's CHARSET3 font saved in
               8 bit color depth and standard palette
               (original). 8 pixels high characters with
               maximum of 9 pixels in width.

FNT3PAL2.BMP : Chris Chadwick's CHARSET3 font saved in
               8 bit color depth and gradient palette.

FNT4PAL1.BMP : Chris Chadwick's CHARSET2 font saved in
               8 bit color depth and standard palette
               (original). It does not feature lower
               case letters. 16*8 pixels large 
               characters.       

FNT4PAL2.BMP : Chris Chadwick's CHARSET2 font saved in
               8 bit color depth and gradient palette.

FNT51PAL1.BMP : Standard ASCII font (low resolution) saved
                in 8 bit color depth and standard palette.
                White color characters. 7*7 pixels large
                characters. Extracted in this case from
                The Griffon Legend's(by syn9) font file.

FNT51PAL2.BMP : Standard ASCII font (low resolution) saved
                in 8 bit color depth and gradient palette.
                White color characters.

FNT52PAL1.BMP : Standard ASCII font (low resolution) saved
                in 8 bit color depth and standard palette.
                Sky blue characters.

FNT52PAL2.BMP : Standard ASCII font (low resolution) saved
                in 8 bit color depth and gradient palette.
                Sky blue characters.

24bitFNT1.BMP, 24bitFNT2.BMP, 24bitFNT3.BMP, 24bitFNT4.BMP,
24bitFNT51.BMP, 24bitFNT52.BMP : All the previous fonts
converted to 24 bit color depth mode from original palettes.

Fonts saved in 48*48 pixels large blocks:
-----------------------------------------

BFNT1PL1.BMP : Chalet font by Kara Computer Graphics. Font
               extracted from Deluxe Paint II (its built-in
               font). 47 pixels high and with up to 48
               pixels wide characters. It does not feature 
               lower case letters. Saved in 8 bit color depth
               mode and standard palette.

BFNT1PL2.BMP : Chalet font by Kara Computer Graphics saved in 
               8 bit color depth mode and gradient palette
               (original).

24bitBFNT1.BMP : Chalet font converted to 24 bit color depth
                 mode from the original palette.

Feel free to use any of these fonts but show the minimum of
courtesy and CREDIT the original authors. ABOVE ALL don't
try to PASS THESE FONTS AS ORIGINALLY YOURS! Also feel 
free to edit these fonts and use them as a basis for your 
own fonts.


4. Creating your own fonts
==========================

You are encouraged to create your own fonts or edit the
ones already present with any kind of drawing program 
that can edit BMP images. The best way to learn how to 
input fonts into the grid blocks is by looking at the 
created fonts. And every time you start creating a new
fond you must use an existing one as a reference since
you can't know in which box which character goes.

The most important thing you should know is that each 
character in the font is captured from the top-left corner 
of the current character's block to the point determined by 
the current character's width (or preset width set inside 
the reference box) and preset height (also set inside the 
reference box). This is well explained on the instructions 
images. 

Preset width sets how wide spacing will be in the 
string (number of pixels) and with fonts loaded with a unique 
width is also sets the unique width of every character. The 
unique width can make creating a font more difficult and 
you should check FONT 2 (FNT2PAL2.BMP) to understand why.
For example,  with "thin" characters like the letter "I" you 
need to leave some space to the left or better yet you need 
to input every character in the middle of the invisible box 
determined with the preset width and preset height. If you 
want your font to feature relative character widths all you 
should do is place each character on the left edge of his 
block and the width will be set automatically by checking 
where's the most right pixel(s) of that character.

Have in mind that the preset height must be that long to
include the lowest pixel of the lowest character in the font.
Same thing when using a unique preset width and ONLY when
using that mode of font loading (the most right pixel of the 
widest character).

I recommend you to use 8 bit drawing programs like Deluxe 
Paint or GrafX2 to work on 8 bit font images and then you can 
convert them (if needed) to 24 bit mode with any 32 bit drawing 
program like Paint Shop Pro. Be sure to change the background 
color (color 0) of every 8 bit image to RGB 255,0,255 since that 
color is considered as transparent in 16 and higher bit color 
depths. A note: You can't change the resolution in GrafX2 from 
320*200 to any other but you can scroll through images that 
exceed it. I found it to be the best tool to work on fonts saved 
in this kind of font format.


5. Credits
==========

Original font printing routine was created by Chis Chadwick
and it came as a part of his Pixel Plus 256 package.
Additional code (font loading subs, font formats, font
files, changes, ...) by Dean Janjic.
Fonts are credited in section 3. Give credits where 
it's due!


6. Updates
==========


28.09.2011 - Made some changes to the code for the routine
to compile with -exx.

09.08.2007 - Boy, time sure flies. Anyway, the routines
were converted so they would compile in FB ver.0.17 and
hopefully in many next versions to come. Few nitpicks were
done in the code you don't need to know about. :P

22.04.2006 - A small fix. Images saved in 24 bit mode were 
corrected in the sense that the transparent color in them 
now works in all color depth modes (16, 24 or 32). Original 
mix-up was a result of an error (if it's an error) which 
was happening when 8 bit images were saved as 24 bit 
images (bright pink background color was not converted 
properly; it was not RGB 255,0,255). Since this issue
was resolved module "16bitcustomfont.bi" was renamed to 
"24bitcustomfont.bi" and some comments were corrected.
Now the images saved in 24 bit mode work in all
16 bit and above color depth modes which was not the
case earlier. 


7. Contact
==========

Send comments, questions, suggestions, good wishes, ill 
wishes, bashing, etc. to lachie13@yahoo.com.

My website: http://lachie.phatcode.net

















