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:

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

Integration

TODO: config file and everything

Now that all of this is done, 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 (bank in b, address in hl), and a “continue” flag in a.

If the “continue” flag is set, basically every variable (including some internal ones) need to be initialised before the call to SetupVWFEngine.

If you want to print to a different area of the tilemap, you should set all sub-labels of wTextbox as well as wPrinterHeadPtr before calling SetupVWFEngine. Note that SetupVWFEngine intentionally does not copy 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 after calling SetupVWFEngine.

Other variables can be set whenever you want.

Printing one character

First, 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!

You can do the above 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.