@database "diskfont"
@master "AMIDEV:NDK/Autodocs/diskfont.doc"

@Node Main "diskfont.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" AvailFonts() " Link "AvailFonts()"}
    @{" CloseOutlineFont() " Link "CloseOutlineFont()"}
    @{" DisposeFontContents() " Link "DisposeFontContents()"}
    @{" ECloseEngine() " Link "ECloseEngine()"}
    @{" EObtainInfoA() " Link "EObtainInfoA()"}
    @{" EOpenEngine() " Link "EOpenEngine()"}
    @{" EReleaseInfoA() " Link "EReleaseInfoA()"}
    @{" ESetInfoA() " Link "ESetInfoA()"}
    @{" GetDiskFontCtrl() " Link "GetDiskFontCtrl()"}
    @{" NewFontContents() " Link "NewFontContents()"}
    @{" NewScaledDiskFont() " Link "NewScaledDiskFont()"}
    @{" OpenDiskFont() " Link "OpenDiskFont()"}
    @{" OpenOutlineFont() " Link "OpenOutlineFont()"}
    @{" SetDiskFontCtrlA() " Link "SetDiskFontCtrlA()"}
@EndNode

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

@{b}   NAME@{ub}
	@{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} -- Inquire available memory & disk fonts.

@{b}   SYNOPSIS@{ub}
	error = AvailFonts(buffer, bufBytes, flags);
	                   A0      D0        D1

	@{"LONG" Link "INCLUDE:exec/types.h/Main" 112} AvailFonts( struct @{"AvailFontsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 120} *buffer, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} bufBytes
		ULONG flags );

@{b}   FUNCTION@{ub}
	@{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} 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 "diskfont/OpenDiskFont()"}, those already in memory are accessed via
	@{"OpenFont" Link "graphics/OpenFont()"}.  The @{"TextAttr" Link "INCLUDE:graphics/text.h/Main" 63} structure required by the open calls
	is part of the information @{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} supplies.

	When @{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} 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.

@{b}   INPUTS@{ub}
	buffer - memory to be filled with struct @{"AvailFontsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 120}
		followed by an array of @{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} 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 "INCLUDE:diskfont/diskfont.h/Main" 115}
		elements instead of @{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} 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).

