JLib Font Extension v1.0                    Copyright 1996 Jonathan Griffiths

INTRODUCTION ===============================================================

Hello Again JLib Users!

 I hope this release of the font extention package is useful to you in
the process of developing (and making prettier) your JLib applications.

 I welcome your comments and suggestions, demo programs or anything else.
You can reach me at jon@ams.co.nz or jpg@wave.co.nz.

Cheers,
    Jon Griffiths.


INSTALLATION ===============================================================

1. You can install this package anywhere you want to on your hard drive, but
   I recommend putting it into the jlib/contrib directory.

2. You should have a copy of JLib installed before using this package, either
   version 1.7 or a later version. This extension will NOT work with earlier
   versions than this.

3. The archive jxfn_X-X (where X-X is the version number) contains a directory
   structure, so users of pkunzip should use the -d option. Unix users should
   use the -L option of unzip to convert the archive file names to lower case.

4. The include file "jx_font.h" in the jx_font/src directory should be copied
   to the standard include directory of your compiler (where jlib.h was
   installed).

5. Change to the src directory and compile the file jx_font.c :

   Watcom: wcc386 <opts> jx_font.c
   djgpp:  gcc -c <opts> jx_font.c
   unix:   gcc -c <opts> jx_font.c
   or:     cc  -c <opts> jx_font.c

   where <opts> are your standard compiler options if appropriate.

6. Make sure you include the object file jx_font.o (or .obj for Watcom) when
   compiling applications that use the font functions.

7. The object file jx_font.o (or .obj for Watcom users) can be added into the
   JLib library file so that you will automatically include it when you link
   with JLib. To do this from within the jx_font/src directory:

   Watcom users should type something like:
    wlib \watcom\lib386\jlib.lib +-jx_font.obj

   Unix users should do something like:
    ar -r /usr/lib/libj.a jx_font.o

   djgpper's should do something like:
    ar -r c:\djgpp\lib\libj.a jx_font.o

   Replacing the library path with an appropriate path for your system.

8. Installation is now complete!


USING THE FONT EXTENSIONS ==================================================

Using the font functions in your applications is very simple. All you
have to do is include the header file <jx_font.h> in your programs and
link with jx_font.o when you are compiling your application.

The functions available have been simplifiled from the first beta release
of this package. In addition, plain fonts can now be written as textured
fonts, by providing a buffer containing a texture which will be wrapped
over the font. This allows plin fonts to be drawn as an almost infinite
number of different textured fonts.

As of version 1.0, loading and displaying multi-color fonts is not yet
supported.


FUNCTION OVERVIEW ==========================================================

General

 In general the font extension behaves just like JLib (it contains full JLib
style debugging code) and is designed to be operationally similar. As in
JLib, NC versions of most functions are provided for you to use at your own
risk.

 Due to time constraints, the function documentation is limited. The source
code   should be fairly easy to follow, and as always, the example programs
can be used as reference material.

 Finally, if you have any problems or bugs, you can contact me for help.


Font Type

typedef {
  {...}                 This is the basic font type. Pointers to this type
}font;                  are passed around much the same way as the buffer_rec
                        structure is used in JLib.


Macros                      Meaning  

FONT_IS_PROPORTIONAL(fptr)  Is the font proportional? (i.e Different widths).
FONT_WIDTH(fptr)            The width (avg for proportional) of font letters.
FONT_HEIGHT(fptr)           The height of font letters.
FONT_FIRST_CHAR(fptr)       The first character in the font (usually ' ').
FONT_LAST_CHAR(fptr)        The last character in the font.
FONT_HAS_CHAR(fptr,c)       Is 'c' drawable in the font.


Font Drawing Styles

 Fonts may be drawn in 2 ways (Stamped or Stenciled), and with three styles,
Normal, Textured, and Underlined. The style is passed to character and
string drawing functions. To define the style you want to draw a string or
letter in, logical OR the style flags together. Since the normal stenciled
style is the default, passing 0 as a style flag causes the default drawing
style to be used.

Available Styles: FONT_STAMP, FONT_TEXTURE, FONT_UNDERLINE

Style                               Effect
0                                           Stenciled Normal
FONT_TEXTURE                                Stenciled Textured
FONT_UNDERLINE                              Stenciled Underlined
FONT_TEXTURE | FONT_UNDERLINE               Stenciled Textured and Underlined

FONT_STAMP                                  Stamped Normal
FONT_STAMP | FONT_TEXTURE                   Stamped Textured
FONT_STAMP | FONT_UNDERLINE                 Stamped Underlined
FONT_STAMP | FONT_TEXTURE | FONT_UNDERLINE  Stamped Textured and Underlined


Font Loading

font *font_load(char *filename);
font *font_free(font *font);

 These functions load and delete a font respectively. They are used in
the same way as sprite_load() and img_load_xxx() in JLib.


Font Information

int  font_letter_height(font *fnt,char c);
int  font_letter_width(font *fnt,char c);
int  font_string_width(font *fnt,char *c);

 These functions return information the size of a character or string when
drawn in the given font. Any characters that can't be drawn in the given font
will return a width of 0 and a height of the standard font height.


Font Drawing Functions

void font_char(font *fnt,BR *dst,int x,int y,char c,
               UBYTE col,BR *src,int style);

This function draws the character c into the buffer dst at position (x,y).
If style includes FONT_TEXTURE, src must point to a buffer large enough to
be used as a texture for the character, and col is ignored. If style does
not include FONT_TEXTURE, src may be NULL, and col is the color to draw the
font letter in.


void font_string(font *fnt,BR *dst,int x,int y,char *s,
                 UBYTE col,BR *src,int style);

This function is the same as font_char() except that it draws entire strings
rather than single characters.


CONVERSION PROGRAMS ========================================================

The directory "jx_font/convert" contains pre-built font conversion programs
to convert fonts into the jx_font extension format.  The jx_font format is
pretty simple and can be seen in the jx_font.c source. Read the conversion
programs source for usage information (I have no time to document them,
sorry!).

Remember that converting a font doesn't make it's copyright go away; please
only use fonts that are freely distributable and put an acknowledgement and
the original copyright notices where appropriate.

At present the following converters are available:

grx2jx.exe:     Build with djgpp V2.x, libgrx2.0 and JLib 1.6 or later.
      Converts from GRX fonts to jx fonts. GRX 2.0 has a huge range of fonts
that come with it in a seperate package called "cbgrxfnt.zip". The base GRX
distribution comes with a few families of fonts which i have included in the
"jx_font/font" directory.  If you've never heard of GRX then you can find
out more about it at the djgpp web site:

        http://www.delorie.com.

win2jx.exe:     Build with Watcom 9.x or later
      A watcom (v9.x) program,  this converts windows .fon files into jx
fonts.  It doesn't support .ttf fonts,  and some fonts don't seem to load.
If you rebuild the program with the latest version of watcom you may well be
able to load .ttf and new font files (it depends on whether Watcom have
extended the functionality of their _registerfonts() function in graph.lib).
If you build this program with Watcom 10.x and can load more fonts, please
mail me the uuencoded executable and I will stick it into this distribution.

There is a freeware utility available which converts .ttf fontf into .fon
font files which you can then convert using win2jx.exe. The program is
called SYSFON and is freely available (try a web search on Alta-Vista for
"sysfon10" and you should find a copy).


Feel free to write more conversion programs and send them in, or if you
have any freely distributable fonts that you want to share, please do.
