@database "diskfont"
@master "Work:RKM/Includes&Autodocs/doc/diskfont.doc"

@Node Main "diskfont.doc"
@toc "2.0Includes_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.0/Includes/libraries/diskfont.h/Main" 94} -- Inquire available memory & disk fonts.

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

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

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

     When @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 94} 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.0/Includes/libraries/diskfont.h/Main" 104}
             followed by an array of @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 94} 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.
             Any combination may be specified.  AFF_TAGGED is set
             to fill the buffer with @{"TAvailFonts" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 99} elements instead
             of @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 94} elements.

RESULTS
     buffer - filled with struct @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 104} 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 existence 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 "OpenDiskFont()"} of it may
             fail.
     error - if non-zero, this indicates the number of bytes needed
             for @{"AvailFonts" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 94} 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.0/Includes/libraries/diskfont.h/Main" 104} *afh;

     ...

     afSize = 400;
     do {
         afh = (struct @{"AvailFontsHeader" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 104} *) 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.0/Includes/libraries/diskfont.h/Main" 94} 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.0/Includes/libraries/diskfont.h/Main" 104}
      * 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 "NewFontContents()"}. (V34)

SYNOPSIS
     DisposeFontContents(fontContentsHeader)
                         A1

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

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

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

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

     A fontContentsHeader other than one acquired by a call
     @{"NewFontContents" link "NewFontContents()"} will crash.

SEE ALSO
     @{"NewFontContents" link "NewFontContents()"} to get structure freed here.

@EndNode

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

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

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

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

FUNCTION
     This function creates a new array of @{"FontContents" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 29} 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.0/Includes/libraries/diskfont.h/Main" 53} 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 "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.0/Includes/libraries/diskfont.h/Main" 63} *NewScaledDiskFont( struct @{"TextFont" Link "ADCD_v1.2:Inc&AD2.0/Includes/graphics/text.h/Main" 90} *,
             struct @{"TTextAttr" Link "ADCD_v1.2:Inc&AD2.0/Includes/graphics/text.h/Main" 73} * );

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

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

         Both the @{"TextFont" Link "ADCD_v1.2:Inc&AD2.0/Includes/graphics/text.h/Main" 90} structure, and segment pointer are contained
         within the @{"DiskFontHeader" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 63} struct.  The @{"DiskFontHeader" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/diskfont.h/Main" 63} structure
         will also be freed as part of the @{"UnLoadSeg()" Link "dos/UnLoadSeg()"} call.
         @{"StripFont()" Link "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 "graphics/SetFont()"} and @{"CloseFont" Link "graphics/CloseFont()"} calls.
    It is important to match this call with a corresponding
    @{"CloseFont" Link "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.0/Includes/graphics/text.h/Main" 66} 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.0/Includes/graphics/text.h/Main" 66}, or @{"TTextAttr" Link "ADCD_v1.2:Inc&AD2.0/Includes/graphics/text.h/Main" 73} 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.

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

@EndNode

