Blinkchain

v1.0.0

Blinkchain v1.0.0 Blinkchain View Source

This module defines the canvas-based drawing API for controlling one or more strips or arrays of NeoPixel-compatible RGB or RGBW LEDs. The virtual drawing surface consists of a single rectangular plane where each NeoPixel can be mapped onto particular coordinates on the surface. These assignments can be "sparse" such that not every location on the virtual surface is associated with a physical NeoPixel.

NOTE: In the current implementation, when drawing to points on the virtual canvas that do not have physical NeoPixels assigned, the data is lost, such that subsequent calls to copy/4 or copy_blit/4 will result in these pixels behaving as if they had all color components set to 0. This may change in a future release, such that the virtual drawing surface would be persistent, even if the given pixels are not associated with physical NeoPixels, to allow for "off-screen" sprite maps for use with copy_blit/4. In the meantime, this could be accomplished by configuring some extra pixels at the end of the chain or on a second channel that don't actually exist.

The Raspberry Pi supports two simultaneous Pulse-Width Modulation (PWM) channels, which are used by Blinkchain to drive an arbitrary-length chain of NeoPixels. Each chain must consist of a single type of device (i.e. all devices in the chain must have the same number and order of color components). Some drawing commands operate on the entire channel (e.g. set_brightness/2 and set_gamma/2), but otherwise, the position of the pixels within the drawing surface is independent of the channel they're driven by. A single drawing command can apply to one or both channels, depending on how the channel topology has been mapped to the virtual drawing surface.

Link to this section Summary

Types

channel_number()

which PWM channel to use (0 or 1)

color()

an RGB or RGBW color specification

point()

an X-Y point specification

uint16()

unsigned 16-bit integer

uint8()

unsigned 8-bit integer

Functions

blit(destination, width, height, data)

Copy the elements from the data list as pixel data, copying it to the region of size width by height and origin of destination, ignoring pixels whose color components are all zero.

copy(source, destination, width, height)

Copy the region of size width by height from source to destination.

copy_blit(source, destination, width, height)

Copy the region of size width by height from source to destination, ignoring pixels whose color components are all zero.

fill(origin, width, height, color)

Fill the region with color, starting at origin and extending to the right by width pixels and down by height pixels.

render()

Render the current canvas state to the physical NeoPixels according to their configured locations in the virtual canvas.

set_brightness(channel, brightness)

This is used to scale the intensity of all pixels in a given channel by brightness/255.

set_gamma(channel, gamma)

Set the gamma curve to be used for the channel.

set_pixel(point, color)

Set the color of the pixel at a given point on the virtual canvas.

Link to this section Types

Link to this type

channel_number() View Source 
channel_number() :: 0 | 1

which PWM channel to use (0 or 1)

Link to this type

color() View Source 
color() ::
  Blinkchain.Color.t()
  | {uint8(), uint8(), uint8()}
  | {uint8(), uint8(), uint8(), uint8()}

an RGB or RGBW color specification

Link to this type

point() View Source 
point() :: Blinkchain.Point.t() | {uint16(), uint16()}

an X-Y point specification

Link to this type

uint16() View Source 
uint16() :: 0..65535

unsigned 16-bit integer

Link to this type

uint8() View Source 
uint8() :: 0..255

unsigned 8-bit integer

Link to this section Functions

Link to this function

blit(destination, width, height, data) View Source 
blit(point(), uint16(), uint16(), [color()]) ::
  :ok
  | {:error, :invalid, :destination}
  | {:error, :invalid, :width}
  | {:error, :invalid, :height}
  | {:error, :invalid, :data}

Copy the elements from the data list as pixel data, copying it to the region of size width by height and origin of destination, ignoring pixels whose color components are all zero.

data must be a list of width x height elements, where each element is a color/0.

Note: Similar to copy_blit/4, this allows a simple transparency mask to be created by setting all of the color components to zero for the pixels that are intended to be transparent.

Link to this function

copy(source, destination, width, height) View Source 
copy(point(), point(), uint16(), uint16()) ::
  :ok
  | {:error, :invalid, :source}
  | {:error, :invalid, :destination}
  | {:error, :invalid, :width}
  | {:error, :invalid, :height}

Copy the region of size width by height from source to destination.

Link to this function

copy_blit(source, destination, width, height) View Source 
copy_blit(point(), point(), uint16(), uint16()) ::
  :ok
  | {:error, :invalid, :source}
  | {:error, :invalid, :destination}
  | {:error, :invalid, :width}
  | {:error, :invalid, :height}

Copy the region of size width by height from source to destination, ignoring pixels whose color components are all zero.

Note: This is different than copy/4 because it allows a simple transparency mask to be created by setting all of the color components to zero for the pixels that are intended to be transparent.

Link to this function

fill(origin, width, height, color) View Source 
fill(point(), uint16(), uint16(), color()) ::
  :ok
  | {:error, :invalid, :origin}
  | {:error, :invalid, :width}
  | {:error, :invalid, :height}
  | {:error, :invalid, :color}

Fill the region with color, starting at origin and extending to the right by width pixels and down by height pixels.

Link to this function

render() View Source 
render() :: :ok

Render the current canvas state to the physical NeoPixels according to their configured locations in the virtual canvas.

Link to this function

set_brightness(channel, brightness) View Source 
set_brightness(channel_number(), uint8()) ::
  :ok | {:error, :invalid, :channel} | {:error, :invalid, :brightness}

This is used to scale the intensity of all pixels in a given channel by brightness/255.

Link to this function

set_gamma(channel, gamma) View Source 
set_gamma(channel_number(), [uint8()]) ::
  :ok | {:error, :invalid, :channel} | {:error, :invalid, :gamma}

Set the gamma curve to be used for the channel.

gamma is a list of 255 8-bit unsigned integers, which will be used as a look-up table to transform the value of each color component for each pixel.

Link to this function

set_pixel(point, color) View Source 
set_pixel(point(), color()) ::
  :ok | {:error, :invalid, :point} | {:error, :invalid, :color}

Set the color of the pixel at a given point on the virtual canvas.