@DATABASE RI FNS Lib V2.5
@Author Conversion program
@NODE OVERVIEW "Overview of RI FNS Lib V2.5"

                                  @{b}@{u}Overview@{ub}@{uu}

This Blitz2 library prints proportional fonts in either Amiga or Blitz mode.
It uses my own (rather primitive) font file format, details of which can be
found at the end of this text file. Fonts can be upto 64 pixels wide and any
height (although the font editor is limited to 64 pixels at the present
moment). Fonts can be output in upto 256 colours (AGA!) and in the following
ways:

   bold, centred, underlined, right-aligned or just standard left-aligned

NOTE: a default font (PERSONAL.8) is built into this library and can be used
by simply using font number 0.  You do not have to install this font, it is
automatically available for your use. A second point is to make is that the
library is set up with a clipping rectangle of 0,0 to 0,0. Thus you have to
use either FNSClip, FNSClipOutput or FNSOutput (with the optional clip
parameter) to set the clipping rectangle before you try to print anything.


These are all the FNS library commands:

			InstallFNS
			RemoveFNS
			FNSClip
			FNSClipOutput
			FNSSetTab
			FNSInk
			FNSOrigin
			FNSOutput
			FNSPrint
			FNSHeight
			FNSLength
			FNSLoad
			FNSSlot
			FNSUnderline
			FNSVersion
			FNSWidth
			FNSPrefs
			FNSUnload
			FNSShadowPrint

NOTE: All return values will be words except when using InstallFNS and
      FNSVersion.

                                 Control Codes
                                 =============

The FNS library now supports an additional control code for a return 
character (Ascii 10). You can now print, using this control code, multiple
lines of text in one go. If you have special print options on, for example
centering, then separate lines of text will automatically be centered below
each other.

Example usage:

  a$="Hello to all you people"+chr$(10)+"out there!"
  FNSPrefs %1,1
  FNSPrint 0,160,100,a$

  This will print "Hello to all you people" and "out there!" on separate
  lines of the destination bitmap. Both lines will be centered.

The control code to changeing ink colour during line printing is still the
same (Ascii 1). See the section on FNSPrint for more information.


FNS Font file format:
=====================

