diskfont.library Reference

Comprehensive function reference for diskfont.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/diskfont).

This page documents 14 functions of diskfont.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

AvailFonts()

AvailFonts -- Inquire available memory & disk fonts.

Synopsis

error = AvailFonts(buffer, bufBytes, flags); A0 D0 D1

LONG AvailFonts(struct AvailFontsHeader*buffer, LONG bufBytes ULONG flags );

Function

AvailFonts fills a user supplied buffer with the structure, described below, that contains information about all the fonts available in memory and/or on disk. Those fonts available on disk need to be loaded into memory and opened via OpenDiskFont, those already in memory are accessed via OpenFont. The TextAttr structure required by the open calls is part of the information AvailFonts supplies.

When AvailFonts fails, it returns the number of extra bytes
it needed to complete the command.  Add this number to your
current buffer size, allocate a new buffer, and try again.

Inputs

buffer - memory to be filled with struct AvailFontsHeader followed by an array of AvailFonts elements, which contains entries for the available fonts and their names.

bufBytes - the number of bytes in the buffer
flags - AFF_MEMORY is set to search memory for fonts to fill
    the structure, AFF_DISK is set to search the disk for
    fonts to fill the structure.  AFF_SCALED is set to
    not filter out memory fonts that are not designed.
    AFF_BITMAP is set to filter out fonts that are not
    stored in Amiga font format, i.e. to filter out
    outline fonts.  Any combination may be specified.
    AFF_TAGGED is set to fill the buffer with TAvailFonts
    elements instead of AvailFonts elements.

    In V46 AFF_OTAG was introduced, it has the reverse
    effect of AFF_BITMAP and filters out all fonts that
    do not have an .otag file, i.e. that are not accesible
    via the bullet API.  When AFF_OTAG and AFF_SCALED are
    both set, or AFF_TYPE is set, each font that is accesible
    via the bullet API and that is freely scalable will be
    shown with an additional entry with a (t)ta_YSize of 0,
    if this entry is absent, the font is not scalable (i.e.
    a non-Amiga bitmap font format that can be converted
    but not scaled by the font engine).

    In V46 AFF_TYPE was introduced, if set, the [t]af_Type
    of disk fonts is not always AFF_DISK, but instead
    AFF_DISK|AFF_BITMAP for bitmap fonts,
    AFF_DISK|AFF_OTAG for .otag fonts,
    AFF_DISK|AFF_OTAG|AFF_SCALED for scalable .otag fonts
    (with a (t)ta_YSize of 0).

Results

buffer - filled with struct AvailFontsHeader followed by the [T]AvailFonts elements, There will be duplicate entries for fonts found both in memory and on disk, differing only by type. The existance of a disk font in the buffer indicates that it exists as an entry in a font contents file -- the underlying font file has not been checked for validity, thus an OpenDiskFont of it may fail. error - if non-zero, this indicates the number of bytes needed for AvailFonts in addition to those supplied. Thus structure elements were not returned because of insufficient bufBytes.

Example

int afShortage, afSize; struct AvailFontsHeader *afh;

...

afSize = 400;
do {
    afh = (struct AvailFontsHeader *) AllocMem(afSize, MEMF_ANY);
    if (afh) {
        afShortage = AvailFonts(afh, afSize, AFF_MEMORY|AFF_DISK);
        if (afShortage) {
            FreeMem(afh, afSize);
            afSize += afShortage;
        }
    }
    else {
        fail("AllocMem of AvailFonts buffer afh failed\n");
        break;
    }
}
    while (afShortage);

\*
 * if (afh) non-zero here, then:
 * 1. it points to a valid AvailFontsHeader
 * 2. it must have FreeMem(afh, afSize) called for it after use
 *\

Bugs

Prior to V46, this routine did not find the taglist stored in tagged disk fonts when the AFF_TAGGED flag was specified, except the font was already loaded to memory. Fixed in V46. Some V45 versions of this routine returned an invalid taglist pointer for the Topaz/9 ROM font when AFF_TAGGED was specified. Fixed in V45.7. Prior to V46, versions with fontcache enabled returned wrong results if AFF_BITMAP was set different at cache creation and cache lookup.

