Home

Welcome to ttf-gdos!

ttf-gdos (Release 2.3)

TTF-GDOS is a GDOS replacement that uses true type fonts as well as
gem fonts.

It is small, fast & efficient and can easily be used without a hard drive.

It also incorporates:
- a caching system so you can use more fonts for a given amount of memory,
- built in bezier functions

This release includes ttf2gem, a utility program that creates accurate gem
fonts from a true type font (new for 2.3)

• ttf-gdos (Release 2.3)
  • DISCLAIMER
  • Quick Start
  • New for Release 2.3
  • New for Release 2.2
  • New for Release 2.1
  • New for Release 2.0
  • New for Release 1.0
  • Features of ttf-gdos
  • What is included in this release?
• What is GDOS?
  • Gem Fonts vs True Type Fonts
• Using TTF-GDOS
  • Creating a ttf-gdos.inf file
  • Important Upgrade Notes
  • The Font Cache
• ttf2gem
  • GST font identification numbers
• The chpr accessory
• The screen drivers
• Using ttf-gdos with Timeworks
• Example - TTF-GDOS on Timeworks
• Some fonts are too big or are not recognised
  • How to fix these font files
• The ttf-dump utility
• Bezier Curves - Programming Info
• The FSMC Cookie
• Programmer's info
• Problems?
• Limitations
• And Finally ...

Using true type fonts gives you 3 big benefits:
- you can choose from a vast range of true type fonts
- true type fonts are scalable so you can have almost any size
font you want
- true type fonts need much less disk storage than typical gem
printer fonts, so even on a low spec machine you can use lots
of fonts.

Gem fonts and true type fonts complement each other perfectly - gem fonts are
small and fast, while true type fonts are device and resolution independent.
A single true type font can scale to any point size at any resolution.

Note that ttf-gdos still behaves like it uses GEM (ie bit mapped) fonts - you
need define a set of point sizes beforehand, and choose one of these sizes
in your program. ttf-gdos creates the correct gem font if it isn't present in
your GEMSYS folder.

It's best to use gem fonts when these font files are small (eg for your
screen), and true-type fonts when the gem font files are large (eg for your
printer). Gem fonts for the screen are fast and render much better for small
point sizes - typically when the font is smaller than 25 or 30 pixels high.
True type fonts are usually much smaller than gem printer fonts, but are
also much slower. For printing the time overhead is less important.

Use the ttf2gem utility program to create any gem font files you need.

DISCLAIMER

TTF-GDOS IS PROVIDED "AS IS" WITHOUT ANY WARRANTY EXPRESSED OR IMPLIED,
INCLUDING THE WARRANTY OF NON-INFRINGEMENT AND THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

THE AUTHOR OF TTF-GDOS WILL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY YOU AS
A RESULT OF USING TTF-GDOS. IN NO EVENT WILL THE AUTHOR BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR LOST PROFITS EVEN IF HE HAS
BEEN ADVISED OF THE POSSIBILITY OF THEIR OCCURRENCE. THE AUTHOR WILL NOT BE
LIABLE FOR ANY THIRD PARTY CLAIMS AGAINST YOU.

IN OTHER WORDS, THE AUTHOR OF TTF-GDOS IS TOTALLY BLAMELESS FOR ANYTHING
(YES, ANYTHING) THAT MAY GO WRONG AS A RESULT OF YOUR USING TTF-GDOS. YOU
MAY USE TTF-GDOS ONLY IF YOU ACCEPT FULL AND ABSOLUTE RESPONSIBILITY FOR
DOING SO.

Quick Start

Skip to the section titled "Using TTF-GDOS" below.

New for Release 2.3

ttf2gem.prg:
This is a utility program that uses freetype's hinting engine to generate
gem fonts from a true type font file.

Bug fixes:
- ndc cordinates failed on tos 2.06
- attributes for multiple virtual workstations did not work

Some code tidy up:
- open virtual workstation finds the root device from the handle parameter.
the device number is ignored.
- handle 0 could be used for vdi calls other than open virtual workstation

New for Release 2.2

symbol files are not remapped, so they now appear in a sensible order
fixed obscure bug in bezier functions
some minor improvements & efficiency gains

New for Release 2.1

* if you are upgrading from a previous release of ttf-gdos
please read carefully the note about compatibility below. ***

1. ttf-gdos now works with timeworks. See separate section below for
   more details.

2. new fix-fwid.prg utility for timeworks

3. bug fixes

4. some utilities enhanced

New for Release 2.0

1. fonts are only generated as they are used, so font loading is now
   almost instantaneous

2. font data is held in a memory cache, so any number of fonts are
   available in a fixed memory space

3. vq_devinfo is supported, so applications can find a meaningful name
   of the installed printers & other devices

4. ttf-gdos installs an FSMC cookie, so aware printer drivers can be
   configured for draft or final quality output

5. bezier curves are supported

New for Release 1.0

1. memory overhead needed to generate fonts is very much reduced, so
   now ttf-gdos can generate more fonts without running out of memory.
   (the fonts still need as much memory to be stored internally)

2. ttf-gdos is now more efficient, faster and more robust.
   Also it uses memory more efficiently.
   It is much, much faster than GDOS, and is more robust too.

3. the set of true type characters available extends beyond character
   128, so currency characters, legal characters, etc are now available.
   Compound characters (ie characters with umlauts, etc) are not yet
   generated.

