ZapRedraw

Pixel co-ordinates

Pixel co-ordinates are used wherever possible to prevent rounding errors when OS co-ordinates are not pixel aligned (these errors do mess things up).

Pixel co-ordinates are from the top left of the screen with the y axis descending. By a 'pixel' I mean a hardware pixel (this differs from an OS pixel in double-pixel emulation modes - this only crops up in the RISC OS 2 MODE 2 wimp!).

Zap redraw block

For several SWIs, R1 points to a redraw block of the type described below. The SWI documentation will mention which data in the block is actually used by that SWI (so should be filled in). Each offset in the block is named with a name beginning 'r_'. The BASIC program E-Library inside !ZapFonts contains a procedure to set these variables up should you be using the BASIC assembler. The contents of some offsets depends on which redraw mode is being used (VDU or DSA), this is indicated by 'VDU:' and 'DSA:'.

Character cache format (r_caddr)

When using VDU redraw, this should point to the name of the font to use, or be zero for the system font.

When using direct screen access, the module will expect this block to contain the bitmaps for all the characters it is asked to print. Each character has size r_cbpc so it will expect to find the bitmap for ASCII character 'n' at address char_start = (!r_caddr) + n × r_cbpc. The character definition then consists of r_charh rows of r_cbpl each so r_cbpc = r_charh × r_cbpl. NB r_cbpl need not be a multiple of 4 so this address need not be word aligned.

The format of a row is the same as that for a sprite file except there is never any left hand side wastage. Ie, the first pixel is aligned to the start of the first word. Each character is r_charw pixels wide and thus requires N = r_charw << r_bpp bits of storage. There are special cases when N is small:

• If 0 < N <= 8 then r_cbpl = 1 and the top 8-N bits of the byte are wasted.

• If 8 < N <= 16 then r_cbpl = 2 and the top 16-N bits of the row are wasted.

• If N > 16 then r_cbpl is aligned to the next multiple of 4 bytes greater or equal to N. (eg if 16 < N <= 32 then r_cbpl = 4, and if 32 < N <= 64 then r_cbpl = 8, etc).

The SWI SWI ZapRedraw_CachedCharSize will calculate the values of r_cbpl and r_cbpc for you from a given size of character.

Only TWO colours can be used in the definition of the character. Set all foreground pixels to 1's and background pixels to 0's. Eg, in a 16 colour mode pixels will be either 1111 or 0000. Unused bits at the end of the words (or bytes) are ignored and so can contain rubbish. The real foreground and background colours are masked in at run time.

Examples:

For 8 × 8 characters at 1 bit per pixel we have 1 byte per row. Eg "E" may be cached as:

If it was in a 16 colour mode then there would be one word per row and the first rows would be:

In general you have:

Word 0 Word (N/4)-1

b0 .... b31 ................... b0 ..... b31

pix0 pix1 ......................pix(r_charw-1) 00000

In practice you first cache the font at one bit per pixel (eg use SWI ZapRedraw_ReadSystemChars) and then convert it to 'n' bits per pixel (for the current mode) by use of SWI ZapRedraw_ConvertBitmap.

Although I have said that the foreground colour must be all 1's and the background all 0's this is not strictly true. The data poked into the screen memory is (foreground mask AND bitmap) OR (background mask BIC bitmap). Thus if you have a foreground mask of &FFFFFFFF and a background mask of 0 then the bitmap will be poked directly into the screen so can have any format you like (though character merging and several other features may not work properly). This idea can be used in conjunction with SWI ZapRedraw_CacheFontChars to create a fast redraw mode for anti aliased fonts (as used in Zap).

Format of text to display (r_data)

This block contains the text to be printed on the screen. There should be sufficient text here to redraw the specified area of the screen (given its size, the scroll offset, character sizes etc). Terminating each line with the bytes 0,2 will ensure the redraw doesn't run out of text horizontally and terminating the line list with a zero will ensure the same vertically. The value in r_data points to a list of words. The n'th word in the list is the offset (from the block data start) of the n'th line of text to be printed in the window. This list can be terminated by a 0 offset in which case all further lines will be cleared to background colour (r_bac).

The data for each line consists of a string of bytes giving the characters to print. By character number 'n' is meant the n'th (n starting from 0) bitmap in your character cache in DSA mode, or the character with code 'n' in VDU redraw mode.

