Современная графика CANVAS

Холст и его кадры

На холсте программа сначала рисует рабочий кадр и затем показывает его оператором PRESENT. Такой порядок удобен для анимации, игровых сцен и подписей поверх изображения. Палитровое окно описано отдельно на странице SCREEN.

Одновременно активна одна поверхность: вызов CANVAS закрывает окно SCREEN, а вызов SCREEN закрывает холст.

В Electron IDE холст открывается в отдельном нативном окне DirectX. Среда автоматически использует доступный графический процессор, включая встроенную графику; если аппаратное устройство создать нельзя, среда пробует программное устройство WARP. Для программы сохраняются те же операторы, координаты и цвета, а быстродействие программного устройства зависит от процессора.

Размер клиентской области окна может отличаться от логического размера холста. Готовый кадр вписывается в окно с сохранением пропорций, а свободные поля остаются чёрными. Оператор SMOOTH выбирает фильтр показа готового кадра. После обычного завершения программы последний кадр можно осмотреть. Команда остановки в IDE закрывает CANVAS; закрытие окна во время выполнения останавливает программу.

Синтаксис

CANVAS <ширина>, <высота>

BEGINFRAME

PRESENT

RGB(<красный>, <зелёный>, <синий>)

CLS

CLS <цвет>

CAMERA <координата X>, <координата Y>

RESETCAMERA

VIEWPORT

VIEWPORT (<левая граница>, <верхняя граница>)-(<правая граница>, <нижняя граница>)

DRAWRECT <координата X>, <координата Y>, <ширина>, <высота>, <цвет>

FILLRECT <координата X>, <координата Y>, <ширина>, <высота>, <цвет>

DRAWLINE <начальный X>, <начальный Y>, <конечный X>, <конечный Y>, <цвет>

DRAWCIRCLE <координата X>, <координата Y>, <радиус>, <цвет>

FILLCIRCLE <координата X>, <координата Y>, <радиус>, <цвет>

DRAWTEXT <текст>, <координата X>, <координата Y>, <цвет>

TEXTWIDTH(<текст>)

TEXTHEIGHT(<текст>)

DRAWIMAGE <изображение>, <координата X>, <координата Y>

DRAWIMAGE <изображение>, <координата X>, <координата Y>, <ширина>, <высота>

DRAWSPRITE <спрайт>, <кадр>, <координата X>, <координата Y>

DRAWSPRITE <спрайт>, <кадр>, <координата X>, <координата Y>, <ширина>, <высота>

DRAWTILE <тайлсет>, <номер тайла>, <координата X>, <координата Y>

DRAWTILEMAP <карта>, <координата X>, <координата Y>

DRAWTILELAYER <карта>, <номер слоя>, <координата X>, <координата Y>

Части синтаксиса

Кадровый цикл

Оператор BEGINFRAME открывает подготовку кадра и подавляет промежуточную публикацию. Пока кадр открыт, индексные операции, изображения и тайлы меняют рабочее изображение; PRESENT явно показывает результат. Если программа рисует вне пары BEGINFRAME/PRESENT, операции PSET, PRESET, PAINT, PUT и вывод ресурсов могут запускать автоматическое обновление окна, поэтому для анимации используется полная пара операторов; явный PRESENT подходит для показа любого подготовленного рисунка.

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

Оператор PRESENT переносит рабочий кадр в окно. После него кадр снова можно изменять; чтобы следующий кадр подготавливался без промежуточного показа, его начинают оператором BEGINFRAME и завершают оператором PRESENT.

Камера, графической области и мировые координаты

Оператор CAMERA x, y задаёт мировую точку, которая отображается в левом верхнем углу выбранной области в пикселях. При выводе из мировых координат вычитается смещение камеры.

Мировые координаты обозначают положения объектов сцены. Камера выбирает часть этой сцены, которую следует нарисовать в окне; хранение объектов остаётся задачей программы.

Экранные координаты обозначают позиции внутри холста. При перемещении камеры положение объекта в мире сохраняется, а его положение на экране меняется.

Каждая мировая графическая координата должна находиться в диапазоне -1000000000..1000000000.

Оператор RESETCAMERA устанавливает смещение 0, 0. После сброса можно рисовать подписи и индикаторы теми же операторами FILLRECT, DRAWRECT и DRAWTEXT.

Оператор VIEWPORT без аргументов выбирает весь холст. Форма с прямоугольником ограничивает рисование заданной экранной областью.