CloseOutlineFont()

CloseOutlineFont -- Release a pointer to an outline font. (V47)

Synopsis

CloseOutlineFont(outlineFont, list) A0 A1

VOID CloseOutlineFont(struct OutlineFont*,List*);

Function

This function indicates that the font specified is no longer in use. It is used to close a font opened by OpenOutlineFont(), so that fonts that are no longer in use do not consume system resources.

Inputs

font - a font pointer as returned by OpenOutlineFont().

list - the same pointer to a struct List (or NULL pointer) that
       was used for the matching OpenOutlineFont() call.
       If you want to share the list between tasks, you are
       responsible for using an appropriate locking mechanism,
       e.g. a Semaphore.

See also

OpenOutlineFont()

DisposeFontContents()

DisposeFontContents -- Free the result from NewFontContents. (V34)

Synopsis

DisposeFontContents(fontContentsHeader) A1

VOID DisposeFontContents(struct FontContentsHeader* );

Function

This function frees the array of FontContents entries returned by NewFontContents.

Inputs

fontContentsHeader - a struct FontContentsHeader pointer returned by NewFontContents.

EXCEPTIONS This command was first made available as of version 34.

A fontContentsHeader other than one acquired by a call
NewFontContents will crash.

See also

NewFontContents()

ECloseEngine()

ECloseEngine -- Release an engine handle. (V47)

Synopsis

ECloseEngine(EEngine) A0

VOID ECloseEngine(struct EGlyphEngine*);

Function

This function is similar to bullet.library/CloseEngine() but does not use a (hidden) "BulletBase" variable that may hold the library base of the wrong font engine if not set properly. It uses EEngine->ege_BulletBase as base of the font engine library to be called.

This function releases the engine handle acquired with EOpenEngine().
It first releases any data acquired with EObtainInfoA() associated
with the engine handle that has not yet been released.

Inputs

EEngine - the handle acquired via EOpenEngine(). If NULL or EEngine->ege_GlyphEngine is NULL, no operation is performed.

Results

EEngine->ege_GlyphEngine is set to NULL. The only error that can occur is when an invalid engine handle is supplied: the application is assumed not to do that.

Example

EndGame(code, arg1, arg2, arg3, arg3) { ... if (EEngine->ege_GlyphEngine != NULL) ECloseEngine(EEngine); if (EEngine->ege_BulletBase != NULL) CloseLibrary(EEngine->ege_BulletBase); ... }

See also

CloseEngine(), EOpenEngine(), CloseOutlineFont()

EObtainInfoA()

EObtainInfoA -- Inquire tagged font and/or glyph metrics. (V47) EObtainInfo -- varargs form of EObtainInfoA.

Synopsis

error = EObtainInfoA(EEngine, tagList) D0 A0 A1

ULONG EObtainInfoA(struct EGlyphEngine*,TagItem*);

error = EObtainInfo(EEngine, firstTag, ...)

ULONG EObtainInfo(struct EGlyphEngine*, Tag, ...);

Function

This function is similar to bullet.library/ObtainInfoA() but does not use a (hidden) "BulletBase" variable that may hold the library base of the wrong font engine if not set properly. It uses EEngine->ege_BulletBase as base of the font engine library to be called.

This function accepts a tag list whose tag field elements are
valid for inquiry, and whose associated data fields are
pointers to the destination in which to place the requested
data.

Tag items that refer to data indirectly (OT_Indirect is set)
return pointers that may be allocated or cached by the
library. This data must be treated as read-only data. When
the application is done with the data acquired via EObtainInfoA(),
it must perform a EReleaseInfoA() to allow the library to release
the data.

Inputs

EEngine - the glyph engine acquired via EOpenEngine() or OpenOutlineFont(). tagList - a tag list containing OT_ tags valid for inquiry paired with the destination pointers for the inquiry results. All destinations are longwords, whether they are pointers or values, and regardless of whether the value could fit in a smaller variable.

Results

This function returns a zero success indication, or a non-zero error code.

Example

struct GlyphMap *glyph; ... if (!(error = EObtainInfo(EEngine, OT_GlyphMap, &glyph, TAG_END))) { ... EReleaseInfo(EEngine, OT_GlyphMap, glyph, TAG_END); }

