namespace RR.Common.Controls
{
    /// <summary>
    /// Абстрактный базовый класс для всех источников ввода в системе.
    /// Определяет унифицированный интерфейс для работы с аппаратными кнопками и виртуальными действиями игроков.
    /// </summary>
    /// <remarks>
    /// Наследники этого класса реализуют конкретные способы ввода:
    /// - COMinput: работа с периферийной платой через COM-порт
    /// - KeyboardInput: эмуляция ввода с клавиатуры для тестирования
    /// 
    /// Класс предоставляет три уровня абстракции:
    /// 1. Низкоуровневый доступ к физическим пинам
    /// 2. Доступ к абстрактным игровым действиям 
    /// 3. Мультиплеерные методы для работы с несколькими игроками
    /// </remarks>
    public abstract class InputSource
    {
        /// <summary>
        /// Инициализирует источник ввода. Должен быть вызван перед использованием других методов.
        /// </summary>
        /// <returns>true если инициализация прошла успешно, false в случае ошибки</returns>
        public abstract bool Initialize();

        //----------------------------------------------------------------------------------

        /// <summary>
        /// Получает текущее состояние конкретной кнопки по её физическому пину.
        /// </summary>
        /// <param name="button">Пин кнопки на периферийной плате</param>
        /// <returns>true если кнопка нажата в текущий момент</returns>
        public abstract bool GetButton(ButtonPinMapping button);

        /// <summary>
        /// Проверяет, была ли кнопка нажата в начале текущего кадра.
        /// </summary>
        /// <param name="button">Пин кнопки на периферийной плате</param>
        /// <returns>true только в первом кадре после нажатия кнопки</returns>
        public abstract bool GetButtonDown(ButtonPinMapping button);

        /// <summary>
        /// Проверяет, была ли кнопка отпущена в начале текущего кадра.
        /// </summary>
        /// <param name="button">Пин кнопки на периферийной плате</param>
        /// <returns>true только в первом кадре после отпускания кнопки</returns>
        public abstract bool GetButtonUp(ButtonPinMapping button);

        //----------------------------------------------------------------------------------

        /// <summary>
        /// Получает состояние кнопки по числовому индексу пина.
        /// Перегрузка для работы с системами, где количество пинов превышает размер перечисления.
        /// </summary>
        /// <param name="pinIndex">Числовой индекс пина (0-based)</param>
        /// <returns>true если кнопка нажата в текущий момент</returns>
        public abstract bool GetButton(int pinIndex);

        /// <summary>
        /// Проверяет нажатие кнопки по числовому индексу пина в текущем кадре.
        /// </summary>
        /// <param name="pinIndex">Числовой индекс пина (0-based)</param>
        /// <returns>true только в первом кадре после нажатия</returns>
        public abstract bool GetButtonDown(int pinIndex);

        /// <summary>
        /// Проверяет отпускание кнопки по числовому индексу пина в текущем кадре.
        /// </summary>
        /// <param name="pinIndex">Числовой индекс пина (0-based)</param>
        /// <returns>true только в первом кадре после отпускания</returns>
        public abstract bool GetButtonUp(int pinIndex);

        //----------------------------------------------------------------------------------

        /// <summary>
        /// Получает состояние игрового действия для любого из игроков.
        /// Используется для мультиплеерных сценариев где важно действие любого игрока.
        /// </summary>
        /// <param name="button">Абстрактное игровое действие</param>
        /// <returns>true если действие активно у первого ИЛИ второго игрока</returns>
        public abstract bool GetButtonAnyPlayer(PlayerAction button);

        /// <summary>
        /// Проверяет начало игрового действия любым игроком в текущем кадре.
        /// </summary>
        /// <param name="button">Абстрактное игровое действие</param>
        /// <returns>true если действие начато любым игроком в этом кадре</returns>
        public abstract bool GetButtonDownAnyPlayer(PlayerAction button);

        /// <summary>
        /// Проверяет завершение игрового действия любым игроком в текущем кадре.
        /// </summary>
        /// <param name="button">Абстрактное игровое действие</param>
        /// <returns>true если действие завершено любым игроком в этом кадре</returns>
        public abstract bool GetButtonUpAnyPlayer(PlayerAction button);

        //----------------------------------------------------------------------------------

        /// <summary>
        /// Получает состояние игрового действия для текущего активного игрока.
        /// Используется для одиночной игры или поочередного управления.
        /// </summary>
        /// <param name="button">Абстрактное игровое действие</param>
        /// <returns>true если действие активно у текущего игрока</returns>
        public abstract bool GetButtonCurrentPlayer(PlayerAction button);

        /// <summary>
        /// Проверяет начало игрового действия текущим игроком в текущем кадре.
        /// </summary>
        /// <param name="button">Абстрактное игровое действие</param>
        /// <returns>true если действие начато текущим игроком в этом кадре</returns>
        public abstract bool GetButtonDownCurrentPlayer(PlayerAction button);

        /// <summary>
        /// Проверяет завершение игрового действия текущим игроком в текущем кадре.
        /// </summary>
        /// <param name="button">Абстрактное игровое действие</param>
        /// <returns>true если действие завершено текущим игроком в этом кадре</returns>
        public abstract bool GetButtonUpCurrentPlayer(PlayerAction button);
    }
}