/** 
 * @file    virtual_led_ring.h
 * @brief   Virtual LED ring module to simulate visual effect of having more LEDs.
 * @author  Kenny Tran
 * @date    Nov 13 2025
 * @version 0.0.1
 *
 * @section LICENSES
 * Copyright (C) Morgan Advanced Programmable Systems, Inc.
 */


#ifndef VIRTUAL_LED_RING_H_
#define VIRTUAL_LED_RING_H_


/*--------------------------------------------------------------------------------------------------
 * INCLUDE FILES
 *------------------------------------------------------------------------------------------------*/
#include <stdint.h>

#include "../lib/errno.h"

#include "../bsp/led_ring.h"


/*--------------------------------------------------------------------------------------------------
 * MACROS & CONSTANTS
 *------------------------------------------------------------------------------------------------*/
/* Virtual resolution multiplier (e.g., 4x means 96 virtual positions for 24 physical LEDs). */
#define VIRTUAL_LED_RING_MULTIPLIER         (4)
#define VIRTUAL_LED_RING_PIXELS             (LED_RING_PIXELS * VIRTUAL_LED_RING_MULTIPLIER)

#define VIRTUAL_LED_RING_GAUSSIAN_WIDTH     (1.2f)      /* Adjust for wider/narrower blur.  */
#define VIRTUAL_LED_RING_COMET_TAIL_LENGTH  (4)         /* Number of trailing LEDs.         */
#define VIRTUAL_LED_RING_COMET_DECAY        (0.5f)      /* Brightness decay per LED.        */


/*--------------------------------------------------------------------------------------------------
 * TYPE DEFINITIONS & ENUMERATIONS
 *------------------------------------------------------------------------------------------------*/
typedef enum
{
    VIRTUAL_LED_RING_MODE_LINEAR,        /* Linear interpolation (2 LEDs)   */
    VIRTUAL_LED_RING_MODE_GAUSSIAN,      /* Gaussian blur (3-5 LEDs)        */
    VIRTUAL_LED_RING_MODE_COMET          /* Trailing comet effect           */
} VIRTUAL_LED_RING_mode_e;


/*--------------------------------------------------------------------------------------------------
 * PUBLIC FUNCTION PROTOTYPES
 *------------------------------------------------------------------------------------------------*/

/**
 * @brief Initialize the smooth LED ring (calls LED_RING_init internally)
 * @return ERRNO_e status code
 */
ERRNO_e VIRTUAL_LED_RING_init (void);

/**
 * @brief Set a virtual LED position with smooth interpolation
 * @param idx Virtual index (0 to VIRTUAL_LED_RING_PIXELS - 1)
 * @param r Red brightness (0-255)
 * @param g Green brightness (0-255)
 * @param b Blue brightness (0-255)
 * @param mode Smoothing mode to use
 * @return ERRNO_e status code
 */
ERRNO_e VIRTUAL_LED_RING_set (uint16_t idx, uint8_t r, uint8_t g, uint8_t b, VIRTUAL_LED_RING_mode_e mode);

/**
 * @brief Set a floating point position (more direct control)
 * @param position Floating point position (0.0 to LED_RING_PIXELS - 0.001)
 * @param r Red brightness (0-255)
 * @param g Green brightness (0-255)
 * @param b Blue brightness (0-255)
 * @param mode Smoothing mode to use
 * @return ERRNO_e status code
 */
ERRNO_e VIRTUAL_LED_RING_set_position (float position, uint8_t r, uint8_t g, uint8_t b, VIRTUAL_LED_RING_mode_e mode);

/**
 * @brief Clear all LEDs (wrapper for LED_RING_clear)
 * @return ERRNO_e status code
 */
ERRNO_e VIRTUAL_LED_RING_clear (void);

/**
 * @brief Update the LED ring display (wrapper for LED_RING_update)
 * @return ERRNO_e status code
 */
ERRNO_e VIRTUAL_LED_RING_update (void);

ERRNO_e VIRTUAL_LED_RING_enable (bool en);


#endif /* VIRTUAL_LED_RING_H_ */