See also

ObtainInfoA(), EReleaseInfoA()

EOpenEngine()

EOpenEngine -- Acquire engine handle. (V47)

Synopsis

success = EOpenEngine(EEngine) D0 A0

LONG EOpenEngine(struct EGlyphEngine*)

Function

This function is similar to bullet.library/OpenEngine() but does not use a (hidden) "BulletBase" variable that may hold the library base of the wrong font engine if not set properly. It uses EEngine->ege_BulletBase as base of the font engine library to be called.

This function establishes a context for access to the bullet
library or another font engine. This context remains valid until
it is closed via ECloseEngine(). Each specific context isolates the
specification of the various font attributes from other contexts
concurrently accessing the same library. A context can be shared
among different tasks if the caller uses a locking mechanism (e.g.
Semaphores) that ensures that the context is not accessed
concurrently and that e.g. a ESetInfo(), EObtainInfo() sequence
cannot be interrupted by another task using the same context.

Inputs

EEngine - pointer to a struct EGlyphEngine that does contain a pointer to the library base of the font engine acquired via OpenLibrary() in EEngine->ege_BulletBase.

Results

If TRUE, EEngine->ege_GlyphEngine contains a pointer to a struct GlyphEngine, if FALSE, EEngine->ege_GlyphEngine is NULL.

Example

struct EGlyphEngine EEngine;

EEngine.ege_BulletBase = OpenLibrary(EngineName, 0);
if (!EEngine.ege_BulletBase)
    EndGame(ERROR_LibOpen, EngineName, 0);
if (!EOpenEngine(&EEngine))
    EndGame(ERROR_InternalCall, "EOpenEngine");

ESetInfo(&EEngine, OT_OTagPath, ...)
...

ECloseEngine(&EEngine);
CloseLibrary(EEngine->ege_BulletBase);

See also

OpenEngine(), ECloseEngine(), OpenOutlineFont()

EReleaseInfoA()

EReleaseInfoA -- Release data obtained with EObtainInfoA. (V47) EReleaseInfo -- varargs form of EReleaseInfoA.

Synopsis

error = EReleaseInfoA(EEngine, tagList) D0 A0 A1

ULONG EReleaseInfoA(struct EGlyphEngine*,TagItem*);

error = EReleaseInfo(EEngine, firstTag, ...)

ULONG EReleaseInfo(struct EGlyphEngine*, Tag, ...);

Function

This function is similar to bullet.library/ReleaseInfoA() but does not use a (hidden) "BulletBase" variable that may hold the library base of the wrong font engine if not set properly. It uses EEngine->ege_BulletBase as base of the font engine library to be called.

This function releases the data obtained with EObtainInfoA().
Data associated with tags that are not indirect, i.e. for which
OT_Indirect is not set, need not be released, but it is not an
error to do so. Released data may be immediately freed or may
become a candidate to be expunged from memory when the system
reaches a low memory condition, depending on the library's
internal implementation.

Each EReleaseInfoA() tag item must be associated with a prior
successfull EObtainInfoA() call.

Inputs

EEngine - the glyph engine acquired via EOpenEngine() or OpenOutlineFont(). tagList - a tag list containing OT_ tags valid for inquiry paired with the data previously acquired for them with EObtainInfoA. NULL pointers are quietly accepted and ignored for indirect data.

Results

This function has no result. The only error that can occur is when the EObtainInfo() and EReleaseInfo() pairs are mismatched: the application is assumed not to do that.

Example

struct GlyphMap *glyph; ... if (!(error = EObtainInfo(EEngine, OT_GlyphMap, &glyph, TAG_END))) { ... EReleaseInfo(EEngine, OT_GlyphMap, glyph, TAG_END); }

See also

ReleaseInfoA(), EObtainInfoA()

ESetInfoA()

ESetInfoA -- Set font and/or glyph metrics. (V47) ESetInfo -- varargs form of ESetInfoA.

Synopsis

error = ESetInfoA(EEngine, tagList) D0 A0 A1

ULONG ESetInfoA(struct EGlyphEngine*,TagItem*);

