Skip to content

Commit f96a709

Browse files
aykevldeadprogram
aykevl
authored and
deadprogram
committed
pixel: add package for efficiently working with raw pixel buffers
This has been optimized for working with SPI displays like the ST7789. By working directly in the native color format of the display, graphics operations can be much, _much_ faster. Also, this makes it easier to use a different color format like RGB444 simply by changing the generic type.
1 parent 3e64e75 commit f96a709

File tree

3 files changed

+481
-0
lines changed

3 files changed

+481
-0
lines changed

‎pixel/image.go‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
package pixel
2+
3+
import (
4+
"unsafe"
5+
)
6+
7+
// Image buffer, used for working with the native image format of various
8+
// displays. It works a lot like a slice: it can be rescaled while reusing the
9+
// underlying buffer and should be passed around by value.
10+
type Image[T Color] struct {
11+
width int16
12+
height int16
13+
data unsafe.Pointer
14+
}
15+
16+
// NewImage creates a new image of the given size.
17+
func NewImage[T Color](width, height int) Image[T] {
18+
if width < 0 || height < 0 || int(int16(width)) != width || int(int16(height)) != height {
19+
// The width/height are stored as 16-bit integers and should never be
20+
// negative.
21+
panic("NewImage: width/height out of bounds")
22+
}
23+
var zeroColor T
24+
var data unsafe.Pointer
25+
if zeroColor.BitsPerPixel()%8 == 0 {
26+
// Typical formats like RGB888 and RGB565.
27+
// Each color starts at a whole byte offset from the start.
28+
buf := make([]T, width*height)
29+
data = unsafe.Pointer(&buf[0])
30+
} else {
31+
// Formats like RGB444 that have 12 bits per pixel.
32+
// We access these as bytes, so allocate the buffer as a byte slice.
33+
bufBits := width * height * zeroColor.BitsPerPixel()
34+
bufBytes := (bufBits + 7) / 8
35+
buf := make([]byte, bufBytes)
36+
data = unsafe.Pointer(&buf[0])
37+
}
38+
return Image[T]{
39+
width: int16(width),
40+
height: int16(height),
41+
data: data,
42+
}
43+
}
44+
45+
// Rescale returns a new Image buffer based on the img buffer.
46+
// The contents is undefined after the Rescale operation, and any modification
47+
// to the returned image will overwrite the underlying image buffer in undefined
48+
// ways. It will panic if width*height is larger than img.Len().
49+
func (img Image[T]) Rescale(width, height int) Image[T] {
50+
if width*height > img.Len() {
51+
panic("Image.Rescale size out of bounds")
52+
}
53+
return Image[T]{
54+
width: int16(width),
55+
height: int16(height),
56+
data: img.data,
57+
}
58+
}
59+
60+
// LimitHeight returns a subimage with the bottom part cut off, as specified by
61+
// height.
62+
func (img Image[T]) LimitHeight(height int) Image[T] {
63+
if height < 0 || height > int(img.height) {
64+
panic("Image.LimitHeight: out of bounds")
65+
}
66+
return Image[T]{
67+
width: img.width,
68+
height: int16(height),
69+
data: img.data,
70+
}
71+
}
72+
73+
// Len returns the number of pixels in this image buffer.
74+
func (img Image[T]) Len() int {
75+
return int(img.width) * int(img.height)
76+
}
77+
78+
// RawBuffer returns a byte slice that can be written directly to the screen
79+
// using DrawRGBBitmap8.
80+
func (img Image[T]) RawBuffer() []uint8 {
81+
var zeroColor T
82+
var numBytes int
83+
if zeroColor.BitsPerPixel()%8 == 0 {
84+
// Each color starts at a whole byte offset.
85+
numBytes = int(unsafe.Sizeof(zeroColor)) * int(img.width) * int(img.height)
86+
} else {
87+
// Formats like RGB444 that aren't a whole number of bytes.
88+
numBits := zeroColor.BitsPerPixel() * int(img.width) * int(img.height)
89+
numBytes = (numBits + 7) / 8 // round up (see NewImage)
90+
}
91+
return unsafe.Slice((*byte)(img.data), numBytes)
92+
}
93+
94+
// Size returns the image size.
95+
func (img Image[T]) Size() (int, int) {
96+
return int(img.width), int(img.height)
97+
}
98+
99+
func (img Image[T]) setPixel(index int, c T) {
100+
var zeroColor T
101+
102+
if zeroColor.BitsPerPixel()%8 == 0 {
103+
// Each color starts at a whole byte offset.
104+
// This is the easy case.
105+
offset := index * int(unsafe.Sizeof(zeroColor))
106+
ptr := unsafe.Add(img.data, offset)
107+
*((*T)(ptr)) = c
108+
return
109+
}
110+
111+
if c, ok := any(c).(RGB444BE); ok {
112+
// Special case for RGB444.
113+
bitIndex := index * zeroColor.BitsPerPixel()
114+
if bitIndex%8 == 0 {
115+
byteOffset := bitIndex / 8
116+
ptr := (*[2]byte)(unsafe.Add(img.data, byteOffset))
117+
ptr[0] = uint8(c >> 4)
118+
ptr[1] = ptr[1]&0x0f | uint8(c)<<4 // change top bits
119+
} else {
120+
byteOffset := bitIndex / 8
121+
ptr := (*[2]byte)(unsafe.Add(img.data, byteOffset))
122+
ptr[0] = ptr[0]&0xf0 | uint8(c>>8) // change bottom bits
123+
ptr[1] = uint8(c)
124+
}
125+
return
126+
}
127+
128+
// TODO: the code for RGB444 should be generalized to support any bit size.
129+
panic("todo: setPixel for odd bits per pixel")
130+
}
131+
132+
// Set sets the pixel at x, y to the given color.
133+
// Use FillSolidColor to efficiently fill the entire image buffer.
134+
func (img Image[T]) Set(x, y int, c T) {
135+
if uint(x) >= uint(int(img.width)) || uint(y) >= uint(int(img.height)) {
136+
panic("Image.Set: out of bounds")
137+
}
138+
index := y*int(img.width) + x
139+
img.setPixel(index, c)
140+
}
141+
142+
// Get returns the color at the given index.
143+
func (img Image[T]) Get(x, y int) T {
144+
if uint(x) >= uint(int(img.width)) || uint(y) >= uint(int(img.height)) {
145+
panic("Image.Get: out of bounds")
146+
}
147+
var zeroColor T
148+
index := y*int(img.width) + x // index into img.data
149+
150+
if zeroColor.BitsPerPixel()%8 == 0 {
151+
// Colors like RGB565, RGB888, etc.
152+
offset := index * int(unsafe.Sizeof(zeroColor))
153+
ptr := unsafe.Add(img.data, offset)
154+
return *((*T)(ptr))
155+
}
156+
157+
if _, ok := any(zeroColor).(RGB444BE); ok {
158+
// Special case for RGB444 that isn't stored in a neat byte multiple.
159+
bitIndex := index * zeroColor.BitsPerPixel()
160+
var c RGB444BE
161+
if bitIndex%8 == 0 {
162+
byteOffset := bitIndex / 8
163+
ptr := (*[2]byte)(unsafe.Add(img.data, byteOffset))
164+
c |= RGB444BE(ptr[0]) << 4
165+
c |= RGB444BE(ptr[1] >> 4) // load top bits
166+
} else {
167+
byteOffset := bitIndex / 8
168+
ptr := (*[2]byte)(unsafe.Add(img.data, byteOffset))
169+
c |= RGB444BE(ptr[0]&0x0f) << 8 // load bottom bits
170+
c |= RGB444BE(ptr[1])
171+
}
172+
return any(c).(T)
173+
}
174+
175+
// TODO: generalize the above code.
176+
panic("todo: Image.Get for odd bits per pixel")
177+
}
178+
179+
// FillSolidColor fills the entire image with the given color.
180+
// This may be faster than setting individual pixels.
181+
func (img Image[T]) FillSolidColor(color T) {
182+
var zeroColor T
183+
184+
// Fast pass for colors of 8, 16, 24, etc bytes in size.
185+
if zeroColor.BitsPerPixel()%8 == 0 {
186+
ptr := img.data
187+
for i := 0; i < img.Len(); i++ {
188+
// TODO: this can be optimized a lot.
189+
// - The store can be done as a 32-bit integer, after checking for
190+
// alignment.
191+
// - Perhaps the loop can be unrolled to improve copy performance.
192+
*(*T)(ptr) = color
193+
ptr = unsafe.Add(ptr, unsafe.Sizeof(zeroColor))
194+
}
195+
return
196+
}
197+
198+
// Special case for RGB444.
199+
if c, ok := any(color).(RGB444BE); ok {
200+
// RGB444 can be stored in a more optimized way, by storing two colors
201+
// at a time instead of setting each color individually. This avoids
202+
// loading and masking the old color bits for the half-bytes.
203+
var buf [3]uint8
204+
buf[0] = uint8(c >> 4)
205+
buf[1] = uint8(c)<<4 | uint8(c>>8)
206+
buf[2] = uint8(c)
207+
rawBuf := unsafe.Slice((*[3]byte)(img.data), img.Len()/2)
208+
for i := 0; i < len(rawBuf); i++ {
209+
rawBuf[i] = buf
210+
}
211+
if img.Len()%2 != 0 {
212+
// The image contains an uneven number of pixels.
213+
// This is uncommon, but it can happen and we have to handle it.
214+
img.setPixel(img.Len()-1, color)
215+
}
216+
return
217+
}
218+
219+
// Fallback for other color formats.
220+
for i := 0; i < img.Len(); i++ {
221+
img.setPixel(i, color)
222+
}
223+
}

