home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD2.1 / Text_Autodocs / bullet.doc < prev    next >
Encoding:
Text File  |  1992-09-11  |  11.1 KB  |  329 lines
  1. TABLE OF CONTENTS
  2.  
  3. bullet.library/--background--
  4. bullet.library/CloseEngine
  5. bullet.library/ObtainInfoA
  6. bullet.library/OpenEngine
  7. bullet.library/ReleaseInfoA
  8. bullet.library/SetInfoA
  9. bullet.library/--background--                   bullet.library/--background--
  10.  
  11.    AMIGA FONTS
  12.     The existence of a disk font is indicated by the existence of
  13.     its associated font contents file, whose name has the suffix
  14.     ".font".  It is this name that is used in the actual font
  15.     open call of the application.  Amiga fonts are collected in
  16.     the directory path(s) associated with the FONTS: assign.  It
  17.     is this assign that is searched if no explicit path name is
  18.     provided in the font open call: use of an explicit path is
  19.     generally discouraged.  The actual bitmaps of traditional
  20.     Amiga fonts are stored in a directory with the name of the
  21.     font contents file stripped of its ".font" suffix.  This
  22.     directory is usually in the same directory as the font
  23.     contents file.  This traditional arrangement is supported by
  24.     the FixFonts system application.
  25.  
  26.     For example:
  27.         o   FONTS: is assigned to Sys:Fonts/
  28.         o   Sys:Fonts/garnet.font exists and describes that the
  29.         font "garnet.font" exists
  30.         o   Sys:Fonts/garnet/ contains the bitmap images for
  31.         sizes 9 and 16
  32.  
  33.     Other variations of file placement may exist, but they
  34.     require custom tools to maintain -- tools available not from
  35.     Commodore, but from other sources such as Fish disks.
  36.  
  37.     Font contents files are flagged with magic numbers that not
  38.     only verify that they are a font contents files but also what
  39.     variation of file structure they contain.
  40.  
  41.    OUTLINE TYPEFACES
  42.     The existence of an outline typeface is indicated by a magic
  43.     number in the font contents file.  They are further described
  44.     in the associated outline typeface tag file, whose name is
  45.     the that of the font contents file with the suffix ".otag"
  46.     substituted for ".font".  This tag file contains a tag list
  47.     that is to be processed and passed to the outline engine
  48.     (i.e.  bullet.library) in order to select the associated
  49.     typeface.  It also contains information applications may use
  50.     to guide their use of the typeface.
  51.  
  52.    OTAG SPECIFICATION EXAMPLE
  53.     Here are the steps necessary to go from an arbitrary font
  54.     name into an environment where glyphs from that font
  55.     can be accessed:
  56.     1.  Read the header from the font contents (.font) file and
  57.         verify that the magic cookie fch_ID is OFCH_ID.
  58.         If it is not, then this is an Amiga bitmap font,
  59.         not an outline font.
  60.     2.  Read the associated outline tag (.otag) file into memory:
  61.         a.  Validate that the OT_FileIdent exists and matches the
  62.         file size.
  63.         b.  Allocate a memory buffer and read the file into it.
  64.         c.  Resolve addresses: for each tag with the OT_Indirect
  65.         bit set, add the memory buffer origin to the
  66.         associated data.
  67.     3.  Find the OT_Engine tag and ensure that you have the
  68.         proper engine open:
  69.         a.  If you already have an engine handle for this engine
  70.         name, you skip these steps.
  71.         b.  append the suffix ".library" to the engine name.
  72.         (e.g. "bullet" becomes "bullet.library").
  73.         c.  use exec's OpenLibrary() to open the library.
  74.         d.  use the engine's OpenEngine() to acquire an engine
  75.         handle.
  76.     4.  Pass the full path name of the .otag file to the engine
  77.         with the OT_OTagPath tag using SetInfo().
  78.     5.  Pass the memory copy of the .otag file to the engine with
  79.         the OT_OTagList tag using SetInfo().  This step may be
  80.         combined with step 4, passing first the path then the
  81.         list in one call.
  82.     The library is now ready to accept glyph metric information
  83.     (e.g. size and glyph code) and produce glyph bitmaps.
  84.  
  85.    DISKFONT USE OF OTAG ENTRIES
  86.     The diskfont library uses other entries from the outline tag
  87.     (.otag) file.  The following are used both during inquiry of
  88.     what typefaces exist (AvailFonts) and during creation of an
  89.     Amiga TextFont (OpenDiskFont):
  90.     o   OT_IsFixed is used to determine whether these outlines
  91.         describe a PROPORTIONAL flagged font.
  92.     o   OT_StemWeight is used to determine whether these outlines
  93.         describe a BOLD style font.
  94.     o   OT_SlantStyle is used to determine whether these outlines
  95.         describe an ITALIC style font.
  96.     o   OT_HorizStyle is used to determine whether these outlines
  97.         describe an EXTENDED style font.
  98.     The following are used only during OpenDiskFont:
  99.     o   OT_YSizeFactor is used to convert the Amiga pixel height
  100.         specification, which describes the distance from the
  101.         lowest decender to the highest ascender, into a point
  102.         size specification, which is related (via YSizeFactor)
  103.         to a nominal character height.
  104.     o   OT_SpaceWidth is used as the width of the space character.
  105.     The following is used only during AvailFonts:
  106.     o   OT_AvailSizes is used to generate a list of sizes
  107.         available for the font.
  108.  
  109. bullet.library/CloseEngine                         bullet.library/CloseEngine
  110.  
  111.     NAME
  112.     CloseEngine -- Release an engine handle
  113.  
  114.     SYNOPSIS
  115.     CloseEngine(engineHandle)
  116.                 A0
  117.  
  118.     void CloseEngine(struct GlyphEngine *);
  119.  
  120.     FUNCTION
  121.     This function releases the engine handle acquired with
  122.     OpenEngine.  It first releases any data acquired with
  123.     ObtainInfoA associated with the engineHandle that has not yet
  124.     been released.
  125.  
  126.     INPUTS
  127.     engineHandle -- the handle acquired via OpenEngine.  If zero,
  128.         no operation is performed.
  129.  
  130.     RESULT
  131.     This function has no result.  The only error that can occur is
  132.     when the when an invalid engineHandle is supplied: the
  133.     application is assumed not to do that.
  134.  
  135.     EXAMPLE
  136.     EndGame(code, arg1, arg2, arg3, arg3)
  137.     {
  138.         ...
  139.         CloseEngine(EngineHandle);
  140.         ...
  141.     }
  142.  
  143.     SEE ALSO
  144.     OpenEngine()
  145.  
  146. bullet.library/ObtainInfoA                         bullet.library/ObtainInfoA
  147.  
  148.     NAME
  149.     ObtainInfoA -- Inquire tagged font and/or glyph metrics
  150.     ObtainInfo -- varargs form of ObtainInfoA
  151.  
  152.     SYNOPSIS
  153.     error = ObtainInfoA(engineHandle, tagList)
  154.                         A0            A1
  155.  
  156.     ULONG ObtainInfoA(struct GlyphEngine *, struct TagItem *);
  157.  
  158.     error = ObtainInfo(engineHandle, firstTag, ...)
  159.  
  160.     ULONG ObtainInfo(struct GlyphEngine *, Tag, ...);
  161.  
  162.     FUNCTION
  163.     This function accepts a tagList whose tag field elements are
  164.     valid for inquiry, and whose associated data fields are
  165.     pointers to the destination in which to place the requested
  166.     data.
  167.  
  168.     Tag items that refer to data indirectly (OT_Indirect is set)
  169.     return pointers that may be allocated or cached by the
  170.     library.  This data must be treated as read-only data.  When
  171.     the application is done with the data acquired via ObtainInfoA,
  172.     it must perform a ReleaseInfoA to allow the library to release
  173.     the data.
  174.  
  175.     INPUTS
  176.     engineHandle -- the handle acquired via OpenEngine.
  177.     tagList -- a tagList containing OT_ tags valid for inquiry
  178.         paired with the destination pointers for the inquiry
  179.         results.  All destinations are longwords, whether they
  180.         are pointers or values, and regardless of whether the
  181.         value could fit in a smaller variable.
  182.  
  183.     RESULT
  184.     This function returns a zero success indication, or a non-zero
  185.     error code.
  186.  
  187.     EXAMPLE
  188.         ULONG pointSize;
  189.         struct GlyphMap *glyph;
  190.         ...
  191.         if (!ObtainInfo(EngineHandle, OT_Glyph, &glyph, TAG_DONE)) {
  192.         ...
  193.         ReleaseInfo(EngineHandle, OT_Glyph, glyph, TAG_DONE);
  194.         }
  195.  
  196.     SEE ALSO
  197.     ReleaseInfoA(), diskfont/diskfonttag.h, diskfont/oterrors.h
  198.  
  199. bullet.library/OpenEngine                           bullet.library/OpenEngine
  200.  
  201.     NAME
  202.     OpenEngine -- Acquire engine handle
  203.  
  204.     SYNOPSIS
  205.     engineHandle = OpenEngine()
  206.  
  207.     struct GlyphEngine *OpenEngine(void)
  208.  
  209.     FUNCTION
  210.     This function establishes a context for access to the bullet
  211.     library.  This context remains valid until it is closed via
  212.     CloseEngine.  Each specific context isolates the specification
  213.     of the various font attributes from other contexts concurrently
  214.     accessing the bullet library.  A context can be shared among
  215.     different tasks.
  216.  
  217.     RESULT
  218.     This function returns an engineHandle, or NULL if for some
  219.     reason no engineHandle can be created.
  220.  
  221.     EXAMPLE
  222.         BulletBase = OpenLibrary("bullet.library", 0);
  223.         if (!BulletBase)
  224.         EndGame(ERROR_LibOpen, "bullet.library", 0);
  225.         EngineHandle = OpenEngine();
  226.         if (!EngineHandle)
  227.         EndGame(ERROR_InternalCall, "OpenEngine");
  228.  
  229.     SEE ALSO
  230.     CloseEngine()
  231.  
  232. bullet.library/ReleaseInfoA                       bullet.library/ReleaseInfoA
  233.  
  234.     NAME
  235.     ReleaseInfoA -- Release data obtained with ObtainInfoA
  236.     ReleaseInfo -- varargs form of ReleaseInfoA
  237.  
  238.     SYNOPSIS
  239.     error = ReleaseInfoA(engineHandle, tagList)
  240.                          A0            A1
  241.  
  242.     ULONG ReleaseInfoA(struct GlyphEngine *, struct TagItem *);
  243.  
  244.     error = ReleaseInfo(engineHandle, firstTag, ...)
  245.  
  246.     ULONG ReleaseInfo(struct GlyphEngine *, Tag, ...);
  247.  
  248.     FUNCTION
  249.     This function releases the data obtained with ObtainInfoA.
  250.     Data associated with tags that are not indirect, i.e. for which
  251.     OT_Indirect is not set, need not be released, but it is not an
  252.     error to do so.  Released data may be immediately freed or may
  253.     become a candidate to be expunged from memory when the system
  254.     reaches a low memory condition, depending on the library's
  255.     internal implementation.
  256.  
  257.     Each ReleaseInfoA tag item must be associated with a prior
  258.     ObtainInfoA.
  259.  
  260.     INPUTS
  261.     engineHandle -- the handle acquired via OpenEngine.
  262.     tagList -- a tagList containing OT_ tags valid for inquiry
  263.         paired with the data previously acquired for them with
  264.         ObtainInfoA.  Null pointers quietly accepted and
  265.         ignored for indirect data.
  266.  
  267.     RESULT
  268.     This function has no result.  The only error that can occur is
  269.     when the Obtain and Release pairs are mismatched: the
  270.     application is assumed not to do that.
  271.  
  272.     EXAMPLE
  273.         ULONG pointSize;
  274.         struct GlyphMap *glyph;
  275.         ...
  276.         error = ObtainInfo(EngineHandle, OT_Glyph, &glyph, TAG_DONE);
  277.         ...
  278.         ReleaseInfo(EngineHandle, OT_Glyph, glyph, TAG_DONE);
  279.  
  280.     SEE ALSO
  281.     ReleaseInfoA(), diskfont/diskfonttag.h, diskfont/oterrors.h
  282.  
  283. bullet.library/SetInfoA                               bullet.library/SetInfoA
  284.  
  285.     NAME
  286.     SetInfoA -- Set font and/or glyph metrics
  287.     SetInfo -- varargs form of SetInfoA
  288.  
  289.     SYNOPSIS
  290.     error = SetInfoA(engineHandle, tagList)
  291.                      A0            A1
  292.  
  293.     ULONG SetInfoA(struct GlyphEngine *, struct TagItem *);
  294.  
  295.     error = SetInfo(engineHandle, firstTag, ...)
  296.  
  297.     ULONG SetInfo(struct GlyphEngine *, Tag, ...);
  298.  
  299.     FUNCTION
  300.     This function accepts a tagList whose tag field elements are
  301.     valid for specification, and whose associated data fields are
  302.     used to supply the specified data.
  303.  
  304.     Data that is supplied via an indirect pointer (OT_Indirect) to
  305.     an array or structure is copied from that array or structure
  306.     into the internal memory of the library.  Changes to the data
  307.     after this call do not affect the engine.
  308.  
  309.     INPUTS
  310.     engineHandle -- the handle acquired via OpenEngine.
  311.     tagList -- a tagList containing OT_ tags valid for
  312.         specification paired with the specification data.
  313.  
  314.     RESULT
  315.     This function returns a zero success indication, or a non-zero
  316.     error code.
  317.  
  318.     EXAMPLE
  319.         if (!(error = SetInfo(EngineHandle, OT_PointHeight, fpoints,
  320.             OT_GlyphCode, GC_daggerdbl, TAG_DONE)) {
  321.         error = ObtainInfo(EngineHandle, OT_Glyph, &glyph);
  322.         ...
  323.         ReleaseInfo(EngineHandle, OT_Glyph, glyph);
  324.         }
  325.  
  326.     SEE ALSO
  327.     diskfont/diskfonttag.h, diskfont/oterrors.h,
  328.  
  329.