Справочник по Screen API

Справочник по библиотеке Screen

Два важных аспекта, которые следует учитывать при использовании Screen – это безопасность функций и типы их выполнения функций.

Типы функций
Списки функций
Программные интерфейсы (API)

Типы функций

Многие вызовы API не выполняются немедленно. Вместо этого команды помещаются в очередь для последующей пакетной обработки. По мере вызова функций команды накапливаются в командном буфере, который связан с контекстом. Эти команды будут обработаны либо при его заполнении, либо при вызове функции-триггера. При пакетной обработке большое количество команд может быть представлено в одной атомарной операции, а при взаимодействии клиента с Composition Manager уменьшается количество передаваемых сообщений и они становятся более крупными. Функции, которые выполняются немедленно, могут также очищать очередь команд и вызывать перерисовку изображения на экране.

Нужно четко понимать модель выполнения каждой используемой функции. Знание этого будет иметь основополагающее значение при разработке.

Все функции Screen API принадлежат к одному из следующих типов:

Тип функции Характеристика
Исполняемые немедленно
Подразумеваемые действия выполняются при вызове функции и не ставятся в очередь исполнения.

Некоторые функции этого типа могут блокировать прикладное приложение в течение некоторого времени, требуемого для выполнения команды в композиторе (Composition Manager). Например, обе функции screen_create_context() и screen_get_event() должны взаимодействовать с композитором (Composition Manager). Функция screen_create_context() обычно возвращает управление сразу после установки соединения с сервисом. А вот screen_get_event() может блокироваться в течение длительных периодов времени, если очередь событий пуста и задан большой или бесконечный тайм-аут.

Функции этого типа не приводят к изменению содержимого дисплея и не исполняют команды в очереди пакетной обработки. Возвращаемое значение указывает, было ли успешным выполнение данной конкретной функции.

Триггеры
Функции этого типа ставятся в очередь для пакетной обработки и приводят к отправке всей очереди на исполнение.

Добавление команд в очередь и последующий её сброс подразумевают, что выполнение функций этого типа зависит от команд, добавленных в очередь ранее. Кроме того, они требуют немедленного взаимодействия с композитором (Composition Manager). Например, функция screen_get_window_property_cv() ставит в очередь команду для получения указанного свойства окна. Затем функция выполняет отправку пакета команд на исполнение в композитор. Она должна исполнить командный буфер потому, что значение возвращаемого свойства может измениться извне или зависеть от ранее добавленной в очередь команды.

Возвращаемое этими функциями значение указывает, были ли успешно выполнены все команды в очереди. Значение, соответствующее успешной обработке, указывает, что все команды в очереди были обработаны и выполнены без ошибок. Альтернативные значения указывают на ошибку либо при выполнении ранее поставленной в очередь команды, либо на ошибку команды flush.


Note: Композитор (Composition Manager) не прекращает обработку пакетных команд при возниконовении ошибки. Все команды, пришедшие в пакете, будут обработаны.




Caution: Если функциям, направленным на считывание или установку свойств объектов API, передано некорректное имя свойства, то очередь не будет отправлена на исполнение. Вместо этого обычно возвращается код ошибки ENOTSUP.



Исполняемые отложенно
Функция ставится в очередь для последующего пакетного исполнения.

Функции этого типа ставят команду в очередь для последующей пакетной обработки. Команда остается в командном буфере до тех пор, пока она не будет отправлена на исполнение функцией-триггером. Менее частая причина исполнения подобных функций – заполнение командного буфера и отсутствие в нем места для новой отложенной команды. В этом случае пакет команд отправляется на исполнение принудительно. После освобождения места в очереди команда из вызванной функции добавляется в очередь. Например, функция screen_set_window_property_cv() ставит в очередь команду для установки указанного свойства окна. Значение свойства не изменяется до тех пор, пока не будет вызвана функция-триггер или пока очередь не переполнится.


Caution: Очередь команд является локальной для каждого прикладного процесса. Так, если один процесс выполнил отложенную функцию с установкой параметра окна, а другой в тот же момент попытался этот параметр считать, то последний получит новое значение только при отправке очереди на исполнение в первом процессе.



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

Триггеры с перерисовкой
Функции этого типа ставятся в очередь для пакетной обработки и приводят к отправке всей очереди на исполнение. Также эти функции могут приводить к перерисовке содержимого на экране монитора.

Логика их работы во многом эквивалентна функциям-триггерам за исключением того, что их выполнение приводит к перерисовке содержимого на экране монитора. Например, функция screen_flush_context() добавляет команду flush в очередь команд пакетной обработки, а затем отправляет данный пакет команд в композитор. Содержимое дисплея при этом обновляется.

Возвращаемое этими функциями значение указывает, были ли успешно выполнены все команды в очереди. Значение, соответствующее успешной обработке, указывает, что все команды в очереди были обработаны и выполнены без ошибок. Альтернативные значения указывают на ошибку либо при выполнении ранее поставленной в очередь команды, либо на ошибку команды flush.

Списки функций

Раздел Описание
Статья помогает выбрать подходящую функцию в зависимости от сценария использования

Программные интерфейсы (API)

Общие типы данных:

Раздел Описание
Параметры блиттинга
Опции flush-операций
Форматы кодирования цветов пикселей
Определения кнопок мыши
Свойства различных объектов Screen API
Типы качества масштабирования
Определения кнопок стилуса
Типы тачскринов
Типы прозрачности
Способы использования буферов видео-памяти

Работа с объектами API:

Раздел Описание
Контекст определяет взаимоотношения с оконной подсистемы
Область памяти в которой хранится и обрабатывается изображение
Окно используется для отображения информации различного вида
Pixmap представляет собой буфер для offscreen рендеринга
Группы окон используются для объединения окон, которые будут разделять свойства и контекст
События взаимодействуют с контекстом для обеспечения реакции на действия
Дисплей представляет собой физическое устройство отображения, такое как монитор или тачскрин




Предыдущий раздел: Оконная подсистема Screen