@{b}   RESULTS@{ub}
	buffer - filled with struct @{"AvailFontsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 120} 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 "diskfont/OpenDiskFont()"} of it may
		fail.
	error - if non-zero, this indicates the number of bytes needed
		for @{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} in addition to those supplied.  Thus
		structure elements were not returned because of
		insufficient bufBytes.

@{b}   EXAMPLE@{ub}
	int afShortage, afSize;
	struct @{"AvailFontsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 120} *afh;

	...

	afSize = 400;
	do {
	    afh = (struct @{"AvailFontsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 120} *) 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" Link "INCLUDE:diskfont/diskfont.h/Main" 110} buffer afh failed\n");
	        break;
	    }
	}
	    while (afShortage);

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

@{b}   BUGS@{ub}
	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.

@EndNode

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

@{b}   NAME@{ub}
	CloseOutlineFont -- Release a pointer to an outline font. (V47)

@{b}   SYNOPSIS@{ub}
	CloseOutlineFont(outlineFont, list)
	                 A0           A1

	VOID CloseOutlineFont(struct @{"OutlineFont" Link "INCLUDE:diskfont/diskfont.h/Main" 137} *, struct @{"List" Link "INCLUDE:exec/lists.h/Main" 19} *);

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

@{b}   INPUTS@{ub}
	font - a font pointer as returned by @{"OpenOutlineFont()" Link "OpenOutlineFont()"}.

	list - the same pointer to a struct @{"List" Link "INCLUDE:exec/lists.h/Main" 19} (or @{"NULL" Link "rexxsupport/NULL"} pointer) that
	       was used for the matching @{"OpenOutlineFont()" Link "OpenOutlineFont()"} call.
	       If you want to share the list between tasks, you are
	       responsible for using an appropriate locking mechanism,
	       e.g. a Semaphore.

@{b}   RESULTS@{ub}

@{b}   SEE ALSO@{ub}
	@{"OpenOutlineFont()" Link "OpenOutlineFont()"}

@EndNode

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

@{b}   NAME@{ub}
	DisposeFontContents -- Free the result from @{"NewFontContents" Link "diskfont/NewFontContents()"}. (V34)

@{b}   SYNOPSIS@{ub}
	DisposeFontContents(fontContentsHeader)
			    A1

	VOID DisposeFontContents( struct @{"FontContentsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 55} * );

@{b}   FUNCTION@{ub}
	This function frees the array of @{"FontContents" Link "INCLUDE:diskfont/diskfont.h/Main" 29} entries
	returned by @{"NewFontContents" Link "diskfont/NewFontContents()"}.

@{b}   INPUTS@{ub}
	fontContentsHeader - a struct @{"FontContentsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 55} pointer
	    returned by @{"NewFontContents" Link "diskfont/NewFontContents()"}.

@{b}   EXCEPTIONS@{ub}
 	This command was first made available as of version 34.

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

@{b}   SEE ALSO@{ub}
	@{"NewFontContents" Link "diskfont/NewFontContents()"} to get structure freed here.

@EndNode

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

@{b}    NAME@{ub}
	ECloseEngine -- Release an engine handle. (V47)

@{b}    SYNOPSIS@{ub}
	ECloseEngine(EEngine)
	             A0

	VOID ECloseEngine(struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} *);

@{b}    FUNCTION@{ub}
	This function is similar to @{"bullet.library/CloseEngine()" Link "bullet/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()" Link "EOpenEngine()"}.
	It first releases any data acquired with @{"EObtainInfoA()" Link "EObtainInfoA()"} associated
	with the engine handle that has not yet been released.

@{b}    INPUTS@{ub}
	EEngine - the handle acquired via @{"EOpenEngine()" Link "EOpenEngine()"}. If @{"NULL" Link "rexxsupport/NULL"} or
	          EEngine->ege_GlyphEngine is @{"NULL" Link "rexxsupport/NULL"}, no operation is
	          performed.

@{b}    RESULT@{ub}
	EEngine->ege_GlyphEngine is set to @{"NULL" Link "rexxsupport/NULL"}. The only error that
	can occur is when an invalid engine handle is supplied: the
	application is assumed not to do that.

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

@{b}    SEE ALSO@{ub}
	@{"bullet.library/CloseEngine()" Link "bullet/CloseEngine()"}, @{"EOpenEngine()" Link "EOpenEngine()"}, @{"CloseOutlineFont()" Link "CloseOutlineFont()"}

@EndNode

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

@{b}    NAME@{ub}
	EObtainInfoA -- Inquire tagged font and/or glyph metrics. (V47)
	EObtainInfo -- varargs form of EObtainInfoA.

@{b}    SYNOPSIS@{ub}
	error = EObtainInfoA(EEngine, tagList)
	D0                   A0       A1

	ULONG EObtainInfoA(struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} *, struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *);

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

	ULONG EObtainInfo(struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} *, @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ...);

@{b}    FUNCTION@{ub}
	This function is similar to @{"bullet.library/ObtainInfoA()" Link "bullet/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" Link "INCLUDE:utility/tagitem.h/Main" 28} 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()" Link "EReleaseInfoA()"} to allow the library to release
	the data.

@{b}    INPUTS@{ub}
	EEngine - the glyph engine acquired via @{"EOpenEngine()" Link "EOpenEngine()"} or
	          @{"OpenOutlineFont()" Link "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.

@{b}    RESULT@{ub}
	This function returns a zero success indication, or a non-zero
	error code.

@{b}    WARNING@{ub}
	The function may return with a non-zero error code before it has
	parsed the whole tag list. The function may not set the pointers
	you passed in to @{"NULL" Link "rexxsupport/NULL"} when an error occured. Be careful to ensure
	that either the pointers you pass in are set to @{"NULL" Link "rexxsupport/NULL"} or that
	you only call @{"EReleaseInfoA()" Link "EReleaseInfoA()"} if EObtainInfoA() returned no error
	code and the EObtainInfoA() tag list did contain only one pointer.

@{b}    EXAMPLE@{ub}
	struct @{"GlyphMap" Link "INCLUDE:diskfont/glyph.h/Main" 29} *glyph;
	...
	if (!(error = EObtainInfo(EEngine, OT_GlyphMap, &glyph, TAG_END)))
	{
	    ...
	    EReleaseInfo(EEngine, OT_GlyphMap, glyph, TAG_END);
	}

@{b}    SEE ALSO@{ub}
	@{"bullet.library/ObtainInfoA()" Link "bullet/ObtainInfoA()"}, @{"EReleaseInfoA()" Link "EReleaseInfoA()"}, @{"diskfont/diskfonttag.h" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0},
	@{"diskfont/oterrors.h" Link "INCLUDE:diskfont/oterrors.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
	EOpenEngine -- Acquire engine handle. (V47)

@{b}    SYNOPSIS@{ub}
	success = EOpenEngine(EEngine)
	D0                    A0

	@{"LONG" Link "INCLUDE:exec/types.h/Main" 112} EOpenEngine(struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} *)

@{b}    FUNCTION@{ub}
	This function is similar to @{"bullet.library/OpenEngine()" Link "bullet/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()" Link "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.

@{b}    INPUTS@{ub}
	EEngine - pointer to a struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} that does contain
	          a pointer to the library base of the font engine
	          acquired via @{"OpenLibrary()" Link "exec/OpenLibrary()"} in EEngine->ege_BulletBase.

@{b}    RESULT@{ub}
	If TRUE, EEngine->ege_GlyphEngine contains a pointer to a
	struct @{"GlyphEngine" Link "INCLUDE:diskfont/glyph.h/Main" 21}, if FALSE, EEngine->ege_GlyphEngine is @{"NULL" Link "rexxsupport/NULL"}.

@{b}    EXAMPLE@{ub}
	struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} 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);

@{b}    SEE ALSO@{ub}
	@{"bullet.library/OpenEngine()" Link "bullet/OpenEngine()"}, @{"ECloseEngine()" Link "ECloseEngine()"}, @{"OpenOutlineFont()" Link "OpenOutlineFont()"}

@EndNode

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

@{b}    NAME@{ub}
	EReleaseInfoA -- Release data obtained with @{"EObtainInfoA" Link "diskfont/EObtainInfoA()"}. (V47)
	EReleaseInfo -- varargs form of EReleaseInfoA.

@{b}    SYNOPSIS@{ub}
	error = EReleaseInfoA(EEngine, tagList)
	D0                    A0       A1

	ULONG EReleaseInfoA(struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} *, struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *);

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

	ULONG EReleaseInfo(struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} *, @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ...);

