Операторы GET и PUT

Что даёт буфер пикселей

Оператор GET считывает прямоугольник активной графической поверхности в подготовленный массив. Оператор PUT выводит массив на активную поверхность с выбранным действием наложения. Буфер позволяет сохранить участок изображения, восстановить его позже, перенести в другую точку или выполнить побитовое наложение.

Массивы GET и PUT хранят индексные цвета в обоих графических режимах. Для полноцветных ресурсов предназначены IMAGE и SPRITE.

Где работают операторы

Перед обменом откройте графический SCREEN 1..10 или холст CANVAS. В режиме SCREEN координаты преобразуются текущими операторами VIEW и WINDOW. На холсте CANVAS передаются мировые координаты: камера преобразует их, а область VIEWPORT ограничивает доступные пиксели.

Синтаксис

GET (<начальный X>, <начальный Y>)-(<конечный X>, <конечный Y>), <буфер>

GET STEP (<начальный X>, <начальный Y>)-STEP (<конечный X>, <конечный Y>), <буфер>

PUT (<координата X>, <координата Y>), <буфер>

PUT STEP (<координата X>, <координата Y>), <буфер>

PUT (<координата X>, <координата Y>), <буфер>, PSET

PUT (<координата X>, <координата Y>), <буфер>, PRESET

PUT (<координата X>, <координата Y>), <буфер>, AND

PUT (<координата X>, <координата Y>), <буфер>, OR

PUT (<координата X>, <координата Y>), <буфер>, XOR

Аргументы

Как устроен буфер

Оператор GET вычисляет прямоугольник и заполняет видимую форму массива buffer[] считанными пикселями. Оператор PUT читает всю видимую форму массива и располагает её начиная с указанной точки. В каждом элементе буфера хранится индекс 0..255; полноцветные значения не сохраняются в этом формате даже при обмене с CANVAS.

Массив должен быть выделен заранее и иметь два измерения. Поддерживаются элементы INTEGER, LONG, DOUBLE и DECIMAL. Видимые ширина и высота массива должны точно соответствовать прямоугольнику GET; несовпадение размеров вызывает ошибку выполнения. При выводе каждый элемент нормализуется по формуле ABS(TRUNC(value)) MOD 256.

Действия PUT

Действие определяет, как цвет буфера сочетается с уже нарисованным пикселем. Если действие не указано, применяется XOR.

Координаты, обрезка и момент показа

Все координаты GET и PUT приводятся к LONG, и обе границы захватываемого прямоугольника включаются. GET не выделяет память под массив и не меняет его размеры. За пределами поверхности или области вывода GET записывает в буфер 0, а PUT пропускает рисование; доступная часть прямоугольника при этом обрабатывается.

На холсте действуют камера и VIEWPORT; настройки VIEW и WINDOW относятся к экрану SCREEN. Проверка результата на холсте идёт по физической точке в POINT(x, y): при VIEWPORT (10, 6)-(15, 11) и CAMERA 100, 50 вызов PUT (100, 50), buffer[], PSET записывает первый элемент в (10, 6), и POINT(10, 6) читает этот пиксель без повторного смещения камеры.

Момент показа различается у операторов: GET только читает поверхность и не показывает новый кадр, а PUT изменяет активную страницу SCREEN или рабочий кадр CANVAS. В открытом кадре холста для показа результата требуется PRESENT; вне открытого кадра действует автоматическое обновление.

Предельные индексы и целостность записи

Операторы GET и PUT поддерживают произвольные допустимые нижние границы массива, в том числе одноэлементное измерение 2147483647 TO 2147483647. Недостаток памяти для временного графического буфера вызывает MB3005, которую можно перехватить через TRY...CATCH. Графический буфер может содержать не более 16 777 216 элементов; превышение вызывает MB3007.

Оператор PUT проверяет все исходные элементы до первой записи. Если числовое значение нельзя использовать как цвет, возникает MB3007, а изображение остаётся прежним. На DirectX готовый прямоугольник передаётся пакетно; действия PSET и PRESET не требуют чтения прежних пикселей. Область отсечения и начало массива не изменяют смысл действий AND, OR и XOR.

SCREEN 1
DIM pixel[2147483647 TO 2147483647, 0 TO 0] AS INTEGER
PSET (5, 5), 12
GET (5, 5)-(5, 5), pixel[]
PUT (10, 10), pixel[], PSET
PRINT pixel[2147483647, 0]

Программа печатает 12 и копирует красный пиксель. Другие исправленные границы показывает запускаемый пример графического аудита. В открытом кадре CANVAS результат становится виден после PRESENT; вне открытого кадра действует автоматическое обновление.

Диагностика

• MB3010: оператор GET или оператор PUT вызван без активного SCREEN и без активного CANVAS.
• MB3007: массив buffer[] не является выделенным двумерным числовым массивом, размеры буфера не совпали с прямоугольником GET, координаты недопустимы или значение буфера у PUT не приводится к корректному числу.

Пример

CANVAS 24, 18
CLS RGB(0, 0, 0)
VIEWPORT (10, 6)-(15, 11)
CAMERA 100, 50

DIM buffer[1 TO 2, 5 TO 6] AS INTEGER

PSET (100, 50), 6
PSET (101, 50), 9
PSET (100, 51), 12
PSET (101, 51), 15

GET (100, 50)-(101, 51), buffer[]
PUT (102, 50), buffer[], PSET

PRESENT
SLEEP

Четыре вызова PSET заполняют блок два на два мировыми координатами, затем GET считывает его в массив, размеры которого совпадают с прямоугольником. Вызов PUT со словом PSET копирует блок правее без наложения на прежние пиксели, а PRESENT показывает рабочий кадр холста.

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

Перечисленные программы можно запустить в Electron IDE для проверки чтения буфера, наложения и обрезки.

• GET: захват прямоугольной области в SCREEN
• GET: захват блока в CANVAS
• PUT: восстановление блока в CANVAS
• PUT: действия по умолчанию, XOR и PRESET

См. также