Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                               SpeedoGDOS


SpeedoGDOS is a new variety of FSM which employs outline font technology
from Bitstream using Speedo-format outline fonts. In addition, several new
calls were added to gain access to internal font information and provide
true WYSIWYG (What-You-See-Is-What-You-Get) output.

The fix31 Data Type

SpeedoGDOS optionally allows the use of the fix31 data type in some calls
for parameters and return values. Old bindings designed for the
Imagen-based FSM will still function properly. Newer bindings may be
written to take advantage of this data type.
The fix31 data type allows for the internal representation and
manipulation of floating-point values without the use of a floating-point
library. It is a 32-bit value with a 1-bit sign and a 31-bit magnitude.
Each value specifies a number in 1/65536 pixels. Examples of this data
type follow:

                   fix31        Floating Point

                 0x00010000          1.0

                 0xFFFF0000         -1.0

                 0x00018000          1.5

Character advances can be simply be added or subtracted to each other
using integer arithmetic. To convert a fix31 unit to an integer (rounding
to 0) use the following code:

        x_integer = (WORD)(x_fix31 >> 16);

To convert a fix31 to an integer and round it to the closest integer use
the following code:

        x_integer = (WORD)((x_fix31 + 32768) >> 16);

Use of fix31 values provides higher character placement accuracy and
access to non-integer point sizes. For specific implementation notes, see
the VDI Function Reference entries for vqt_advance32(),
v_getbitmap_info(), vst_arbpt32(), and vst_setsize32().

Kerning

SpeedoGDOS outline fonts have the ability to be kerned using two methods.
Track kerning is global for an entire font and has three settings, normal,
tight, and extra tight. Pair kerning works for individual pair groups of
characters. In addition, new pairs may be defined as necessary to produce
the desired output.

Kerning is taken into account with v_ftext() and vqt_advance() only when
enabled. Use the calls vst_kern(), vqt_pairkern(), and vqt_trackkern() to
access kerning features.

Caching

All SpeedoGDOS extent and outline rendering calls are cached for improved
performance. Cache files may be loaded or saved to disk as desired to
preserve the current state of the cache. In addition, an application might
want to flush the cache before doing an output job to a device such as
a printer to improve performance with new fonts.

The call vqt_cachesize() can be used to estimate the ability of the cache
to store data for an unusually large character and prevent memory overflow
errors.

Special Effects

The call vst_scratch() determines the method used when calculating the
size of the special effects buffer. In general an application should not
allow the user to use algorithmically generated effects on Speedo fonts.
In most cases, special effects are available by simply choosing another
font.

The problem is that Speedo fonts may be scaled to any size and SpeedoGDOS
has no way of predicting the upper-limit on the size of a character to
allocate special effects memory. Currently, SpeedoGDOS allocates a buffer
large enough to hold the largest character possible from the point sizes
in the 'ASSIGN.SYS' file and those listed in the 'EXTEND.SYS' file. If
your application limits special effects to these sizes then no problems
will occur.

If you intend to restrict users to using special effects only with bitmap
fonts you may call vst_scratch() with a mode parameter of 1, memory
allocation will be relaxed to only take bitmap fonts into account. You may
also specify a mode parameter of 2 if you plan to allow no special effects
at all. The vst_scratch() call must be made prior to calling
vst_load_fonts().

Speedo Character Indexes

Speedo fonts contain more characters than the Atari ASCII set can define.
Fonts may be remapped with a CPX using the vqt_get_table() call (this
method is not recommended on an application basis as this call affects all
applications in the system).

Another method involves the use of a new call, vst_charmap(). Calling
this function with a mode parameter of 0 causes all functions which take
character indexes (like v_ftext(), vqt_width(), etc.) to interpret
characters as WORDs rather than BYTEs and utilize Speedo International
Character Encoding rather than ASCII.

The Function Reference provides two alternate bindings for v_ftext() and
v_ftext_offset() called v_ftext16() and v_ftext_offset16() which correctly
output 16-bit Speedo character text rather than 8-bit ASCII text.
A complete listing of the Bitstream International Character Set is listed
in Appendix G: Speedo Fonts.

Speedo Font IDs

The function vqt_name() is used with all versions of GDOS to return
a unique integer identifier for each font. Because some bitmap font ID's
conflicted with Bitstream outline font ID's, SpeedoGDOS versions 4.20 and
higher add 5000 to each of the outline font ID's to differentiate them
from bitmap fonts.


See also    GDOS 1.x, FONTGDOS, FSM-GDOS