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

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

@{" --background-- " Link "--background--"}    @{" ObtainInfoA() " Link "ObtainInfoA()"}    @{" ReleaseInfoA() " Link "ReleaseInfoA()"}
@{" CloseEngine() " Link "CloseEngine()"}     @{" OpenEngine() " Link "OpenEngine()"}     @{" SetInfoA() " Link "SetInfoA()"}

@EndNode

@Node "--background--" "bullet.library/--background--"

AMIGA FONTS
    The existence of a disk font is indicated by the existence of
    its associated font contents file, whose name has the suffix
    ".font".  It is this name that is used in the actual font
    open call of the application.  Amiga fonts are collected in
    the directory path(s) associated with the FONTS: assign.  It
    is this assign that is searched if no explicit path name is
    provided in the font open call: use of an explicit path is
    generally discouraged.  The actual bitmaps of traditional
    Amiga fonts are stored in a directory with the name of the
    font contents file stripped of its ".font" suffix.  This
    directory is usually in the same directory as the font
    contents file.  This traditional arrangement is supported by
    the FixFonts system application.

    For example:
        o   FONTS: is assigned to Sys:Fonts/
        o   Sys:Fonts/garnet.font exists and describes that the
            font "garnet.font" exists
        o   Sys:Fonts/garnet/ contains the bitmap images for
            sizes 9 and 16

    Other variations of file placement may exist, but they
    require custom tools to maintain -- tools available not from
    Commodore, but from other sources such as Fish disks.

    Font contents files are flagged with magic numbers that not
    only verify that they are a font contents files but also what
    variation of file structure they contain.

OUTLINE TYPEFACES
    The existence of an outline typeface is indicated by a magic
    number in the font contents file.  They are further described
    in the associated outline typeface tag file, whose name is
    the that of the font contents file with the suffix ".otag"
    substituted for ".font".  This tag file contains a tag list
    that is to be processed and passed to the outline engine
    (i.e.  bullet.library) in order to select the associated
    typeface.  It also contains information applications may use
    to guide their use of the typeface.

OTAG SPECIFICATION EXAMPLE
    Here are the steps necessary to go from an arbitrary font
    name into an environment where glyphs from that font
    can be accessed:
    1.  Read the header from the font contents (.font) file and
        verify that the magic cookie fch_ID is OFCH_ID.
        If it is not, then this is an Amiga bitmap font,
        not an outline font.
    2.  Read the associated outline tag (.otag) file into memory:
        a.  Validate that the OT_FileIdent exists and matches the
            file size.
        b.  Allocate a memory buffer and read the file into it.
        c.  Resolve addresses: for each tag with the OT_Indirect
            bit set, add the memory buffer origin to the
            associated data.
    3.  Find the OT_Engine tag and ensure that you have the
        proper engine open:
        a.  If you already have an engine handle for this engine
            name, you skip these steps.
        b.  append the suffix ".library" to the engine name.
            (e.g. "bullet" becomes "bullet.library").
        c.  use exec's @{"OpenLibrary()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/OpenLibrary()"} to open the library.
        d.  use the engine's @{"OpenEngine()" Link "OpenEngine()"} to acquire an engine
            handle.
    4.  Pass the full path name of the .otag file to the engine
        with the OT_OTagPath tag using SetInfo().
    5.  Pass the memory copy of the .otag file to the engine with
        the OT_OTagList tag using SetInfo().  This step may be
        combined with step 4, passing first the path then the
        list in one call.
    The library is now ready to accept glyph metric information
    (e.g. size and glyph code) and produce glyph bitmaps.

