How‐to

This page describes how to integrate gb-vwf into your project.

Download

First, download vwf.asm. For the font encoder, you can either:

• Download a pre-built binary from the releases page.
• Or build it yourself by installing Rust and running cargo build --release in the font_encoder directory,

Configuration

gb-vwf needs a lot of information unique to each setup it's used in, such as font information, and possibly some customisations. Thus, gb-vwf expects that you provide it a path to a configuration file, in the VWF_CFG_FILE variable. (This path will be passed to INCLUDE, and thus subject to -I processing.)

• -DVWF_CFG_FILE=path/to/file.inc: This is more useful if compiling vwf.asm stand-alone.
• def VWF_CFG_FILE equs "path/to/file.inc": This is more useful before a INCLUDE "vwf.asm", if you're using that.

The contents of the configuration file are described in their own page.

Usage

After hooking gb-vwf to your build system (you may want to take a look at the Charmap page), here are the three parts to using gb-vwf.

Global initialisation

The following should be performed just once, when the game starts. If you forget to, your emulator should throw “reading uninitialised RAM” errors at you.

• wNbPixelsDrawn should be set to 0.

Setting up printing of a new string

The function of interest is SetupVWFEngine. This function wants the full pointer to the string (ROM bank in b, address in hl), and a “continue previous string” flag in a.

• If the “continue” flag is non-zero, basically every variable, including some internal ones, must have been initialised before the call to SetupVWFEngine.
• If the “continue” flag is zero, the auto-linewrapper will assume that a new line is being started from the left edge of the textbox.

If you want to print to a different area of the tilemap than previously, you should set all sub-labels of wTextbox as well as wPrinterHeadPtr before calling SetupVWFEngine. Note that SetupVWFEngine intentionally does not set wPrinterHeadPtr to wTextbox.origin, to allow printing e.g. in the middle of the textbox.

If you want to print to a different tile range than previously, you should set wCurTileID, wCurTileID.min, and wCurTileID.max either after calling SetupVWFEngine, or also set wNbPixelsDrawn to 0.

Other variables can be set whenever you want.

Printing one character

In a loop:

• call TickVWFEngine,
• then call PrintVWFChars.

You can call PrintVWFChars however long after TickVWFEngine as you want; TickVWFEngine does not touch VRAM whatsoever.

Warning

Make sure to call PrintVWFChars at least once after calling TickVWFEngine! The latter sets some "message" flags for the former, and they may be lost if TickVWFEngine is called twice in a row without PrintVWFChars!

The inverse (call TickVWFEngine :: call PrintVWFChars :: call PrintVWFChars), however, is completely fine.

You can repeat that loop as long as wSourceStack.len is not equal to 0. If it is, then the engine has finished printing the string. Do not call TickVWFEngine if wSourceStack.len is zero, except if the TEXTF_WAITING flag is set in wFlags.