4. ttf-gdos can now use screen drivers to scale true type characters
   correctly for the screen.

5. ttf-gdos now has a utility to extract fonts loaded by ttf-gdos and
   dump them as gem fonts. This can be used as a simple true type to
   gem font converter.

6. I've found and fixed a couple of bugs

Features of ttf-gdos

As well as being faster than GDOS, and being able to use True Type fonts,
ttf-gdos has a few extra features.

1. ttf-gdos can use Motorola Format Fonts !!! This can make font loading
   faster, since Intel Format fonts don't need to be internally converted.

2. ttf-gdos can load drivers from the current directory, as well as from the
   gemsys directory. This should benefit users with a ram disk because
   permanently resident drivers can be loaded from the boot disk, rather
   than being copied from the boot disk to ram disk, then to memory.
   This saves one copy operation, ramdisk storage, and avoids the need to
   make sure the ramdisk is enabled before ttf-gdos is initialised.

3. For Programmers: open virtual workstation with handle = 0, rather than
   use the handle found by calling graf_handle().

4. You can change printer drivers from within the same application (usually).
   See the description of the chpr accessory below. This can be useful when
   switching between draft and final quality printouts.

This is possible because ttf-gdos gives utilities a way to access and
change some of its internal configuration data. See below for more
details. This should make possible many useful tools in future releases
of ttf-gdos.

What is included in this release?

As well as ttf-gdos itself and this doc, ttf-gdos is released with these
utility programs:
- ttf2gem.prg (create hinted gem fonts from ttf files)
- chq.acc (switch printer between draft/final output)
- ifonts.ttp (list info on gem fonts in current folder)
- int2mot.ttp (convert intel gem font to motorola format)
- mot2int.ttp (convert motorola gem font to intel format)
- show-all.ttp (see all loaded fonts)
- drv_rpt.ttp (report lots of info about gdos drivers)
- ass-conv.ttp (this is used to set up ttf-gdos.inf files)
- chpr.acc (change default printer driver)
- ttf-dump.prg (dump loaded true type fonts in gem format)
- fix-fwid.prg (you might need this for timeworks)

Only the last 4 of these are specific to ttf-gdos, the others can be used
on other gdos programs.

Source code for all these utilities is included, and some other programming
information.

What is GDOS?

TLDR:
The part of the Atari operating system that draws shapes is called the VDI.
GDOS add fonts and printers to the VDI

GDOS means "Graphic Device Output System", and it is used by an application
to load fonts and print graphics. There are many GDOS programs available,
eg gdos, g+plus, fontgdos, speedo, amc gdos, nvdi, and of course ttf-gdos.

GDOS has these components:
- a configuration file (created by you)
- a printer driver (that you select to match your printer)
- fonts
- the GDOS program itself (or a replacement)

Your application doesn't know which fonts you have, or how to drive your
printer. Indeed, when the application was written, your fonts and type of
printer might not have existed. The configuration file, however, lists the
installed fonts and printer driver(s). This configuration file is read into
GDOS, so your application can use GDOS to load fonts and output graphics
to your printer.

In ttf-gdos, this configuration file is called ttf-gdos.inf and is created
with a setup utility. In (most?) other versions of GDOS this file is called
assign.sys, and is created with a text editor.

These references provide lots of very good information on GDOS:
* John Naylon About GDOS & the assign.sys file
* Douglas Wheeler Everything you ever wanted to know about GDOS
* Gerd Castan More Joy of GDOS

Google should find them for you.

Gem Fonts vs True Type Fonts

GEM fonts are bitmaps, ie they contain the dot pattern of each character in
a font. This makes them:
- very fast because almost no processing is needed to generate the
font, and
- high quality because each dot is correctly placed in the character
image.

The larger the point size of the character, and the smaller the dot size of
the output device, the more dots are required to define the font, and the
larger the file needed to store the font. A 10 point screen font is very
small - it takes only about 2 kBytes of disk space, but at 36 points for a
360 dpi ink jet printer, a font needs about 300 kBytes.
A separate file is needed for each point size for both the screen and
printer, so the disk space required to store a set of GEM fonts can be a
major drawback.
Gem fonts for printers are a bit thin on the ground, so the range of sizes
available for screen fonts might not match the available sizes of printer
fonts. The image displayed on the screen then might not accurately match
the final printed page.

True type fonts describe character outlines, so any size of font for any
device can be derived from a single font file by scaling the outline and then
generating the dot pattern.
This eliminates the drawbacks of bitmapped fonts, but these calculations are
very long, slow and computer intensive.
Also, at small point sizes and for low resolution devices (eg screens) the
generated fonts are likely to be low quality because the font outline is
unlikely to be aligned to the dot grid of the output device. Typically fonts
less than 25 or 30 pixels high should have gem font files.

The height of a font in pixels is given by this formula:

height in pixels = dpi * (point size) / 72

where dpi is the device resolution in dots per inch.

So for a screen at 90 dpi, a 20 point font is 25 pixels high, so fonts smaller
than this should be gem fonts.

True Type fonts have instructions (aka hinting) to fit the outline to the dot
grid and so generate high quality fonts at small point sizes. ttf-gdos does
not process these instructions - this helps keep ttf-gdos small and fast.
The ttf2gem utility program included in this release uses the freetype
hinting engine to generate high quality gem fonts from true type fonts.

