-
Notifications
You must be signed in to change notification settings - Fork 3
Variables
Only variables that are exported by default are documented here. They should be considered to form the engine's "public API" so to speak.
Other variables are documented in the engine internals.
How many pixel columns of the tile buffer have been drawn for now.
This must be set to 0 before the first call to SetupVWFEngine.
This is a collection of bits with various semantics. Please do not update bits that aren't documented here, as some of the other flags are used internally by gb-vwf.
To avoid having to use magic numbers to refer to the flags, two constants are exported for each flag: TEXTB_xxx contains the bit index of flag xxx (suitable for bit, set, and res), while TEXTF_xxx contains 1 << TEXTB_xxx (suitable for and, or, xor).
Tip
The bit indices of the flags can be relied upon not to change outside of major versions, but if relying on them (e.g. using add a, a to test for bit 7), it is advisable to assert TEXTB_xxx == 7 to ease upgrading to a future major version of gb-vwf.
Note that all flags are cleared when calling SetupVWFEngine with the “continue“ flag clear.
If this is set, TickVWFEngine will not do anything... just waiting.
This flag is meant to be reset by external code, such as when the user has pressed a button.
This flag is simply set by the SYNC control character, and does nothing nor is ever reset by the engine.
It is merely meant to signal to external code that the engine has reached a certain point, for synchronisation purposes—hence the name.
If set, glyphs will be written as colour #1 instead of the default #3. (In more technical terms: this controls whether the high bitplane is written to.)
This is controlled by the COLOR control character.
How many ticks between printing two characters; only reloaded by TickVWFEngine right before printing a character.
The value 0 is special, as it makes each call to TickVWFEngine try not to write a single character, but instead to write as much as possible (which is limited by how much info can be passed to PrintVWFChars at once).
The intended use case is to call the two functions in a loop as fast as possible until the string is done being printed, in order to print an entire string instanly (hence the name).
However, it is also possible to use this as a cheap way to print characters faster than 1 per frame: almost every call to TickVWFEngine with this parameter guarantees that a new tile is ready, so calling the two functions once per frame essentially translates to printing 1.5 to 2 characters per frame, depending on the font.
(Some fast readers find 1 character per frame to be fairly slow.)
How many entries deep the (sub-)string pointer stack currently is.
When this reads 0, the VWF engine has finished printing everything, and TickVWFEngine should not be called!
Note that this is updated by TickVWFEngine, but that PrintVWFChars should still be called once after it reaches 0; and that it's fine to call PrintVWFChars while this variable is equal to zero.
The ID of the tile (in VRAM) that is being written to.
The minimum value that wCurTileID should take.
The maximum value that wCurTileID should take, exclusive.
The logic is as follows: after incrementing wCurTileID (because a tile has just finished being written to), if it has become equal to .max, it's set to .min instead.
Pointer to the tilemap location where the current tile's ID is being written.
This should lie somewhere within the rectangle defined by wTextbox.
Important
If updating this mid-print, you probably should update wNbLinesRemaining and/or wNbLinesRead accordingly.
This defines the textbox's area: .origin contains a pointer to the top-left tilemap entry, and .width and .height specify the size, in tiles.
How many lines of the textbox haven't been fully written to yet.
Strictly speaking, this is a cache, as it could be computed as wTextbox.height - (wPrinterHeadPtr - wTextbox.origin) / 32... but that's expensive to calculate 😛
How many lines the user has already acknowledged by “waiting”.
TickVWFEngine decrements this every time a new line is printed, and sets the “waiting” flag when it reaches 0.
However, clearing the flag does not reload this value!
It it intended that whatever clears the flag also sets this to whatever is appropriate (usually wTextbox.height).