DISKFONT USE OF OTAG ENTRIES
    The diskfont library uses other entries from the outline tag
    (.otag) file.  The following are used both during inquiry of
    what typefaces exist (AvailFonts) and during creation of an
    Amiga @{"TextFont" Link "ADCD_v1.2:Inc&AD2.1/Includes/graphics/text.h/Main" 88} (OpenDiskFont):
    o   OT_IsFixed is used to determine whether these outlines
        describe a PROPORTIONAL flagged font.
    o   OT_StemWeight is used to determine whether these outlines
        describe a BOLD style font.
    o   OT_SlantStyle is used to determine whether these outlines
        describe an ITALIC style font.
    o   OT_HorizStyle is used to determine whether these outlines
        describe an EXTENDED style font.
    The following are used only during OpenDiskFont:
    o   OT_YSizeFactor is used to convert the Amiga pixel height
        specification, which describes the distance from the
        lowest decender to the highest ascender, into a point
        size specification, which is related (via YSizeFactor)
        to a nominal character height.
    o   OT_SpaceWidth is used as the width of the space character.
    The following is used only during AvailFonts:
    o   OT_AvailSizes is used to generate a list of sizes
        available for the font.

@EndNode

@Node "CloseEngine()" "bullet.library/CloseEngine"

NAME
    CloseEngine -- Release an engine handle

SYNOPSIS
    CloseEngine(engineHandle)
                A0

    void CloseEngine(struct @{"GlyphEngine" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 25} *);