Originally, when most Atari users had dot matrix printers, gem fonts were ideal
because they were fast, high quality and support tools were easy to develop.
With the advent of inkjet printers, the drawbacks of gem fonts became
apparent, and outline fonts became neccessary.

So there you have it - gem fonts are fast, hi quality and for a screen,
consume only a small amount of disk space.
True type fonts are better suited for printers because they save disk
space, generate any font size, and their slowness is unimportant.

Using TTF-GDOS

Using ttf-gdos is very similar to using GDOS, ie

1. put ttf-gdos.prg in the auto folder

2. create a folder for your fonts & driver(s). This folder is normally
   called gemsys, but can be given any name. A ramdisk is a good place to
   put this folder. In fact since release 2.0 of ttf-gdos, the font files
   are accessed so often that you are strongly advised to use a ram disk!

3. put gem fonts, true type fonts and drivers in the gemsys folder

4. put your ttf-gdos.inf file in root directory of boot disk. The
   ttf-gdos.inf file is created from an assign.sys file with the ass-conv
   setup utility. See below for details.

5. ttf-gdos should load every time your machine boots.

Creating a ttf-gdos.inf file

The ass-conv utility creates a ttf-gdos.inf from an assign.sys file (but it can be
given any name for ttf-gdos).

** You need to regenerate your ttf-gdos.inf file if you are upgrading from
** release 2.0 or earlier

Use an existing assign.sys or create a new one if you want to include
true type fonts. See below for info.

Now run ass-conv.ttp, giving it 2 parameters:
- the input filename, eg assign.sys
- the output filename, eg ttf-gdos.inf

If one or both parameters are missing, defaults of assign.sys and
ttf-gdos.inf are used.

Your ttf-gdos.inf file should now be created in the current directory. Copy
it to the root (ie top) directory of your boot disk if it isn't already there.

The assign.sys can be as normal, (say when inherited from an old GDOS setup),
optionally with true type fonts added with lines in this format:

;& ttfname (id), size1, size2, etc

    - ttfname is the name of the true type font file
    - id is the gem id for the true type font to adopt
    - size1, size2, etc is a comma separated list of required font 
      file sizes

For example, this line added to your assign.sys file will generate times
fonts with an id of 14 in sizes of 8, 10, 15 & 24 points:

;& times.ttf (14), 8,10,15,24

Note the id of the ttf should match the id of any corresponding GEM fonts.
This release of ttf-gdos includes a program called ifont that lists all
gemfonts in the current directory and their id numbers.

If you use true type fonts, you should also specify a cache size.
To specify a cache of, say, 150 kBytes, just add the following line to
your assign.sys:

; cache = 150

ass-conv makes the first comment line it finds into a title line.

See the example assign.sys included with ttf-gdos.

Important Upgrade Notes

Release 2.1 of ttf-gdos uses a new format for the ttf-gdos.inf file

You must use the latest ass-conv utility to recreate ttf-gdos.inf whenever
you upgrade from release 2.0 or earlier. If ttf-gdos finds an old format
ttf-gdos.inf file, it will report "ttf-gdos.inf has old format".

This also affects the accessory chpr. The latest version will advise you to
upgrade if it finds an old version of ttf-gdos.

Old versions of chpr will not find the printer drivers if used with the
new ttf-gdos.

If an old ttf-gdos is used with a new format ttf-gdos.inf, it will report
that the ttf-gdos.inf has incorrect format.

The Font Cache

The font cache enables all fonts to share memory, so the number of fonts
available to an application is not bound by the available system memory.
Only font data that is used needs to be held in memory, so the cache
can be smaller than would be required if all available fonts were held in
memory.
New fonts are added as they are used, and older fonts can be discarded to
make room for them.

The ideal size of the font cache depends on
- the size of largest font. The bigger the font size, the bigger the
cache must be to hold it. A 36 point font, for example, uses about
4 times as much cache memory as an 18 point font.
- the pattern of font usage. If you frequently switch between
several different fonts, you will want to hold them all in the
cache at once to avoid them being spilled, so the cache will need
to be larger than if you use only one or two fonts for long periods
of time.
- the amount of available memory. You need to keep as much memory
free as possible.

The font cache should hold at least the largest font and an overhead of
10kBytes needed for true type table data. If the cache is this size,
however, every time the largest font is used all other fonts are discarded
to make room for it. They may need to be regenerated soon after, slowing
down the system. To avoid this the cache can be made large enough to hold
the largest font and one or two regularly used fonts. If it is made too
large it may never be filled, or it may not improve system performance enough
to justify its memory use.

Assuming the largest font is 36 points, and sufficient memory is available,
a good setting for the cache size is:

    360 dpi printer         500kBytes       (Stylus, BubbleJet)
    300 dpi printer         350kBytes   (HP DeskJet)
    180 dpi printer         150kBytes   (Epson 24 Pin)

Timeworks users may need to make the cahe size much larger (about 3 or 4
times larger!) if memory permits.

To balance your memory budget, consider that a fontgdos printer driver normally needs
the following to hold a page image:
180 dpi 0.5 MB
300 dpi (deskjet) 1MB
360 dpi 1.5 MB

Timeworks users may need to make the cache size much larger (enough to hold all
fonts used on a single page) if memory permits. Timeworks drivers need don't as much
internal memory as fontgdos drivers, so this should not be a problem.

If there isn't enough memory, print at a lower resolution or have smaller
point sizes.