@{b}    FUNCTION@{ub}
	This function is similar to @{"bullet.library/ReleaseInfoA()" Link "bullet/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()" Link "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()" Link "EObtainInfoA()"} call.

@{b}    INPUTS@{ub}
	EEngine - the glyph engine acquired via @{"EOpenEngine()" Link "EOpenEngine()"} or
	          @{"OpenOutlineFont()" Link "OpenOutlineFont()"}.
	tagList - a tag list containing OT_ tags valid for inquiry
	          paired with the data previously acquired for them
	          with @{"EObtainInfoA" Link "diskfont/EObtainInfoA()"}. @{"NULL" Link "rexxsupport/NULL"} pointers are quietly
	          accepted and ignored for indirect data.

@{b}    RESULT@{ub}
	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.

@{b}    EXAMPLE@{ub}
	struct @{"GlyphMap" Link "INCLUDE:diskfont/glyph.h/Main" 29} *glyph;
	...
	if (!(error = EObtainInfo(EEngine, OT_GlyphMap, &glyph, TAG_END)))
	{
	    ...
	    EReleaseInfo(EEngine, OT_GlyphMap, glyph, TAG_END);
	}

@{b}    SEE ALSO@{ub}
	@{"bullet.library/ReleaseInfoA()" Link "bullet/ReleaseInfoA()"}, @{"EObtainInfoA()" Link "EObtainInfoA()"}, @{"diskfont/diskfonttag.h" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0},
	@{"diskfont/oterrors.h" Link "INCLUDE:diskfont/oterrors.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
	ESetInfoA -- Set font and/or glyph metrics. (V47)
	ESetInfo -- varargs form of ESetInfoA.

@{b}    SYNOPSIS@{ub}
	error = ESetInfoA(EEngine, tagList)
	D0                A0       A1

	ULONG ESetInfoA(struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} *, struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} *);

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

	ULONG ESetInfo(struct @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126} *, @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ...);