The byte 0 in the data for a line introduces a control code. Bytes 1-255 just print characters n = 1-255 as normal, within the current chunk of 256 characters. The chunk is chunk 0 (characters 0-255) at the start of each line, and is changed by the control codes 0,11 and 0,12, so that characters above 255 may be reached. When the chunk is C then the byte b prints character C + b (C is always a multiple of 256, so characters from 0 to &FFFFFF may be reached). For a character cache which you supply, there is only chunk 0 and the control code 0,3 may be used to reach the characters above 255. Characters which are not defined are drawn using the null glyph. The characters 0-31 and the character &7F are not normally letters; Zap treats these specially - see below.

The currently defined control sequences are:

Where a control code takes a sub-style S, it is a sub-style. In DSA mode with a font handle, ZapRedraw changes the sub-style for you; the change is also reported to the extension routine, if there is one. With a character cache you supply, sub-style changes can only be performed by an extension routine.

Note that sequences with codes 0, 3, 4 and 8 evaluate to one 'screen printable character', codes 1, 6, 7, 9, 10, 11 and 12 to none, and code 2 to as many as is required. Thus it is not a simple matter to calculate the start of the n'th actual printable character given a string containing control codes as above. The SWI SWI ZapRedraw_FindCharacter does this for you.

In DSA mode with a character cache you supply, character 'n' just looks up the cached character at address r_caddr + n × r_cbpc. Usually the bitmaps will correspond to the VDU list below so that character &20 will be the bitmap for a space etc. If r_caddr is a font handle then ZapRedraw looks up the character in the font, and uses the font's null glyph for characters which the font does not define. The cursor characters &100-&105 (used by the 0,8 control code) are always available in a font handle, and ZapRedraw generates the control characters 0-&1F and the null glyph if the font does not contain them.

In VDU mode character 'n' is the character code (a Unicode character if the Font Manager supports UTF-8, as it does for Font Manager 3.40 and later, and for the system font in modes where the characters can be defined) and is interpreted as below:

The characters are drawn using SWI OS_WriteN / SWI OS_WriteC / SWI OS_Plot (or SWI Font_Paint if not using the system font).

Use SWI ZapRedraw_FindCharacter to jump over the control codes. Use SWI ZapRedraw_PrepareDataLine to automatically generate the r_data lines from normal text with foreground and background colour masks. Use SWI ZapRedraw_AddVduBitmaps to create the bitmaps for character codes 0-&1F,&7F and >= &100.

ZapRedraw supports sixteen sub-styles, in both VDU and DSA redraw modes, using the same convention in both. The sub-style number is a byte S in which bit 0 means strikethrough, bit 5 bold, bit 6 italic and bit 7 underlined. The sub-style at the start of the line is the bottom 8 bits of r_caddr when it is a font handle, and the control codes 0,9 and 0,10 change it during the line. See Sub-styles for how each mode renders them.

Sub-styles

A sub-style is a variation of the base font. The sub-style number S is a byte in which:

The other bits are ignored when selecting a font (except that, in DSA mode, bit 4 has the same effect as bit 0). SWI ZapRedraw_PrepareDataLine uses bit 3 of the sub-style list to mean inverse video, and swaps the foreground and background colours while it is set.

In DSA mode each sub-style has its own bitmaps. ZapRedraw looks for a file in the font directory whose name is made up of the letters of the sub-style (see the description of font files); if the exact combination is not present, it falls back to the nearest combination which is, and finally the base font.

In VDU mode the font is a Font Manager font. If r_flags bit 3 is set, ZapRedraw looks for the variants of the font named by appending .Bold, .Oblique (or .Italic), and .Bold.Oblique (or .Bold.Italic) to the font name; where the font name already ends in a style, the final component is replaced. The bold and italic bits (5 and 6) select between the four fonts found. Strikethrough and underline are drawn as lines by ZapRedraw. Rendering of the variants has some technical difficulties, because they tend to have different bounding boxes from the default font at the same point size and aspect ratio; no attempt is made to compensate for this.

Format of palette data (r_palette)

All colours are specified as offsets in the palette table. Thus if you set r_for to 1 then the module will look up the word at offset 4*1 in the palette table when it comes to printing a character.

Font handles