ttf2gem

ttf2gem does what it says - it creates gem fonts from true type fonts.
There's a very wide choice of true type fonts and with ttf2gem you can create
the corresponding gem fonts at any (reasonable) size you like.

It is based on freetype 1.2, which is a freely available true type library.

ttf2gem is also free, but is not guaranteed in any way at all.

TTF-GDOS recommends using gem fonts (i.e. bit maps) for small font sizes on
the screen.

True type fonts contain instructions for generating accurate fonts for small
font sizes (aka hinting) and ttf2gem uses the freetype font engine do do this.
You can use the fonts as generated, or polish them up with a font editor.

It should be easy to use. Just run it, choose your true type font and gem
font file name and point size.

There's just a few things to consider:

Any point size from 2 to 99 is valid.

Make up a gem font name that includes the point size.
If you put a double '??' in the gem file name, ttf2gem replaces the '??' pair
with the font point size when it writes the gem font file. This saves
entering the point size in the file name every time you create a new size
for your chosen true type font. It also avoids the possibility of
creating, say, a 10 point font with a 12 point name.

You also need to set the screen resolution of your output application.

For a hi rez screen this is usually 90 dpi, but can be 80 dpi
for timeworks, opus and possibly some other programs.
Choose 90 dpi if you are unsure, and check that the font sizes on the screen
match the font sizes on the printed paper. Alternatively (or additionally),
compare the font size of your generated fonts with the fonts shipped by your
application.

Most GDOS variants need Intel format fonts.

TTF-GDOS can use either, but Motorola format fonts are slightly more efficient.
This is because Motorola format fonts are already in the correct format for
the GDOS drivers.

The characters in the font are normally rearranged so they appear as
expected in the Atari character set, but those fonts with an id in the range
128-130 are assumed to be symbolic fonts and the characters are kept in
their original (non-alphabetic) order.

There is very little guidance on choosing a font id.

ttf2gem will try to suggest a font id derived from the font family, but
you can override this if you want.

All fonts are identified by their id, so different fonts need a different id.
If your work is moved to a new GDOS environment (say another computer), you
need the fonts there to have the same id, otherwise your document is spoiled.

Digital research specify that swiss (aka helvetica) font has an id = 2,
and times has an id = 14. The fonts distributed with GDOS by Atari are
consistent with this. Atari's typewriter font has an id = 15.

Apart from that, your options are:

• make up a font id, but take care not to give a font 2 different ids, or give
  2 fonts the same id.

• some applications can use only a font id <= 255

• the font id must be <= 4095. Larger numbers are reserved for italics, bolds,
  etc

• GST has compiled a list of font ids. It's in the timeworks publisher manual, and reproduced below.

• ttf2gem by default makes a font id from the IBM font class and family codes
  stored in the ttf file.
  This means that work using different fonts in different environments should
  look similar if the font ids are assigned in this way.

The assigned font id is 256 * (class id) + (subclass id). For example,
the font Century Schoolbook has a class id = 4 (Clarendon Serifs), and a
subclass id = 2 (Modern), so the assigned gem font id is 4*256 + 2 = 1026.
The references below have more information of these font id numbers.

Note that some ttf fonts don't contain this information.

Fonts with an ID less than 256 have class ID = 0 which is for IBM
unclassified fonts. So IBM and GST font IDs do not assign different
meanings to the same ID.

references:
https://www.afpconsortium.org/uploads/1/1/8/4/118458708/fgid-registry-afpc-font-typeface-registry.pdf
https://docs.microsoft.com/en-us/typography/opentype/spec/ibmfc
https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6OS2.html

GST font identification numbers

** ID Font**
2 Helvetica
3 Commercial Script
4 Old English
5 Raphael
6 Uncial
7 Stunt Roman
8 Cooper Black
9 Charter
10 Black Letter
14 Times
20 Century Schoolbook
21 Palatino
22 Garamond
23 Bookman
24 Lubalin Graph
25 Souvenir
26 Benguiat
27 Glypha
28 Friz Quadrata
29 Zapf Chancery
30 Trump
31 Melior
32 Galliard
33 Baskerville
34 Goudy
35 Park Avenue/ Coronet
36 Bodoni
37 Bodoni Poster
38 Century Old Style
39 Cheltenham
41 Brush
42 Lubalin Graph Extra Bold
43 Century II
45 Lucida Serif
47 American Classic
48 American Classic Extrabold
49 Century ll Light
50 Helvetica Narrow
51 Avant Garde (see 81)
52 Optima
53 Korinna
54 Helvetica Light
55 Helvetica Black
56 Franklin Gothic
57 Franklin Gothic Heavy
58 Helvetica Condensed Light
59 Helvetica Condensed
60 Helvetica Condensed Black
61 Antique Olive
62 Futura
63 Gill Sans
64 Gill Sans Extra Bold
65 Univers
66 Bauhaus
67 Triumvirate
69 Lucida Sans
70 Antique Olive Compact
71 Univers Extra Bold
72 Trade Condensed
73 Trade Extracondensed
74 Trade Extended
75 Dom Casual/Diagonal
76 Globe Gothic Outline
77 Manhattan
78 Optima Outline
79 Uncle Sam Open
80 Broadway
81 Avant Garde (see 51)
82 Futura Light
83 Futura Book
84 Futura Heavy
85 Futura Extra Black
86 Futura Medium Condensed
100 American Typewriter
101 Machine
102 Courier
103 Prestige Elite
104 Orator
105 Letter Gothic
106 Lucida Monospaced
128 Symbol
129 Zapf Dingbats
130 Sonata (Music)
131 IBM Keycap

