Display scrolling

[bdbarnett]

@tdhoward I created scroll_touch_test.py since you and I spoke last to figure out how to make touches go to the correct part of the screen during scrolling, and realized I needed a better method of scrolling! All other scrolling tests up to this point just use .vscrdef(tfa, vsa, bfa) and .vscsad(vssa). Those write to the corresponding registers in the display hardware, but are a little difficult to use. I added .set_vscroll(tfa, bfa) and exposed .tfa, .vsa and .bfa as readonly attributes. The biggest benefit is the addition of the read/write attribute .vscroll and the .translate_point() method.

TFA, VSA and BFA are sent to the VSCRDEF register of the hardware and define the top free area, vertical scroll area and bottom free area. They must (or at least should) total the height of the visible display. VSSA is the vertical screen start address and is sent to the VSCSAD address of the hardware. It specifies the line in memory to use as the first line of the VSA. If VSSA is 0, the TFA gets duplicated to the top of the VSA. I can't think of a circumstance where this would ever be desirable, and it makes writing code, especially loops, more difficult. Instead, I added the read/write attribute .vscroll. Setting .vscroll = n sets VSSA to n + tfa, so that assigning 0 to it scrolls to the top of the VSA, which is perfect. .vscroll first calculates n % VSA, which allows looping the scrolled area more than once. This is getting very difficult to explain!

In hindsight, I don't know that .set_vscroll is necessary. It does the same thing as .vscrdef, except it calculates VSA on the fly. It also resets the VSSA to the start of the VSA using .vscroll, so maybe we leave it in. My reasoning for creating it was that non-hardware displays, such as PGDisplay and SDLDisplay, don't have an obvious correlation to VSCRDEF and VSCSAD, so .set_vscroll and .vscroll seem more intuitive.

That sums up the display side of scrolling. To handle the touch input side, I added the .translate_point() method. Initially, I wanted to have it called in the background by the event/device system on every event with a .pos attribute when TFA, BFA, and VSSA weren't all 0. However, the event object returned by SDL is read-only, so changing it on the fly would mean recreating the event object with the new position. I haven't convinced myself that's a good idea yet, so instead, .translate_point has to be called by the user code anytime scrolling is used. Basically, if the y axis of the point supplied to .translate_point is in the VSA, it translates it to match the VSSA, again applying n % VSA to account for scrolling past the bottom of the VSA.

DisplayBuffer isn't a display object like BusDisplay, but is meant to be usable in any place a display object would be used. Instead of writes such as .pixel, .line, .blit_rect, etc. going directly to the display, they are written to a MicroPython framebuf.FrameBuffer object and then copied to the display. Unlike rotations which will be difficult to implement in DisplayBuffer, I think scrolling should be fairly easy. I'm going to work on it tonight.

[bdbarnett]

@tdhoward Scrolling is now working in displaybuf.DisplayBuffer. Had to add these lines (with a little help from ChatGPT).

_display_drv_get_attrs = {"set_vscroll", "tfa", "bfa", "vsa", "vscroll", "translate_point"}
_display_drv_set_attrs = {"vscroll"}

    def __getattr__(self, name):
        if name in _display_drv_get_attrs:
            return getattr(self.display_drv, name)
        raise AttributeError(f"{self.__class__.__name__} object has no attribute '{name}'")

    def __setattr__(self, name, value):
        if name in _display_drv_set_attrs:
            return setattr(self.display_drv, name, value)
        super().__setattr__(name, value)