Skip to content

Latest commit

 

History

History
404 lines (313 loc) · 14.3 KB

graphics.common.md

File metadata and controls

404 lines (313 loc) · 14.3 KB
Raw

graphics.common

API for generic bitmap graphics library

Methods

Method Description
bgcolor() Set background color for subsequent drawing
bitmap() Copy a bitmap to the display buffer
box() Draw a box
char_attrs() Set attributes for text rendering
circle() Draw a circle
clear() Clear the display buffer
copy() Copy from one screen location to another
cut() Copy from one screen location to another and clear the origin to the background color
fgcolor() Set foreground color of subsequent drawing operations
font_addr() Set address of font definition
font_height() Return the set font height
font_sz() Set expected dimension of font, in pixels
font_width() Return the set font width
line() Draw line
plot() Plot pixel
point() Get color of pixel
pos_xy() Set text draw position, in character-cell col and row
putchar() Write a character to the display
rgbw8888_rgb32() Return 32-bit long from discrete Red, Green, Blue, White color components
rgbw8888_rgb32_brightness() Return 32-bit long from discrete Red, Green, Blue, White color components, and clamp brightness
rgb565_r5() Return 5-bit red component of 16-bit RGB color
rgb565_g6() Return 6-bit green component of 16-bit RGB color
rgb565_b5() Return 5-bit blue component of 16-bit RGB color
scale() Scale a region of the display up by size
scroll_down() Scroll a region of the display down by one pixel
scroll_left() Scroll a region of the display left by one pixel
scroll_right() Scroll a region of the display right by one pixel
scroll_up() Scroll a region of the display up by one pixel
text_cols() Get number of displayable text columns, based on set display width and set font width
text_rows() Get number of displayable text rows, based on set display height and set font height

NOTE: In addition to the above, all terminal output-type methods are available for text rendering, through the use of terminal.common.spinh

bgcolor(c)

Set background color for subsequent drawing

  • Parameters:
    • c: background color
  • Returns: none
  • Affects: clear(), cut(), putchar()

bitmap(ptr_bmap, xs, ys, bm_wid, bm_lns)

Copy a bitmap to the display buffer

  • Parameters:
    • ptr_bmap: address of/pointer to buffer containing bitmap data
    • (xs, ys): screen location to copy bitmap to, in pixels
    • bm_wid: width of bitmap, in pixels
    • bm_lns: total number of lines in bitmap
  • Returns: none
  • NOTE: If the preprocessor symbol GFX_DIRECT is defined at build-time, a driver-specific implementation will be used, instead.

box(sx, sy, ex, ey, c, f)

Draw a box

  • Parameters:
    • (sx, sy): starting (upper-left) screen location of box
    • (ex, ey): ending (lower-right) screen location of box
    • c: color of box
    • f: flag to set if box should be filled (boolean)
  • Returns: none
  • NOTE: If the preprocessor symbol GFX_DIRECT is defined at build-time, a driver-specific implementation will be used, instead.

char_attrs(attrs)

Set attributes for text rendering

  • Parameters:
    • attrs: bitmask of attributes
  • Returns: none
  • Available symbols:
    • DRAW_BG: draw the background when drawing text (warning: slower)
  • Aliases: charattrs()

circle(cx, cy, r, c, f)

Draw a circle

  • Parameters:
    • (cx, cy): screen location to draw circle (center)
    • r: radius of circle
    • c: color of circle
    • f: flag to set if circle should be filled (boolean)
  • Returns: none

clear()

Clear the display

  • Parameters: none
  • Returns: none
  • NOTE: The display will be cleared to the color currently set by bgcolor().

copy(sx, sy, ex, ey, dx, dy)

Copy rectangular region from one screen location to another

  • Parameters:
    • (sx, sy): starting (upper-left) screen location to copy
    • (ex, ey): ending (lower-right) screen location to copy
    • (dx, dy): destination screen location to copy to
  • Returns: none
  • NOTE: This functionality depends on being able to read the current display contents, so is only usable when a buffered display is being used. If GFX_DIRECT is defined at build time, this method won't be available.

cut(sx, sy, ex, ey, dx, dy)

Copy rectangular region from one screen location to another and clear the origin to the background color

  • Parameters:
    • (sx, sy): starting (upper-left) screen location to copy
    • (ex, ey): ending (lower-right) screen location to copy
    • (dx, dy): destination screen location to copy to
  • Returns: none
  • NOTE: The region copied from will be cleared to the color set by bgcolor()
  • NOTE: This functionality depends on being able to read the current display contents, so is only usable when a buffered display is being used. If GFX_DIRECT is defined at build time, this method won't be available.

fgcolor(c)

Set foreground color of subsequent drawing operations

  • Parameters:
    • c: background color
  • Returns: none
  • Affects: putchar()

font_addr(ptr_fnt)

Set address of font definition

  • Parameters:
    • ptr_fnt: address of/pointer to start of font table
  • Returns: none
  • Aliases: fontaddress()

font_height()

Get the currently set font height

  • Parameters: none
  • Returns: current font height, in pixels
  • Aliases: fontheight()

font_scl(s)

Set font rendering scale

  • Parameters:
    • s: factor to scale up font width and height rendering by
  • Returns: none
  • Aliases: fontscale()

font_sz(w, h)

Set expected dimension of font

  • Parameters:
    • w: width of font glyphs, in pixels
    • h: height of font glyphs, in pixels
  • Returns: none
  • Aliases: fontsize()

font_spacing(h, v)