Границы VIEWPORT задаются в физических пикселях холста. Камера смещает мир внутри этой области. Сброс камеры не сбрасывает область, а изменение области не сбрасывает камеру.

Для чтения уже нарисованного пикселя функция POINT(x, y) принимает физические координаты холста без преобразования камерой и областью. Одноаргументная форма POINT(selector) доступна только в SCREEN.

В примере преобразования координат мировая точка (100, 50) попадает в физическую точку (10, 6). Её цвет следует читать вызовом POINT(10, 6).

Индексные операторы PSET, PRESET и PAINT также работают на холсте. Их координаты мировые: при рисовании учитываются камера и текущая область.

Правая и нижняя границы области не входят в неё. Если пересечение с холстом пусто, возникает ошибка. Примитивы, текст, изображения и спрайты обрезаются по выбранной области.

Для холста используйте CAMERA и VIEWPORT. Операторы VIEW и WINDOW принадлежат окну SCREEN.

Цвета, примитивы и текст

Встроенная функция RGB формирует цвет 0xRRGGBB. Оператор CLS очищает рабочий кадр чёрным, а форма CLS color — переданным полноцветным значением.

Операторы DRAWRECT и FILLRECT рисуют рамку и заполненный прямоугольник. Оператор DRAWLINE рисует отрезок, а DRAWCIRCLE и FILLCIRCLE — контур и заполненный круг.

Оператор DRAWTEXT выводит пиксельный текст. Функции TEXTWIDTH и TEXTHEIGHT измеряют его в пикселях по тем же правилам; обе требуют активного холста.

Операторы DRAWIMAGE и DRAWSPRITE поддерживают те же формы, что и на экране, но на холсте используют мировые координаты и текущую камеру.

Оператор DRAWTILE рисует один тайл значения TILESET в натуральном размере.

Средства TILEMAP позволяют рисовать карту целиком или по слоям, читать клетки функциями MAPTILE, MAPTILESET, MAPTILEFLAGS и изменять их оператором SETMAPTILE. Объектные слои автоматически не рисуются и не изменяются как тайловая сетка.

Оператор PSET записывает индекс 0..255 в одну мировую точку. Его удобно использовать для проверки положения пикселя и простых процедурных рисунков.

Оператор PRESET использует ту же систему координат. Если цвет пропущен, записывается текущий фоновый индекс; после открытия холста он равен 0.

Оператор PAINT заполняет область начиная с мировой точки. Цвета заливки и границы остаются индексными.

Операторы GET и PUT обмениваются индексным двумерным буфером 0..255. На холсте они используют мировые координаты, камеру и текущую область вывода.

Точный договор координат и измерения текста

Для CANVAS ширина и высота приводятся к LONG и должны лежать в 1..16384, а площадь не должна превышать 16 777 216 пикселей; неподходящие размеры сообщают MB3007. Отказ создания устройства или поверхности сообщается как перехватываемая ошибка MB3005. Координаты камеры, примитивов и текста приводятся к LONG; проверяемые мировые координаты лежат в -1000000000..1000000000. Размеры прямоугольника должны быть положительными, радиус круга может быть нулём.

Внутри выбранной области физическая точка вычисляется так: X = левая граница области + мировой X - камера X; Y = верхняя граница области + мировой Y - камера Y. VIEWPORT задаёт физические границы; правая и нижняя границы исключаются. Поэтому даже при нулевой камере мировое начало располагается в начале выбранной области, а не обязательно в точке (0, 0) холста.

DRAWTEXT принимает STRING, две координаты LONG и цвет INTEGER. TEXTWIDTH и TEXTHEIGHT принимают STRING и возвращают INTEGER в пикселях; обе функции требуют CANVAS. Ширина равна числу единиц UTF-16 в самой длинной строке, умноженному на 8. Символ CR не занимает ячейку; LF начинает следующую строку. Высота равна числу строк, умноженному на 12. Для пустой строки ширина равна 0, высота — 12; суррогатная пара занимает две ячейки.

Нативный холст DirectX поддерживает размеры до 16384 пикселей по каждой стороне. Это ограничение графической поверхности среды, а не изменение типа аргументов оператора CANVAS. Создание поверхности также требует достаточно памяти; если устройство или поверхность создать нельзя, выполнение завершается с сообщением об отказе графической среды.

RGB принимает три LONG в диапазоне 0..255 и возвращает INTEGER с кодом 0xRRGGBB. Выход компонента за диапазон сообщает MB3007. BEGINFRAME очищает рабочий кадр, PRESENT показывает его; оба оператора не принимают аргументов и требуют CANVAS.

