----------------------------------------------------------------------------- ==== RI FNS Library V1.0(C)1996 ==== ----------------------------------------------------------------------------- Written By Stephen McNamara ©1996 Red When Excited Ltd Introduction ============ 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. 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 about it. 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) Statement: FNSSetTab ------------------------------------------------------------------------- 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. Function: FNSLoad -------------------------------------------------------------------------- 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! Statement: FNSUnLoad -------------------------------------------------------------------------- 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. Function: FNSSlot ------------------------------------------------------------------------- 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. Function: InstallFNS ------------------------------------------------------------------------- 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 Statement: RemoveFNS ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: RemoveFNS font# This command simply removes an installed font from the list of font 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 Statement: FNSPrint ------------------------------------------------------------------------- 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 setting a drawing rectangle on the currently used bitmap to limit the output of the font - see FNSClip for more info. Instead of a string, though, you can give the address of a null terminated string in memory. Also, you can change the colour that text is being output in 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 Statement: FNSOutput -------------------------------------------------------------------------- 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 Statement: FNSInk ------------------------------------------------------------------------- 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 max posible range, though, is limited to 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 Statement: FNSPrefs ------------------------------------------------------------------------- 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 Function: FNSHeight ------------------------------------------------------------------------- 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 Function: FNSUnderline ------------------------------------------------------------------------- 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 Function: FNSWidth ------------------------------------------------------------------------- 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 Statement: FNSClip ------------------------------------------------------------------------- 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 heightest 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 Statement: FNSClipOutput ------------------------------------------------------------------------- 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 Statement: FNSOrigin ------------------------------------------------------------------------- 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. Function: FNSLength ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: a=FNSLength (font#,a$[,prefs]) This command is 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 Function: FNSVersion ------------------------------------------------------------------------- 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.0 of the library. 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)