If you have a font which does not appear in this list, select a font
identification value between 150 and 254, but make sure not to select
the same value twice for two different fonts.

Notes:
1. Avant Garde is duplicated with ID 51 & 81
2. Atari Typewriter font has ID 15 and is missing from this list. It is equivalent to Courier New or Nimbus monospace which has an ID of 102 in the GST list.
3. Many equivalent fonts have different names, eg Swiss 721 and Helvetica or Palatino and Book Antiqua. If you need to identify or compare fonts, try http://www.identifont.com
4. font ID == 1 is reserved for the system font.

The chpr accessory

This is a desk accessory that is typically used to switch your printer
between draft and final quality modes.

Select drivers that drive your printer in draft & letter quality and assign
device ids 21 & 22 to them. chpr then simply swaps the ids for devices 21
& 22.

Applications normally print to device 21 (without knowing what it is), so
swapping device ids can change the printer driver, and hence the output
resolution.
The handy feature here is that with true type fonts you already have the
fonts for both printer drivers.

eg My Epson stylus prints at 360 dpi with the sq.sys driver, and at 180 dpi
with the nb15.sys driver.

In my assign.sys file, I set driver nb15.sys to device number 21, and sq.sys
to device number 22, as in these 2 lines ...

21 nb15.sys ; 180 dpi, draft quality

22 sq.sys ; 360 dpi, final quality

I start with draft quality printouts. This is much faster (and saves ink).
When ready for a final quality printout, I can choose "select sq" from the
desk accs menu. chpr gives a single beep and the next printout is final
quality using the sq.sys driver.

chpr.acc will also look for subdirectories with the same name as the driver
just selected and copy all files in there up to its parent. This is useful
for applications that use width files. So, in the above example, I create
the width files for the nb15.sys driver, and copy them into a folder called
nb15.sys. Note that the sub folder is created below the folder where the
application and width file is, this is not necessarily the root. Then I
switch to the sq.sys driver, generate a new set of width files and copy them
into a folder called sq.sys.
Now switching between the drivers also copies the corresponding width file to
the application folder.

My timeworks directory setup, for example, looks something like this:
(top level)
gemsys\
epson360.b36 (360 dpi driver)
epsonlq.elq (180 dpi driver)
... font files, etc ...
epson360.b36\
screen.wid
printer.wid
epsonlq.elq\
screen.wid
printer.wid
fix-fwid.prg
fontwid.app
fontwid.rsc
timeworks.app
... other files ...

Notice that there are directories epsonlq.elq and epson360.b36 that have the
same names as the printer driver files in the gemsys directory.
Whenever chpr changes the default printer driver, it copies the correct
screen.wid and printer.wid files up to the timeworks directory.

Notes:

• 360 dpi drivers need about 4 times as much memory to print a page as
  180 dpi drivers, so be careful not to run out of memory.

• you must use the latest release of chpr with release 2.1 of ttf-gdos.inf.
  The older releases will not be able to find the printer info with the
  new ttf-gdos

The screen drivers

For hi rez users only:
A problem with true type fonts for the screen is that some applications scale
one inch on the screen at 90 dots, and others at 80 dots. ttf-gdos uses the
screen driver to find what scale the fonts should be, but the in-built driver
reports a completely different dot size (viz 69 dpi).
To scale fonts correctly for the application, use either screen90.sys or
screen80.sys. These are front end interfaces to the drivers built into
the TOS ROM, and they modify the reported screen dot sizes to 80 or 90 dpi.

They are used exactly as the drivers of any other device, but must be used
for screen device 4.

Technical note: the application opens a virtual workstation, specifing the
handle of the root device (screen 4 for hi rez). The screenXX.sys should be
attached to this root device (ie screen 4).

;example assign.sys file:
1p screen.sys
2p screen.sys
3p screen.sys
4r screen90.sys ; forces 90 dpi screen metrics
times09.fnt
swiss09.fnt
.... etc ...

Using ttf-gdos with Timeworks

From release 2.1, ttf-gdos works with timeworks, but read on ...

Some versions of fontwid work only with gem fonts. Fortunately ttf-gdos has
hooks which can be used to work around this problem. Put the fix-fwid
utility program in the same directory as fontwid, and instead of
running fontwid, run fix-fwid. fix-fwid sets up a gem font only
configuration then calls fontwid for you. See the fix-fwid.c file for
details.

The printer drivers supplied with timeworks use display lists rather than
page buffers to create an output. The timeworks drivers use much less memory
but are slower and the font data could be lost when they read it. If this
becomes a problem, you may need to use a larger font cache, or try other
drivers.

Example - TTF-GDOS on Timeworks

Let's hang all this together by setting up ttf-gdos with Timeworks, V1.
Let's assume timeworks is already installed in C:\publish, and we have a startup floppy disk. We have a standard hi res monitor.
We'll use arial, times and courier true type fonts. See note [1] below.

1. Timeworks keeps its fonts and printer driver in c:\publish\gemsys. See note [2].
   Most other apps share the same gemsys folder in c:\gemsys.
   We need to put our ttf fonts there, and it will be best if we put the
   ttf-gdos utlity programs ass-conv.ttp, ttf2gem.prg and drv_rpt.prg there
   too.