Пример

CANVAS 320, 180

BEGINFRAME
VIEWPORT (0, 28)-(320, 180)
CAMERA 48, 0
CLS RGB(12, 18, 28)
FILLRECT 48, 28, 96, 96, RGB(26, 72, 140)
DRAWLINE 0, 132, 460, 132, RGB(255, 255, 255)
FILLCIRCLE 96, 76, 4, RGB(255, 242, 170)

RESETCAMERA
VIEWPORT
FILLRECT 0, 0, 320, 24, RGB(6, 8, 12)
DRAWTEXT "Очки: 12", 8, 6, RGB(255, 242, 170)
PRESENT
SLEEP

Пример области и подписей оставляет верхнюю полосу для индикаторов, рисует мир внутри отдельной области, затем сбрасывает камеру и область и выводит подпись поверх кадра.

Приёмочный пример нативного игрового кадра рисует сто движущихся кругов, перемещает камеру стрелками и переключает сглаживание клавишами 1 и 2. Нажмите ESC, чтобы завершить программу.

Диагностика

• MB3007: ширина или высота CANVAS не является положительным допустимым размером.
• MB3007: компонент RGB находится вне диапазона 0..255.
• MB3007: ширина или высота DRAWRECT / FILLRECT меньше либо равна нулю.
• MB3007: радиус DRAWCIRCLE / FILLCIRCLE отрицателен.
• MB3007: координаты CAMERA, VIEWPORT, DRAWLINE, DRAWTEXT и других современных примитивов выходят за поддерживаемый диапазон -1000000000..1000000000.
• MB3007: прямоугольный графической области после обрезки по границам CANVAS становится пустым.
• MB3010: BEGINFRAME, PRESENT, CLS color, CAMERA, RESETCAMERA, VIEWPORT, DRAWRECT, FILLRECT, DRAWLINE, DRAWCIRCLE, FILLCIRCLE, DRAWTEXT, TEXTWIDTH, TEXTHEIGHT, DRAWTILE, DRAWTILEMAP или DRAWTILELAYER вызваны без активного CANVAS.
• MB3010: POINT(x, y) вызван без активного SCREEN или CANVAS.
• MB3010: PSET, PRESET, PAINT, GET или PUT вызваны без активного SCREEN и без активного CANVAS.
• MB3010: DRAWIMAGE или DRAWSPRITE вызваны без активного SCREEN или CANVAS.

Запускаемые примеры

Для ручного запуска откройте программы из samples/graphics/modern/ и samples/graphics/game/.

• CANVAS: прямоугольники, IMAGE и SPRITE в двух кадрах
• CANVAS: экранных индикаторов-текст после RESETCAMERA
• CANVAS: мировые координаты и камера
• CANVAS: линии и круги
• CANVAS: VIEWPORT, экранных индикаторов и отдельная область мира
• PSET: мировая точка внутри VIEWPORT
• PRESET: фоновый пиксель внутри VIEWPORT
• PAINT: заливка мировой области внутри VIEWPORT
• GET: чтение мирового блока через VIEWPORT
• PUT: возврат мирового блока через VIEWPORT
• POINT: чтение физического пикселя из CANVAS
• TEXTWIDTH: измерение ширины экранных индикаторов-текста
• TEXTHEIGHT: измерение высоты экранных индикаторов-текста
• DRAWTILE: вывод тайлов из одного атласа
• DRAWTILEMAP: вывод карты и отдельного слоя
• SETMAPTILE: изменение и очистка клетки карты
• maze_chase: флагманский игровой пример современного слоя

Пределы поверхности и проверка координат

У оператора CANVAS ширина и высота задаются целыми числами от 1 до 16384 пикселей, а произведение размеров не должно превышать 16 777 216 пикселей. Проверка выполняется до создания поверхности. Нарушение этих пределов и нехватка памяти при её создании вызывают перехватываемую ошибку MB3007.

Координаты операторов DRAWRECT, FILLRECT, DRAWIMAGE и DRAWSPRITE проверяются так же, как координаты остальных современных команд: допустимы целые значения от −1 000 000 000 до 1 000 000 000 включительно. Камера не изменяет этот предел. Недопустимая координата вызывает MB3007 до рисования и изменения текущей позиции.

TRY
    CANVAS 16385, 1
CATCH err
    PRINT err.Code
END TRY

Пример печатает MB3007; графическое окно не создаётся.

См. также

Короткие проверки функций