@{b}    FUNCTION@{ub}
	This function is similar to @{"bullet.library/SetInfoA()" Link "bullet/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.

@{b}    INPUTS@{ub}
	EEngine - the glyph engine acquired via @{"EOpenEngine()" Link "EOpenEngine()"} or
	          @{"OpenOutlineFont()" Link "OpenOutlineFont()"}.
	tagList - a tag list containing OT_ tags valid for
	          specification paired with the specification data.

@{b}    RESULT@{ub}
	This function returns a zero success indication, or a non-zero
	error code.

@{b}    NOTES@{ub}
	The function may return with a non-zero error code before it has
	parsed the whole tag list.

@{b}    EXAMPLE@{ub}
	// 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);
	    }
	}

@{b}    SEE ALSO@{ub}
	@{"bullet.library/SetInfoA()" Link "bullet/SetInfoA()"}, @{"diskfont/diskfonttag.h" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0}, @{"diskfont/oterrors.h" Link "INCLUDE:diskfont/oterrors.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
       GetDiskFontCtrl -- Inquire diskfont global settings. (V45)

@{b}   SYNOPSIS@{ub}
       value = GetDiskFontCtrl( tagid );
                                 D0

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} GetDiskFontCtrl( @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} tagitem );


@{b}   FUNCTION@{ub}
       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" Link "INCLUDE:diskfont/diskfont.h/Main" 110} sorting values.
       The @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} passed in identifies the type of data item
       to read.