error = ESetInfo(EEngine, firstTag, ...)

ULONG ESetInfo(struct EGlyphEngine*, Tag, ...);

Function

This function is similar to bullet.library/SetInfoA() but does not use a (hidden) "BulletBase" variable that may hold the library base of the wrong font engine if not set properly. It uses EEngine->ege_BulletBase as base of the font engine library to be called.

This function accepts a tag list whose tag field elements are
valid for specification, and whose associated data fields are
used to supply the specified data.

Data that is supplied via an indirect pointer (OT_Indirect is set)
to an array or structure is copied from that array or structure
into the internal memory of the library. Changes to the data
after this call do not affect the engine.

Inputs

EEngine - the glyph engine acquired via EOpenEngine() or OpenOutlineFont(). tagList - a tag list containing OT_ tags valid for specification paired with the specification data.

Results

This function returns a zero success indication, or a non-zero error code.

Notes

The function may return with a non-zero error code before it has parsed the whole tag list.

Example

// Get Euro glyph with 16 points height if (!(error = ESetInfo(EEngine, OT_PointHeight, 0x00100000, OT_GlyphCode, 0x20AC, TAG_END))) { if (!(error = EObtainInfo(EEngine, OT_GlyphMap, &glyph, TAG_END))) { ... EReleaseInfo(EEngine, OT_GlyphMap, glyph, TAG_END); } }

See also

SetInfoA()

GetDiskFontCtrl()

GetDiskFontCtrl -- Inquire diskfont global settings. (V45)

Synopsis

value = GetDiskFontCtrl( tagid ); D0

LONG GetDiskFontCtrl( LONG tagitem );

Function

GetDiskFontCtrl reads global settings of the diskfont library, as the setting of the base DPI X and Y values, the cache enable flag and the AvailFonts sorting values. The TagItem passed in identifies the type of data item to read.

Inputs

tagid - a tag ID as documented in diskfont/diskfonttag.h that identifies the kind of data item to inquiry.

           The following tag values are currently supported:
           (see diskfont/diskfonttag.h)

           Font generator DPI settings:

           DFCTRL_XDPI
           DFCTRL_YDPI     X and Y dpi device resolution

           DFCTRL_XDOTP
           DFCTRL_YDOTP    X and Y dpi dot sizes.

           DFCTRL_CACHE    AvailFonts cache enable (BOOL)

           DFCTRL_SORTMODE AvailFonts font sorting (LONG)

           currently defined sort orders are:

                   DFCTRL_SORT_OFF don't sort
                   DFCTRL_SORT_ASC localized ascending
                   DFCTRL_SORT_DES localized descending

Results

value - The current diskfont default setting for the selected tag item. The result code is undocumented if an unknown tag value is passed in.

Notes

This call is not semaphore protected. This means that several calls to this function and SetDiskFontCtrl() might cause inconsistent results. The function will not fail or crash, but the result might be near to useless in a multitasking system. This function should never be called by the average user. Its sole purpose is to provide the font preferences editor with data about the current diskfont settings. It should not be called for other purposes.

Example

BOOL cache;

   cache = GetDiskFontCtrl(DFCTRL_CACHE);

   \* read the current cache enable flag. *\

NewFontContents()

NewFontContents -- Create a FontContents image for a font. (V34)

Synopsis

fontContentsHeader = NewFontContents(fontsLock,fontName) D0 A0 A1

struct FontContentsHeader*NewFontContents( BPTR, char * );

Function

This function creates a new array of FontContents entries that describe all the fonts associated with the fontName, specifically, all those in the font directory whose name is that of the font sans the ".font" suffix.

Inputs

fontsLock - a DOS lock on the FONTS: directory (or other directory where the font contents file and associated font directory resides). fontName - the font name, with the ".font" suffix, which is also the name of the font contents file.

Results

fontContentsHeader - a struct FontContentsHeader pointer.

EXCEPTIONS This command was first made available as of version 34.

D0 is zero if the fontName is does not have a ".font" suffix,
if the fontName is too long, if a DOS error occurred, or if
memory could not be allocated for the fontContentsHeader.

See also

DisposeFontContents()

