APTR handle = LoadFont(STRPTR name, int size, struct hwLoadFontCtrl *lf,
                  struct hwTagList *tags);

LoadFont() is also passed a pointer to a struct hwLoadFontCtrl in the third parameter. This structure is used to pass some additional arguments to your plugin and your plugin can also pass some information back to Hollywood using this structure pointer. struct hwLoadFontCtrl looks like this:

struct hwLoadFontCtrl { STRPTR Name; [out] STRPTR Adapter; [in] ULONG *Palette; [out] ULONG TransPen; [out] ULONG Flags; [in/out] int Depth; [out] int Height; [out] int Baseline; [out] struct hwUserTagList *UserTags; [in] };

Here's an explanation of the individual structure members:

Name:

This can be set to a string that contains the name of the font. The string pointer must remain valid until FreeFont() is called.

Adapter:

Users can specify the file adapter that should be used to open certain files. If this member is non-NULL, Hollywood wants your plugin to use the file adapter specified in Adapter to open the file. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to open the file. See hw_FOpenExt for details.

Palette:

If the font is a palette-based color font, you need to set this member to a pointer to a palette, stored as a ULONG array of 256 RGB colors. Note that the ULONG array must always have 256 entries, even if the font's bit depth is less than 8. Initialize unused palette entries to 0.

TransPen:

If the font is a palette-based color font and uses a transparent pen, set this structure member to the index of the pen that should appear transparent. Pen indices start from 0. By default, pen 0 will appear transparent. If you want to have no transparency, set this member to HWPEN_NONE.

Flags:

This field contains a combination of bit flags. Some can be set by Hollywood before it calls LoadFont() and some flags can be set by your plugin to pass information back to Hollywood. The following flags are currently defined:

HWFONTFLAGS_VECTOR:

Set this flag if the font you have opened is a vector font. This means that you must implement SetFontScale() so that it applies a scaling factor when Hollywood asks for it. If you also set HWFONTFLAGS_LAYOUT (see below), you don't have to implement SetFontScale() but in that case your RenderText() implementation must be able to apply a 2D transformation matrix to the text before drawing.

HWFONTFLAGS_USEPOINTS:

Hollywood will set this flag if the size passed to LoadFont() is in points instead of pixels. Your implementation must look for this flag and act accordingly.

HWFONTFLAGS_ANTIALIAS:

Set this flag if the font supports anti-aliasing.

HWFONTFLAGS_NOFILE:

Set this flag if the font passed to your LoadFont() implementation in the name parameter isn't a file. This is important to know for Hollywood's linker. If HWFONTFLAGS_NOFILE isn't set, the linker will try to link the font when compiling applets or executables. This must be prevented for fonts that do not directly exist as files. E.g. if your LoadFont() function is passed "Arial" in name and you don't set HWFONTFLAGS_NOFILE, Hollywood's linker will try to link a file named "Arial" which will of course fail.

HWFONTFLAGS_LAYOUT:

Set this flag if your plugin wants to take over font layouting completely. By default, Hollywood's font layouter is used which means that Hollywood will take care of handling word-wrapping, kerning, justification, alignment, text formatting codes and so on. This means that your plugin just needs to deliver the glyph extents and bitmaps and Hollywood will do the rest. If your plugin wants to its own layouting, though, you can set the HWFONTFLAGS_LAYOUT flag. In that case, Hollywood's layouter won't be used at all for this font but your plugin can do its own layouting.

Depth:

This member must be set to the color depth of the font. Set this to 1 for monochrome fonts, to 8 for fonts that support anti-aliasing (i.e. 256 levels of gray) or to 32 for color fonts with alpha transparency. If the Palette member is set as well (see above), Depth must be a value between 1 and 8. Note that if you set this to 8 with Palette set to NULL to indicate that the font supports anti-aliasing your RenderText() implementation must also be able to draw to a 1-bit monochrome target. In other words: Fonts that support anti-aliasing must also support non-anti-aliased drawing.

Height:

Set this to the font height in pixels.

Baseline:

Set this to the baseline of the font. Hollywood needs to know the font's baseline to correctly position font styles like underlining etc.

UserTags:

This member will be set to a list of user tags in case they were specified in the Hollywood script. User tags are a way of passing additional information from Hollywood scripts to plugin functions. Note that even if your plugin doesn't support any user tags, you should still look for this tag and pass the user tags to hw_FOpenExt because the user tags passed in UserTags could also be intended for another plugin, namely the file adapter plugin passed in Adapter. See User tags for details.

Please note that you should not use ANSI C functions like fopen() to open the file that is passed to this function because the filename that is passed to this function can also be a specially formatted filename specification that Hollywood uses to load files that have been linked to applets or executables. In order to be able to load these files correctly, you have to use special IO functions provided by Hollywood. See File IO information for details.

name

name of the font to open; this isn't necessarily a file

size

desired font size

lf

pointer to a struct LoadFontCtrl that is used to exchange further information

tags

tag list containing further options or NULL

handle

a handle that identifies this font or NULL if the plugin doesn't want to handle this font