5.4 Dot-Matrix Display (DMD)

Dot matrix APIs should only be called from display effects.

There are two key objects you should understand: pages and windows.

A display page is special RAM which holds the frame buffer that determines which pixels are turned on and off. Display memory cannot be accessed like ordinary memory, though; it does not have a fixed address.

A display window is an address that the CPU can use to read/write display memory – that is, it sees one of the display pages.

There can be more display pages than windows, so not all pages are accessible at all times. Through mapping calls, you decide which pages are mapped to which windows.

You must go through several steps for each frame you want to write. For each step, there are several APIs to choose from.

• Allocate a new display page. The new page may contain old, stale data in it; it is not necessarily initialized. Allocation alone does not make it accessible, only reserved.

  dmd_alloc_map

  Allocate and map a single page into either the low or high area.
  

  dmd_alloc_low_high

  Allocate and map two pages at once. The pages will always have consecutive page numbers (N and N+1).

  Do not assume that the low and high windows are contiguous in memory.
  

  dmd_dup_mapped

  Allocate and map a page pair that is copy of what is currently mapped.

• Map the page into one of the display windows. FreeWPC requires at least two windows; some platforms support more. These two windows are called the low window and high window; the pages that are mapped there are the low page and the high page. The simplest effects can be be done using only the low page. If you need color, or flashing effects, you will probably need both the low and high page. In the API names below, the term map refers to either low or high.

• Initialize the page if necessary. If you are writing text only, you would want to clear the page first. If you are filling the page with a full-size image, that is not necessary.

  dmd_clean_page_map

  Zero a display page.
  

  dmd_copy_page

  Copy an entire page from one buffer to another.

• Render text and graphics on the page. Text APIs implicitly write to the low page only. Graphics APIs generally write to the low page if dealing with only 1 color, or to both low and high pages if multiple colors are used. If you need to write to the high page, use dmd_flip_low_high to swap them temporarily.

  font_render_string

  Write text in the given font, starting at a specific coordinate.
  

  font_render_string_center

  Write text in the given font, centered about the given coordinate.
  

  font_render_string_right

  Write text in the given font, right-justified against the specified coordinate.
  

  bmp_draw

  Draw an arbitrary sized bitmap onto the low page.
  

  frame_draw

  Draw a full-size, 4-color frame onto the low and high pages.
  

  dmd_text_outline

  Generate a text outline page. On input, the low page should contain nothing but text. The high page should be allocated, but need not be clean. On output, the high page will contain an outline mask.

  This API should be used when rendering text onto a color image. Each '1' bit in the mask corresponds to a pixel that should be made black in the final image, so that the text stands out from the background image. See dmd_overlay_outline below for a method to do this.

• Optionally, create a composite of several pages together For example, overlaying text onto background art. You can use overlay pages, which are additional fixed buffers that do not need to be allocated. You can use compositing APIs to join multiple pages together in different ways.

  dmd_overlay

  Overlay ("or") the low overlay page onto the allocated low page. Use when both the allocation and the overlay are mono.
  

  dmd_overlay_color

  Overlay both low/high overlay pages onto the allocated low/high pages. Use when both the allocation and the overlay are 4-color.
  

  dmd_overlay_onto_color

  A hybrid of the above two APIs, used when the allocation is in color, but the overlay is mono.
  

  dmd_overlay_outline

  Overlays text onto a color image. The allocated low/high pages contain the image. The low overlay page contains the text. The high overlay page contains the outline mask, created with dmd_text_outline.

  This is a fairly slow call, as it is requires several AND and OR operations.
  

  dmd_and_page

  A low-level function to AND the contents of the low page, using the high page as a mask.
  

  dmd_or_page

  A low-level function to OR into the contents of the low page, using data from the high page.
  

  dmd_xor_page

  A low-level function to XOR the contents of the low page with the data in the high page.

• Show the page. Until the page is shown, it is not visible. This prevents each step of the rendering process from being seen, which is not visually appealing. Once the page is shown, it is implicitly freed back to the system, meaning that any new changes to the display require allocating a new page again. The page does not need to remain mapped into a window for it to be visible.

  dmd_show_map

  Show a single display page as a 1-color image. It can be in either window.
  

  dmd_show_other

  If the low page is currently visible, then show the high page; and vice versa.
  

  dmd_show2

  Show both display pages together as a 4-color (3 plus black) image.

  Prior to showing the image, you can schedule a transition. You call dmd_sched_transition just before showing to say which transition should be used.

Other APIs are listed below.

dmd_flip_low_high

Flip the mappings, so that the low page appears in the high region, and vice versa.

dmd_rough_copy

dmd_rough_erase

Erase a rough region of the low page. The x coordinates must be 8-bit aligned.