‎pixel/image_test.go‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
package pixel_test
2+
3+
import (
4+
"image/color"
5+
"testing"
6+
7+
"tinygo.org/x/drivers/pixel"
8+
)
9+
10+
func TestImageRGB565BE(t *testing.T) {
11+
image := pixel.NewImage[pixel.RGB565BE](5, 3)
12+
if width, height := image.Size(); width != 5 && height != 3 {
13+
t.Errorf("image.Size(): expected 5, 3 but got %d, %d", width, height)
14+
}
15+
for _, c := range []color.RGBA{
16+
{R: 0xff, A: 0xff},
17+
{G: 0xff, A: 0xff},
18+
{B: 0xff, A: 0xff},
19+
{R: 0x10, A: 0xff},
20+
{G: 0x10, A: 0xff},
21+
{B: 0x10, A: 0xff},
22+
} {
23+
image.Set(4, 2, pixel.NewColor[pixel.RGB565BE](c.R, c.G, c.B))
24+
c2 := image.Get(4, 2).RGBA()
25+
if c2 != c {
26+
t.Errorf("failed to roundtrip color: expected %v but got %v", c, c2)
27+
}
28+
}
29+
}
30+
31+
func TestImageRGB444BE(t *testing.T) {
32+
image := pixel.NewImage[pixel.RGB444BE](5, 3)
33+
if width, height := image.Size(); width != 5 && height != 3 {
34+
t.Errorf("image.Size(): expected 5, 3 but got %d, %d", width, height)
35+
}
36+
for _, c := range []color.RGBA{
37+
{R: 0xff, A: 0xff},
38+
{G: 0xff, A: 0xff},
39+
{B: 0xff, A: 0xff},
40+
{R: 0x11, A: 0xff},
41+
{G: 0x11, A: 0xff},
42+
{B: 0x11, A: 0xff},
43+
} {
44+
encoded := pixel.NewColor[pixel.RGB444BE](c.R, c.G, c.B)
45+
image.Set(0, 0, encoded)
46+
image.Set(0, 1, encoded)
47+
encoded2 := image.Get(0, 0)
48+
encoded3 := image.Get(0, 1)
49+
if encoded != encoded2 {
50+
t.Errorf("failed to roundtrip color %v: expected %d but got %d", c, encoded, encoded2)
51+
}
52+
if encoded != encoded3 {
53+
t.Errorf("failed to roundtrip color %v: expected %d but got %d", c, encoded, encoded3)
54+
}
55+
c2 := encoded2.RGBA()
56+
if c2 != c {
57+
t.Errorf("failed to roundtrip color: expected %v but got %v", c, c2)
58+
}
59+
c3 := encoded3.RGBA()
60+
if c3 != c {
61+
t.Errorf("failed to roundtrip color: expected %v but got %v", c, c3)
62+
}
63+
}
64+
}

0 commit comments

Comments
 (0)