Using Pangomonium's high-level interface is really easy. It extends standard Hollywood text
commands like SetFont() and TextOut() to support advanced text rendering features
like complex layouts and colored glyphs like emojis. To draw text using Pangomonium through
normal Hollywood commands, just make sure you open the font using Pangomonium by passing the
Loader tag to SetFont(). Once you have opened a font through Pangomonium, all Hollywood
commands that draw text will automatically do so through Pangomonium as well, e.g.:
@REQUIRE "pangomonium"
SetFont("Noto Sans CJK HK Regular", 72, {Loader = "pangomonium"})
SetFontStyle(#ANTIALIAS)
; "What is your name?" in Japanese
Local t = {21517, 21069, 12399, 12394, 12435, 12391, 12377, 12363}
For Local k = 0 To ListItems(t) - 1 Do text$ = text$ .. Chr(t[k])
TextOut(#CENTER, #CENTER, text$)
|
The code above will set the font to Noto Sans CJK HK Regular size 72 and draw some Japanese
text. By passing "pangomonium" to the Loader tag you tell SetFont() to open the font
through Pangomonium instead of through Hollywood's inbuilt font engine or through a font
engine provided by the host operating system.
Another advantage of using the high-level interface is the fact that Pangomonium supports true vector-based text transformation without any quality loss. Hollywood's inbuilt font engines only support lossless scaling of vector text. As soon as text is rotated, a lossy algorithm is used so drawing rotated text using Pangomonium will give you a better quality.
Furthermore, Pangomonium allows you to use Pango's markup language which can do some advanced
text formatting that Hollywood's inbuilt text engine can't do. For example, Pango's markup
language allows you to use different font sizes in a single text object. So if you need
more powerful formatting capabilities than supported by Hollywood's inbuilt text renderer,
you might also want to use Pangomonium instead. See playout:SetMarkup() for more
information on Pango's markup language. Also note that Pango's markup language isn't enabled
by default in Pangomonium for compatibility reasons. If you want to use it, you need enable
it explicitly by setting the Markup tag to True (see below).
Note that in the code above we explicitly tell SetFont() to use Pangomonium to open the font
by passing "pangomonium" in the Loader tag. Alternatively, you can also globally enable
Pangomonium for all Hollywood commands dealing with fonts by simply installing Pangomonium's
font adapter. This can be done by setting the InstallAdapter tag to True when @REQUIREing
Pangomonium, e.g. like this:
@REQUIRE "pangomonium", {InstallAdapter = True}
|
If you globally enable Pangomonium, you don't have to use the Loader tag with SetFont()
or other Hollywood commands that deal with fonts any longer because if Pangomonium is globally
enabled, commands like SetFont() will automatically ask Pangomonium for every font that is to be
opened whether or not the plugin would like to handle this font. Keep in mind, though, that
by default Pangomonium will never fail on font opening so if you globally activate it
like above, it will take over the handling of each and every font you open, which might not be
what you want. You can modify this behaviour by setting the NoFail user tag to False,
in which case Pangomonium will fail if a font is not available. If you want Pangomonium
to handle all fonts in your script, however, globally enabling it using InstallAdapter as
shown above can be a good idea.
When using Pangomonium you can also pass some additional arguments to SetFont(), OpenFont()
or the @FONT preprocessor by using Hollywood's user tags. The following additional arguments
are recognized by Pangomonium:
NoFailFalse. Defaults
to True.
MarkupTrue, Pangomonium will allow you to use the Pango markup language in
the text you pass to Hollywood calls like TextOut(). By default, Pangomonium only supports
Hollywood's text formatting codes. If you want it to use Pango's markup language instead of
Hollywood's text formatting codes, set this tag to True. See playout:SetMarkup() for
information on Pango's markup language. Defaults to False.
MonochromeTrue if you want Pangomonium to operate in monochrome mode. This will reduce
memory consumption by 75% because Pangomonium only needs to allocate one pixel channel instead
of four but you will only be able to use single-colored text in monochrome mode so things
like color emojis won't be drawn correctly. Defaults to False.
NoFT2True. In that case, Pangomonium will use the host operating
system's default text renderer instead (e.g. DirectWrite on Windows, Core Text on macOS etc.)
Note that on AmigaOS and compatibles the only available renderer is FreeType2 so you mustn't
set this tag to True on AmigaOS. Defaults to False.
Here's how you can pass user tags to Pangomonium:
@REQUIRE "pangomonium"
SetFont("Arial", 72, {Loader = "pangomonium", UserTags = {Markup = True}})
SetFontStyle(#ANTIALIAS)
TextOut(#CENTER, #CENTER, "<span bgcolor=\"red\">Hello</span>")
|
The code above demonstrates how to enable Pango's markup language in Pangomonium's high-level interface.