Add support for 4-bit and 5-bit color depth (#42)

Extends the minimum supported bit depth from 6-bit to 4-bit, enabling
higher refresh rates on large panel arrays at the cost of reduced
color gradation.

Changes:
- Update static_assert in color_lut.h to allow BitDepth >= 4
- Add DEPTH_4 and DEPTH_5 options to Kconfig with descriptive help text
- Update documentation (COLOR_GAMMA.md, MENUCONFIG.md, README.md) with
  new bit depth options and use case guidance

Author: stuartparmenter

components/hub75/Kconfig

@@ -214,7 +214,9 @@ menu "HUB75 RGB LED Matrix Driver"
                 Higher bit depth = better color gradients but slower refresh rate.
                 Changes require full rebuild to regenerate LUT.
 
-                  - 6-bit: 64 levels/channel (fastest refresh)
+                  - 4-bit: 16 levels/channel (maximum refresh, limited colors)
+                  - 5-bit: 32 levels/channel
+                  - 6-bit: 64 levels/channel (fast refresh)
                   - 7-bit: 128 levels/channel
                   - 8-bit: 256 levels/channel (good balance)
                   - 9-bit: 512 levels/channel
@@ -224,8 +226,21 @@ menu "HUB75 RGB LED Matrix Driver"
 
                 Driver auto-adjusts BCM timing to maintain target refresh rate.
 
+            config DEPTH_4
+                bool "4-bit (Maximum Refresh)"
+                help
+                    16 levels per channel (4,096 total colors).
+                    Use for very large panel arrays where refresh rate is critical.
+                    Visible banding in gradients is expected.
+
+            config DEPTH_5
+                bool "5-bit"
+                help
+                    32 levels per channel (32,768 total colors).
+                    Good balance between refresh rate and color quality for large displays.
+
             config DEPTH_6
-                bool "6-bit (Fastest)"
+                bool "6-bit (Fast)"
 
             config DEPTH_7
                 bool "7-bit"
@@ -248,6 +263,8 @@ menu "HUB75 RGB LED Matrix Driver"
 
         config HUB75_BIT_DEPTH
             int
+            default 4 if DEPTH_4
+            default 5 if DEPTH_5
             default 6 if DEPTH_6
             default 7 if DEPTH_7
             default 8 if DEPTH_8

components/hub75/README.md

@@ -204,7 +204,7 @@ config.layout = Hub75PanelLayout::HORIZONTAL;
 
 **Higher quality display:**
 ```cpp
-// Bit depth: Configure via menuconfig (6-12 bit available)
+// Bit depth: Configure via menuconfig (4-12 bit available)
 // (idf.py menuconfig → HUB75 → Panel Settings → Bit Depth)
 config.double_buffer = true;   // Tear-free updates
 config.min_refresh_rate = 90;  // Smoother for cameras
@@ -218,7 +218,7 @@ config.rotation = Hub75Rotation::ROTATE_90;  // 90° clockwise
 ```
 
 **Bit Depth Configuration:**
-Bit depth is **compile-time only** (6-12 bits supported):
+Bit depth is **compile-time only** (4-12 bits supported):
 - Configure via `idf.py menuconfig` → HUB75 → Panel Settings → Bit Depth
 - Or CMake: `target_compile_definitions(app PRIVATE HUB75_BIT_DEPTH=10)`
 - Changes require full rebuild (regenerates LUT at compile time)

components/hub75/include/hub75_config.h

@@ -55,7 +55,7 @@ extern "C" {
 #endif
 
 /**
- * Bit depth configuration (6-12 bits)
+ * Bit depth configuration (4-12 bits)
  * Set via menuconfig or override: -DHUB75_BIT_DEPTH=10
  */
 #ifndef HUB75_BIT_DEPTH

components/hub75/src/color/color_lut.h

@@ -112,11 +112,11 @@ constexpr double cie1931(double lightness) {
 
 /**
  * @brief Generate CIE 1931 lookup table at compile time
- * @tparam BitDepth Target bit depth (6-12)
+ * @tparam BitDepth Target bit depth (4-12)
  * @return std::array of 256 values scaled to BitDepth range
  */
 template<uint8_t BitDepth> constexpr std::array<uint16_t, 256> generate_cie1931_lut() {
-  static_assert(BitDepth >= 6 && BitDepth <= 12, "Bit depth must be 6-12");
+  static_assert(BitDepth >= 4 && BitDepth <= 12, "Bit depth must be 4-12");
 
   constexpr uint16_t max_val = (1 << BitDepth) - 1;
   std::array<uint16_t, 256> lut{};
@@ -138,7 +138,7 @@ template<uint8_t BitDepth> constexpr std::array<uint16_t, 256> generate_cie1931_
  * @brief Generate Gamma 2.2 lookup table at compile time
  */
 template<uint8_t BitDepth> constexpr std::array<uint16_t, 256> generate_gamma22_lut() {
-  static_assert(BitDepth >= 6 && BitDepth <= 12, "Bit depth must be 6-12");
+  static_assert(BitDepth >= 4 && BitDepth <= 12, "Bit depth must be 4-12");
 
   constexpr uint16_t max_val = (1 << BitDepth) - 1;
   std::array<uint16_t, 256> lut{};
@@ -158,7 +158,7 @@ template<uint8_t BitDepth> constexpr std::array<uint16_t, 256> generate_gamma22_
  * @brief Generate Linear lookup table at compile time
  */
 template<uint8_t BitDepth> constexpr std::array<uint16_t, 256> generate_linear_lut() {
-  static_assert(BitDepth >= 6 && BitDepth <= 12, "Bit depth must be 6-12");
+  static_assert(BitDepth >= 4 && BitDepth <= 12, "Bit depth must be 4-12");
 
   constexpr uint16_t max_val = (1 << BitDepth) - 1;
   std::array<uint16_t, 256> lut{};

docs/COLOR_GAMMA.md

@@ -80,9 +80,12 @@ Driver uses **CIE 1931** by default (better for LEDs). Future: configurable gamm
 
 | Depth | Colors | Levels/Channel | Gradient Quality | Memory | Refresh Rate |
 |-------|--------|----------------|------------------|--------|--------------|
-| **8-bit** | 16.7M | 256 | Good | Baseline | Fast |
-| **10-bit** | 1.07B | 1024 | Better | +25% | Medium |
-| **12-bit** | 68.7B | 4096 | Best | +50% | Slower |
+| **4-bit** | 4K | 16 | Limited | -50% | Maximum |
+| **5-bit** | 32K | 32 | Basic | -37% | Very Fast |
+| **6-bit** | 262K | 64 | Acceptable | -25% | Fast |
+| **8-bit** | 16.7M | 256 | Good | Baseline | Medium |
+| **10-bit** | 1.07B | 1024 | Better | +25% | Slower |
+| **12-bit** | 68.7B | 4096 | Best | +50% | Slowest |
 
 ### Trade-offs
 
@@ -96,6 +99,17 @@ Driver uses **CIE 1931** by default (better for LEDs). Future: configurable gamm
 
 ### When to Use Each Depth
 
+**4-bit / 5-bit**:
+- Very large panel arrays where refresh rate is critical
+- Simple graphics, text displays, status indicators
+- Visible banding in gradients is expected
+- Maximum refresh rate for smooth animations on large displays
+
+**6-bit**:
+- Large multi-panel setups needing high refresh
+- Gaming displays, fast animations
+- Acceptable gradient quality with CIE 1931 correction
+
 **8-bit**:
 - General use, animations, gaming displays
 - Fast refresh (120+ Hz achievable)

docs/MENUCONFIG.md

@@ -141,6 +141,9 @@ Choose which example to build in main/:
 - **Type**: choice
 - **Default**: 8-bit
 - **Options**:
+  - `4-bit` - 16 levels/channel (maximum refresh, limited colors)
+  - `5-bit` - 32 levels/channel (very fast refresh)
+  - `6-bit` - 64 levels/channel (fast refresh)
   - `8-bit` - 256 levels/channel (good balance)
   - `10-bit` - 1024 levels/channel (better gradients)
   - `12-bit` - 4096 levels/channel (best quality)