typehints/micropython/framebuf.pyi

"""
Frame buffer manipulation.

Descriptions taken from:
https://raw.githubusercontent.com/micropython/micropython/master/docs/library/framebuf.rst.

This module provides a general frame buffer which can be used to create
bitmap images, which can then be sent to a display.
"""

__author__ = "Howard C Lovatt"
__copyright__ = "Howard C Lovatt, 2020 onwards."
__license__ = "MIT https://opensource.org/licenses/MIT (as used by MicroPython)."
__version__ = "7.3.0"  # Version set by https://github.com/hlovatt/tag2ver

from typing import overload, Final

from uio import AnyWritableBuf

MONO_VLSB: Final[int] = ...
"""
Monochrome (1-bit) color format
    This defines a mapping where the bits in a byte are vertically mapped with
    bit 0 being nearest the top of the screen. Consequently each byte occupies
    8 vertical pixels. Subsequent bytes appear at successive horizontal
    locations until the rightmost edge is reached. Further bytes are rendered
    at locations starting at the leftmost edge, 8 pixels lower.
"""

MONO_HLSB: Final[int] = ...
"""
Monochrome (1-bit) color format
    This defines a mapping where the bits in a byte are horizontally mapped.
    Each byte occupies 8 horizontal pixels with bit 7 being the leftmost.
    Subsequent bytes appear at successive horizontal locations until the
    rightmost edge is reached. Further bytes are rendered on the next row, one
    pixel lower.
"""

MONO_HMSB: Final[int] = ...
"""
Monochrome (1-bit) color format
    This defines a mapping where the bits in a byte are horizontally mapped.
    Each byte occupies 8 horizontal pixels with bit 0 being the leftmost.
    Subsequent bytes appear at successive horizontal locations until the
    rightmost edge is reached. Further bytes are rendered on the next row, one
    pixel lower.
"""

RGB565: Final[int] = ...
"""
Red Green Blue (16-bit, 5+6+5) color format
"""

GS2_HMSB: Final[int] = ...
"""
Grayscale (2-bit) color format
"""

GS4_HMSB: Final[int] = ...
"""
Grayscale (4-bit) color format
"""

GS8: Final[int] = ...
"""
Grayscale (8-bit) color format
"""

class FrameBuffer:
    """
   The FrameBuffer class provides a pixel buffer which can be drawn upon with
   pixels, lines, rectangles, text and even other FrameBuffer's. It is useful
   when generating output for displays.
   
   For example::
   
       import framebuf
   
       # FrameBuffer needs 2 bytes for every RGB565 pixel
       fbuf = framebuf.FrameBuffer(bytearray(10 * 100 * 2), 10, 100, framebuf.RGB565)
   
       fbuf.fill(0)
       fbuf.text('MicroPython!', 0, 0, 0xffff)
       fbuf.hline(0, 10, 96, 0xffff)
   """

    def __init__(
        self,
        buffer: AnyWritableBuf,
        width: int,
        height: int,
        format: int,
        stride: int = ...,
        /,
    ):
        """
       Construct a FrameBuffer object.  The parameters are:
       
           - *buffer* is an object with a buffer protocol which must be large
             enough to contain every pixel defined by the width, height and
             format of the FrameBuffer.
           - *width* is the width of the FrameBuffer in pixels
           - *height* is the height of the FrameBuffer in pixels
           - *format* specifies the type of pixel used in the FrameBuffer;
             permissible values are listed under Constants below. These set the
             number of bits used to encode a color value and the layout of these
             bits in *buffer*.
             Where a color value c is passed to a method, c is a small integer
             with an encoding that is dependent on the format of the FrameBuffer.
           - *stride* is the number of pixels between each horizontal line
             of pixels in the FrameBuffer. This defaults to *width* but may
             need adjustments when implementing a FrameBuffer within another
             larger FrameBuffer or screen. The *buffer* size must accommodate
             an increased step size.
       
       One must specify valid *buffer*, *width*, *height*, *format* and
       optionally *stride*.  Invalid *buffer* size or dimensions may lead to
       unexpected errors.
      """
    def fill(self, c: int, /) -> None:
        """
       Fill the entire FrameBuffer with the specified color.
      """
    @overload
    def pixel(self, x: int, y: int, /) -> int:
        """
       If *c* is not given, get the color value of the specified pixel.
       If *c* is given, set the specified pixel to the given color.
      """
    @overload
    def pixel(self, x: int, y: int, c: int, /) -> None:
        """
       If *c* is not given, get the color value of the specified pixel.
       If *c* is given, set the specified pixel to the given color.
      """
    def hline(self, x: int, y: int, w: int, c: int, /) -> None:
        """
       Draw a line from a set of coordinates using the given color and
       a thickness of 1 pixel. The `line` method draws the line up to
       a second set of coordinates whereas the `hline` and `vline`
       methods draw horizontal and vertical lines respectively up to
       a given length.
      """
    def vline(self, x: int, y: int, h: int, c: int, /) -> None:
        """
       Draw a line from a set of coordinates using the given color and
       a thickness of 1 pixel. The `line` method draws the line up to
       a second set of coordinates whereas the `hline` and `vline`
       methods draw horizontal and vertical lines respectively up to
       a given length.
      """
    def line(self, x1: int, y1: int, x2: int, y2: int, c: int, /) -> None:
        """
       Draw a line from a set of coordinates using the given color and
       a thickness of 1 pixel. The `line` method draws the line up to
       a second set of coordinates whereas the `hline` and `vline`
       methods draw horizontal and vertical lines respectively up to
       a given length.
      """
    def rect(self, x: int, y: int, w: int, h: int, c: int, /) -> None:
        """
       Draw a rectangle at the given location, size and color. The `rect`
       method draws only a 1 pixel outline whereas the `fill_rect` method
       draws both the outline and interior.
      """
    def fill_rect(self, x: int, y: int, w: int, h: int, c: int, /) -> None:
        """
       Draw a rectangle at the given location, size and color. The `rect`
       method draws only a 1 pixel outline whereas the `fill_rect` method
       draws both the outline and interior.
      """
    def text(self, s: str, x: int, y: int, c: int = 1, /) -> None:
        """
       Write text to the FrameBuffer using the the coordinates as the upper-left
       corner of the text. The color of the text can be defined by the optional
       argument but is otherwise a default value of 1. All characters have
       dimensions of 8x8 pixels and there is currently no way to change the font.
      """
    def scroll(self, xstep: int, ystep: int, /) -> None:
        """
       Shift the contents of the FrameBuffer by the given vector. This may
       leave a footprint of the previous colors in the FrameBuffer.
      """
    def blit(
        self,
        fbuf: FrameBuffer,
        x: int,
        y: int,
        key: int = -1,
        pallet: FrameBuffer | None = None,
        /,
    ) -> None:
        """
       Draw another FrameBuffer on top of the current one at the given coordinates.
       If *key* is specified then it should be a color integer and the
       corresponding color will be considered transparent: all pixels with that
       color value will not be drawn.
       
       The *palette* argument enables blitting between FrameBuffers with differing
       formats. Typical usage is to render a monochrome or grayscale glyph/icon to
       a color display. The *palette* is a FrameBuffer instance whose format is
       that of the current FrameBuffer. The *palette* height is one pixel and its
       pixel width is the number of colors in the source FrameBuffer. The *palette*
       for an N-bit source needs 2**N pixels; the *palette* for a monochrome source
       would have 2 pixels representing background and foreground colors. The
       application assigns a color to each pixel in the *palette*. The color of the
       current pixel will be that of that *palette* pixel whose x position is the
       color of the corresponding source pixel.
      """