2 Now copy ttf-gdos' example assign.sys to the gemsys folder and for
convenience, rename it ttf.sys.

3 use your favourite text editor to edit ttf.sys.
The first comment line is the title displayed when ttf-gdos starts up.
Normally, it flashes past so quickly that you can't see it, but if there is
an error, ttf-gdos pauses.

4 Next, set the path, lower or upper case doesn't matter. This is for
timeworks:

~~~
path = c:\publish\gemsys

4 Now it's time to add the true type fonts.   A single true type font is for
  all devices and all sizes.  We need to specify the font, the gem font id and
  the required sizes.

 ~~~
 ;& arial.ttf (2) 10,12,18,24,36
  ;& times.ttf (14) 10,12,18,24,36
  ;& cour.ttf (15) 10,12,14

The ";&" says this is a true type font description. Then follows the font
file name, the gem font id in (parenthesis) and then a list of point sizes.

All gem apps expect your standard sans-serif (Arial here), serif (times) and
monospaced (courier) fonts to have these ids.
For more information on the font id, see the ttf2gem documentation.

5 A standard hi res screen is device 4 for atari GEM, In order to scale the
fonts correctly, ttf-gdos needs to know the screen resolution.
For timeworks (and opus spreadsheet), an inch on the paper is scaled to 80
dots on the screen. Most other GEM apps use 90 dots.

Edit the following line to set the screen resolution to 80 dpi:

04r screen80.sys

If your gdos setup is not for timeworks, leave this line as it is.

6 True type fonts smaller than about 20 points do not render well on the screen at hi
res, so we need to use ttf2gem to create gem fonts.
Start up ttf2gem - we put it in the gemsys folder earlier, and follow these steps:
* Choose Arial.ttf
* In the gem font file name field, put arial??.fnt, The double question mark will become the point size.
* Replace the number in the font id box with 2 (to match step 4 above)
* Set the horizontal and vertical screen resolutions to 80 dpi
* Set the point size to 10
* Click generate .... and wait several seconds
* That's the 10 point font done, now set the point size to 12, and click generate again.
* Same again for 14 points, and whatever else matches your true type spec from step 4 above.
* Now choose new ttf file, and choose times.ttf
* change the name to times??.fnt
* change the font id to 14
* change point size to 10
* click generate to create the 10 point times font.
* repeat for the other times point sizes
* and then the same again for courier, setting its font id to 15

Next list these and any other gem fonts you need under the hi res screen
driver section of the ttf.sys file. I've added timeworks bullet fonts. The
result should be something like this:

 04r screen80.sys ; HIGH RESOLUTION. 90 dpi
 ; fonts less than about 20 pts should be bitmapped
 arial10.fnt
 arial12.fnt
 arial18.fnt
 times10.fnt
 times12.fnt
 times18.fnt
 cour10.fnt
 cour12.fnt
 cour14.fnt

 shdb07.fnt  ; timeworks bullets
 shdb10.fnt
 shdb14.fnt
 shdb18.fnt
 shdb36.fnt

7 For GEM, the printer is device 21. Set it up as you would for standard
gdos. For timeworks, the printer line should look like this:

 21 printer.sys

For other apps, choose a suitable driver from, say, fontgdos.
Most printers have a good resolution so should not need a list of gem fonts,
but you can add some if it is necessary.

8 Setting the cache size might need some careful consideration. If this setup
is not for timeworks, and assuming enough memory, follow the guidance in the
comments there. For timeworks, make the cache size much bigger. (about three
times larger).

9 Nearly there! We need to put the ttf-gdos configuration file onto the boot
disk. Run ass-conv.ttp, We copied this to the gemsys folder earlier.
In the parameter dialog, enter these parameters:

ttf.sys  a:\ttf-gdos.inf

where ttf,sys is the name of the file we edited, and a: is the boot disk.

10 Now reboot and check
After rebooting, ttf-gdos should find its inf file and then start up.
run drv_rpt, save the report to disk, or show it on the screen.
Check that it reports that ttf-gdos is your gdos version, check the fonts for screen and printer are
present as expected for all sizes, and that their font ids are correct. If
there are duplicate fonts it probably means that the true type and gem font
ids do not match.
If you aren't using a standard hi res screen, and are unsure which screen
device to use, put a different gem font under each screen, run see what
font is available.

11 last step - run fontwid
Skip this step if you aren't setting up for timeworks.
for timeworks V1, every time you change a font or use a new printer
resolution you need to run fontwid.prg.

Timeworks2 looks for gem fonts in the gemsys folder, but only the gem fonts are
there. Run fix-fontwid instead. It creates temporary gem fonts
corresponding to the true type fonts, then runs the fontwid.app for you. It
cleans up afterwards.

12 run your app
You should have all fonts at all sizes, with screen and printer fonts matching.
each other.
If you find that timeworks has garbled fonts at the top of a page, try to increase cache size

Notes:
[1] This example uses Microsoft fonts because they're well known, hi quality and widely available.
There are licence conditions, basically
* don't hack them,
* don't make your own profit from them,
* treat them with respect.
The recent versions of the fonts are huge, so I prefer using the original
windows 3.1 versions. Google "windows 3.1 true type fonts".
If the fonts you want are compressed, 7zip will probably unpack them.

[2] this folder is normally called gemsys, but it can have any name, and be
anywhere

