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

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

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

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

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

from drawzero import *

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

  • Функциям рисования line, circle, rect, polygon, text, image и их заполненным вариантам.
  • Помощникам для анимации и времени: run, tick, sleep, fps, quit.
  • Вводу с клавиатуры и мыши: get_keys_pressed, keys_mods_pressed, get_mouse_pressed, а также общим спискам keysdown, keysup, mousemotions, mousebuttonsdown, mousebuttonsup.
  • Утилитам: объекту 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 ведет себя одинаково в обеих средах.