Проверки свойств ресурсов печатают результаты в текстовой панели IDE. Они используют файлы репозитория по относительным путям; открывать холст для чтения свойств не требуется.

• RGB: короткая проверка результата

Пример измерения текста

CANVAS 80, 40
PRINT TEXTWIDTH("")
PRINT TEXTHEIGHT("")
PRINT TEXTWIDTH("😀")
PRINT TEXTWIDTH("AB" + CHRW(10) + "C")
PRINT TEXTHEIGHT(CHRW(10))

Вывод в текстовой панели: 0, 12, 16, 16 и 24. Суррогатная пара занимает две ячейки, ширина нескольких строк равна ширине самой длинной, а перевод строки создаёт вторую строку даже без видимых символов.

Встроенная функция TEXTWIDTH

Функция TEXTWIDTH возвращает ширину самой длинной строки текста в пикселях. Значение позволяет заранее расположить текст оператора DRAWTEXT, а сам вызов работает только при активном CANVAS.

Синтаксис

TEXTWIDTH(<текст>)

Аргумент

Передайте STRING с текстом, который требуется измерить. Пустая строка и переводы строк допустимы.

Результат и ограничения

Функция возвращает INTEGER. Число единиц UTF-16 самой длинной строки умножается на 8. CR пропускается, LF начинает следующую строку. Для пустой строки результат 0. Измерение не рисует текст, не учитывает камеру и не обрезается областью VIEWPORT.

Диагностика

Известное компилятору отсутствие CANVAS сообщает MB2046; отсутствие холста при выполнении сообщает MB3010.

Пример

CANVAS 80, 40
PRINT TEXTWIDTH("AB")

Программа печатает 16 в текстовой панели.

См. также

CANVAS и DRAWTEXT.

Встроенная функция TEXTHEIGHT

TEXTHEIGHT возвращает высоту текста в пикселях. Значение позволяет заранее расположить текст оператора DRAWTEXT, а сам вызов работает только при активном CANVAS.

Синтаксис

TEXTHEIGHT(<текст>)

Аргумент

Передайте STRING с текстом, который требуется измерить. Пустая строка и переводы строк допустимы.

Результат и ограничения

Функция возвращает INTEGER. Число строк умножается на 12. Каждый LF добавляет строку; для пустой строки результат 12. Символ CR не добавляет строку. Измерение не рисует текст, не учитывает камеру и не обрезается областью VIEWPORT.

Диагностика

Известное компилятору отсутствие CANVAS сообщает MB2046; отсутствие холста при выполнении сообщает MB3010.

Пример

CANVAS 80, 40
PRINT TEXTHEIGHT("")

Программа печатает 12 в текстовой панели.

См. также

CANVAS и DRAWTEXT.

Встроенная функция RGB

Вызов RGB собирает полноцветный код из красного, зелёного и синего компонентов. Графическая поверхность для него не нужна, а готовое значение передают полноцветным операторам CANVAS.

Синтаксис

RGB(<красный>, <зелёный>, <синий>)

Аргументы

Все три аргумента приводятся к LONG. Красный аргумент задаёт интенсивность красного, зелёный — зелёного, синий — синего. Каждый компонент должен находиться в 0..255 включительно: 0 означает отсутствие компонента, 255 — максимальную интенсивность.

Результат и ограничения

Результат имеет тип INTEGER и код 0xRRGGBB. Это полноцветное значение для CANVAS; индексные операторы SCREEN используют собственный цветовой договор.

Диагностика

Компонент вне диапазона 0..255 сообщает MB3007.

Пример

PRINT RGB(255, 255, 255)

Программа печатает 16777215 — код белого цвета.

Пример примитивов CANVAS

CANVAS 160, 100
BEGINFRAME
DRAWRECT 5, 5, 40, 25, RGB(255, 255, 255)
FILLRECT 55, 5, 40, 25, RGB(0, 128, 255)
DRAWLINE 5, 40, 95, 40, RGB(255, 255, 0)
DRAWCIRCLE 25, 70, 15, RGB(0, 255, 0)
FILLCIRCLE 75, 70, 15, RGB(255, 0, 0)
DRAWTEXT "Axiom", 105, 10, RGB(255, 255, 255)
PRESENT
SLEEP

После PRESENT окно показывает белую рамку, синий заполненный прямоугольник, жёлтый отрезок, зелёный контур круга, красный заполненный круг и белую надпись. До PRESENT рисование находится только в рабочем кадре. Числа координат измеряются в мировых пикселях; камера здесь нулевая, область занимает весь холст.