343 lines
10 KiB
Markdown
343 lines
10 KiB
Markdown
# Pixel Buffer (pixbuf) Module
|
|
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2020-?? | [nwf](https://github.com/nwf) | nwf | [pixbuf.c](../../app/modules/pixbuf.c) |
|
|
|
|
The pixbuf library offers C-array byte objects and convenient utility functions
|
|
for maintaining small frame buffers, usually for use with LED arrays, as
|
|
supported by, e.g., ws2812.
|
|
|
|
## pixbuf.newBuffer()
|
|
Allocate a new memory buffer to store LED values.
|
|
|
|
#### Syntax
|
|
`pixbuf.newBuffer(numberOfLeds, numberOfChannels)`
|
|
|
|
#### Parameters
|
|
- `numberOfLeds` length of the LED strip (in pixels)
|
|
- `numberOfChannels` the channel count (bytes per pixel)
|
|
|
|
#### Returns
|
|
`pixbuf.buffer` object
|
|
|
|
## pixbuf.buffer:get()
|
|
Return the value at the given position, in native strip color order.
|
|
|
|
#### Syntax
|
|
`buffer:get(index)`
|
|
|
|
#### Parameters
|
|
- `index` position in the buffer (1 for first LED)
|
|
|
|
#### Returns
|
|
`(color)`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer = pixbuf.newBuffer(32, 4)
|
|
print(buffer:get(1))
|
|
0 0 0 0
|
|
```
|
|
|
|
## pixbuf.buffer:set()
|
|
Set the value at the given position, in native strip color order.
|
|
|
|
#### Syntax
|
|
`buffer:set(index, color)`
|
|
|
|
#### Parameters
|
|
- `index` position in the buffer (1 for the first LED)
|
|
- `color` payload of the color
|
|
|
|
Payload could be:
|
|
- `number, number, ...`, passing as many colors as required by the array type
|
|
- `table` should contain one value per color required by the array type
|
|
- `string` with a natural multiple of the colors required by the array type
|
|
|
|
`string` inputs may be used to set multiple consecutive pixels!
|
|
|
|
#### Returns
|
|
The buffer
|
|
|
|
#### Example
|
|
```lua
|
|
buffer = pixbuf.newBuffer(32, 3)
|
|
buffer:set(1, 255, 0, 0) -- set the first LED green for a GRB strip
|
|
```
|
|
|
|
```lua
|
|
buffer = pixbuf.newBuffer(32, 4)
|
|
buffer:set(1, {255, 0, 0, 255}) -- set the first LED white and red for a RGBW strip
|
|
```
|
|
|
|
```lua
|
|
-- set the first LED green for a RGB strip and exploit the return value
|
|
buffer = pixbuf.newBuffer(32, 3):set(1, string.char(0, 255, 0))
|
|
```
|
|
|
|
## pixbuf.buffer:size()
|
|
Return the size of the buffer in number of LEDs.
|
|
|
|
#### Syntax
|
|
`buffer:size()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`int`
|
|
|
|
## pixbuf.buffer:channels()
|
|
Return the buffer's channel count.
|
|
|
|
#### Syntax
|
|
`buffer:channels()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`int`
|
|
|
|
## pixbuf.buffer:fill()
|
|
Fill the buffer with the given color.
|
|
The number of given bytes must match the channel count of the buffer.
|
|
|
|
#### Syntax
|
|
`buffer:fill(color)`
|
|
|
|
#### Parameters
|
|
- `color` bytes for each channel
|
|
|
|
#### Returns
|
|
The buffer
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:fill(0, 0, 0) -- fill the buffer with black for a RGB strip
|
|
```
|
|
|
|
## pixbuf.buffer:dump()
|
|
Returns the contents of the buffer (the pixel values) as a string. This can then be saved to a file or sent over a network and may be fed back to [`pixbuf.buffer:set()`](#pixbufbufferset).
|
|
|
|
#### Syntax
|
|
`buffer:dump()`
|
|
|
|
#### Returns
|
|
A string containing the pixel values.
|
|
|
|
#### Example
|
|
```lua
|
|
local s = buffer:dump()
|
|
```
|
|
|
|
## pixbuf.buffer:replace()
|
|
Inserts a string (or a pixbuf) into another buffer with an offset.
|
|
The buffer must be of the same type or an error will be thrown.
|
|
|
|
#### Syntax
|
|
`buffer:replace(source[, offset])`
|
|
|
|
#### Parameters
|
|
- `source` the pixel values to be set into the buffer. This is either a string or a pixbuf.
|
|
- `offset` the offset where the source is to be placed in the buffer. Default is 1. Negative values can be used.
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:replace(anotherbuffer:dump()) -- copy one buffer into another via a string
|
|
buffer:replace(anotherbuffer) -- copy one buffer into another
|
|
newbuffer = buffer.sub(1) -- make a copy of a buffer into a new buffer
|
|
```
|
|
|
|
## pixbuf.buffer:mix()
|
|
This is a general method that loads data into a buffer that is a linear combination of data from other buffers. It can be used to copy a buffer or,
|
|
more usefully, do a cross fade. The pixel values are computed as integers and then range limited to [0, 255]. This means that negative
|
|
factors work as expected, and that the order of combining buffers does not matter.
|
|
|
|
#### Syntax
|
|
`buffer:mix(factor1, buffer1, ...)`
|
|
|
|
#### Parameters
|
|
- `factor1` This is the factor that the contents of `buffer1` are multiplied by. This factor is scaled by a factor of 256. Thus `factor1` value of 256 is a factor of 1.0.
|
|
- `buffer1` This is the source buffer. It must be of the same shape as the destination buffer.
|
|
|
|
There can be any number of factor/buffer pairs.
|
|
|
|
#### Returns
|
|
The output buffer.
|
|
|
|
#### Example
|
|
```lua
|
|
-- loads buffer with a crossfade between buffer1 and buffer2
|
|
buffer:mix(256 - crossmix, buffer1, crossmix, buffer2)
|
|
|
|
-- multiplies all values in buffer by 0.75
|
|
-- This can be used in place of buffer:fade
|
|
buffer:mix(192, buffer)
|
|
```
|
|
|
|
## pixbuf.buffer:mix4I5()
|
|
Like [`pixbuf.buffer:mix()`](#pixbufbuffermix) but treats the first channel as
|
|
a scaling, 5-bit intensity value. The buffers must all have four channels.
|
|
This is mostly useful for APA102 LEDs.
|
|
|
|
## pixbuf.buffer:power()
|
|
Computes the total energy requirement for the buffer. This is merely the total sum of all the pixel values (which assumes that each color in each
|
|
pixel consumes the same amount of power). A real WS2812 (or WS2811) has three constant current drivers of 20mA -- one for each of R, G and B. The
|
|
pulse width modulation will cause the *average* current to scale linearly with pixel value.
|
|
|
|
#### Syntax
|
|
`buffer:power()`
|
|
|
|
#### Returns
|
|
An integer which is the sum of all the pixel values.
|
|
|
|
#### Example
|
|
```lua
|
|
-- Dim the buffer to no more than the PSU can provide
|
|
local psu_current_ma = 1000
|
|
local led_current_ma = 20
|
|
local led_sum = psu_current_ma * 255 / led_current_ma
|
|
|
|
local p = buffer:power()
|
|
if p > led_sum then
|
|
buffer:mix(256 * led_sum / p, buffer) -- power is now limited
|
|
end
|
|
```
|
|
|
|
## pixbuf.buffer:powerI()
|
|
Like [`pixbuf.buffer:power()`](#pixbufbufferpower) but treats the first channel as
|
|
a scaling intensity value.
|
|
|
|
## pixbuf.buffer:fade()
|
|
Fade in or out. Defaults to out. Multiply or divide each byte of each led with/by the given value. Useful for a fading effect.
|
|
|
|
#### Syntax
|
|
`buffer:fade(value [, direction])`
|
|
|
|
#### Parameters
|
|
- `value` value by which to divide or multiply each byte
|
|
- `direction` pixbuf.FADE\_IN or pixbuf.FADE\_OUT. Defaults to pixbuf.FADE\_OUT
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:fade(2)
|
|
buffer:fade(2, pixbuf.FADE_IN)
|
|
```
|
|
|
|
## pixbuf.buffer:fadeI()
|
|
Like [`pixbuf.buffer:fade()`](#pixbufbufferfade) but treats the first channel as
|
|
a scaling intensity value. This is mostly useful for APA102 LEDs.
|
|
|
|
## pixbuf.buffer:shift()
|
|
Shift the content of (a piece of) the buffer in positive or negative direction. This allows simple animation effects. A slice of the buffer can be specified by using the
|
|
standard start and end offset Lua notation. Negative values count backwards from the end of the buffer.
|
|
|
|
#### Syntax
|
|
`buffer:shift(value [, mode[, i[, j]]])`
|
|
|
|
#### Parameters
|
|
- `value` number of pixels by which to rotate the buffer. Positive values rotate forwards, negative values backwards.
|
|
- `mode` is the shift mode to use. Can be one of `pixbuf.SHIFT_LOGICAL` or `pixbuf.SHIFT_CIRCULAR`. In case of SHIFT\_LOGICAL, the freed pixels are set to 0 (off). In case of SHIFT\_CIRCULAR, the buffer is treated like a ring buffer, inserting the pixels falling out on one end again on the other end. Defaults to SHIFT\_LOGICAL.
|
|
- `i` is the first offset in the buffer to be affected. Negative values are permitted and count backwards from the end. Default is 1.
|
|
- `j` is the last offset in the buffer to be affected. Negative values are permitted and count backwards from the end. Default is -1.
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:shift(3)
|
|
```
|
|
|
|
## pixbuf.buffer:sub()
|
|
This implements the extraction function like `string.sub`. The indexes are in leds and all the same rules apply.
|
|
|
|
#### Syntax
|
|
`buffer1:sub(i[, j])`
|
|
|
|
#### Parameters
|
|
- `i` This is the start of the extracted data. Negative values can be used.
|
|
- `j` this is the end of the extracted data. Negative values can be used. The default is -1.
|
|
|
|
#### Returns
|
|
A buffer containing the extracted piece.
|
|
|
|
#### Example
|
|
```
|
|
b = buffer:sub(1,10)
|
|
```
|
|
|
|
## pixbuf.buffer:__concat()
|
|
This implements the `..` operator to concatenate two buffers. They must have the same number of colors per led.
|
|
|
|
#### Syntax
|
|
`buffer1 .. buffer2`
|
|
|
|
#### Parameters
|
|
- `buffer1` this is the start of the resulting buffer
|
|
- `buffer2` this is the end of the resulting buffer
|
|
|
|
#### Returns
|
|
The concatenated buffer.
|
|
|
|
#### Example
|
|
```
|
|
ws2812.write(buffer1 .. buffer2)
|
|
```
|
|
## pixbuf.buffer:map()
|
|
Map a function across each pixel of one, or zip a function along two,
|
|
pixbuf(s), storing into the buffer on which it is called.
|
|
|
|
#### Syntax
|
|
`buffer0:map(f, [buffer1], [start1], [end1], [buffer2, [start2]])`
|
|
|
|
#### Parameters
|
|
- `f` This is the mapping function; it is applied for each pixel to all channels of `buffer1` and
|
|
all channels of `buffer2`, if given. It must return a value for each channel of the output
|
|
buffer, `buffer0`.
|
|
- `buffer1` The first source buffer. Defaults to `buffer0`.
|
|
- `start1` This is the start of the mapped range of `buffer1`. Negative values can be used and will be interpreted as before the end of `buffer1`. The default is 1.
|
|
- `end1` this is the end of the mapped range. Negative values can be used. The default is -1 (i.e., the end of `buffer1`).
|
|
- `buffer2` is a second buffer, for zip operations
|
|
- `start2` This is the start of the mapped range within `buffer2`. Negative values can be used and will be interpreted as before the end of `buffer2`. The default is 1.
|
|
|
|
`buffer0` must have sufficient room to recieve all pixels from `start1` to
|
|
`end1` (which is true of the defaults, when `buffer1` is `buffer0` and `start1`
|
|
is 1 and `end1` is -1). `buffer2`, if given, must have sufficient pixels after
|
|
`start2`.
|
|
|
|
#### Returns
|
|
`buffer0`
|
|
|
|
#### Examples
|
|
|
|
Change channel order within a single buffer:
|
|
```Lua
|
|
buffer:map(function(r,g,b) return g,r,b end)
|
|
```
|
|
|
|
Change channel order for a subset of pixels:
|
|
```Lua
|
|
buffer:map(function(r,g,b) return g,r,b end, nil, 2, 5)
|
|
```
|
|
|
|
Extract one channel for a subset of pixels:
|
|
```Lua
|
|
outbuf = pixbuf.create(11, 1)
|
|
outbuf:map(function(r,g,b) return b end, inbuf, 10, 20)
|
|
```
|
|
|
|
Concatenate channels per pixel, possibly with different offsets in buffers:
|
|
```Lua
|
|
outbuf:map(function(...) return ... end, inbuf1, inbuf2)
|
|
outbuf:map(function(...) return ... end, inbuf1, 5, 10, inbuf2, 3)
|
|
```
|