0
# Color Displays
1

2
16-bit color (5-6-5 RGB) OLED displays supporting full-color rendering with 65,536 colors. These displays provide vibrant graphics and images with hardware-accelerated color processing and framebuffer optimization.
3

4
## Capabilities
5

6
### SSD1331 Display
7

8
Serial interface to a 16-bit color SSD1331 OLED display with hardware acceleration for drawing primitives and color mode support.
9

10
```python { .api }
11
class ssd1331:
12
    def __init__(self, serial_interface=None, width=96, height=64, rotate=0, framebuffer=None, **kwargs):
13
        """
14
        Initialize SSD1331 color OLED display.
15

16
        Parameters:
17
        - serial_interface: Serial interface (usually luma.core.interface.serial.spi)
18
        - width: Number of horizontal pixels (default: 96)
19
        - height: Number of vertical pixels (default: 64)
20
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
21
        - framebuffer: Framebuffering strategy (diff_to_previous or full_frame)
22
        """
23

24
    def contrast(self, level):
25
        """
26
        Set display contrast level.
27

28
        Parameters:
29
        - level: Contrast level 0-255
30

31
        Note: Setting to low values may not dim display significantly.
32
        Not suitable for fade-in/out animations.
33
        """
34
```
35

36
**Supported Resolutions**: (96,64)
37

38
Usage example:
39

40
```python
41
from luma.core.interface.serial import spi
42
from luma.oled.device import ssd1331
43
from luma.core.render import canvas
44

45
# Initialize device with SPI
46
serial = spi(port=0, device=0, bus_speed_hz=8000000)
47
device = ssd1331(serial)
48

49
# Draw colorful content
50
with canvas(device) as draw:
51
    # RGB color tuples
52
    draw.rectangle((0, 0, 96, 64), fill=(0, 0, 255))      # Blue background
53
    draw.ellipse((10, 10, 86, 54), fill=(255, 0, 0))      # Red circle
54
    draw.text((20, 25), "Color!", fill=(255, 255, 255))    # White text
55

56
# Adjust contrast
57
device.contrast(128)  # Medium contrast
58
```
59

60
### SSD1351 Display
61

62
Serial interface to a 16-bit color SSD1351 OLED display with advanced features including BGR mode, offset support, and enhanced color management.
63

64
```python { .api }
65
class ssd1351:
66
    def __init__(self, serial_interface=None, width=128, height=128, rotate=0, framebuffer=None, h_offset=0, v_offset=0, bgr=False, **kwargs):
67
        """
68
        Initialize SSD1351 color OLED display.
69

70
        Parameters:
71
        - serial_interface: Serial interface (usually luma.core.interface.serial.spi)
72
        - width: Number of horizontal pixels (default: 128)
73
        - height: Number of vertical pixels (default: 128)
74
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
75
        - framebuffer: Framebuffering strategy (diff_to_previous or full_frame)
76
        - h_offset: Horizontal offset in pixels (default: 0)
77
        - v_offset: Vertical offset in pixels (default: 0)
78
        - bgr: Set to True for BGR pixel order instead of RGB (default: False)
79
        """
80

81
    def contrast(self, level):
82
        """
83
        Set display contrast level for all color channels.
84

85
        Parameters:
86
        - level: Contrast level 0-255
87
        """
88

89
    def command(self, cmd, *args):
90
        """
91
        Send command and optional arguments to the display.
92

93
        Parameters:
94
        - cmd: Command byte
95
        - args: Optional command arguments
96
        """
97
```
98

99
**Supported Resolutions**: (96,96), (128,128), (128,96)
100

101
Usage example:
102

103
```python
104
from luma.core.interface.serial import spi
105
from luma.oled.device import ssd1351
106
from luma.core.framebuffer import full_frame
107

108
# Initialize with custom settings
109
serial = spi(port=0, device=0, bus_speed_hz=8000000)
110
device = ssd1351(serial, width=128, height=128, 
111
                 framebuffer=full_frame(), bgr=False)
112

113
# Create gradient effect
114
with canvas(device) as draw:
115
    for i in range(128):
116
        color = (i * 2, 255 - i * 2, 128)
117
        draw.line([(i, 0), (i, 127)], fill=color)
118

119
# Fine-tune contrast
120
device.contrast(200)
121

122
# Send custom command
123
device.command(0xA6)  # Normal display mode
124
```
125

126
### Working with Color Images
127

128
Color displays support 24-bit RGB PIL Images which are automatically converted to 16-bit 5-6-5 RGB format:
129

130
```python
131
from PIL import Image
132

133
# Load and display a color image
134
img = Image.open("photo.jpg")
135
img = img.resize((128, 128))  # Resize to display dimensions
136
img = img.convert("RGB")      # Ensure RGB mode
137

138
# Display the image
139
device.display(img)
140

141
# Or use with canvas for overlay graphics
142
with canvas(device) as draw:
143
    draw.bitmap((0, 0), img)
144
    draw.text((10, 10), "Overlay Text", fill=(255, 255, 0))
145
```
146

147
## Performance Optimization
148

149
### Framebuffer Strategies
150

151
Color displays benefit significantly from framebuffer optimization:
152

153
```python
154
from luma.core.framebuffer import diff_to_previous, full_frame
155

156
# Default - only update changed pixels (recommended)
157
device1 = ssd1351(serial, framebuffer=diff_to_previous())
158

159
# Always update entire display
160
device2 = ssd1351(serial, framebuffer=full_frame())
161
```
162

163
### Color Format Optimization
164

165
The displays use 16-bit 5-6-5 RGB format internally:
166

167
```python
168
# Efficient color definitions (reduced precision)
169
RED = (248, 0, 0)      # Maps to 5-bit red
170
GREEN = (0, 252, 0)    # Maps to 6-bit green  
171
BLUE = (0, 0, 248)     # Maps to 5-bit blue
172

173
# These give the same result as full precision
174
RED_FULL = (255, 0, 0)
175
GREEN_FULL = (0, 255, 0)
176
BLUE_FULL = (0, 0, 255)
177
```
178

179
## Common Patterns
180

181
### Error Handling
182

183
```python
184
import luma.core.error
185

186
try:
187
    device = ssd1351(serial, width=200, height=200)
188
except luma.core.error.DeviceDisplayModeError as e:
189
    print(f"Unsupported resolution: {e}")
190
```
191

192
### BGR Mode Usage
193

194
Some displays have BGR pixel ordering:
195

196
```python
197
# For displays with BGR pixel order
198
device = ssd1351(serial, bgr=True)
199

200
# Colors will be automatically swapped
201
with canvas(device) as draw:
202
    draw.rectangle((0, 0, 50, 50), fill=(255, 0, 0))  # Still specify as RGB
203
```
204

205
### Display Offsets
206

207
Handle displays with memory offsets:
208

209
```python
210
# Display with offset positioning
211
device = ssd1351(serial, h_offset=16, v_offset=8)
212

213
# Drawing coordinates remain the same
214
with canvas(device) as draw:
215
    draw.text((0, 0), "Top Left")  # Automatically accounts for offset
216
```