@database "diskfont"
@master "ADCD_v1.2:Inc&AD2.1/Includes/doc/diskfont.doc"

@Node Main "diskfont.doc"
@TOC 2.1Includes_Autodocs/Autodocs

@{" AvailFonts() " Link "AvailFonts()"}             @{" NewFontContents() " Link "NewFontContents()"}      @{" OpenDiskFont() " Link "OpenDiskFont()"}
@{" DisposeFontContents() " Link "DisposeFontContents()"}    @{" NewScaledDiskFont() " Link "NewScaledDiskFont()"}

@EndNode

@Node "AvailFonts()" "diskfont.library/AvailFonts"

NAME
    @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 95} -- Inquire available memory & disk fonts.

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

    LONG AvailFonts( struct @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 105} *buffer, LONG bufBytes
            ULONG flags );

FUNCTION
    @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 95} 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" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/diskfont/OpenDiskFont()"}, those already in memory are accessed via
    @{"OpenFont" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/graphics/OpenFont()"}.  The @{"TextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64} structure required by the open calls
    is part of the information @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 95} supplies.

    When @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 95} 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" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 105}
            followed by an array of @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 95} 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" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 100}
            elements instead of @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 95} elements.

RESULTS
    buffer - filled with struct @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 105} 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" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/diskfont/OpenDiskFont()"} of it may
            fail.
    error - if non-zero, this indicates the number of bytes needed
            for @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 95} in addition to those supplied.  Thus
            structure elements were not returned because of
            insufficient bufBytes.

EXAMPLE
    int afShortage, afSize;
    struct @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 105} *afh;

    ...

    afSize = 400;
    do {
        afh = (struct @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 105} *) AllocMem(afSize, 0);
        if (afh) {
            afShortage = AvailFonts(afh, afSize, AFF_MEMORY|AFF_DISK);
            if (afShortage) {
                FreeMem(afh, afSize);
                afSize += afShortage;
            }
        }
        else {
            fail("AllocMem of @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 95} buffer afh failed\n");
            break;
        }
    }
        while (afShortage);

    /*
     * if (afh) non-zero here, then:
     * 1. it points to a valid @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 105}
     * 2. it must have FreeMem(afh, afSize) called for it after use
     */

@EndNode

@Node "DisposeFontContents()" "diskfont.library/DisposeFontContents"

NAME
    DisposeFontContents -- Free the result from @{"NewFontContents" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/diskfont/NewFontContents()"}. (V34)

SYNOPSIS
    DisposeFontContents(fontContentsHeader)
                        A1

    VOID DisposeFontContents( struct @{"FontContentsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 52} * );

FUNCTION
    This function frees the array of @{"FontContents" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 26} entries
    returned by @{"NewFontContents" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/diskfont/NewFontContents()"}.

INPUTS
    fontContentsHeader - a struct @{"FontContentsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 52} pointer
        returned by @{"NewFontContents" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/diskfont/NewFontContents()"}.

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

    A fontContentsHeader other than one acquired by a call
    @{"NewFontContents" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/diskfont/NewFontContents()"} will crash.

SEE ALSO
    @{"NewFontContents" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/diskfont/NewFontContents()"} to get structure freed here.

@EndNode

@Node "NewFontContents()" "diskfont.library/NewFontContents"

NAME
    NewFontContents -- Create a @{"FontContents" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 26} image for a font. (V34)

SYNOPSIS
    fontContentsHeader = NewFontContents(fontsLock,fontName)
    D0                                   A0        A1

    struct @{"FontContentsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 52} *NewFontContents( BPTR, char * );

FUNCTION
    This function creates a new array of @{"FontContents" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 26} 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.

RESULT
    fontContentsHeader - a struct @{"FontContentsHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 52} 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" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/diskfont/DisposeFontContents()"} to free the structure acquired here.

@EndNode

@Node "NewScaledDiskFont()" "diskfont.library/NewScaledDiskFont"

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

SYNOPSIS
    header = NewScaledDiskFont(srcFont, destTextAttr)
    D0                         A0       A1

    struct @{"DiskFontHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 62} *NewScaledDiskFont( struct @{"TextFont" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 88} *,
            struct @{"TTextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 71} * );

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" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64} or
        @{"TTextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 71}.

RESULT
    header - a pointer to a @{"DiskFontHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 62} 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()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/graphics/StripFont()"} on the font,
        and then calling @{"UnLoadSeg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/dos/UnLoadSeg()"} on the segment created
        by this function.

        Both the @{"TextFont" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 88} structure, and segment pointer are contained
        within the @{"DiskFontHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 62} struct.  The @{"DiskFontHeader" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfont.h/Main" 62} structure
        will also be freed as part of the @{"UnLoadSeg()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/dos/UnLoadSeg()"} call.
        @{"StripFont()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/graphics/StripFont()"} is a new graphics.library call as of V36.

@EndNode

@Node "OpenDiskFont()" "diskfont.library/OpenDiskFont"

NAME
    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" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/graphics/SetFont()"} and @{"CloseFont" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/graphics/CloseFont()"} calls.
    It is important to match this call with a corresponding
    @{"CloseFont" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/graphics/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" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64} 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" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 64}, or @{"TTextAttr" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 71} 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()" Link "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).

@EndNode

