SETHS BMP FONTLIB v3d.11

This app and included library of functions are all freeware! Yep, that means you can use them as much as you like. If you'd like to credit me then that's cool, just put me down as Seth Jeffery or cyberseth, and my email is cyberseth@muscle-power.net

Basically, you use the included app "FontCreator.exe" to make your cool-looking bitmap fonts and then save them. The font creator saves two files: one BMP file which is the image, and one FTD file which holds all the extra data like image positions etc. If you want you can make the BMP files smaller by using whatever graphics software you have to convert it to PNG files...

Then all you need to do to use your bitmap fonts is something like:

Include "bmpfont.bb" ; or Include "bmpfont3d.bb"

myfont = LoadBMPFont("fontname")

BMPText myfont, 10, 10, "Testing testing, 1 2 3!"

Look at the 3 bmptest.bb files for demos on how the BMPfonts are loaded and used. You should find it's pretty straightforward, and I've tried to make it as simplistic as possible. Use the "bmpfont.bb" include for 2D fonts and text, and use the "bmpfont3d.bb" include for 3D fonts and text.

If you can't figure it out, here is a run-down of all the commands.

2D COMMANDS

LoadBMPFont( filename$ [, LoadPNG ])
Loads a BMP font into memory and returns its file handle. NOTE: Do not supply the file extension, as the software has to load both the image AND the FTD file. If your image is a PNG file then specify LoadPNG as 1.


BMPText( bmpfnt, x#, y#, txt$ [, h_align [, v_align [, width ]]] )
Writes text at ( x, y ) using the specified BMP font. h_align and v_align will vertically/horizonally centre the text if specified as true. If you set the value of width, then the text will be automatically WRAPPED to the specified width.

BMPTextHeight( bmpfnt, txt$, width [, linesonly ] )
Returns the height (in pixels) that the specified, wrapped text takes up. If you just want the number of lines instead of pixels, set linesonly to True.

BMPFontHeight( bmpfnt )
Returns the height of the BMP font.

BMPStringWidth( bmpfnt, txt$ )
Returns the width, in pixels, of a string, using the specified BMP font.

FreeBMPFont( bmpfnt )
Destroys the BMP font, and frees up the resources it uses.

BMPInput( bmpfnt, x, y, txt$, answer$ [, maxlength [, cursormk ]] )
Allows the program to input text from the user without disrupting the flow of the code in the way that the standard Input command does. The format is: answer$ = BMPInput( bmpfnt, x, y, txt$, answer$ ... )

Every time the function is called, the program checks for any keys pressed and adds them to answer$, or if delete is pressed it subtracts from the length of answer$.

If txt$ is supplied then the Input is drawn to the screen straight away, where txt$ can be used as a question prefix before answer$, for example "Enter Name: ". If txt$ is not supplied then nothing will be drawn to the screen, and the function will solely be used to input key presses into answer$.

Supplying maxlength will result in the user only being allowed to enter a certain number of characters.

You also have the option of having a blinking cursor drawn at the end of your input text. The cursormk parameter accepts three values: BMPFNT_NONE, BMPFNT_VISIBLE and BMPFNT_BLINKING. If you wish to change the blink rate, use the SetBMPInputCursorRate function.


SetBMPInputCursorRate( on [, off ] )
Sets the time in milliseconds for when the cursor for the BMPInput command blinks on and off. If "off" is omitted, it is assumed to be the same length of time as "on".


3D COMMANDS

LoadBMPTexture( filename$ [, flags ] )
Loads a BMP font into memory as a texture for use with BMP meshes, and returns its handle. As in the LoadBMPFont function, do NOT specify the filename's extension.

FLAGS
0 - Unmasked texture.. BMP file
1 - font is stored in a PNG file, instead of a BMP
2 - Alpha-fade the edges of the font (makes it slightly anti-aliased)
4 - Masked edges of the font

It must be noted that for the crispest font, you should create it in the BMP FontCreator with a mask color of 0,0,0 and load it with flag 4. It is also much faster to load this way, because otherwise the software must go through each pixel and check its colour against the mask colour specified, editing the alpha value manually...


BMPTexture( bmpfnt )
Returns a handle associating the texture used with the BMP font, if you need it.


CreateBMPMesh( bmpfnt, txt$ [, width# [, parent ]] )

Creates a single-surface mesh using the specified BMP font texture, containing the specified text, and returns its entity handle. The entity's pivotal position is always in the centre. If you specify the width, in 3D units, the text will wrap.

The exact measurements of the mesh are calculated so that the height per line is always equal to one unit. Thus the width will be equal to: BMPStringWidth( bmpfnt, txtline$ ) / BMPFontHeight( bmpfnt )
Or you could find it with MeshWidth..


CreateBMPCylinder( bmpfnt, txt$ [, parent ] )
Creates a cylindrical mesh using the specified BMP font texture, containing the specified text, and returns its entity handle. Any Carriage returns [ chr(13) ] in the text will be used to create a new line in the cylinder. The entity's pivotal position is always the centre.

The cylinder has a radius of 1 unit, and a height of 1 unit per line of text.


FreeBMPTexture( bmpfnt )
Destroys a BMP font texture and frees up the resources and video memory that it takes up.

AddToMesh( mesha [, meshb ] )
If you have two BMPMeshes with the same font then rather than having two separate meshes with two separate surfaces, this function allows you to combine them both into one. The second mesh will be inserted into the first mesh at its current position.


WELL, HAVE FUN!!
- Seth Jeffery