Using the Pixel Framebuf library is easy. The most complicated part of it is the initialization, because it can vary so widely with each specific setup, so start with that and then go over each of the functions available to you.

Initialization

For initialization, we'll go over the different options and what the specific parameters mean so you can best determine which options to change for your setup.

  • pixels - (required) The NeoPixels or DotStars object that you initialized
  • width - (required) The width of the framebuf in pixels.
  • height - (required) The height of the framebuf in pixels.
  • orientation - The direction that the pixels are physically laid out in either columns or rows. The value is HORIZONTAL by default and you will need to import VERTICAL if you want to set the value to VERTICAL.

  • alternating - If the pixels zigzag, you will want to set this to True. If they are laid out in the same direction, you will want to set this to False. The default value is True.

  • reverse_x - Set this to True if you want to reverse the direction of all pixels horizontally.

  • reverse_y - Set this to True if you want to reverse the direction of all pixels vertically.

  • top - An optional tuple representing the top left pixel.

  • bottom - An optional tuple representing the bottom right pixel.

  • rotation - A value between 0 and 3 representing the initial rotation of the Framebuffer. This can also be set later with the rotation property.

Example Initializations

Here are the initializations for a few of the panels we have available. In these examples, it is assumed that you have done the necessary imports and setup as described on the Import and Setup page and that your NeoPixels or DotStars are named pixels.

32x8 Panel

Download: file
pixel_framebuf = PixelFramebuffer(
    pixels,
    32,
    8,
    orientation=VERTICAL,
    rotation=2
)

16x16 Panel

Download: file
pixel_framebuf = PixelFramebuffer(
    pixels,
    16,
    16,
    reverse_x=True,
)

NeoPixel FeatherWing

Download: file
pixel_framebuf = PixelFramebuffer(
    pixels,
    8,
    4,
    alternating=False,
)

DotStar FeatherWing

Download: file
pixel_framebuf = PixelFramebuffer(
    pixels,
    12,
    6,
    alternating=False,
)

Drawing Functions

All drawing functions are based on coordinates starting from the upper left-hand side as the starting point.

Displaying the Framebuffer

Each time you want to display the current Framebuffer, you will need to call the display() function. This function takes no parameters and displays whatever is currently in memory.  We will show you how to use it in each of the drawing function example code snippets.

Fill

To fill in the entire Framebuffer with a specific color, you can use the fill() function. For instance, to fill it with Blue (0x0000FF), you would use the following command:

Download: file
pixel_framebuf.fill(0x0000FF)
pixel_framebuf.display()

To turn all the pixels off, you can set them to 0x000000.

Download: file
pixel_framebuf.fill(0x000000)
pixel_framebuf.display()

Pixel Drawing

To draw a pixel, you just need to use the pixel() function and provide the coordinates and color. For instance, if you wanted to draw a set the pixel at (4, 6) to red, you would use the following command:

Download: file
pixel_framebuf.pixel(4, 6, 0xFF0000)
pixel_framebuf.display()

If you wanted to get the pixel's value, you would retrieve it like this:

Download: file
color = pixel_framebuf.pixel(4, 6)

Line Drawing

To draw a line, you just need to to use the line() function and provide the starting coordinates, ending coordinates, and color. For instance, if you wanted to draw a line from (0, 0) to (7, 9) in red (0xFF0000), you would use the following command:

Download: file
pixel_framebuf.line(0, 0, 7, 9, 0xFF0000)
pixel_framebuf.display()

Horizontal and Vertical Line Drawing

To draw horizontal or vertical, you can use the hline() and vline() functions. These are optimized for fast drawing because they don't need to calculate a slope. You just need to pass the x and y coordinates along with the length of the line in pixels and the color you wish to draw.

To use these functions, to draw a 5 pixel red line starting at (2, 3), you would use the following:

Download: file
pixel_framebuf.hline(2, 3, 5, 0xFF0000)
pixel_framebuf.vline(2, 3, 5, 0xFF0000)
pixel_framebuf.display()

Rectangle Drawing

To draw a non-filled Rectangle, you will want to use the rect() function. You provide it starting coordinates, width, height, and line color. To draw a red rectangle at (2, 2) with a width of 8 and a height of 12, you would use:

Download: file
pixel_framebuf.rect(2, 2, 8, 12, 0xFF0000)
pixel_framebuf.display()

To draw a filled rectangle, you would do the same thing with the fill_rect() function:

Download: file
pixel_framebuf.fill_rect(2, 2, 8, 12, 0xFF0000)
pixel_framebuf.display()

Text Drawing

To draw text, you would use the text() function, provide the string, upper left coordinates of the text, and the color. For instance, to draw "Hi" at (3, 4) in green (0x00FF00), you would use the following:

Download: file
pixel_framebuf.text("Hi", 3, 4, 0x00FF00)
pixel_framebuf.display()

Text can go off the screen and simply redrawing the text in different positions on top of the same background can produce an animated text effect.

This guide was first published on Sep 22, 2020. It was last updated on Sep 22, 2020.

This page (Usage) was last updated on Nov 06, 2020.