Font handles are a concept introduced in ZapRedraw 0.40. They make the process of loading and caching fonts much easier, and they also allow transparent access to font sub-styles in DSA mode in the same manner as in VDU mode. To initialise your font, pass the font name (eg 08x16.System) to SWI ZapRedraw_FindFont, and place the returned font handle in r_caddr. To find the size of the font, the call SWI ZapRedraw_ReadCharSize is provided. When you have finished with the font, you should call SWI ZapRedraw_LoseFont.

Font handles take the form &HHHHHHSS

HHHHHH is the font handle proper (a number from 1 to 32), and SS is the sub-style. Thus the lower 8 bits of r_caddr are the initial font sub-style to use at the start of the line. They have the same effect as r_for and r_bac. 0,9 and 0,10 control codes may be used to change sub-style during the line. Any value of r_caddr below &8000 is taken to be a font handle; larger values are the addresses of a character cache or font name which you provide.

When r_caddr is a font handle, ZapRedraw does the following for you:

• It loads the font on demand, converts the bitmaps to the number of bits per pixel in r_bpp, and converts them again when r_bpp changes, so you do not need to cache the characters yourself. In modes with 32 bits per pixel the 1 bit per pixel bitmaps are plotted directly.
• It sets r_charw, r_charh, r_cbpl and r_cbpc in the redraw block to match the font each time the block is used for DSA redraw. (In VDU mode the character size is that of the cell in which the font is plotted, and it is not stored in the block.)
• It provides its own workspace, if r_workarea is 0.
• It changes the sub-style for the control codes 0,9 and 0,10, and selects the chunk for the control codes 0,11 and 0,12. The characters above 255 which the font contains can therefore be drawn, and those it does not contain are drawn as the null glyph.
• If r_flags bit 5 is set, it chooses double height mode.

A font handle is counted: each call to SWI ZapRedraw_FindFont which finds an already loaded font adds a user to the handle, and each call to SWI ZapRedraw_LoseFont removes one. There are 32 handles available to all the applications which use ZapRedraw. The font data remains cached after it has no users, so that a font which is closed and then reopened is not reloaded, until the memory is needed for another font or until *ZapFontTidy is used.

A font handle allocated for VDU mode may be passed directly to SWI ZapRedraw_RedrawArea in DSA mode. This converts it to anti-aliased bitmaps on demand, exactly as Zap's aa-DSA mode does. The algorithm used is simple, but gives good results; it chooses an anti-aliased bitmap unless the colours of the text and its background are too similar for it to matter, when it uses a 1 bit per pixel bitmap instead, and it never uses anti-aliasing if r_flags bit 9 is set. Sub-styles are ignored.

The application should lose its handles when it has finished, before the module can be killed. ZapRedraw cannot be killed while any handle has users (see Service_ZapRedrawDying).

Fonts and the font path

The bitmap fonts which DSA redraw uses are found along the path variable ZapFontsSource$Path. This is a comma separated list of directories, which the application !ZapFonts sets to the directories Fonts and Encodings inside it. An application which uses ZapRedraw should use !ZapFonts rather than carry its own fonts, so that the fonts are shared; !ZapFonts also sets Zap$Redraw to the location of the ZapRedraw module, which an application's !Run file can use to load the module.

A font is a file within one of the directories (or within a subdirectory of them; the names use dots to separate the levels, and are not case sensitive), such as 08x16.System for the font in the file 08x16.System. A font directory is a directory whose name is used as the font name. The file named 0 within it is the base font, and the others are its sub-styles (see Font files). If the name of a font is the name of a directory and not of a file, then the base font in it is used, and its sub-styles. A link is a small text file which refers to another font; the names of fonts are the names of the links and the fonts. The names of fonts follow the convention <width>x<height>.<name>, such as 08x16.System, though this is not enforced by the module.

The names which ZapRedraw lists in menus (see SWI ZapRedraw_ListFonts) come from Messages files. In each directory on the path, ZapRedraw looks for the file Messagesn, where n is the number of the current territory (in decimal); if it is not there, the file Messages1 is used. This is a normal MessageTrans file in which each line

Font_identifier:name

describes one font, and each line

Encoding_identifier:name

