Net Yaroze User Font Module

By Matt Verran  (indirect help from Tenchi)

Description	

Here is a font module so you can include your own fonts into your yaroze
projects. Hopefully it is easy to use and does the job expected. See
usage for instructions. Please if you like or intend to use contact me
and let me know. I wouldn’t mind a little credit if it gets in any
finished projects. I have tried to keep this documentation close to the
official Yaroze docs, hopefully people will find it more helpful. I do
strongly recommend printing it out though, reading a word doc while
trying to code isn’t nice, and you run the risk of another shoddy MS
program crashing your computer before you have chance to save. Please
read the usage section, it contains importat stuff.

Contents	

		Usage

		Contact

		data structures

			Font

		functions

			LoadFont

			ColFont

			DispFont

			DispFontDX

Usage		

Firstly in order to use this module you must have a “fonttile.tim”.
An example has been included, but this is just for test purposes and not
really adequate for most applications, it contains no numbers for
example. In this version fonttile.tim must be an 8-bit tim, and each
letter must occupy the same amount of space. This means you cannot have
a proportional font. Also don’t forget to set the transparency setting
(‘translucent except black’ checkbox in Timutil) if you want to be
able to use it.

Simply drop font.o and font.h into the same directory as your code and
add the line “#include font.h” to your main.c file. Don’t forget
to load  in the fonttile.tim to the yaroze before you run code that
tries to load/display a font. 

To load the example fontile.tim include the lines:

Font sFont;  //this is your font structure

sFont.char_width=8;

sFont.char_height=8;

sFont.rows=2;

sFont.columns=13;

sFont.start_char='a';

sFont.end_char='z';

sFont.tim_data=SPRITE_ADDRESS;  //SPRITE ADDRESS is where 						  //you
loaded fontile.tim

LoadFont( &sFont );

This declares your Font structure and sets it up then LoadFont finishes
off the initialisation so you can use it. Now to put text on the screen:

ColFont(128,128,128,0,&sFont);

DispFont("my little test is success", 50, 94, &sFont );

	ColFont sets the font colour to white non-transparent. DispFont then 
puts it up on the screen, note this must be called in the render section
of 	your code. Another very important convention is that your GSOT 
variable must be called ‘world_ordering_table’ and the index used
for 	double 	buffering must be called ‘output_buffer_index’. They
must also 	be defined as extern. If you don’t like this then you can
go in and 	change the offending lines in font.c and remake it. Or if you
are really 	adventurous you could implement a proper solution and mail
me the 	updated source, I will then update this archive and credit you.

	I’ll let you figure out DispFontDX by yourself, nice eh?

Lastly I will try and explain why there is a start and end character 
setting in the Font structure. When DispFont tries to display your
string 	it converts it to ASCII (if you don’t know what this is, go
find out and 	get an ASCII table while you are away). Basically as long
as the 	character blocks in your Tim are in the same order as ASCII you
can 	give the start and end chars and the routines will work so you
could 	draw a Tim containing the entire ASCII table or one with just the
	numbers 0 to 9, it is up to you. Quick tip: if you do want to use 
numbers then turn your numeric values into strings using the sprintf 
function.

Contact	

Matt Verran / frktlx

email: matt@frktl.freeserve.co.uk

url: http://www.frktl.freeserve.co.uk

NY url: http://www.netyaroze-europe.com/frktlx˜/

If anyone wants to suggest, improve, comment or complain please don’t
hesitate to do so. I know this isn’t perfect, there were several font
display methods discussed on the newsgroups that improve on what is here
but that wasn’t the point. The point was to get a working bolt-on font
mechanism out to all those people who were having problems. At the
moment I am busy working on my own game project but if anyone wants to
improve the code please send the new version to me so I can update this
package. I don’t mind updating these docs. On the other hand if anyone
wants to do some good examples again please get them to me so I can
include with this lot.

Font

Font definition

Structure	

		struct Font {

				int rows, columns;

				int char_height, char_width;

				char start_char,end_char;

				long tim_data;

				u_char start_u, start_v;

				GsSPRITE spriteHandler; 

				GsIMAGE imageHandler; 

		}; 

Members	

		rows, columns			The number of rows and columns of 							characters
that the fonttile texture uses.

		char_height, char_width	The height and width (in pixels) that 						
defines one character in the fonttile 							texture.

tim_data			The address in main ram that the fontile 					is stored.

		start_char, end_char		The first and last characters represented 					
in the fonttile texture.

		start_u, start_v		Stores the start coordinates of the 							fonttile,
set internally  in LoadFont, no 						need to touch.

		spriteHandler			Internal sprite handler, set internally  in 					
LoadFont, no need to touch.

		imageHandler			Internal tim image handler, set internally  						in
LoadFont, no need to touch.

		

Comments	

This structure is the definition for a user font. The rows, columns,
char_height, char_width, start_char, end_char and tim_data members must
all be set up before the LoadFont function call is made.

LoadFont

Loads and initialises user font

Format	

		void LoadFont (

Font *Font

)

Arguments	

Font				Font structure to be loaded into.

Return Value	

		None

Comments	

Loads the fonttile texture from main ram into video ram and sets up the
Font structure internal members start_u, start_v, spriteHandler and
imageHandler.

Notes		

The rows, columns, char_height, char_width, start_char, end_char and
tim_data members of the Font structure to be loaded into must all be set
up before the LoadFont function call is made.

ColFont

Changes colour and transparency settings for font

Format	

		void ColFont (

u_char r, g, b, 

u_char trsp, 

Font *Font

)

Arguments	

r, g, b,				Red green and blue that the passed font is 					to be set
to, 0-255, 128=original value.

trsp,				Set to 1 if you want to make the font 						transparent, 0
otherwise.

Font				Font that colour values are to be applied 					to.

Return Value	

		None

Comments	

Allows alteration of colour values and transparency effects on fonts.

DispFont

Renders text to screen using user font

Format	

		void DispFont (

char *text, 

int x, y, 

Font *Font

)

Arguments	

text				String that is to be rendered to screen.

x, y				Position (in pixels) on screen that string 					is to start.

Font				Font that is to be used for rendering.

Return Value	

		None

Comments	

Renders a string onto the current active screen buffer at specified
position using passed font.

Notes		

Any characters in the string that are not within the start_char-end_char
range will be replaced with a blank space on render.

See Also	

		DispFontDX()

DispFontDX

Renders text to screen using user font

Format	

		void DispFontDX (

char *text, 

int x, y, 

short scalex, scaley,

long rotate,

Font *Font

)

Arguments	

text				String that is to be rendered to screen.

x, y				Position (in pixels) on screen that string 					is to start.

scalex, scaley			x and y direction scaling values, 						4096=original
size.

Rotate				rotation angle, 4096=1 degree.

Font				Font that is to be used for rendering.

Return Value	

		None

Comments	

Deluxe version of  DispFont, allows rotation and scaling of each char as
well as standard font rendering, operates slower than DispFont. The
rotate and scale values operate the same value on each character of the
string, they are to allow wizzy graphical effects.

Notes		

Any characters in the string that are not within the start_char-end_char
range will be replaced with a blank space on render.

See Also	

		DispFont()