FUNCTION
    This function releases the engine handle acquired with
    @{"OpenEngine" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/OpenEngine()"}.  It first releases any data acquired with
    @{"ObtainInfoA" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/ObtainInfoA()"} associated with the engineHandle that has not yet
    been released.

INPUTS
    engineHandle -- the handle acquired via @{"OpenEngine" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/OpenEngine()"}.  If zero,
            no operation is performed.

RESULT
    This function has no result.  The only error that can occur is
    when the when an invalid engineHandle is supplied: the
    application is assumed not to do that.

EXAMPLE
    EndGame(code, arg1, arg2, arg3, arg3)
    {
        ...
        CloseEngine(EngineHandle);
        ...
    }

SEE ALSO
    @{"OpenEngine()" Link "OpenEngine()"}

@EndNode

@Node "ObtainInfoA()" "bullet.library/ObtainInfoA"

NAME
    ObtainInfoA -- Inquire tagged font and/or glyph metrics
    ObtainInfo -- varargs form of ObtainInfoA

SYNOPSIS
    error = ObtainInfoA(engineHandle, tagList)
                        A0            A1

    ULONG ObtainInfoA(struct @{"GlyphEngine" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 25} *, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    error = ObtainInfo(engineHandle, firstTag, ...)

    ULONG ObtainInfo(struct @{"GlyphEngine" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 25} *, Tag, ...);

FUNCTION
    This function accepts a tagList 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 ObtainInfoA,
    it must perform a @{"ReleaseInfoA" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/ReleaseInfoA()"} to allow the library to release
    the data.

INPUTS
    engineHandle -- the handle acquired via @{"OpenEngine" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/OpenEngine()"}.
    tagList -- a tagList 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.

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

EXAMPLE
        ULONG pointSize;
        struct @{"GlyphMap" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 33} *glyph;
        ...
        if (!ObtainInfo(EngineHandle, OT_Glyph, &glyph, TAG_DONE)) {
            ...
            ReleaseInfo(EngineHandle, OT_Glyph, glyph, TAG_DONE);
        }

SEE ALSO
    @{"ReleaseInfoA()" Link "ReleaseInfoA()"}, @{"diskfont/diskfonttag.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfonttag.h/Main" 0}, @{"diskfont/oterrors.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/oterrors.h/Main" 0}

@EndNode

@Node "OpenEngine()" "bullet.library/OpenEngine"

NAME
    OpenEngine -- Acquire engine handle

SYNOPSIS
    engineHandle = OpenEngine()

    struct @{"GlyphEngine" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 25} *OpenEngine(void)

FUNCTION
    This function establishes a context for access to the bullet
    library.  This context remains valid until it is closed via
    @{"CloseEngine" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/CloseEngine()"}.  Each specific context isolates the specification
    of the various font attributes from other contexts concurrently
    accessing the bullet library.  A context can be shared among
    different tasks.

RESULT
    This function returns an engineHandle, or NULL if for some
    reason no engineHandle can be created.

EXAMPLE
        BulletBase = OpenLibrary("bullet.library", 0);
        if (!BulletBase)
            EndGame(ERROR_LibOpen, "bullet.library", 0);
        EngineHandle = OpenEngine();
        if (!EngineHandle)
            EndGame(ERROR_InternalCall, "OpenEngine");

SEE ALSO
    @{"CloseEngine()" Link "CloseEngine()"}

@EndNode

@Node "ReleaseInfoA()" "bullet.library/ReleaseInfoA"

NAME
    ReleaseInfoA -- Release data obtained with @{"ObtainInfoA" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/ObtainInfoA()"}
    ReleaseInfo -- varargs form of ReleaseInfoA

SYNOPSIS
    error = ReleaseInfoA(engineHandle, tagList)
                         A0            A1

    ULONG ReleaseInfoA(struct @{"GlyphEngine" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 25} *, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    error = ReleaseInfo(engineHandle, firstTag, ...)

    ULONG ReleaseInfo(struct @{"GlyphEngine" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 25} *, Tag, ...);

FUNCTION
    This function releases the data obtained with @{"ObtainInfoA" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/ObtainInfoA()"}.
    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 ReleaseInfoA tag item must be associated with a prior
    @{"ObtainInfoA" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/ObtainInfoA()"}.

INPUTS
    engineHandle -- the handle acquired via @{"OpenEngine" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/OpenEngine()"}.
    tagList -- a tagList containing OT_ tags valid for inquiry
            paired with the data previously acquired for them with
            @{"ObtainInfoA" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/ObtainInfoA()"}.  Null pointers quietly accepted and
            ignored for indirect data.

RESULT
    This function has no result.  The only error that can occur is
    when the Obtain and Release pairs are mismatched: the
    application is assumed not to do that.

EXAMPLE
        ULONG pointSize;
        struct @{"GlyphMap" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 33} *glyph;
        ...
        error = ObtainInfo(EngineHandle, OT_Glyph, &glyph, TAG_DONE);
        ...
        ReleaseInfo(EngineHandle, OT_Glyph, glyph, TAG_DONE);

SEE ALSO
    ReleaseInfoA(), @{"diskfont/diskfonttag.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfonttag.h/Main" 0}, @{"diskfont/oterrors.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/oterrors.h/Main" 0}

@EndNode

@Node "SetInfoA()" "bullet.library/SetInfoA"

NAME
    SetInfoA -- Set font and/or glyph metrics
    SetInfo -- varargs form of SetInfoA

SYNOPSIS
    error = SetInfoA(engineHandle, tagList)
                     A0            A1

    ULONG SetInfoA(struct @{"GlyphEngine" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 25} *, struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.1/Includes/utility/tagitem.h/Main" 29} *);

    error = SetInfo(engineHandle, firstTag, ...)

    ULONG SetInfo(struct @{"GlyphEngine" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/glyph.h/Main" 25} *, Tag, ...);

FUNCTION
    This function accepts a tagList 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) 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
    engineHandle -- the handle acquired via @{"OpenEngine" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/bullet/OpenEngine()"}.
    tagList -- a tagList containing OT_ tags valid for
            specification paired with the specification data.

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

EXAMPLE
        if (!(error = SetInfo(EngineHandle, OT_PointHeight, fpoints,
                OT_GlyphCode, GC_daggerdbl, TAG_DONE)) {
            error = ObtainInfo(EngineHandle, OT_Glyph, &glyph);
            ...
            ReleaseInfo(EngineHandle, OT_Glyph, glyph);
        }

SEE ALSO
    @{"diskfont/diskfonttag.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/diskfonttag.h/Main" 0}, @{"diskfont/oterrors.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/diskfont/oterrors.h/Main" 0},

@EndNode

