![\"\"](\"docs\/geowrite\/geowrite_2_scrrecovery.gif\")
<\/p>\nIn the series about the internals of the geoWrite WYSIWYG text editor for the C64, this article discusses how the app manages to extend its usable RAM by 5 KB using a custom screen recovery solution.<\/p>\n
<\/p>\n
Any graphical user interface that allows overlapping items has to deal with the problem of recovery: When dialogs and pull-down menus are shown, they cover parts of the screen, and when they are dismissed, the underlying UI needs to be revealed again.<\/p>\n
There are two basic approaches to this:<\/p>\n
When the dialog or menu is dismissed, the system calls the same text or image rendering code again that drew it in the first place.<\/p>\n<\/li>\n
Before the dialog or menu is drawn, the system saves the pixel data that will be overwritten, and after the item is dismissed, the saved pixels get written back onto the screen.<\/p>\n<\/li>\n<\/ol>\n
The latter solution requires additional memory, but is a lot faster and doesn’t create a potentially jarring redraw.<\/p>\n
GEOS uses the “restore the pixel data” approach, but with a twist.<\/p>\n
Let’s look at the GEOS memory layout again:<\/p>\n
-----------------------------------------\n$0000 Zero page, stack, system variables\n-----------------------------------------\n$0400\n\n\n\n\n Application memory\n\n\n\n\n\n-----------------------------------------\n$6000\n Background bitmap\n\n-----------------------------------------\n$8000 System buffers and variables\n-----------------------------------------\n$9000 Disk driver\n-----------------------------------------\n$A000\n Screen bitmap\n\n-----------------------------------------\n$C000 GEOS KERNAL\n\n\n-----------------------------------------\n<\/code><\/pre>\nThe 8 KB of 320×200 monochrome bitmap data resides at $A000-$BF40. In addition, GEOS statically reserves a whole 8 KB just for screen recovery: The “background bitmap” at $6000-$7F40 allows GEOS to recover the whole screen area.<\/p>\n
\u00a0Imprint and Recover<\/h3>\n
This background bitmap is really just another (invisible) framebuffer with the same layout as the actual screen bitmap. When saving pixels, they get copied from the screen (“foreground”) bitmap to the same offset in the background bitmap and vice versa.<\/p>\n
These two functions are the core of the API:<\/p>\n
\nImprintRectangle<\/code> \u2013\u00a0copy rectangle from fg bitmap to bg bitmap<\/li>\nRecoverRectangle<\/code> \u2013\u00a0copy rectangle from bg bitmap to fg bitmap<\/li>\n<\/ul>\nWhile applications are free to use the API this way, the system-suggested way is actually different.<\/p>\n
Display Buffering<\/h3>\n
When using the core GEOS API, it’s not actually necessary to save the pixels (ImprintRectangle<\/code>) before overwriting them. The background buffer already contains a copy!<\/p>\nThat’s because all graphics code can be configured to either draw to the foreground bitmap, the background bitmap, or both.<\/p>\n
To calculate the offset in the bitmap of a y coordinate, all internal drawing code calls GetScanLine<\/code>. This function usually returns two pointers in virtual registers r5 and r6:<\/p>\n\n- r5: pointer to the pixel line in the foreground<\/em> screen<\/li>\n
- r6: pointer to the pixel line in the background<\/em> screen<\/li>\n<\/ul>\n
Any code in the GEOS drawing library then stores the pixel data in both the locations pointed to by r5 and r6:<\/p>\n
[...]\n sta (r5),y\n sta (r6),y\n<\/code><\/pre>\nFor as little as an extra 6 clock cycles for every byte to be stored (which is 8 pixels), the drawing code stores it into both bitmaps, so there is usually no need to copy data from the foreground to the background bitmap.<\/p>\n
Now when the system draws a menu or a dialog, it only draws it into the foreground buffer. That’s because the GetScanLine<\/code> call can actually return different kinds of pointers depending on the global system variable dispBufferOn<\/code>:<\/p>\n\n\n\n dispBufferOn<\/code> <\/th>\n r5 <\/th>\n r6 <\/th>\n<\/tr>\n<\/thead>\n \n\n %11000000<\/code> (default) <\/td>\n fg screen ptr <\/td>\n bg screen ptr <\/td>\n<\/tr>\n \n %10000000<\/code> <\/td>\n fg screen ptr <\/td>\n fg screen ptr <\/td>\n<\/tr>\n \n %01000000<\/code> <\/td>\n bg screen ptr <\/td>\n bg screen ptr <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nBy only setting one<\/em> of bits 6 and 7, all drawing code can effectively be instructed to only draw to the foreground or the background bitmap. In this case, the two sta<\/code> instructions will just store the pixel data to the same location twice.<\/p>\nThe system default is to draw everything to both bitmaps \u2013\u00a0except menus and dialogs, which are only ever drawn to the foreground bitmap. There is therefore no need to call ImprintRectangle<\/code>: All that the built-in code has to do is call RecoverRectangle<\/code> on the rectangle that it overwrote.<\/p>\nScreen Recovery in geoWrite<\/h2>\n
geoWrite is a very complex application that is very tight on memory, so it was designed to reclaim as much as possible of the 8 KB normally used for screen recovery. Text rendering is very slow, so redrawing the page as a recovery strategy is out of the question.<\/p>\n
Instead, geoWrite stores the saved pixels more efficiently: The buffer only really needs to be as big as is required for the largest rectangle ever saved while in the app. And for geoWrite, that’s dialogs, which are 200×104 pixels. So that’s 2600 bytes instead of 8000 bytes.<\/p>\n
The code to save a screen rectangle is called with the following arguments in virtual registers:<\/p>\n
\nr1<\/code>: the pointer to the recovery buffer<\/li>\nr2L<\/code>: x \u00f7 8<\/li>\nr2H<\/code>: y<\/li>\nr3L<\/code>: width \u00f7 8<\/li>\nr3H<\/code>: height<\/li>\n<\/ul>\nX coordinates have to be divisible by 8, so that the pixels are at byte boundaries.<\/p>\n
The Code<\/h3>\n
The following is the main code, slightly edited for readability. It iterates over all lines of the rectangle and, on save, appends the bitmap bytes to the array of saved data. On recover, it does the opposite.<\/p>\n
@loop1: ldx r2H ; y coord\n jsr GetScanLine ; r5 := ptr to bitmap\n lda r2L ; x coord \/ 8\n asl a\n asl a\n asl a ; * 8\n bcc :+\n inc r5H\n: tay\n MoveB r3L, r4L ; copy byte count\n@loop2: bit r4H ; save or recover?\n bpl @1\n jsr @recv\n bra @2\n@1: jsr @save\n@2: IncW r1 ; advance buffer pointer\n add #8 ; account for quirky VIC-II memory layout\n bcc :+\n inc r5H\n: tay\n dec r4L ; dec byte counter\n bne @loop2 ; loop for horizontal bytes\n inc r2H\n dec r3H ; dec line counter\n bne @loop1 ; loop for lines\n rts\n<\/code><\/pre>\nThis is the subroutine for copying a byte from the screen to the buffer…<\/p>\n
@save: lda (r5),y ; read screen byte\n tax\n tya\n pha ; save offset\n ldy #0\n txa\n sta (r1),y ; write into buffer\n pla ; restore offset\n rts\n<\/code><\/pre>\n…and the code for copying a byte from the buffer to the screen:<\/p>\n
@recv: tya ; save offset\n pha\n ldy #0\n lda (r1),y ; read from buffer\n tax\n pla\n tay ; restore offset\n txa\n sta (r5),y ; write onto screen\n tya\n rts\n<\/code><\/pre>\nThe Tables<\/h3>\n
geoWrite uses a table with the buffer pointer, x, y, width and height values for each use case, so only an offset within the table has to be passed:<\/p>\n
; r1L\/r1H r2L r2H r3L r3H\n; ptr x y wdth hght\nscrrecvtabs:\nscrrecvtab_geos:\n .word MEM_SCRREST\n .byte 0, 15, 10, 128\nscrrecvtab_file:\n .word MEM_SCRREST\n .byte 3, 15, 7, 100\n[...]\n<\/code><\/pre>\nThe first item in the table is for saving and restoring the rectangle under the “geos” menu, and so on.<\/p>\n
MEM_SCRREST<\/code> is the address of the start of the recover buffer. The buffer pointer isn’t always MEM_SCRREST<\/code> though:<\/p>\nscrrecvtab_font:\n .word MEM_SCRREST\n .byte 17, 15, 10, 114\nscrrecvtab_fontsize:\n .word MEM_SCRREST + 1408\n .byte 26, 15, 9, 114\n<\/code><\/pre>\nThis is because the font menu has a sub-menu for the point size:<\/p>\n
![\"\"](\"docs\/geowrite\/font_menu.png\")
<\/p>\n
When the font menu is open, the rectangle covered by it is already saved in the buffer. The rectangle under the point size menu has to be saved in the area following the already occupied data.<\/p>\n
Memory Layout<\/h3>\n
Conveniently, the RAM area for the background bitmap immediately follows the application’s memory. Apps are free to just not use the background bitmap at all. By setting dispBufferOn<\/code> to %10000000<\/code> globally, the system will never touch the $6000-$7FFF area.<\/p>\nHere’s a mostly to scale overview of the geoWrite memory map compared to the GEOS default:<\/p>\n
GEOS Default geoWrite\n------------------------- -------------------------\n$0400 $0400\n\n Main Code\n\n\n Application memory -------------------------\n Overlay Code $3244\n -------------------------\n $4310\n Page Data\n\n------------------------- -------------------------\n$6000 Font Heap $5E68\n Background bitmap _________________________\n Recovery Data $75D8\n------------------------- -------------------------\n<\/code><\/pre>\ngeoWrite puts the recovery buffer at the topmost 2600 bytes of the $0400-$8000 window that is available to the application if it doesn’t use the background screen.<\/p>\n
The reason for this location is because the range $7900-$7F40 is where GEOS requires the printer driver to be loaded once the application wants to print. It overlaps the background screen on purpose: As long as the application is not printing, so no space for the driver is wasted. And once it is printing, it just can’t use the background buffer any more. The same is true in geoWrite’s model.<\/p>\n
Triggers<\/h3>\n
Aside from setting dispBufferOn<\/code> to just the foreground, using one’s own save\/recover logic requires the app to make sure the save and recover code gets called at the right times.<\/p>\nFor dialogs, this is easy: Apps have to explicitly show them by calling the doDlgBox<\/code> API, so before calling it, geoWrite saves the respective rectangle, and once the API returns, it recovers it.<\/p>\nFor menus, it’s more tricky. The application has to trigger on the open event of a sub-menu.<\/p>\n
Usually, the data structure of a menu for the doMenu<\/code> API contains pointers to sub-menu data structures, forming the complete menu tree, like this:<\/p>\nmenu_main:\n .byte 0, 14, 0, 191 ; pos & size\n .byte HORIZONTAL | UN_CONSTRAINED | 3 ; #items\n\n .word txt_geos ; string \"geos\"\n .byte SUB_MENU ; =below is a sub-menu ptr\n .word menu_geos ; sub-menu data structure\n\n .word txt_file\n .byte SUB_MENU\n .word menu_file\n\n .word txt_edit\n .byte SUB_MENU\n .word menu_edit\n<\/code><\/pre>\nThis way, an application can describe a complete menu tree with just data structures and no code.<\/p>\n
But instead of a pointer to a sub-menu (code SUB_MENU<\/code>), the data structure can alternatively contain a pointer to code<\/em> that returns a sub-menu data structure (code DYN_SUB_MENU<\/code>):<\/p>\n .word txt_geos ; string \"geos\"\n .byte DYN_SUB_MENU ; =below is a code ptr\n .word callbackGeos ; code, called on sub-menu open\n<\/code><\/pre>\nIn this example, whenever the “geos” item is clicked, the callbackGeos<\/code> function is called, which saves the rectangle that will be covered by the “geos” sub-menu, and returns a pointer to the sub-menu to be presented (edited for clarity):<\/p>\ncallbackGeos:\n ldx #scrrecvtab_geos-scrrecvtabs\n stx a2L\n jsr screenSave\n LoadW r0, menu_geos\n rts\n<\/code><\/pre>\nFor the recovery of the rectangle, there is actually a GEOS system variable supporting this use case: If the application sets the RecoverVector<\/code> pointer to anything but 0, closing a menu will call that code instead of doing its own RecoverRectangle<\/code>-based recovery.<\/p>\nThis is where it points in geoWrite (again edited for clarity):<\/p>\n
appRecoverVector:\n ldx a2L\n jsr screenRecover\n rts\n<\/code><\/pre>\nThe function reuses the previously set offset in the screen recovery table (in virtual register a2L) for buffer location, the origin and size of the rectangle.<\/p>\n
Conclusion<\/h2>\n
Berkeley Softworks wrote the GEOS operating system as well as many major applications like geoWrite, geoPaint, geoPublish and geoCalc, yet they implemented two different methods for screen recovery: The system way of doing it wastes space, but is very simple to use. And the way they do it in the applications is very much tied to the specific use case, but very optimized.<\/p>\n","protected":false},"excerpt":{"rendered":"
In the series about the internals of the geoWrite WYSIWYG text editor for the C64, this article discusses how the app manages to extend its usable RAM by 5 KB using a custom screen recovery solution. Article Series The Overlay System Screen Recovery \u2190 this article Font Management Zero Page Copy Protection Localization File Format … Read more<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2,5,41,8,15,22],"tags":[],"class_list":["post-1428","post","type-post","status-publish","format-standard","hentry","category-2","category-archeology","category-c64","category-commodore","category-geos","category-operating-systems"],"_links":{"self":[{"href":"https:\/\/www.pagetable.com\/index.php?rest_route=\/wp\/v2\/posts\/1428","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.pagetable.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.pagetable.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.pagetable.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.pagetable.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=1428"}],"version-history":[{"count":0,"href":"https:\/\/www.pagetable.com\/index.php?rest_route=\/wp\/v2\/posts\/1428\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.pagetable.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=1428"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.pagetable.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=1428"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.pagetable.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=1428"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}