/**
 * ============================================================================
 * === SSD1306 128x64 IIC LCD Interface
 * ============================================================================
 * 
 * Provides a simple interface for rendering text to an SSD1306 LCD.
 * 
 * digimint
 */

#pragma once

#include "FontComicSansMS16.h"

#include <freertos/FreeRTOS.h>
#include <freertos/task.h>

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

// LCD target address
#define IIC_LCD_ADDR (0x3C)

#define LCD_TAG "LCD"

extern uint8_t LCD_data[8][128];
extern bool LCD_rowChanged[8];

/**
 * Initialize the LCD interface.
 * 
 * This command configures the IIC bus, sends the proper initialization commands
 * to the LCD, and spawns a task to update the display regularly.
 * 
 * @param updateTaskHandle If this variable is not NULL, a handle to the display
 *        update task will be stored in it.
 */
void LCD_init(TaskHandle_t* updateTaskHandle);


/**
 * Render a single character to the LCD buffer.
 * 
 * @warning This function does not perform bounds checking.
 * 
 * @param font The font to use for text rendering.
 * @param oChr The character to render.
 * @param x The x-coordinate for the top-left of the character.
 * @param y The y-coordinate for the top-left of the character.
 * @param invert Whether the character should be inverted before display.
 */
void LCD_renderChar(font_t font, const char oChr, uint16_t x, uint16_t y, bool invert);

/**
 * Render text to the LCD buffer.
 * 
 * @warning This function does not protect against buffer overrun.
 * 
 * @param font The font to use for text rendering.
 * @param str The text to render.
 * @param x The x-coordinate for the top-left of the first character.
 * @param y The y-coordinate for the top-left of the first character.
 * @param invert Whether the character should be inverted before display.
 */
void LCD_renderText(font_t font, const char* str, uint16_t x, uint16_t y, bool invert);

/**
 * Render text in Comic Sans
 * 
 * A convenience macro that expands to
 * 
 * `LCD_renderText(FontComicSansMS16, str, x, y);`
 */
static inline void LCD_renderTextCS(const char* str, uint16_t x, uint16_t y){
    LCD_renderText(FontComicSansMS16, str, x, y, false);
}

/**
 * Manually force an immediate update of the LCD.
 * 
 * Note that this function will be called automatically by the LCD update task
 * during normal operation, so it generally should not be manually invoked.
 * 
 * A semaphore is used to ensure that only one task attempts to communicate with
 * the display at a time.
 * 
 * @param block If true, then the calling task will block until the LCD is
 *        available for communication. Otherwise, if the LCD is not immediately
 *        available, the function will simply return `false`.
 * 
 * @return `true` if the LCD was successfully updated; `false` otherwise.
 * 
 * @note This function will only return false if two conditions apply:
 *       (1) `block` is false; and
 *       (2) The LCD semaphore has been taken (i.e. the LCD is currently busy)
 */
bool LCD_updateDisplay(bool block);