Some fonts are too big or are not recognised

When ttf-gdos was developed (at the time of windows 3.1) true type fonts were typically a few tens of kbytes in size.

This was acceptable for a normal Atari ST(E) with a single floppy drive and 1MB memory.

Also, the fonts of this era used an old apple character map (format 0) that was very efficient so that's what ttf-gdos used (and still does).

Now true type fonts are often much larger (several hunderd kbytes) and this makes them awkward to use for an Atari system.
Also, current fonts may not include the apple format 0 character map, so ttf-gdos cannot use them.

How to fix these font files

You need the fontforge font editor.
This is an excellent free open source font editor available for windows, mac & linux. See https://fontforge.org/en-US/

Read the licence for the font to see if you have permission to modify the file.
If you make changes, you might need to change the font name.
Then do this:

• load the font into fontforge
• To change the name:
  In the menus, go to Element -> Font Info -> PS Names
• Now go to Encoding -> Reencode -> Macintosh Latin
• now find char 255,
  it should be a 'caron', which looks like an upside down 'circumflex'
  (so an upside down one of these -> '^', often called 'caret' or 'hat')
  if you highlight this (or any) character it's number and name are shown
  on the menu bar
• highlight all characters beyond this
• all the highlighted characters are unusable for ttf-gdos, so delete them:
  from the menu, choose Edit -> Clear (or right click -> Clear)
• Now save the file:
  File -> Generate Fonts
  enter the file name
  tick append fontlog entry
  enter date, your name, and description, eg "changes for ttf-gdos"
  click Generate

You should now have a usable font file, typically about 60kB size, and it should have the format 0 character map.

The ttf-dump utility

(Since release 2.3, you might prefer to use the ttf2gem utility program.)

Want to create some gem fonts that match your true type fonts?
You may want a gem font because it loads faster, or because you can tidy it
up with a font editor.
Use this utility to dump any font loaded into ttf-gdos for the screen or
printer as a gem font file.

It loads all the device fonts and displays a select box with each font listed.
Choose any of these fonts, fill in the gem file name field and click on "dump"
to create a corresponding GEM font file. You can use a font editor to tidy
up the saved gem font if you need to.
You can choose Motorola or Intel format by clicking the radio button.
Motorola fonts load faster, but most GDOS's can load only Intel fonts.
ttf-gdos can load either.

Bezier Curves - Programming Info

TTF-GDOS implements these bezier functions:
v_bez_qual()
v_bez_control()
v_bez()
v_bez_fill()

Details of the arguments & return values for these calls can be found in the
documentation of your compiler bindings.

v_bez_qual() sets the quality of a bezier curve. A bezier curve is generated
as a series of short straight line segments. A high quality bezier curve is
made from many short straight lines, whereas a lower quality bezier curve has
fewer longer straight line segments. Higher quality bezier curves thus appear
smoother, but are slower.

v_bez_control() simply returns the bezier quality set for the current
workstation. It can be used by your application to test if the GDOS supports
bezier functions. TTF-GDOS does not support the use of this function to
enable or disable bezier curves.

v_bez() outputs a (possibly disjoint) series of bezier curves & poly lines.

Each element in bezarr[] is a flag that controls the behaviour of the
corresponding input point.

If bit 0 (ie ls bit) of the flag is set to one, the corresponding point and
the next three points define a bezier curve:
1. start point
2. 1st control point
3. 2nd control point
4. end point

If bit 0 is zero, the corresponding point is part of a polyline.

If bit 1 is set, the corresponding point starts a new disconnected bezier
curve.

Note: The C function calls are as described here, but internally the C
libraries byte swap bezarr[] for intel compatible format.
If you are not using the C library, but directly programming the VDI
interface, you need to do the byte swapping yourself.

See the example bezier test program.

v_bez_fill() is similar to v_bez(), but it forms a closed contour and fills
it with the current fill pattern.

The FSMC Cookie

The value field of the 'FSMC' cookie contains a pointer to a structure with
information about the current version of GDOS as follows:

typedef struct {
char[4] gdos_id;
int16 gdos_version;
int16 gdos_quality;
} gdos_info;

For ttf-gdos, gdos_id will be 'TTFG'. It is '_FSM' for FSMGDOS, '_FNT' for
FONTGDOS, or '_SPD' for SpeedoGDOS.

The structure member gdos_version contains the currently installed version of
GDOS with the major version number being in the high byte and the minor
version being in the low byte.

The structure member gdos_quality is initialised to -1 to indicate that
printouts will be processed at the 'default' quality setting. Applications
may change this value to 0 to force GDOS drivers to output in DRAFT mode
or 1 to force GDOS drivers to output in FINAL mode. The variable should
be restored to -1 after each print.

The chq.acc accessory modifies the gdos_quality flag to control the printer
driver's output quality. Note that some drivers may ignore this flag.

Programmer's info

1. You can call v_opnvwk() with handle = 0, rather than finding an
   initial value from the AES with graf_handle(...). See ttf-dump.c for
   an example.

2. The ttf-gdos.inf format is defined in ttf-gdos.h
   see also ass-conv.c

3. On return from vst_load_fonts(): contrl[10] & contrl[11] contain
   a pointer to the font chain. See linea/vdi documentation for info
   on the font structure. This is read-only info, don't try to modify
   it. See also the ttf-dump utility. Note that future versions of
   ttf-gdos may not maintain all the expected data in the font chain, so
   be warned.

