[dma] Refactor common parts of PlatformDMA implementations (#4)

Author: stuartparmenter

components/hub75/CMakeLists.txt

@@ -7,6 +7,7 @@ idf_component_register(
         "src/color/color_lut.cpp"
         "src/color/color_convert.cpp"
         "src/platforms/platform_detect.cpp"
+        "src/platforms/platform_dma.cpp"
         "src/drivers/fm6126a.cpp"
         # Platform-specific sources added conditionally below
     INCLUDE_DIRS

components/hub75/README.md

@@ -140,11 +140,12 @@ Double buffering doubles memory usage but enables tear-free animation. PARLIO us
 - `void set_brightness(uint8_t brightness)` - Set display brightness (0-255)
 - `void set_intensity(float intensity)` - Set intensity multiplier (0.0-1.0) for smooth dimming
 - `uint8_t get_brightness()` - Get current brightness value
-- `void set_gamma_mode(Hub75GammaMode mode)` - Set gamma correction mode
-  - `Hub75GammaMode::NONE` - No gamma correction (linear)
-  - `Hub75GammaMode::CIE1931` - CIE 1931 standard (recommended)
-  - `Hub75GammaMode::GAMMA_2_2` - Gamma 2.2 correction
-- `Hub75GammaMode get_gamma_mode()` - Get current gamma mode
+
+**Gamma Correction:**
+Gamma correction mode is set at initialization via `config.gamma_mode` and cannot be changed at runtime:
+- `Hub75GammaMode::NONE` - No gamma correction (linear)
+- `Hub75GammaMode::CIE1931` - CIE 1931 standard (recommended, default)
+- `Hub75GammaMode::GAMMA_2_2` - Gamma 2.2 correction
 
 **Dual-Mode Brightness System:**
 - **Basis brightness** (0-255): Adjusts hardware OE (output enable) timing in DMA buffers

components/hub75/include/hub75.h

@@ -149,18 +149,6 @@ class Hub75Driver {
    */
   void set_intensity(float intensity);
 
-  /**
-   * @brief Set gamma correction mode
-   * @param mode Gamma mode
-   */
-  void set_gamma_mode(Hub75GammaMode mode);
-
-  /**
-   * @brief Get current gamma mode
-   * @return Current gamma mode
-   */
-  Hub75GammaMode get_gamma_mode() const;
-
   // ========================================================================
   // Information
   // ========================================================================
@@ -187,15 +175,9 @@ class Hub75Driver {
   Hub75Config config_;
   bool running_;
 
-  // Color conversion LUTs
-  const uint16_t *lut_;
-
   // Platform-specific DMA engine
   hub75::PlatformDma *dma_;
 
-  // Helper methods
-  void initialize_lut_();
-
   HUB75_IRAM inline size_t get_pixel_offset_(uint16_t x, uint16_t y) const {
     // Total width includes all panels in layout
     return (y * (config_.panel_width * config_.layout_cols)) + x;

components/hub75/src/color/color_convert.h

@@ -10,7 +10,9 @@
 #pragma once
 
 #include "hub75_config.h"
+#include "hub75_types.h"  // For Hub75PixelFormat, Hub75ColorOrder
 #include <stdint.h>
+#include <stddef.h>  // For size_t
 
 namespace hub75 {
 
@@ -40,6 +42,93 @@ HUB75_CONST HUB75_IRAM inline constexpr uint8_t scale_5bit_to_8bit(uint8_t val5)
  */
 HUB75_CONST HUB75_IRAM inline constexpr uint8_t scale_6bit_to_8bit(uint8_t val6) { return (val6 << 2) | (val6 >> 4); }
 
+// ============================================================================
+// Pixel Format Extraction
+// ============================================================================
+
+/**
+ * @brief Extract RGB888 values from various pixel formats
+ *
+ * Handles RGB565, RGB888, and RGB888_32 formats with endianness and color order.
+ * This is a hot-path function used in draw_pixels() implementations.
+ *
+ * @param buffer Source pixel buffer
+ * @param pixel_idx Index of pixel to extract (not byte offset)
+ * @param format Pixel format (RGB565, RGB888, or RGB888_32)
+ * @param color_order Color component order (RGB or BGR, for RGB888_32 only)
+ * @param big_endian True if buffer is big-endian
+ * @param r8 Output: 8-bit red component (0-255)
+ * @param g8 Output: 8-bit green component (0-255)
+ * @param b8 Output: 8-bit blue component (0-255)
+ */
+HUB75_IRAM inline void extract_rgb888_from_format(const uint8_t *buffer, size_t pixel_idx, Hub75PixelFormat format,
+                                                  Hub75ColorOrder color_order, bool big_endian, uint8_t &r8,
+                                                  uint8_t &g8, uint8_t &b8) {
+  switch (format) {
+    case Hub75PixelFormat::RGB565: {
+      // 16-bit RGB565
+      const uint8_t *p = buffer + (pixel_idx * 2);
+      uint16_t rgb565;
+      if (big_endian) {
+        rgb565 = (uint16_t(p[0]) << 8) | p[1];
+      } else {
+        rgb565 = (uint16_t(p[1]) << 8) | p[0];
+      }
+
+      // Extract RGB565 components
+      const uint8_t r5 = (rgb565 >> 11) & 0x1F;
+      const uint8_t g6 = (rgb565 >> 5) & 0x3F;
+      const uint8_t b5 = rgb565 & 0x1F;
+
+      // Scale to 8-bit using color conversion helpers
+      r8 = scale_5bit_to_8bit(r5);
+      g8 = scale_6bit_to_8bit(g6);
+      b8 = scale_5bit_to_8bit(b5);
+      break;
+    }
+
+    case Hub75PixelFormat::RGB888: {
+      // 24-bit packed RGB
+      const uint8_t *p = buffer + (pixel_idx * 3);
+      r8 = p[0];
+      g8 = p[1];
+      b8 = p[2];
+      break;
+    }
+
+    case Hub75PixelFormat::RGB888_32: {
+      // 32-bit RGB with padding
+      const uint8_t *p = buffer + (pixel_idx * 4);
+      if (color_order == Hub75ColorOrder::RGB) {
+        if (big_endian) {
+          // Big-endian xRGB: [x][R][G][B]
+          r8 = p[1];
+          g8 = p[2];
+          b8 = p[3];
+        } else {
+          // Little-endian xRGB stored as BGRx: [B][G][R][x]
+          r8 = p[2];
+          g8 = p[1];
+          b8 = p[0];
+        }
+      } else {  // BGR
+        if (big_endian) {
+          // Big-endian xBGR: [x][B][G][R]
+          r8 = p[3];
+          g8 = p[2];
+          b8 = p[1];
+        } else {
+          // Little-endian xBGR stored as RGBx: [R][G][B][x]
+          r8 = p[0];
+          g8 = p[1];
+          b8 = p[2];
+        }
+      }
+      break;
+    }
+  }
+}
+
 // ============================================================================
 // Compile-Time Validation
 // ============================================================================

components/hub75/src/core/hub75_driver.cpp

@@ -42,7 +42,7 @@ using PlatformDMAImpl = ParlioDma;
 // Constructor / Destructor
 // ============================================================================
 
-Hub75Driver::Hub75Driver(const Hub75Config &config) : config_(config), running_(false), lut_(nullptr), dma_(nullptr) {
+Hub75Driver::Hub75Driver(const Hub75Config &config) : config_(config), running_(false), dma_(nullptr) {
   ESP_LOGI(TAG, "Driver created for %s (%s)", getPlatformName(), getDMAEngineName());
   ESP_LOGI(TAG, "Panel: %dx%d, Layout: %dx%d, Virtual: %dx%d", (unsigned int) config_.panel_width,
            (unsigned int) config_.panel_height, (unsigned int) config_.layout_cols, (unsigned int) config_.layout_rows,
@@ -80,9 +80,6 @@ bool Hub75Driver::begin() {
     return false;
   }
 
-  // Initialize color LUT
-  initialize_lut_();
-
   // Initialize shift driver chips (panel-level, platform-agnostic)
   // Must happen before DMA starts transmitting data
   esp_err_t err = DriverInit::initialize(config_);
@@ -98,9 +95,6 @@ bool Hub75Driver::begin() {
     return false;
   }
 
-  // Pass LUT for gamma correction during pixel writes
-  dma_->set_lut(lut_);
-
   // Start DMA transfer
   dma_->start_transfer();
 
@@ -191,13 +185,6 @@ void Hub75Driver::set_intensity(float intensity) {
   }
 }
 
-void Hub75Driver::set_gamma_mode(Hub75GammaMode mode) {
-  config_.gamma_mode = mode;
-  initialize_lut_();  // Regenerate LUT
-}
-
-Hub75GammaMode Hub75Driver::get_gamma_mode() const { return config_.gamma_mode; }
-
 // ============================================================================
 // Information
 // ============================================================================
@@ -213,16 +200,3 @@ uint16_t Hub75Driver::get_height() const {
 }
 
 bool Hub75Driver::is_running() const { return running_; }
-
-// ============================================================================
-// Private Helper Methods
-// ============================================================================
-
-void Hub75Driver::initialize_lut_() {
-  lut_ = get_lut(config_.gamma_mode, config_.bit_depth);
-  ESP_LOGI(TAG, "Initialized %s LUT for %d-bit depth",
-           config_.gamma_mode == Hub75GammaMode::CIE1931     ? "CIE1931"
-           : config_.gamma_mode == Hub75GammaMode::GAMMA_2_2 ? "Gamma2.2"
-                                                             : "Linear",
-           config_.bit_depth);
-}

components/hub75/src/platforms/gdma/gdma_dma.cpp

@@ -62,7 +62,7 @@ constexpr uint16_t RGB_LOWER_MASK = (1 << R2_BIT) | (1 << G2_BIT) | (1 << B2_BIT
 constexpr uint16_t RGB_MASK = RGB_UPPER_MASK | RGB_LOWER_MASK;  // 0x003F
 
 GdmaDma::GdmaDma(const Hub75Config &config)
-    : config_(config),
+    : PlatformDma(config),
       dma_chan_(nullptr),
       bit_depth_(config.bit_depth),
       lsbMsbTransitionBit_(0),
@@ -85,8 +85,7 @@ GdmaDma::GdmaDma(const Hub75Config &config)
       active_idx_(0),
       descriptor_count_(0),
       basis_brightness_(config.brightness),  // Use config value (default: 128)
-      intensity_(1.0f),
-      lut_(nullptr) {
+      intensity_(1.0f) {
   // Zero-copy architecture: DMA buffers ARE the display memory
   // Note: panel_width_, etc. will be set in init()
 }
@@ -466,8 +465,6 @@ void GdmaDma::set_intensity(float intensity) {
 // Pixel API (Direct DMA Buffer Writes)
 // ============================================================================
 
-void GdmaDma::set_lut(const uint16_t *lut) { lut_ = lut; }
-
 HUB75_IRAM void GdmaDma::draw_pixels(uint16_t x, uint16_t y, uint16_t w, uint16_t h, const uint8_t *buffer,
                                      Hub75PixelFormat format, Hub75ColorOrder color_order, bool big_endian) {
   // Always write to active buffer (CPU drawing buffer)
@@ -496,102 +493,19 @@ HUB75_IRAM void GdmaDma::draw_pixels(uint16_t x, uint16_t y, uint16_t w, uint16_
       uint16_t px = x + dx;
       uint16_t py = y + dy;
 
-      // ============================================================
-      // COORDINATE TRANSFORMATION PIPELINE
-      // ============================================================
-
-      Coords c = {.x = px, .y = py};
-
-      // Step 1: Panel layout remapping (if multi-panel grid)
-      if (needs_layout_remap_) {
-        c = PanelLayoutRemap::remap(c, layout_, panel_width_, panel_height_, layout_rows_, layout_cols_);
-      }
-
-      // Step 2: Scan pattern remapping (if non-standard panel)
-      if (needs_scan_remap_) {
-        c = ScanPatternRemap::remap(c, scan_wiring_, panel_width_);
-      }
-
-      // Use transformed coordinates for DMA buffer writes
-      px = c.x;
-      py = c.y;
-
-      // Debug assertions - automatically disabled in release builds
-      assert(px < dma_width_ && "Transformed X exceeds DMA buffer width!");
-      assert(py < panel_height_ && "Transformed Y exceeds row buffer height!");
-
-      const uint16_t row = py % (panel_height_ / 2);
-      const bool is_lower = (py >= panel_height_ / 2);
+      // Coordinate transformation pipeline (layout + scan remapping)
+      auto transformed =
+          transform_coordinate(px, py, needs_layout_remap_, needs_scan_remap_, layout_, scan_wiring_, panel_width_,
+                               panel_height_, layout_rows_, layout_cols_, dma_width_, num_rows_);
+      px = transformed.x;
+      const uint16_t row = transformed.row;
+      const bool is_lower = transformed.is_lower;
 
       const size_t pixel_idx = (dy * w) + dx;
       uint8_t r8 = 0, g8 = 0, b8 = 0;
 
-      // Extract RGB based on format
-      switch (format) {
-        case Hub75PixelFormat::RGB565: {
-          // 16-bit RGB565
-          const uint8_t *p = buffer + (pixel_idx * 2);
-          uint16_t rgb565;
-          // No endianness hint - LVGL default is big-endian, ESP32-native is little-endian
-          if (big_endian) {
-            rgb565 = (uint16_t(p[0]) << 8) | p[1];
-          } else {
-            rgb565 = (uint16_t(p[1]) << 8) | p[0];
-          }
-
-          // Extract RGB565 components
-          const uint8_t r5 = (rgb565 >> 11) & 0x1F;
-          const uint8_t g6 = (rgb565 >> 5) & 0x3F;
-          const uint8_t b5 = rgb565 & 0x1F;
-
-          // Scale to 8-bit using color conversion helpers
-          r8 = scale_5bit_to_8bit(r5);
-          g8 = scale_6bit_to_8bit(g6);
-          b8 = scale_5bit_to_8bit(b5);
-          break;
-        }
-
-        case Hub75PixelFormat::RGB888: {
-          // 24-bit packed RGB
-          const uint8_t *p = buffer + (pixel_idx * 3);
-          r8 = p[0];
-          g8 = p[1];
-          b8 = p[2];
-          break;
-        }
-
-        case Hub75PixelFormat::RGB888_32: {
-          // 32-bit RGB with padding
-          const uint8_t *p = buffer + (pixel_idx * 4);
-          if (color_order == Hub75ColorOrder::RGB) {
-            // No endianness hint - split between LVGL default and ESP32-native
-            if (big_endian) {
-              // Big-endian xRGB: [x][R][G][B]
-              r8 = p[1];
-              g8 = p[2];
-              b8 = p[3];
-            } else {
-              // Little-endian xRGB stored as BGRx: [B][G][R][x]
-              r8 = p[2];
-              g8 = p[1];
-              b8 = p[0];
-            }
-          } else {  // BGR
-            if (big_endian) {
-              // Big-endian xBGR: [x][B][G][R]
-              r8 = p[3];
-              g8 = p[2];
-              b8 = p[1];
-            } else {
-              // Little-endian xBGR stored as RGBx: [R][G][B][x]
-              r8 = p[0];
-              g8 = p[1];
-              b8 = p[2];
-            }
-          }
-          break;
-        }
-      }
+      // Extract RGB888 from pixel format
+      extract_rgb888_from_format(buffer, pixel_idx, format, color_order, big_endian, r8, g8, b8);
 
       // Apply LUT correction
       const uint16_t r_corrected = lut_[r8];

components/hub75/src/platforms/gdma/gdma_dma.h

@@ -71,11 +71,6 @@ class GdmaDma : public PlatformDma {
   void draw_pixels(uint16_t x, uint16_t y, uint16_t w, uint16_t h, const uint8_t *buffer, Hub75PixelFormat format,
                    Hub75ColorOrder color_order, bool big_endian) override;
 
-  /**
-   * @brief Set gamma correction LUT
-   */
-  void set_lut(const uint16_t *lut) override;
-
   /**
    * @brief Clear all pixels to black
    */
@@ -120,7 +115,6 @@ class GdmaDma : public PlatformDma {
   // BCM timing calculation (calculates lsbMsbTransitionBit for OE control)
   void calculate_bcm_timings();
 
-  const Hub75Config config_;
   gdma_channel_handle_t dma_chan_;
   const uint8_t bit_depth_;      // Bit depth from config (6, 7, 8, 10, or 12)
   uint8_t lsbMsbTransitionBit_;  // BCM optimization threshold (calculated at init)
@@ -158,9 +152,6 @@ class GdmaDma : public PlatformDma {
   // Brightness control (implementation of base class interface)
   uint8_t basis_brightness_;  // 1-255
   float intensity_;           // 0.0-1.0
-
-  // Gamma correction LUT (owned by Hub75Driver, just a pointer here)
-  const uint16_t *lut_;
 };
 
 }  // namespace hub75