Перейти к содержанию

Обзор архитектуры DrawZero

Этот документ объясняет, как устроен DrawZero, не раскрывая низкоуровневые детали реализации. Он помогает участникам проекта понимать зоны ответственности и при этом сохранять простой публичный API для учащихся.

Публичный интерфейс

Все функции библиотеки переэкспортируются, поэтому достаточно одного импорта:

from drawzero import *

Этот вызов открывает доступ к:

  • Функциям рисования line, circle, rect, polygon, text, image и их заполненным вариантам.
  • Помощникам для анимации и времени: run, tick, sleep, fps, quit.
  • Ввод: keyboard, mouse, events() и пространства констант K, M, MOD, E.
  • Утилитам: объекту screen в стиле Pygame Zero, вектору-"черепашке" Pt, построителю цветовых переходов Gradient, локализации через set_lang, цветовому пространству (C, COLORS, THECOLORS, ALL_COLORS), константам клавиатуры (K, KEY) и функции copy_examples() для копирования учебных примеров.
  • Настройке холста, включая set_virtual_size().

Все пользовательские руководства в документации используют именно такой стиль импорта.

Поток рендеринга

Каждая функция рисования проверяет и нормализует аргументы (координаты, углы, цвета, радиусы), а затем передает их активному рендереру. Выбор рендерера зависит от переменной окружения EJUDGE_MODE:

  • Если переменная не установлена или равна false, DrawZero открывает графическое окно на pygame и рисует напрямую на экране.
  • Если EJUDGE_MODE равна true (например, в автоматических проверяющих системах и CI), DrawZero переключается на текстовый режим и печатает сериализованные команды вместо открытия окна.

Независимо от выбранного режима, вызов tick() обрабатывает события окна, обновляет общие списки ввода и поддерживает анимацию на скорости около 30 FPS. Если пропускать tick(), новые события не попадут в программу, поэтому руководство подчеркивает необходимость вызывать его в каждом кадровом цикле.

Виртуальный холст и масштабирование координат

Библиотека работает с виртуальным холстом 1000×1000. Функции рисования принимают целые и дробные числа; значения приводятся к текущему виртуальному размеру и затем сопоставляются с реальными размерами окна. set_virtual_size() позволяет сценариям менять логическое разрешение, когда нужно использовать другую систему координат. Функции ввода мыши всегда возвращают позиции в тех же виртуальных координатах вне зависимости от физических размеров окна.

Утилиты и константы

Публичный API содержит несколько помощников, которые активно используются примерами и тестами:

  • Pt хранит позицию и направление, поддерживает движение в стиле "черепашки" и ведет себя как изменяемый 2D-вектор.
  • Gradient преобразует числа в цвета, интерполируя по списку образцов.
  • Цветовые пространства (C, COLORS, THECOLORS, ALL_COLORS) дают доступ к таблице цветов pygame без ручного ввода RGB-троек.
  • Константы клавиатуры K и KEY повторяют соглашения pygame, поэтому можно писать K.space, K.left и другие атрибуты как в GUI, так и в headless-режиме.
  • copy_examples() копирует встроенные примеры в рабочую директорию, помогая новичкам быстрее начать эксперименты.

Примеры и документация

В пакете есть двуязычные примеры, демонстрирующие примитивы, анимацию, градиенты, загрузку изображений и работу с клавиатурой/мышью. Документация MkDocs повторяет эти сценарии с подробными пояснениями. Тесты напрямую импортируют многие примеры, поэтому новые примеры должны избегать побочных эффектов при импорте, если только они не заключены в блок if __name__ == "__main__":.

Набор тестов

Автотесты покрывают функции рисования, градиенты, локализованные сообщения об ошибках, арифметику точек и импорт примеров. В непрерывной интеграции они запускаются как в графическом режиме, так и в текстовом (EJUDGE_MODE=true), чтобы убедиться, что публичный API ведет себя одинаково в обеих средах.

Кадры ввода

Опрос рендерера передаёт события общему обработчику, не зависящему от бэкенда. Публичный tick() или sleep() публикует один снимок после всех внутренних опросов. Запросы читают этот стабильный снимок. Данные событий фиксируют масштаб при получении; неизменяемые типизированные кортежи создаются и кешируются по запросу. Логические клавиши и физические сканкоды учитываются отдельно. Возвращение фокуса сверяет конечное удержание без новых переходов. См. руководство по вводу.