4. vq_vgdos() returns a pointer to MAGIC_NR in the following structure:
   

pointer to tt fonts ( FONT_RECORD struct )

                 pointer to gem fonts ( FILENAME )
                 pointer to gem path string
                 MAGIC_NR      (int32)          <--- vq_vgdos()
                 version       (uint8)
                 len gempath   (uint8)
                 file length   (uint16) 
                 cache size    (uint16) 
                 reserved      (uint16)
                 nr gem fonts  (uint16)
                 nr tt fonts   (uint8)
                 nr workstns   (uint8)
                 workstations  (struct)

The structures are as defined for ttf-gdos.inf, see ttf-gdos.h
Note that this differs from release 2.0 and earlier.


The version field is the version of this structure definition.
Check that it equals MY_VERSION (also defined in ttf-gdos.h) before accessing this structure.


The cache size is in kBytes.


You can change the ttf-gdos configuration by changing the contents of this structure. See chpr.c and ass-conv.c source for examples.
Changing the true type fonts will probably be catastrophic, but their point sizes can be altered.


The gempath is a string, with a trailing '\'. Its length is defined by the 'len gempath' field, and it must immediately be followed by at
least 14 free bytes so any valid file name can be appended to it.


The psize_mask in the FONT_RECORD struct is defined so each bit set causes a different point size to be created, so

        msbit = 7 points
        .... 
        lsbit 38 points

A tool can set up its own values for the workstations, gemfonts struct & gempath and modify the pointers to make ttf-gdos use these (ie the tool's) values. Be careful though, like most features that provide lots of flexibility, you can easily do things that are
invalid (like make a driver resident when it isn't loaded, etc).

Problems?

If you're not sure if the problem is with your application or your setup, try
EasyDraw or Kandinsky - they both work well with ttf-gdos.

EasyText DTP works fine too, but but uses width files that depend on printer
resolution, so you need to re-run the font widths program if you use new fonts
or change the printer resolution.

OPUS spreadsheet appears to use width files in a similar way to EasyText.

Printer drivers use an enormous amount of memory, especially at 360 dpi.
If you don't get the results you expected for your printer, try these
- make more memory available if you can (eg smaller ramdisk, don't
load accessories, etc..).
- Try using a driver that prints at a lower resolution - the fonts
and page image will need much less memory (about 25% as much).
- Get more memory for your system!!

It is worth noting that you need 4MB to attempt printing at 360 dpi. To
build an image of the page, the printer driver takes 1.4 MB of memory (this
is unavoidable). At 360 dpi, a font cache should be about 500kB and a
typical application needs about 1 MB, so this leaves just enough for a RAM
disk, printer spooler, desk accessories, or whatever (if you are careful).

Carefully check your assign.sys file. If your application loads true type
fonts when you expected gem fonts to appear, look for defined screen drivers
without gem fonts listed. A particularly tricky scenario is when screen 4 is
defined without gem fonts and screen 3 is defined with fonts. With GDOS, the
application tries to load fonts for screen 4 and fails, so loads them for
screen 3 instead. Under ttf-gdos, however, it does find fonts for screen 4,
so uses them. The solution is to remove screen 4 from assign.sys, or define
the fonts for screen 4 intead of, or as well as screen 3.

Timeworks drivers (any others?) use a different method to create a printout.
If the fonts at the end of the page are ok, but the fonts at the top are not,
increase the size of the cache.

Limitations

ttf-gdos handles gem fonts with no known problems, but generating true type
fonts does incur a performance penalty. It has no known bugs (at least not
by me), and only a few limitations.

Most of these issues should be addressed over the next and subsequent
releases.

• True type fonts take ages to generate. This can't be improved much, but
  ttf-gdos has a font management system that generates fonts only as they are
  needed, and caches them to use both time and memory as efficiently as
  possible.

• Only the outline part of the true type fonts are used, the hinting
  instructions are ignored, so the fonts are well formed only at large point
  sizes/resolutions. Use gem fonts at point sizes where the true type fonts
  are not cleanly generated.

• there are apparently some (rogue) applications that don't allow enough
  space in the cntrl[] array when loading fonts. These applications are
  unlikely to work correctly. (If you're a programmer, make sure you allow
  at least 12 ints (ie 16 bits) in this array).

• applications that scan the assign.sys file won't necessarily work because
  ttf-gdos uses a configuration file with a different name and format. There
  may be some scope for fudging by using an equivalent assign.sys.

• programs that use font hiding and other techniques that rely on internal
  knowledge of GDOS are unlikely to work with ttf-gdos.
  Some applications can have their font hiding turned off.

• ttf-gdos uses lots of Malloc()s, so TOS versions older than 1.4 may be
  able to handle only a few fonts. The solution here is to upgrade to a new
  version of TOS.

• compound characters (characters with umlauts, accents, etc) are not
  currently generated.

• Initially tested at hi rez only, on an STE with 4 MBytes, and an Epson Stylus
  printer at 120, 180 & 360 dpi. For version 2.3 tested on the hatari
  emulator, no printer supported.

And Finally ...

Since version 2.2, ttf-gdos is GPL'd, so may be freely used and distributed,
including with source code.

ttf2gem uses the freetype library. and has a BSD licence.

The licence text should be included with this release.

Trevor Blight

Project Members:

• Trevor Blight (admin)