/*
 * face_animation.h — Face Emotion Renderer for LCD Display
 *
 * Renders expressive face animations for 5 core emotions:
 * - HAPPY: upturned eyes, curved smile
 * - SAD: downturned eyes, frown
 * - CURIOUS: raised eyebrows, wide eyes, slight tilt
 * - ANGRY: downturned brows, narrowed eyes, clenched mouth
 * - SLEEPING: closed eyes, relaxed mouth, gentle sway (optional)
 *
 * HOW IT WORKS:
 * - State machine with smooth transitions (easing over N frames)
 * - Idle behavior: periodic blinking (duration configurable)
 * - Each emotion has parameterized eye/mouth shapes (position, angle, curvature)
 * - Transitions interpolate between emotion parameter sets
 * - render() draws current state to LCD framebuffer via face_lcd_*() API
 * - tick() advances frame counter, handles transitions, triggers blink
 *
 * ANIMATION SPECS:
 * - Frame rate: 30 Hz (via systick)
 * - Transition time: 0.5–1.0s (15–30 frames)
 * - Blink duration: 100–150 ms (3–5 frames)
 * - Blink interval: 4–6 seconds (120–180 frames at 30Hz)
 *
 * API:
 *  - face_animation_init() — Initialize state machine
 *  - face_animation_set_emotion(emotion) — Request state change (with smooth transition)
 *  - face_animation_tick() — Advance animation by 1 frame (call at 30Hz from systick)
 *  - face_animation_render() — Draw current face to LCD framebuffer
 */

#ifndef FACE_ANIMATION_H
#define FACE_ANIMATION_H

#include <stdint.h>
#include <stdbool.h>

/* === Emotion Types === */
typedef enum {
    FACE_HAPPY    = 0,
    FACE_SAD      = 1,
    FACE_CURIOUS  = 2,
    FACE_ANGRY    = 3,
    FACE_SLEEPING = 4,
    FACE_NEUTRAL  = 5,  /* Default state */
} face_emotion_t;

/* === Animation Parameters (per emotion) === */
typedef struct {
    int16_t eye_x;              /* Eye horizontal offset from center (pixels) */
    int16_t eye_y;              /* Eye vertical offset from center (pixels) */
    int16_t eye_open_y;         /* Eye open height (pixels) */
    int16_t eye_close_y;        /* Eye close height (pixels, 0=fully closed) */
    int16_t brow_angle;         /* Eyebrow angle (-30..+30 degrees, tilt) */
    int16_t brow_y_offset;      /* Eyebrow vertical offset (pixels) */
    int16_t mouth_x;            /* Mouth horizontal offset (pixels) */
    int16_t mouth_y;            /* Mouth vertical offset (pixels) */
    int16_t mouth_width;        /* Mouth width (pixels) */
    int16_t mouth_curve;        /* Curvature: >0=smile, <0=frown, 0=neutral */
    uint8_t blink_interval_ms;  /* Idle blink interval (seconds, in 30Hz ticks) */
} face_params_t;

/* === Public API === */

/**
 * Initialize face animation system.
 * Sets initial emotion to NEUTRAL, clears blink timer.
 */
void face_animation_init(void);

/**
 * Request a state change to a new emotion.
 * Triggers smooth transition (easing) over TRANSITION_FRAMES.
 */
void face_animation_set_emotion(face_emotion_t emotion);

/**
 * Advance animation by one frame.
 * Called by systick ISR at 30 Hz.
 * Handles:
 *  - Transition interpolation
 *  - Blink timing and rendering
 *  - Idle animations (sway, subtle movements)
 */
void face_animation_tick(void);

/**
 * Render current face state to LCD framebuffer.
 * Draws eyes, brows, mouth, and optional idle animations.
 * Should be called after face_animation_tick().
 */
void face_animation_render(void);

/**
 * Get current emotion (transition-aware).
 * Returns the target emotion, or current if transition in progress.
 */
face_emotion_t face_animation_get_emotion(void);

/**
 * Trigger a blink immediately (for special events).
 * Overrides idle blink timer.
 */
void face_animation_blink_now(void);

/**
 * Check if animation is idle (no active transition).
 */
bool face_animation_is_idle(void);

#endif // FACE_ANIMATION_H