espressif2022/esp_emote_gfx

readme

# ESP Emote GFX

## Introduction
A lightweight graphics framework for ESP-IDF with support for images, labels, animations, and fonts.

[![Component Registry](https://components.espressif.com/components/espressif2022/esp_emote_gfx/badge.svg)](https://components.espressif.com/components/espressif2022/esp_emote_gfx)

## Features

- **Images**: Display images in RGB565A8 format
- **Animations**: GIF animations with [ESP32 tools](https://esp32-gif.espressif.com/)
- **Fonts**: LVGL fonts and FreeType TTF/OTF support
- **QR Codes**: Dynamic QR code generation and display
- **Timers**: Built-in timing system for smooth animations
- **Memory Optimized**: Designed for embedded systems

## Dependencies

1. **ESP-IDF**  
   Ensure your project includes ESP-IDF 5.0 or higher. Refer to the [ESP-IDF Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/) for setup instructions.

2. **FreeType**  
   This component depends on the FreeType library for font rendering.

3. **ESP New JPEG**  
   JPEG decoding support through the ESP New JPEG component.

## Usage

### Basic Setup

```c
#include "gfx.h"

// Initialize the GFX framework
gfx_core_config_t gfx_cfg = {
    .flush_cb = flush_callback,
    .h_res = BSP_LCD_H_RES,
    .v_res = BSP_LCD_V_RES,
    .fps = 50,
    // other configuration...
};
gfx_handle_t emote_handle = gfx_emote_init(&gfx_cfg);
```

For detailed widget usage and operations, see the [Widget Operations Reference](#widget-operations-reference) section below.


## Examples and Test Applications

For comprehensive widget usage examples, refer to the test applications in `esp_emote_gfx/test_apps/`. These examples demonstrate real-world usage patterns and advanced features.

### Running Test Examples

```bash
cd esp_emote_gfx/test_apps
idf.py build flash monitor
```

The test application includes the following widget demonstrations:

#### Timer Operations
- Creating and configuring timers
- Pausing, resuming, and resetting timers
- Setting repeat counts and periods
- Timer callback implementations

#### Animation Widget Examples
- Loading different animation formats (4-bit, 8-bit, 24-bit)
- Setting animation segments and playback control
- Mirror effects and positioning
- Multiple animation objects management

#### Label Widget Examples
- LVGL font rendering with Chinese text support
- FreeType font loading and usage
- Text formatting with `gfx_label_set_text_fmt()`
- Long text handling (scroll, wrap modes)
- Background colors and text styling

#### Image Widget Examples
- Loading C array format images
- Loading binary format images with headers
- Multiple image objects with different formats
- Image positioning and sizing

#### QR Code Widget Examples
- Creating QR codes with different data types
- Configuring error correction levels (LOW, MEDIUM, QUARTILE, HIGH)
- Customizing colors and sizes
- Centered display with automatic scaling

#### Multi-Object Scenarios
- Combining animations, images, and labels
- Object layering and interaction
- Resource management for multiple widgets
- Performance considerations

## Widget Operations Reference

### Common Object Operations

All widgets inherit from the base object system and support these common operations:

```c
// Object creation (replace 'widget' with img, label, or anim)
gfx_obj_t *obj = gfx_widget_create(emote_handle);

// Position and size
gfx_obj_set_pos(obj, x, y);                    // Set absolute position
gfx_obj_set_size(obj, width, height);          // Set size
gfx_obj_get_size(obj, &width, &height);        // Get current size

// Alignment
gfx_obj_align(obj, GFX_ALIGN_CENTER, x_offset, y_offset);
gfx_obj_align(obj, GFX_ALIGN_TOP_MID, 0, 10);
gfx_obj_align(obj, GFX_ALIGN_BOTTOM_LEFT, 5, -5);

// Visibility and cleanup
gfx_obj_set_hidden(obj, true);                 // Hide object
gfx_obj_set_hidden(obj, false);                // Show object
gfx_obj_delete(obj);                           // Delete object
```

### Label Widget Operations

```c
// Font management
gfx_label_set_font(label_obj, (gfx_font_t)&font_puhui_16_4);  // LVGL font

// FreeType font creation
gfx_label_cfg_t font_cfg = {
    .name = "DejaVuSans.ttf",
    .mem = font_data,
    .mem_size = font_size,
    .font_size = 20,
};
gfx_font_t freetype_font;
gfx_label_new_font(&font_cfg, &freetype_font);
gfx_label_set_font(label_obj, freetype_font);

// Text operations
gfx_label_set_text(label_obj, "Hello World");
gfx_label_set_text_fmt(label_obj, "Count: %d, Value: %.2f", 42, 3.14);

// Styling
gfx_label_set_color(label_obj, GFX_COLOR_HEX(0xFF0000));      // Text color
gfx_label_set_bg_color(label_obj, GFX_COLOR_HEX(0x00FF00));   // Background color
gfx_label_set_bg_enable(label_obj, true);                     // Enable background

// Long text handling
gfx_label_set_long_mode(label_obj, GFX_LABEL_LONG_WRAP);           // Wrap text
gfx_label_set_long_mode(label_obj, GFX_LABEL_LONG_SCROLL);        // Scroll text smoothly
gfx_label_set_long_mode(label_obj, GFX_LABEL_LONG_SCROLL_SNAP);   // Scroll with snap (paging)

// Scroll control (for GFX_LABEL_LONG_SCROLL)
gfx_label_set_scroll_step(label_obj, 2);                          // Set scroll speed (pixels per tick)

// Snap scroll control (for GFX_LABEL_LONG_SCROLL_SNAP)
gfx_label_set_snap_interval(label_obj, 2000);                     // Stay 2 seconds per section
gfx_label_set_snap_loop(label_obj, true);                          // Enable continuous looping

// Cleanup
gfx_label_delete_font(freetype_font);  // Delete FreeType font when done
```

### Image Widget Operations

The framework supports RGB565A8 format images, which provide 16-bit RGB color with 8-bit alpha transparency. This format is optimized for embedded systems with limited memory.

#### RGB565A8 Format Details

- **RGB565**: 16-bit color (5 bits red, 6 bits green, 5 bits blue)
- **Alpha8**: 8-bit alpha channel for transparency
- **Memory Layout**: RGB565 data followed by Alpha data
- **File Size**: Width × Height × 3 bytes per image

#### Converting PNG to RGB565A8

Use the provided conversion script to convert PNG images to RGB565A8 format:

```bash
# Convert single PNG file to C array format
python scripts/png_to_rgb565a8.py image.png

# Convert single PNG file to binary format
python scripts/png_to_rgb565a8.py image.png --bin

# Batch convert all PNG files in current directory to binary format
python scripts/png_to_rgb565a8.py ./ --bin

# Convert with byte swapping (for different endianness)
python scripts/png_to_rgb565a8.py ./ --bin --swap16

# Convert to specific output directory
python scripts/png_to_rgb565a8.py ./ --bin --output ./converted_images/
```

**Script Options:**
- `--bin`: Output binary format instead of C array format
- `--swap16`: Enable byte swapping for RGB565 data
- `--output`, `-o`: Specify output directory

#### Using RGB565A8 Images

```c
// Create an image object
gfx_obj_t *img_obj = gfx_img_create(emote_handle);

// Method 1: Using C array format (generated by script without --bin)
extern const gfx_image_dsc_t my_image;
gfx_img_set_src(img_obj, (void*)&my_image);

// Method 2: Using binary format (generated by script with --bin)
gfx_image_dsc_t img_dsc;
img_dsc.data_size = binary_data_size;
img_dsc.data = binary_data_ptr;
// Copy header from binary data
memcpy(&img_dsc.header, binary_data_ptr, sizeof(gfx_image_header_t));
img_dsc.data += sizeof(gfx_image_header_t);
img_dsc.data_size -= sizeof(gfx_image_header_t);
gfx_img_set_src(img_obj, (void*)&img_dsc);

// Set position and display
gfx_obj_set_pos(img_obj, 100, 100);

// The framework automatically handles:
// - Image format detection (C array vs binary)
// - Memory layout parsing
// - Size calculation from image header
```

### Animation Widget Operations

Create animations using the [ESP32 GIF animation tools](https://esp32-gif.espressif.com/) (converts GIF files to EAF animation format):

```c
// Create animation object
gfx_obj_t *anim_obj = gfx_anim_create(emote_handle);

// Load animation data
gfx_anim_set_src(anim_obj, anim_data, anim_size);
gfx_obj_set_size(anim_obj, 200, 150);

// Playback control
gfx_anim_set_segment(anim_obj, start_frame, end_frame, fps, loop);
gfx_anim_start(anim_obj);
gfx_anim_stop(anim_obj);

// Visual effects
gfx_anim_set_mirror(anim_obj, enable, offset);  // Manual mirror effect
gfx_anim_set_auto_mirror(anim_obj, enable);     // Auto mirror effect (automatic horizontal mirroring)
```

### QR Code Widget Operations

Generate and display QR codes dynamically:

```c
// Create QR code object
gfx_obj_t *qrcode_obj = gfx_qrcode_create(emote_handle);

// Set QR code data (text, URL, etc.)
gfx_qrcode_set_data(qrcode_obj, "https://www.espressif.com");

// Configure size (square, both width and height)
gfx_qrcode_set_size(qrcode_obj, 200);  // 200x200 pixels

// Set error correction level
gfx_qrcode_set_ecc(qrcode_obj, GFX_QRCODE_ECC_HIGH);  // Options: LOW, MEDIUM, QUARTILE, HIGH

// Customize colors
gfx_qrcode_set_color(qrcode_obj, GFX_COLOR_HEX(0x000000));      // Foreground (modules)
gfx_qrcode_set_bg_color(qrcode_obj, GFX_COLOR_HEX(0xFFFFFF));   // Background

// Position and display
gfx_obj_align(qrcode_obj, GFX_ALIGN_CENTER, 0, 0);

// The QR code is automatically centered if the display size doesn't match the scaled QR size
```

**Error Correction Levels:**
- `GFX_QRCODE_ECC_LOW`: ~7% error tolerance
- `GFX_QRCODE_ECC_MEDIUM`: ~15% error tolerance
- `GFX_QRCODE_ECC_QUARTILE`: ~25% error tolerance
- `GFX_QRCODE_ECC_HIGH`: ~30% error tolerance

**Note:** The QR code is automatically scaled and centered within the display size. If the display size cannot be evenly divided by the QR module size, the QR code will be centered with background color padding.

### Timer System Operations

```c
// Create timer callback
void timer_callback(void *user_data) {
    // Timer callback code
}

// Create and configure timer
gfx_timer_handle_t timer = gfx_timer_create(emote_handle, timer_callback, 1000, user_data);

// Control timer
gfx_timer_pause(timer);
gfx_timer_resume(timer);
gfx_timer_reset(timer);
gfx_timer_set_period(timer, new_period_ms);
gfx_timer_set_repeat_count(timer, count);

// Cleanup
gfx_timer_delete(emote_handle, timer);
```

### Thread Safety

All widget operations must be performed within the graphics lock:

```c
gfx_emote_lock(emote_handle);
// Perform widget operations here
gfx_obj_set_pos(obj, x, y);
gfx_label_set_text(label, "New text");
gfx_emote_unlock(emote_handle);
```

## API Reference

The main API is exposed through the `gfx.h` header file, which includes:

- `core/gfx_types.h` - Type definitions and constants
- `core/gfx_core.h` - Core graphics functions
- `core/gfx_timer.h` - Timer and timing utilities
- `core/gfx_obj.h` - Graphics object system
- `widget/gfx_img.h` - Image widget functionality
- `widget/gfx_label.h` - Label widget functionality
- `widget/gfx_anim.h` - Animation framework
- `widget/gfx_qrcode.h` - QR Code widget functionality

## License

This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit issues and enhancement requests.