NewScaledDiskFont()

NewScaledDiskFont -- Create a DiskFont scaled from another. (V36)

Synopsis

header = NewScaledDiskFont(srcFont, destTextAttr) D0 A0 A1

struct DiskFontHeader*NewScaledDiskFont(TextFont*, TTextAttr* );

Inputs

srcFont - the font from which the scaled font is to be constructed. destTextAttr - the desired attributes for the new scaled font. This may be a structure of type TextAttr or TTextAttr.

Results

header - a pointer to a DiskFontHeader structure. This is not being managed by the diskfont.library, however.

Notes

o This function may use the blitter. o Fonts containing characters that render wholly outside the character advance cell are currently not scalable. o The font, and memory allocated for the scaled font can can be freed by calling StripFont() on the font, and then calling UnLoadSeg() on the segment created by this function.

    Both the TextFont structure, and segment pointer are contained
    within the DiskFontHeader struct.  The DiskFontHeader structure
    will also be freed as part of the UnLoadSeg() call.
    StripFont() is a new graphics.library call as of V36.

OpenDiskFont()

OpenDiskFont -- Load and get a pointer to a disk font.

Synopsis

font = OpenDiskFont(textAttr) D0 A0

Function

This function finds the font with the specified textAttr on disk, loads it into memory, and returns a pointer to the font that can be used in subsequent SetFont and CloseFont calls. It is important to match this call with a corresponding CloseFont call for effective management of font memory.

   If the font is already in memory, the copy in memory is used.
   The disk copy is not reloaded.

Inputs

textAttr - a TextAttr structure that describes the text font attributes desired.

Results

D0 is zero if the desired font cannot be found.

Notes

As of V36, OpenDiskFont() will automatically attempt to construct a font for you if:

           You have requested a font size which does not exist
           as a designed font, and

           You have not set the DESIGNED bit in the ta_Flags
           field of the TextAttr, or TTextAttr struct.

   Constructed fonts are created by scaling a designed font.
   A designed font is one which typically resides on disk,
   or in ROM (e.g., a font which has been designed by hand
   using a drawing tool).  Designed fonts generally look better
   than fonts constructed by the font scaler, but designed
   fonts also require disk space for each font size.

   Always set the DESIGNED bit if you do not want constructed fonts,
   or use AvailFonts() to find out which font sizes already exist.

   As of V37 the diskfont.library supported built-in outline
   fonts.  Then in V38 the outline font engine was moved to
   a new library, "bullet.library."

Bugs

This routine will not work well with font names whose file name components are longer than the maximum allowed (30 characters).

OpenOutlineFont()

OpenOutlineFont -- Search, load, validate and relocate an .otag file, if requested open the font engine library and a glyph engine. (V47)

Synopsis

outlinefont = OpenOutlineFont(fileName, list, flags) D0 A0 A1 D0

struct OutlineFont*OpenOutlineFont(STRPTR fileName, List*list, ULONG flags);

Function

This function finds the .otag file for the specified outline font on disk, loads it into memory, validates that OT_FileIdent exists and matches the file size, validates that OT_Engine exists and relocates all OT_Indirect tags. If requested, it opens the font engine library and a glyph engine and calls ESetInfo() with the appropriate OT_OTagPath and OT_OTagList tags. It returns a pointer to a struct OutlineFont. It is important to match this call with a corresponding CloseOutlineFont() call for effective management of memory.

Inputs

fileName - file or font name to open. If fileName contains a ':', the .otag file will be searched in the path specified with fileName, otherwise it will be searched in FONTS:. The fileName may have either the ".font" or the ".otag" suffix or no suffix (just the font name, e.g. "Nimbus Sans L Regular Condensed Italic"). It is not limited in length.

list -     ignored when OFF_OPEN not set. A pointer to a struct
       List that has to be initialized with NewList() before
       the first call of OpenOutlineFont() and has to be used
       for every subsequent call of OpenOutlineFont() and
       CloseOutlineFont(), or NULL. If not NULL, the function
       uses this list to avoid re-opening font engine libraries
       for your task that were already opened by a previous
       call of OpenOutlineFont(). You either must pass the same
       list for all calls of OpenOutlineFont() and
       CloseOutlineFont() or always use NULL. If you want to
       share the list between tasks, you are responsible
       for using an appropriate locking mechanism, e.g. a
       Semaphore.