Header: 256 bytes.
	0-3   : 'FNS.' - file identifier - looked for by InstallFNS
	4-5   : height of font (#word)
	6-7   : width of font in multiples of 16 (#word)
	8-9   : underline position (offset from top of font, #word)
	10-11 : size of data for each font character
		[ (WIDTH/8) * height ]
	32-255: byte giving widths of each character in the font.
		These bytes doesn't really hold the width, rather
		they hold the value to add to the X position of the
		character to get to the position to print the next
		character at (!).

       256-EOF: character data starting at ASCII 32 (space)

@ENDNODE OVERVIEW

@NODE FNSSetTab "RI FNS Lib V2.5"

@{fg shine}Statement: FNSSetTab@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSSetTab tab_width

  Use this command to set the tab spacing used when printing. The value
given should be the spacing IN pixels.

@ENDNODE FNSSetTab

@NODE FNSLoad "RI FNS Lib V2.5"

@{fg shine}Function: FNSLoad@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: suc=FNSLoad (filename$,font#)

  This command is used to load a font from disk and automatically install it
for use by the FNS commands. Filename$ should be the full name of the file to
load (path$+file$) and font# should be 0<= and >=15. This command returns a
value of -1 for failure or the font number the font was installed as (see
InstallFNS). A failure could either be a load error or an installation error.

You should make sure that the file you load IS an FNS font file.

IMPORTANT NOTE: to use this command, you must have our RIAM*S library
                installed on your copy of Blitz2. Running it without this
                library could, and probably will, cause a major crash of
                your computer. 

Also note that if you do an ERASEALL (RIAM*S library command for erasing
banks), you will DELETE your font from memory!

@ENDNODE FNSLoad

@NODE FNSUnLoad "RI FNS Lib V2.5"

@{fg shine}Statement: FNSUnLoad@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSUnLoad font#

  This command is used to remove a font installed with the FNSLoad command.
When this command runs it automatically removes the font entry in the FNS
commands and deletes the memory that the font file is held in. There is no
need to do this at the end of a program as the RIAM*S library automatically
frees up all allocated memory.

@ENDNODE FNSUnLoad

@NODE FNSSlot "RI FNS Lib V2.5"

@{fg shine}Function: FNSSlot@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: address.l=FNSSlot

  FNSSlot returns the adres of 16 longwords. These longwords are the actual
adresses of fonts in memory. This command is really just for testing
purposes.

@ENDNODE FNSSlot

@NODE InstallFNS "RI FNS Lib V2.5"

@{fg shine}Function: InstallFNS@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: font_num.b=InstallFNS(font_num.b,address.l)

  This is used to install a font so that it is available for use by the
output routines. Font_num should be a number 0=> and <=15, address should be
the address in memory of the FNS font file. This function will check that the
address given does contain a FNS font (it will look for the header 'FNS.'),
if it cannot find the font or something else goes wrong it will return a 0
to you, otherwise it will return the number the font was installed as.

NOTE: The font number you give is automatically ANDED with $F when you
      call this function, thus if you supply a number greater that 15
      you could actually overwrite a previously installed font.

See:  RemoveFNS

@ENDNODE InstallFNS

@NODE RemoveFNS "RI FNS Lib V2.5"

@{fg shine}Statement: RemoveFNS@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: RemoveFNS font#

  This command simply removes an installed font from the list of fonts held
internally by the FNS routines. There is no real need to remove fonts as
installing fonts takes up no memory, except of course the actual font data. 
You do not need to remove FNS fonts before ending a program.

See: InstallFNS

@ENDNODE RemoveFNS

@NODE FNSPrint "RI FNS Lib V2.5"

@{fg shine}Statement: FNSPrint@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSPrint font_num.b,x.w,y.w,a$/string_address[,preferences,colour]

  This command prints the string a$ in an FNS font at the position X,Y.
Font_num is the number of a previously installed FNS font, the output of
this command is sent to the current FNS bitmap (see FNSOutput). You can set
a drawing rectangle on the currently used bitmap to limit the output of the
font - see FNSClip for more information.

Instead of a string, though, you can give the address of a null terminated
string in memory. Also, you can change the colour of the text output in the
current string by putting the character ASCII 1 followed by a byte value
from 0-255 specifying the colour to change to.

The optional parameters are for controlling how the text is output. They
automatically overide the default setting but are not permanent, i.e. the
default output style and colour are restored after the line has been output.
Use FNSInk and FNSPrefs to set the default font output mode.

See: FNSOuput,FNSInk,FNSPrefs,FNSOrigin,FNSClip

@ENDNODE FNSPrint

@NODE FNSOutput "RI FNS Lib V2.5"

@{fg shine}Statement: FNSOutput@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSOutput bitmap#[,clip_update]

  This command selects a bitmap for use by the FNS routines, the bitmap must
be a previously reserved Blitz 2 bitmap object. After this command all FNS
font printing will occur on the selected bitmap. The optional parameter
allows you to update the clipping rectangle for output at the same time as
setting the output bitmap. Setting clip_update to a non-zero value will
cause the clipping area to automatically be set to the dimensions of the
selected bitmap.

NOTE: This command MUST be used before you attempt to use FNSPrint.
      The maximum depth of the bitmap for printing is 8 bitplanes since this
      is all Blitz 2 currently supports.

See: FNSClip,FNSClipOutput

@ENDNODE FNSOutput

@NODE FNSInk "RI FNS Lib V2.5"

@{fg shine}Statement: FNSInk@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSInk colour#

  This sets the output colour for the FNS font drawing routines. The number
range is dependant on the depth of the destination bitmap, the maximum
possible range, though, is limited from 0 to 255 colours. The FNS output
routines will attempt to draw in all the bitplanes of the selected bitmap,
any extra bits in the ink colour will be ignored.

See: FNSPrefs

@ENDNODE FNSInk

@NODE FNSPrefs "RI FNS Lib V2.5"

@{fg shine}Statement: FNSPrefs@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSInk preferences[,colour#]

  This sets the output prefs for the FNS font drawing routines but at the
same time also sets the colour for the FNS routines (optional). At the moment
the following options are available, the bits of the preferences byte are
used to select the different options:

                       bit 0: Centred text
                       bit 1: Bold text
                       bit 2: Underline
		       bit 3: Right aligned

See: FNSInk,FNSPrint,FNSLength

@ENDNODE FNSPrefs

@NODE FNSHeight "RI FNS Lib V2.5"

@{fg shine}Function: FNSHeight@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: height.w=FNSHeight(font_num)

  This routine returns the height of a previously installed FNS font.

Font_num should be 0=> and <=15.

See: FNSUnderline,FNSWidth

@ENDNODE FNSHeight

@NODE FNSUnderline "RI FNS Lib V2.5"

@{fg shine}Function: FNSUnderline@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: under_pos=FNSUnderline(font_num)

  This routine returns the underline position of the selected FNS font.

Font_num should be 0=> and <=15.

See: FNSHeight,FNSWidth

@ENDNODE FNSUnderline

@NODE FNSWidth "RI FNS Lib V2.5"

@{fg shine}Function: FNSWidth@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: width.w=FNSWidth(font_num)

  This routine returns the width in multiples of 16 of the selected FNS font.  Font_num should be >=0 and <=15.

See: FNSHeight,FNSUnderline

@ENDNODE FNSWidth

@NODE FNSClip "RI FNS Lib V2.5"

@{fg shine}Statement: FNSClip@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSClip x1,y1,x2,y2

  This command is used to limit the output of the FNSPrint command. The
co-ordinates given should describe a rectangle that is to be used to clip
the output. This rectangle can be thought of as a window on the bitmap - no
printing can occur outside of the window.

X1,Y1 are the top left corner of the clipping rectangle and X2,Y2 are the
bottom right corner. Please note that both X co-ordinates should be multiples
of 16 and that X2 should be the highest multiple of 16 that you do not wish
output to occur at. Thus if your bitmap is 320x256 then you would use the
following to set the clipping rectangle to the full bitmap:

		FNSClip 0,0,320,256

See: FNSClipOutput,FNSOutput

@ENDNODE FNSClip

@NODE FNSClipOutput "RI FNS Lib V2.5"

@{fg shine}Statement: FNSClipOutput@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSClipOutput

  This command is used to quickly set the clipping rectangle for the FNS
commands to the full size of a bitmap.

See: FNSClip,FNSOutput

@ENDNODE FNSClipOutput

@NODE FNSOrigin "RI FNS Lib V2.5"

@{fg shine}Statement: FNSOrigin@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSOrigin [x,y]

  This command is used to set an origin co-ordinate for printing output.
Whenever you use FNSPrint, the origin co-ordinates are added (as words) to
the co-ordinates you give for output, i.e. setting the origin at 100,0 and
printing at co-ordinates 0,0 will cause the output to be at 100,0.

Using this command without any parameters will cause the origin to be reset
to the position 0,0.

NOTE: This command does not affect the use of the FNSClip command.

@ENDNODE FNSOrigin

@NODE FNSLength "RI FNS Lib V2.5"

@{fg shine}Function: FNSLength@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: a=FNSLength (font#,a$[,prefs])

  This command is the equivalent of the basic command a=len(a$) except that
it returns the x size, in pixels, of the string if it were to be printed in
the font font#. The optional preferences parameter allows you to adjust the
output of the string, if you specify no preferences then this function will
use the previously selected preferences to calculate the string length. 
Using preferences allows you to account for things like bold text output.

See: FNSPrefs

@ENDNODE FNSLength

@NODE FNSVersion "RI FNS Lib V2.5"

@{fg shine}Function: FNSVersion@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: a.q=FNSVersion

  This command allows you to test the version number of the FNS library that
your program is being compiled with. It returns a quick float value and so
you should use a quick float variable for the answer. This doc file was
written for version 1.1 of the library.

@ENDNODE FNSVersion

@NODE FNSShadowPrint "RI FNS Lib V2.5"

@{fg shine}Statement: FNSShadowPrint@{fg text}
-----------------------------------------------------------------------------
Modes : Amiga/Blitz
Syntax: FNSShadowPrint fontnum,x,y,a$/string_address,[prefs,colour[,shadow]]

  This command is almost the same as FNSPrint, the only difference is that
it outputs the specified text string twice - giving the illusion of a shadow
on the string. The parameters are the same as FNSPrint, the extra parameter
allows you to specify the colour of the shadow - if not specified the shadow
defaults to colour 0.

This command allows the replacing of:

		FNSPrint 0,x+1,y+1,"Hello",0,0
		FNSPrint 0,x,y,"Hello",0,1

with

		FNSShadowPrint 0,x,y,"Hello",0,1,0

@ENDNODE FNSShadowPrint

@NODE MAIN "RI FNS Lib V2.5"

.---------------------------------------------------------------------------.
|                              @{b}RI FNS Lib V2.5@{ub}                              |
`---------------------------------------------------------------------------'

                         ©1996 Red When Excited Ltd

        Undocumented commands added by Toby Zuijdveld 02/03/1999
                       mailto: hotcakes@abacus.net.au

                             @{"     Overview     " link OVERVIEW}

                               Command Index                                

             @{" FNSClip        " link FNSClip}                @{" FNSClipOutput  " link FNSClipOutput}
             @{" FNSHeight      " link FNSHeight}                @{" FNSInk         " link FNSInk}
             @{" FNSLength      " link FNSLength}                @{" FNSLoad        " link FNSLoad}
             @{" FNSOrigin      " link FNSOrigin}                @{" FNSOutput      " link FNSOutput}
             @{" FNSPrefs       " link FNSPrefs}                @{" FNSPrint       " link FNSPrint}
             @{" FNSSetTab      " link FNSSetTab}                @{" FNSShadowPrint " link FNSShadowPrint}
             @{" FNSSlot        " link FNSSlot}                @{" FNSUnderline   " link FNSUnderline}
             @{" FNSUnLoad      " link FNSUnLoad}                @{" FNSVersion     " link FNSVersion}
             @{" FNSWidth       " link FNSWidth}                @{" InstallFNS     " link InstallFNS}
             @{" RemoveFNS      " link RemoveFNS}

                                @{" Examples " LINK Examples}

                              @{" Main Document " LINK "Blitz2:RedHelp/REDBlitzLibs/REDBLITZLIBS.GUIDE/MAIN"}
                              @{" Library Index " LINK "Blitz2:RedHelp/REDBlitzLibs/REDBLITZLIBS.GUIDE/LIBRARYLIST"}

@ENDNODE MAIN

@NODE Examples "Example Programs"

                             @{b}@{u}Example Programs@{ub}@{uu}

@{fg shine}EXAMPLE 1@{fg text} - FNS library (C)1994 Reflective Images :

           @{" Load Example 1 " system "run >NIL: BLITZ2:REDHelp/ShowExample File=Blitz2:RedHelp/REDBlitzLibs/Examples/RIFNSLib1.bb"}
           @{" Compile It!    " system "run >NIL: BLITZ2:REDHelp/ShowExample File=COMPILE"}

@ENDNODE Examples