Merge branch 'feat/add_h264_encoder_decoder_demo' into 'master'

feat(esp_h264): Add esp_h264 enocder and decoder example

Closes AUD-6406

See merge request espressif/esp-idf!39676

Author: suda-morris

examples/peripherals/.build-test-rules.yml

@@ -87,6 +87,13 @@ examples/peripherals/gpio/matrix_keyboard:
   enable:
     - if: IDF_TARGET == "esp32s2"
 
+examples/peripherals/h264:
+  enable:
+    - if: IDF_TARGET in ["esp32p4", "esp32s3"]
+      reason: only supports esp32p4 and esp32s3
+  depends_components:
+    - esp_h264
+
 examples/peripherals/i2c/i2c_basic:
   disable:
     - if: SOC_I2C_SUPPORTED != 1

examples/peripherals/h264/CMakeLists.txt

@@ -0,0 +1,7 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists.txt file.
+
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(esp_h264_example)

examples/peripherals/h264/README.md

@@ -0,0 +1,153 @@
+| Supported Targets | ESP32-P4 | ESP32-S3 |
+| ----------------- | -------- | -------- |
+
+# H.264 Encoder-Decoder Example
+
+## Overview
+
+This example demonstrates how to use H.264 hardware/software encoder and decoder with visual pattern generation:
+
+- Generate colorful test patterns for video processing
+- Encode video frames using H.264 codec (hardware on ESP32-P4, software on ESP32-S3)
+- Decode the encoded frames back to original format using software decoder
+- Display visual comparison between source and decoded images
+
+The example supports multiple YUV formats and provides side-by-side colorized display in the console. All encoding parameters are configurable through the ESP-IDF menuconfig system.
+
+## Configuration
+
+This example provides comprehensive configuration options through `idf.py menuconfig`:
+
+### H.264 Encoder Type Selection
+- **Hardware Encoder**: Available only on ESP32-P4, provides better performance and lower power consumption
+- **Software Encoder**: Available on all targets (ESP32-S3, ESP32-P4), uses more CPU resources
+
+### Configurable Parameters
+All parameters can be adjusted in "H.264 Example Configuration" menu:
+
+- **Video Width**: 64-1920 pixels (default: 320)
+- **Video Height**: 64-1080 pixels (default: 240) 
+- **Frame Rate**: 1-60 fps (default: 30 for hardware, 15 for software)
+- **Bitrate**: 64K-10M bps (default: 512K for hardware, 256K for software)
+- **GOP Size**: 1-255 frames (default: 30)
+- **QP Value**: 10-51 (default: 26 for hardware, 28 for software)
+
+### Target-Specific Defaults
+- **ESP32-P4**: Optimized for hardware encoding with higher performance settings
+- **ESP32-S3**: Optimized for software encoding with conservative settings
+
+## How to use example
+
+### Prerequisites Required
+
+This example requires:
+- ESP32-P4 development board (for hardware encoding) or ESP32-S3 development board (for software encoding)
+- USB cable for programming and power supply
+- Terminal that supports ANSI color codes for proper visual output
+
+### Configure the Example
+
+Before building, configure the example parameters:
+
+```bash
+idf.py menuconfig
+```
+
+Navigate to: `Component config` → `H.264 Example Configuration`
+
+1. **Select Encoder Type**: Choose between Hardware (ESP32-P4 only) or Software encoder
+2. **Adjust Parameters**: Configure video resolution, frame rate, bitrate, etc.
+3. **Save and Exit**: Press 'S' to save configuration
+
+### Build and Flash
+
+For ESP32-P4 (with hardware encoding support):
+```bash
+idf.py set-target esp32p4
+idf.py menuconfig  # Configure as needed
+idf.py build
+idf.py -p PORT flash monitor
+```
+
+For ESP32-S3 (software encoding only):
+```bash
+idf.py set-target esp32s3
+idf.py menuconfig  # Software encoder will be automatically selected
+idf.py build
+idf.py -p PORT flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```bash
+I (1555) H264_ENC_DEC: H264 Example starting: 320x240 @ 30fps
+I (1565) H264_ENC_DEC: Encoder: Hardware, Decoder: Software
+I (1575) H264_ENC_DEC: Config: GOP=30, Bitrate=512000 bps, QP=26
+I (1585) H264_DEC.SW: tinyh264 version: 1c7f584
+I (1585) H264_ENC_DEC: H264 encode-decode loop started (320x240 @ 30fps)
+
+Frame 0: source image             |            decoded image
+[Colorized bar patterns displayed side by side using ANSI colors]
+
+Frame 1: source image             |            decoded image
+[Colorized bar patterns displayed side by side using ANSI colors]
+
+Frame 2: source image             |            decoded image
+[Colorized bar patterns displayed side by side using ANSI colors]
+...
+
+I (21465) H264_ENC_DEC: H264 process Completed successfully
+I (21475) main_task: Returned from app_main()
+```
+
+*Note: The exact values shown will depend on your menuconfig settings.*
+
+## Video Format Support
+
+- **ESP_H264_RAW_FMT_I420**: Planar YUV 4:2:0 format (decoder output, software encoder input)
+- **ESP_H264_RAW_FMT_O_UYY_E_VYY**: Interlaced YUV format (hardware encoder input on ESP32-P4)
+
+## Performance Recommendations
+
+### For ESP32-P4 (Hardware Encoding):
+- Resolution: Up to 1920x1080 supported
+- Frame Rate: 30-60 fps achievable
+- Bitrate: 512K-5M bps recommended
+- QP: 20-30 for optimal quality/performance balance
+
+### For ESP32-S3 (Software Encoding):
+- Resolution: 320x240 or smaller recommended
+- Frame Rate: 10-15 fps for stable performance  
+- Bitrate: 256K-1M bps recommended
+- QP: 28-35 for better performance
+
+## Troubleshooting
+
+**Configuration Issues:**
+- Use `idf.py menuconfig` to verify H.264 settings before building
+- Ensure hardware encoder is only selected for ESP32-P4 target
+
+**Memory allocation failures:**
+- Reduce resolution or frame rate in menuconfig
+- Ensure sufficient SPIRAM is available
+- Check ESP-IDF memory configuration
+
+**Encoding/decoding errors:**
+- Verify the correct target is selected (ESP32-P4 for hardware)
+- Check that H.264 component is properly configured in menuconfig
+- Adjust bitrate settings for your resolution/frame rate combination
+
+**Performance Issues:**
+- Lower resolution, frame rate, or bitrate for software encoding
+- Use hardware encoder on ESP32-P4 for better performance
+- Increase QP value to reduce computational load
+
+**Visual output issues:**
+- Ensure your terminal supports ANSI color codes
+- Try different terminal applications if colors don't display properly
+
+(For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you as soon as possible.)

examples/peripherals/h264/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRC_DIRS "./"
+                       INCLUDE_DIRS "./")

examples/peripherals/h264/main/Kconfig.projbuild

@@ -0,0 +1,96 @@
+menu "H.264 Example Configuration"
+
+    choice H264_ENCODER_TYPE
+        prompt "H.264 Encoder Type"
+        default H264_ENCODER_HARDWARE if IDF_TARGET_ESP32P4
+        default H264_ENCODER_SOFTWARE
+        help
+            Select the H.264 encoder type to use.
+            Hardware encoder is only available on ESP32P4 and provides
+            better performance and lower power consumption.
+            Software encoder is available on all targets but requires
+            more CPU resources.
+
+        config H264_ENCODER_HARDWARE
+            bool "Hardware Encoder (ESP32P4 only)"
+            depends on IDF_TARGET_ESP32P4
+            help
+                Use hardware H.264 encoder.
+                This option is only available on ESP32P4 which has
+                dedicated H.264 hardware encoding capabilities.
+                Provides better performance and lower power consumption
+                compared to software encoding.
+
+        config H264_ENCODER_SOFTWARE
+            bool "Software Encoder"
+            help
+                Use software H.264 encoder using OpenH264 library.
+                Available on all supported targets (ESP32S3, ESP32P4)
+                but requires more CPU resources and power consumption
+                compared to hardware encoding.
+    endchoice
+
+    menu "H.264 Encoder Parameters"
+
+        config H264_ENCODER_WIDTH
+            int "Video Width"
+            range 64 1920
+            default 320
+            help
+                Video frame width in pixels.
+                Must be multiple of 16 for optimal performance.
+                Recommended values: 128, 160, 320, 640, 1280.
+
+        config H264_ENCODER_HEIGHT
+            int "Video Height"
+            range 64 1080
+            default 240
+            help
+                Video frame height in pixels.
+                Must be multiple of 16 for optimal performance.
+                Recommended values: 96, 120, 240, 480, 720.
+
+        config H264_ENCODER_FPS
+            int "Frame Rate (FPS)"
+            range 1 60
+            default 30 if H264_ENCODER_HARDWARE
+            default 15 if H264_ENCODER_SOFTWARE
+            help
+                Video frame rate in frames per second.
+                Hardware encoder can support higher frame rates.
+                Software encoder performance depends on CPU capability.
+
+        config H264_ENCODER_BITRATE
+            int "Bitrate (bps)"
+            range 64000 10000000
+            default 512000 if H264_ENCODER_HARDWARE
+            default 256000 if H264_ENCODER_SOFTWARE
+            help
+                Video bitrate in bits per second.
+                Higher bitrate provides better quality but larger file size.
+                Hardware encoder can handle higher bitrates more efficiently.
+                Typical values: 256K-1M for low quality, 1M-5M for high quality.
+
+        config H264_ENCODER_GOP_SIZE
+            int "GOP Size"
+            range 1 255
+            default 30
+            help
+                Group of Pictures size. Determines the frequency
+                of I-frames in the video stream.
+                Larger GOP size = better compression, higher latency.
+                Smaller GOP size = lower compression, lower latency.
+
+        config H264_ENCODER_QP_VALUE
+            int "Quantization Parameter (QP)"
+            range 10 51
+            default 26 if H264_ENCODER_HARDWARE
+            default 28 if H264_ENCODER_SOFTWARE
+            help
+                Quantization parameter that controls video quality.
+                Lower values = higher quality, larger file size.
+                Higher values = lower quality, smaller file size.
+                Hardware encoder can handle lower QP values more efficiently.
+
+    endmenu
+endmenu