ESP Emote GFX

Introduction

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

Features

• Images: Display images in RGB565A8 format
• Animations: GIF animations with ESP32 tools
• Fonts: LVGL fonts and FreeType TTF/OTF support
• 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 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

#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 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

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

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:

// 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

// 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

// 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:

# 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

// 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 (converts GIF files to EAF animation format):

// 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)

Timer System Operations

// 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:

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

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Contributing

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