describes one encoding. The identifier is the name by which the font or encoding is found on the path. As brackets cannot be used in the tokens, < and > are used in the identifier in their place and are converted to brackets when the identifier is read. The name is the text to show to the user in the territory; if it is empty, the identifier is used instead, and if it ends in * then that font is the default one for an ambiguous name (and the * is not part of the name). The lists are scanned when the module starts, and can be scanned again by *ZapFontInstall after the path has changed. They are sorted using the territory's collation.

Font files

Font files must be of type Data (&FFD) and link files of type Text (&FFF). There are two formats of font file: the original format, used for fonts of up to 256 glyphs, and the format which divides fonts of up to 4 billion glyphs into chunks.

The bitmaps of the glyphs are held at one bit per pixel in the format used for the character cache of a 2 colour mode: each row of a glyph is a whole number of bytes (1 byte if the glyph is up to 8 pixels wide, 2 if up to 16 pixels wide, and otherwise the next multiple of 4 bytes), the leftmost pixel is in the least significant bit, and the rows start at the top of the glyph. Pixels which are set are in the foreground colour.

The original format is:

Any glyphs above 255 in the file are ignored. If the font does not start at character 0 then the glyphs for the control characters 0-&1F are made from the letters (0 is the digit 0, and 1-&1F are copies of &41-&5F). The cursor glyphs for characters &7F and &100-&105 are always made by ZapRedraw, as is the null glyph, which is used for the characters the font does not define.

The chunked format is:

The chunk directory follows immediately. The glyphs are divided into chunks of up to 256 glyphs, and the directory has an entry of four words for each chunk:

The glyph data for a chunk consists of the bitmaps of the glyphs in order. If the chunk has fewer than 256 glyphs then the data starts with a translation table of 256 bytes: for each of the 256 characters of the chunk, the table gives the number of its glyph in the data plus 1, or 0 if it is not defined. The table is not present for a chunk with all 256 glyphs. Chunk 0 must be present and have all 256 glyphs, including the glyphs for the control characters; it should use the Acorn Extended Latin 1 encoding where possible. The null glyph is a bitmap of the same size as the others; if there is none then ZapRedraw uses a dotted box. ZapRedraw loads chunk 0 when it loads the font and the other chunks the first time that they are needed.

Where a font has sub-styles, it is a directory. The file 0 is the base font, and the files for the sub-styles have names made of the letters of the styles they are for, in the order U, S, I, B: B (bold), I (italic), S (strikethrough), U (underlined), or any combination such as IB or USIB. When ZapRedraw needs a sub-style it tries the file for exactly that combination of styles. If there is none, it takes away the styles in turn and tries again: first underline, then italic, then bold, then strikethrough; then pairs of styles; then it uses the single style files if they exist; and finally the base font. Fonts directly in the font directory are not given sub-styles.

A link file contains the bytes "ZFLK" followed by 10, and then the path of the font linked to, ending in a zero byte. A link cannot refer to another link. A link may be the file 0 of a font directory, which is the base font when the directory is chosen.

Encodings

An encoding translates the character codes of text into Unicode, so that text in any of the 8 bit character sets can be displayed using a font which holds Unicode characters. Encodings are found by name along ZapFontsSource$Path, and are handled with SWI ZapRedraw_Encoding. An encoding file is of type Data (&FFD) and has the format:

Two encodings are built in: UTF8 and UTF16, which are not tables and have no file. The supplied encodings are the ISO Latin character sets (Latin1 to Latin10), Arabic, Hebrew, Greek, Cyrillic, KOI8-R, Thai and Welsh.

Memory use, caching and mode changes

The font data and the converted bitmaps are held in a dynamic area named "Zap font cache" (the name is a message token, FontCache), which is created when the module starts, and which can be at most 2 megabytes. If the dynamic area cannot be created because the system does not support them (which is the case before RISC OS 3.5) then font handles cannot be used in DSA mode. The memory is returned when fonts with no users are tidied and the cache is compacted, either when a new font is needed or with *ZapFontTidy.

ZapRedraw watches for the mode change service call (Service_ModeChange, &46). On a mode change the sizes of the VDU fonts are read again for the new mode. The DSA fonts are converted again to the new number of bits per pixel the next time that they are used. Applications must read the screen details into the redraw block again with SWI ZapRedraw_ReadVduVars, and the number of bits per pixel for the cache with SWI ZapRedraw_ReadModeBPP, after a mode change.

VDU redraw mode