@{b}   INPUTS@{ub}
       tagid - a tag ID as documented in @{"diskfont/diskfonttag.h" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0}
               that identifies the kind of data item to inquiry.

               The following tag values are currently supported:
               (see @{"diskfont/diskfonttag.h)" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0}

               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" Link "INCLUDE:diskfont/diskfont.h/Main" 110} cache enable (BOOL)

               DFCTRL_SORTMODE @{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} font sorting (LONG)

               currently defined sort orders are:

                       DFCTRL_SORT_OFF don't sort
                       DFCTRL_SORT_ASC localized ascending
                       DFCTRL_SORT_DES localized descending

@{b}   RESULTS@{ub}
       value  - The current diskfont default setting for the
                selected tag item.
                The result code is undocumented if an unknown
                tag value is passed in.

@{b}   EXAMPLE@{ub}

       @{"BOOL" Link "INCLUDE:exec/types.h/Main" 168} cache;

       cache = GetDiskFontCtrl(DFCTRL_CACHE);

       \* read the current cache enable flag. *\


@{b}   NOTES@{ub}
       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.

@{b}   BUGS@{ub}

@{b}   SEE ALSO@{ub}
       @{"diskfont/diskfonttag.h" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
	NewFontContents -- Create a @{"FontContents" Link "INCLUDE:diskfont/diskfont.h/Main" 29} image for a font. (V34)

@{b}   SYNOPSIS@{ub}
	fontContentsHeader = NewFontContents(fontsLock,fontName)
       D0                                   A0        A1

	struct @{"FontContentsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 55} *NewFontContents( @{"BPTR" Link "INCLUDE:dos/dos.h/Main" 131}, char * );

@{b}   FUNCTION@{ub}
	This function creates a new array of @{"FontContents" Link "INCLUDE:diskfont/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.

@{b}   INPUTS@{ub}
	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.

@{b}   RESULT@{ub}
	fontContentsHeader - a struct @{"FontContentsHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 55} pointer.

@{b}   EXCEPTIONS@{ub}
	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.

@{b}   SEE ALSO@{ub}
	@{"DisposeFontContents" Link "diskfont/DisposeFontContents()"} to free the structure acquired here.

@EndNode

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

@{b}   NAME@{ub}
	NewScaledDiskFont -- Create a DiskFont scaled from another. (V36)

@{b}   SYNOPSIS@{ub}
	header = NewScaledDiskFont(srcFont, destTextAttr)
	D0                         A0       A1

	struct @{"DiskFontHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 65} *NewScaledDiskFont( struct @{"TextFont" Link "INCLUDE:graphics/text.h/Main" 87} *,
		struct @{"TTextAttr" Link "INCLUDE:graphics/text.h/Main" 70} * );

@{b}   INPUTS@{ub}
	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 "INCLUDE:graphics/text.h/Main" 63} or
	    @{"TTextAttr" Link "INCLUDE:graphics/text.h/Main" 70}.

@{b}   RESULT@{ub}
	header - a pointer to a @{"DiskFontHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 65} structure.  This is not
		being managed by the diskfont.library, however.

@{b}   NOTES@{ub}
	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 "INCLUDE:graphics/text.h/Main" 87} structure, and segment pointer are contained
	    within the @{"DiskFontHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 65} struct.  The @{"DiskFontHeader" Link "INCLUDE:diskfont/diskfont.h/Main" 65} 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"

@{b}   NAME@{ub}
       OpenDiskFont -- Load and get a pointer to a disk font.

@{b}   SYNOPSIS@{ub}
       font = OpenDiskFont(textAttr)
       D0                  A0

@{b}   FUNCTION@{ub}
       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.

@{b}   INPUTS@{ub}
       textAttr - a @{"TextAttr" Link "INCLUDE:graphics/text.h/Main" 63} structure that describes the text font
               attributes desired.

@{b}   RESULTS@{ub}
       D0 is zero if the desired font cannot be found.

@{b}   NOTES@{ub}
       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 "INCLUDE:graphics/text.h/Main" 63}, or @{"TTextAttr" Link "INCLUDE:graphics/text.h/Main" 70} 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."

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

@EndNode

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

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

@{b}   SYNOPSIS@{ub}
	outlinefont = OpenOutlineFont(fileName, list, flags)
	D0                            A0        A1    D0

	struct @{"OutlineFont" Link "INCLUDE:diskfont/diskfont.h/Main" 137} *OpenOutlineFont(STRPTR fileName,
					    struct @{"List" Link "INCLUDE:exec/lists.h/Main" 19} *list, ULONG flags);

@{b}   FUNCTION@{ub}
	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" Link "INCLUDE:diskfont/diskfont.h/Main" 137}.
	It is important to match this call with a corresponding
	@{"CloseOutlineFont()" Link "CloseOutlineFont()"} call for effective management of memory.

@{b}   INPUTS@{ub}
	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" Link "INCLUDE:exec/lists.h/Main" 19} that has to be initialized with @{"NewList()" Link "amiga_lib/NewList()"} before
		   the first call of OpenOutlineFont() and has to be used
		   for every subsequent call of OpenOutlineFont() and
		   @{"CloseOutlineFont()" Link "CloseOutlineFont()"}, or @{"NULL" Link "rexxsupport/NULL"}. If not @{"NULL" Link "rexxsupport/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()" Link "CloseOutlineFont()"} or always use @{"NULL" Link "rexxsupport/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.

@{b}   RESULTS@{ub}
	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" Link "INCLUDE:diskfont/diskfont.h/Main" 137}.

@{b}   NOTES@{ub}
	If you did not set OFF_OPEN and want to open the font later:
	open the font engine library via @{"OpenLibrary()" Link "exec/OpenLibrary()"} and store it in
	olf_EEngine.ege_BulletBase, if successful call @{"EOpenEngine()" Link "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()" Link "exec/CloseLibrary()"}) and
	you _must_ set all olf_EEngine members back to @{"NULL" Link "rexxsupport/NULL"} before
	calling @{"CloseOutlineFont()" Link "CloseOutlineFont()"}. Or just use your own @{"EGlyphEngine" Link "INCLUDE:diskfont/diskfont.h/Main" 126}
	structure instead.

@{b}   EXAMPLE@{ub}
	struct @{"OutlineFont" Link "INCLUDE:diskfont/diskfont.h/Main" 137} *outlineFont;

	if (outlineFont = OpenOutlineFont("Helvetica", @{"NULL" Link "rexxsupport/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);
	}

@{b}   SEE ALSO@{ub}
	@{"CloseOutlineFont()" Link "CloseOutlineFont()"}, @{"CloseOutlineFont()" Link "CloseOutlineFont()"}, @{"ESetInfoA()" Link "ESetInfoA()"},
	@{"EObtainInfoA()" Link "EObtainInfoA()"}, @{"EReleaseInfoA()" Link "EReleaseInfoA()"}, @{"diskfont/diskfont.h" Link "INCLUDE:diskfont/diskfont.h/Main" 0},
	@{"diskfont/diskfonttag.h" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0}, @{"diskfont/oterrors.h" Link "INCLUDE:diskfont/oterrors.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
       SetDiskFontCtrlA -- Adjust disk font global settings. (V45)
       SetDiskFontCtrl -- varargs form of SetDiskFontCtrlA.

@{b}   SYNOPSIS@{ub}
       SetDiskFontCtrlA( tags );
                          A0

       void SetDiskFontCtrlA( struct @{"TagItem" Link "INCLUDE:utility/tagitem.h/Main" 30} * );

       void SetDiskFontCtrl( @{"Tag" Link "INCLUDE:utility/tagitem.h/Main" 28}, ... );


@{b}   FUNCTION@{ub}
       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" Link "INCLUDE:diskfont/diskfont.h/Main" 110} font sorting order.

@{b}   INPUTS@{ub}
       tags -  a tag list defining the global settings that are
               to be adjusted.

               The following tag values are currently supported:
               (see @{"diskfont/diskfonttag.h)" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0}

               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" Link "INCLUDE:diskfont/diskfont.h/Main" 110} cache enable (BOOL)

               DFCTRL_SORTMODE @{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} 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" Link "dos/Flush()"} the cache?      (BOOL)

                       If TRUE, a cache flush is initiated.

@{b}   RESULTS@{ub}


@{b}   EXAMPLE@{ub}

       SetDiskFontCtrl(DFCTRL_CACHE,TRUE,TAG_DONE);

       \* enable the @{"AvailFonts" Link "INCLUDE:diskfont/diskfont.h/Main" 110} cache. *\


@{b}   NOTES@{ub}
       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()" Link "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.

@{b}   WARNING@{ub}
	Prior to V46, setting DFCTRL_XDOTP and/or DFCTRL_YDOTP to
	something else than the default (100) may result in the fact
	that diskfont.library is no longer able to create bitmap fonts
	from outline fonts since some font engines dont support
	an OT_DotSize different from the default and return an error.
	Since V46, the font generator now retries with OT_DotSize
	of 100% if the first try failed.

@{b}   BUGS@{ub}

@{b}   SEE ALSO@{ub}
       @{"diskfont/diskfonttag.h" Link "INCLUDE:diskfont/diskfonttag.h/Main" 0}, @{"utility/tagitem.h" Link "INCLUDE:utility/tagitem.h/Main" 0}

@EndNode