flags -    currently only OFF_OPEN is specified, when not set,
       the .otag file is only searched, loaded, validated and
       relocated and you can e.g. examine the OTagList and
       decide whether you want to use this font or not.
           See below how to open the font later.

Results

D0 is zero if the desired .otag file cannot be found, loaded or validated, the font engine library or glyph engine could not be opened or the ESetInfo() call specifying OT_OTagPath and OT_OTagList failed. Otherwise D0 points to a struct OutlineFont.

Notes

If you did not set OFF_OPEN and want to open the font later: open the font engine library via OpenLibrary() and store it in olf_EEngine.ege_BulletBase, if successful call EOpenEngine() with the address of olf_EEngine, if successful call ESetInfo() with olf_OTagPath and olf_OTagList as OT_OTagPath / OT_OTagList, if successful you can use the font. But: you must clean up yourself when done (ECloseEngine(), CloseLibrary()) and you must set all olf_EEngine members back to NULL before calling CloseOutlineFont(). Or just use your own EGlyphEngine structure instead.

Example

struct OutlineFont *outlineFont;

if (outlineFont = OpenOutlineFont("Helvetica", NULL, OFF_OPEN))
{
    if (ESetInfo(&outlineFont->olf_EEngine,
         OT_DeviceDPI, (XDPI << 16) | YDPI,
         OT_PointHeight, PointHeight,
         TAG_END) == OTERR_Success)
    {
    // Now all is set up to use the font with
    // ESetInfo(), EObtainInfo() and EReleaseInfo()
    }
    CloseOutlineFont(outlineFont, NULL);
}

See also

CloseOutlineFont(), ESetInfoA(), EObtainInfoA(), EReleaseInfoA()

SetDiskFontCtrlA()

SetDiskFontCtrlA -- Adjust disk font global settings. (V45) SetDiskFontCtrl -- varargs form of SetDiskFontCtrlA.

Synopsis

SetDiskFontCtrlA( tags ); A0

void SetDiskFontCtrlA(TagItem* );

void SetDiskFontCtrl( Tag, ... );

Function

SetDiskFontCtrl adjusts the global settings passed in in the form of a tag list and installs them into the the diskfont internal database. This includes the base DPI X and Y values, the cache enable flag and the AvailFonts font sorting order.

Inputs

tags - a tag list defining the global settings that are to be adjusted.

           The following tag values are currently supported:
           (see diskfont/diskfonttag.h)

           Font generator DPI settings:

           DFCTRL_XDPI
           DFCTRL_YDPI     X and Y dpi device resolution

           DFCTRL_XDOTP
           DFCTRL_YDOTP    X and Y dpi dot sizes.

           DFCTRL_CACHE    AvailFonts cache enable (BOOL)

           DFCTRL_SORTMODE AvailFonts font sorting (LONG)

           currently defined sort orders are:

                   DFCTRL_SORT_OFF don't sort
                   DFCTRL_SORT_ASC localized ascending
                   DFCTRL_SORT_DES localized descending

           DFCTRL_CACHEFLUSH Flush the cache?      (BOOL)

                   If TRUE, a cache flush is initiated.

Notes

The SetDiskFontCtrlA() function is the assembly language interface which takes the tag list pointer in A0. SetDiskFontCtrl() is the stack based wrapper for convenient C language calls.

   This call is not semaphore protected. This means that
   several calls to this function and GetDiskFontCtrl()
   might cause inconsistent results. The function will not
   fail or crash, but the result might be near to useless
   in a multitasking system.
   This function should never be called by the average
   user. Its sole purpose is to allow the font
   preferences editor to adjust the diskfont internal
   data in a user friendly way. It should not be called
   for other purposes, especially, applications *MUST NOT*
   call this to enable or disable the cache setting. This
   should be left to the user by selecting the preferences.

Example

SetDiskFontCtrl(DFCTRL_CACHE,TRUE,TAG_DONE);

   \* enable the AvailFonts cache. *\