In VDU redraw mode ZapRedraw draws with the operating system rather than writing the screen memory. Each line is drawn in three passes: first the backgrounds, as rectangles of each background colour (using the fast rectangle plot of SWI ZapRedraw_PlotRectangle if r_flags bit 4 is set, and OS_Plot otherwise); then the characters, with Font_Paint for a font and OS_WriteC for the system font; and then any merged characters and cursors. The colours of the palette entries are translated to the nearest available colours with ColourTrans.

The system font is used when the font name is 0. The characters 0-&1F, &7F and &100-&105 are drawn as described in Format of text to display by ZapRedraw, since the operating system's meaning of these characters is not the one wanted. Characters above 255 are drawn with UTF-8 text if the Font Manager supports it (Font Manager 3.40 or later); the system font characters are defined temporarily with VDU 23 in the Unicode range of the operating system, via the international service call (&43), and restored afterwards.

ViewFinder

If the ViewFinder module (version 1.29 or later) is present and is in use (the system variable ViewFinder$Enable being set to a non-zero number, or ViewFinder 1.41 or later which is assumed to be active), ZapRedraw has ViewFinder draw the text and the rectangles, since ViewFinder modes cannot be written directly. This is automatic and needs nothing from the application, except that SWI ZapRedraw_RedrawRaster cannot be used, and SWI ZapRedraw_ReadModeBPP returns 0 so that 1 bit per pixel caches are used.

Using ZapRedraw

An application which draws text with ZapRedraw does this:

• When starting, check that the module is present (with RMEnsure) and issue the first call to SWI ZapRedraw_Version if the version matters. Find the font with SWI ZapRedraw_FindFont and keep the handle. Fill in the redraw block: r_flags, r_caddr (the handle), r_palette (made with SWI ZapRedraw_CreatePalette), r_for, r_bac and r_linesp, and read the character size with SWI ZapRedraw_ReadCharSize to size the windows.
• Call SWI ZapRedraw_ReadVduVars to fill in the screen details, and again after each mode change.
• Build the r_data for the visible lines, using SWI ZapRedraw_PrepareDataLine and SWI ZapRedraw_AddCursorSmart.
• On a redraw event, set r_scrollx and r_scrolly with SWI ZapRedraw_GetRectangle and call SWI ZapRedraw_RedrawArea for each rectangle, or use SWI ZapRedraw_RedrawWindow or SWI ZapRedraw_UpdateWindow to do the loop.
• When finishing, call SWI ZapRedraw_LoseFont for each font found.
• Be ready for Service_ZapRedrawStarted, after which any addresses obtained from SWI ZapRedraw_Version are no longer valid.

Debugging commands

Builds of ZapRedraw made for debugging also have the commands ZapFontDescribe (describes the font blocks, encodings and free memory of the cache), ZapFontDie (forgets all font handles without freeing their memory, so that the module can be killed) and ZapFontDebug (prints an internal variable), and profiling builds also have ZapFontProfile. These are only present in debugging builds of ZapRedraw, are subject to change, and should not be relied on.

R0=0 : Starting a raster line

R0=1 : Foreground and background colours changing

R0=2 : Reserved

R0=3 : Reserved

R0=4 : About to merge characters

NB Any changes you make to these registers will be effective for this one character only the normal values being stacked.

R0=5 : Reserved

R0=6 => Foreground colour changing

As for R0 = 1

R0=7 => Background colour changing

As for R0 = 1

R0=8 : About to merge cursors

Registers as for R0 = 4.

If R7 < &100 then R10 / R11 will be set to R9 / R8 and next char drawn.

If R7 >= &100 then the characters will be merged with R9 copied into R8.

R0=9 : Font change

Registers as for R0 = 1

R0=10 : Foreground colour, background colour and font change

Registers as for R0 = 1

Note that if you are not using a font handle then changing font during redraw must be done in an extension routine for DSA redraws. With a font handle, ZapRedraw has already changed to the new sub-style before the extension routine is called.

R0=11 : Chunk change

Registers as for R0 = 1, with R3 the address of the next character after the control code and R4 the address of the glyph data for the new chunk (0 if in line spacing, 1 if the chunk does not exist). Called after control code 0,11.

R0=12 : Large chunk change

As for R0 = 11. Called after control code 0,12.

R0>12 : Reserved