Summary

OK, so I implemented bitmap screen capture.  (I also fixed some bugs since last post regarding the Help screen)

Deets

I had recently implemented a Screen Capture feature that captured the TRS-80 screen in text mode.  It was a bit of work to get that implemented -- mostly because of infrastructure needs (e.g. generating file names, etc.) -- so I decided to make my life easier then by just doing a text-mode capture.  That was easy, since the TRS-80 is a character device, but that mode doesn't capture hypervisor screens, color, or HRG graphics.  So doing a bitmap capture was left for a separate activity.  Well, I guess now was the time for that.  (Oh, along the way I fixed some Help screen bug reported by a user Mikael ☉. Bonnier -- thanks so much for the detailed info; that really makes it easier to fix.)

The TRS-80 is principally a monochrome device, but I support some color boards, and so I did want to be able to have color output.  There's a boatload of image formats, but I chose to 'be conservative in what I send', and settled quickly on Windows DIB format as an easy-to-generate-and-widely-accepted format for output.

DIB itself supports many forms of data representation, from monochrome 1-bit-per-pixel to 32-bits-per-pixel.  The TRS-80 was natively monochrome, so 1bpp was natural, but I did want to capture my glorious colour extensions, so I wanted a color form.  4bpp made a lot of sense, but then I'd have to fiddle with a color look-up table ('CLUT'/palette) and I just didn't want to fiddle with that, so I decided to unconditionally emit a 24bpp image.  This simplified coding, though it made file size much bigger than it strictly needed to be.  But who cares?!  You've got huge SD to store it!  So I carried on with 24bpp in all cases for now.

So I started coding.  At first I got some images that were plausible, but nonsensical:

examining these I could tell that I had flubbed up byte offsets into the screen buffers and some other bugs.  Hacking a little further, I got:

This looks sensible, but I know it's not right because the colors are wrong.  Red and Blue were switched, so I fixed that:

Now,! we're there!  I also added in support for the HRG mod, which is technically a separate overlay frame buffer:

who can forget sinus?

But one thing to note is that these bitmaps are in the native resolution of the TRS-80 -- i.e. 384x192 -- and does not consider that those pixels are not square.  For most anticipated uses (e.g. documentation), this is probably fine, but strictly it is not aspect-ratio-correct.  I leave it as an exercise for the user to translate in their own programs to do that correction.  E.g. here is a native cap:

but here is how it looks on a real screen, as fixed up in Photoshop:

The needed transformation is simple:  2x horizontal and 3x vertical.  I could have done this in the emulator code, but it would have made the file size even bigger, and incurred more CPU, so I left that as a post-production exercise when needed.

The file writing activity seems to take a lot of time.  On my UBW32 device, a screen cap takes about 3 sec(?!?!!).  So understand that the entire system will be non-responsive during that time.

The default key binding for screen cap is aF8, but it can be altered in the config file, as with the others:

textcap= F8            #capture text screen buffer (ansi)
textcapu= sF8          #capture text screen buffer (unicode)
bmpcap= aF8            #capture bitmap screen buffer

Future

Maybe I'll implement 4-bit indexed color, and 1-bit monochrome formats.  This should conserve the I/O bandwidth, making of snappier snaps.  The images currently are 200k, but a monochrome would be 9k, and a 4bbp color would be 36k, so there's a real savings.  If it turns out to save execution time, then I might also consider correcting the aspect ratio as well (by doubling hres and tripling vres), but this will sextuple back to the 200k file size for the 4bbp images.