Set spacing between character cells

  • Parameters:
    • h: horizontal space, in pixels
    • v: vertical space, in pixels
  • Returns: none
  • Aliases: fontspacing()

font_width()

Get the currently set font width

  • Parameters: none
  • Returns: current font width, in pixels
  • Aliases: fontwidth()

line(sx, sy, ex, ey, c)

Draw line

  • Parameters:
    • (sx, sy): starting screen location of line
    • (ex, ey): ending screen location of line
    • c: color of line
  • Returns: none
  • NOTE: If the preprocessor symbol GFX_DIRECT is defined at build time, a driver-specific implementation will be used, instead.

plot(x, y, c)

Plot pixel

  • Parameters:
    • (x, y): screen location to draw pixel
    • c: color of pixel
  • Returns: none
  • NOTE: This method appears in the display driver, since it is implementation-specific.

point(x, y)

Get color of pixel

  • Parameters:
    • (x, y): screen location of pixel
  • Returns: color of the pixel at the given screen location
  • NOTE: This functionality depends on being able to read the current display contents, so is only usable when a buffered display is being used. If GFX_DIRECT is defined at build time, this method won't be available.

pos_xy(x, y)

Set text draw position, in character-cell col and row

  • Parameters:
    • (x, y): screen location to position next text display, in character cell columns and rows
  • Returns: none

putchar(ch)

Write a character to the display

  • Parameters:
    • ch: character to display
  • Returns: none
  • Aliases: tx(), char()
  • NOTE: If the preprocessor symbol GFX_DIRECT is defined at build-time, a driver-specific implementation will be used, instead (some implementations may have limitations)

rgbw8888_rgb32(r, g, b, w)

Return 32-bit long from discrete Red, Green, Blue, White color components

  • Parameters:
    • r: 8-bit red color component
    • g: 8-bit green color component
    • b: 8-bit blue color component
    • w: 8-bit white color component
  • Returns: 32-bit packed long comprised of the given color components

rgbw8888_rgb32_brightness(r, g, b, w, level)

Return 32-bit long from discrete Red, Green, Blue, White color components, and clamp brightness

  • Parameters:
    • r: 8-bit red color component
    • g: 8-bit green color component
    • b: 8-bit blue color component
    • w: 8-bit white color component
    • level: brightness level, in percent
  • Returns: 32-bit packed long comprised of the given color components

rgb565_r5(rgb565)

Get 5-bit red component of 16-bit RGB color

  • Parameters:
    • rgb565: 16-bit color word
  • Returns: 5-bit red color component of word

rgb565_g6(rgb565)

Get 6-bit green component of 16-bit RGB color

  • Parameters:
    • rgb565: 16-bit color word
  • Returns: 6-bit green color component of word

rgb565_b5(rgb565)

Get 5-bit blue component of 16-bit RGB color

  • Parameters:
    • rgb565: 16-bit color word
  • Returns: 5-bit blue color component of word

scale(sx, sy, ex, ey, dx, dy, scl)

Copy a region of the display to another location, and scale it up

  • Parameters:
    • (sx, sy): starting screen location to copy
    • (ex, ey): ending screen location to copy
    • (dx, dy): destination screen location to copy to
    • scl: factor to scale up copied region by
  • Returns: none
  • NOTE: This functionality depends on being able to read the current display contents, so is only usable when a buffered display is being used. If GFX_DIRECT is defined at build time, this method won't be available.

scroll_down(sx, sy, ex, ey)

Scroll a region of the display down by 1 pixel

  • Parameters:
    • (sx, sy): starting screen location to scroll
    • (ex, ey): ending screen location to srcoll
  • Returns: none
  • NOTE: This functionality depends on being able to read the current display contents, so is only usable when a buffered display is being used. If GFX_DIRECT is defined at build time, this method won't be available.
  • Aliases: scrolldown()

scroll_left(sx, sy, ex, ey)

Scroll a region of the display left by 1 pixel

  • Parameters:
    • (sx, sy): starting screen location to scroll
    • (ex, ey): ending screen location to srcoll
  • Returns: none
  • NOTE: This functionality depends on being able to read the current display contents, so is only usable when a buffered display is being used. If GFX_DIRECT is defined at build time, this method won't be available.
  • Aliases: scrollleft()

scroll_right(sx, sy, ex, ey)

Scroll a region of the display right by 1 pixel

  • Parameters:
    • (sx, sy): starting screen location to scroll
    • (ex, ey): ending screen location to srcoll
  • Returns: none
  • NOTE: This functionality depends on being able to read the current display contents, so is only usable when a buffered display is being used. If GFX_DIRECT is defined at build time, this method won't be available.
  • Aliases: scrollright()

scroll_up(sx, sy, ex, ey)

Scroll a region of the display up by 1 pixel

  • Parameters:
    • (sx, sy): starting screen location to scroll
    • (ex, ey): ending screen location to srcoll
  • Returns: none
  • NOTE: This functionality depends on being able to read the current display contents, so is only usable when a buffered display is being used. If GFX_DIRECT is defined at build time, this method won't be available.
  • Aliases: scrollup()

text_cols()

Get number of displayable text columns

  • Parameters: none
  • Returns: number of columns
  • NOTE: This value depends on the display dimensions and currently set font width.
  • Aliases: textcols()

text_rows()

Get number of displayable text rows

  • Parameters: none
  • Returns: number of rows
  • NOTE: This value depends on the display dimensions and currently set font height.
  • Aliases: textrows()