gf_surface_attach()

Создание новой поверхности для существующего блока памяти

Прототип:

#include <gf/gf.h>
 
int gf_surface_attach( gf_surface_t *psurface,
                       gf_dev_t gdev,
                       int w,
                       int h,
                       int stride,
                       gf_format_t format,
                       const gf_palette_t *palette,
                       uint8_t *ptr,
                       unsigned flags );

Аргументы:

psurface: Указатель на память, куда будет сохранен дескриптор создаваемой поверхности.
gdev: Дескриптор графического устройства, полученный с помощью вызова функции gf_dev_attach(), обслуживающего поверхность.
w,h: Ширина и высота поверхности в пикселях.
stride: Число байт на одну строку данных (scanline) в буфере данных, ассоциированном с поверхностью.
format: Формат поверхности типа gf_format_t. Если используется упакованный формат, вы должны указать формат с явно заданным endianness вместо не endianness-специфичного варианта.
palette: Указатель на палитру поверхности типа gf_palette_t. Вы можете передать NULL только в том случае, если формат поверхности не предколагает наличия палитры (отличные от GF_FORMAT_PAL8 форматы).
ptr: Указатель на буфер памяти, содержащий данные изображения.
flags: Флаги, влияющие на параметры поверхности. В настоящий момент нет ни одного ожидаемого функцией флага, следует передавать значение 0.

Функция создает поверхность и присоединяет к ней уже существующий буфер с данными. Это позволяет дать определние вашему собственному буферу памяти в пространстве ресурсов графической подсистемы. Корректная инициализация поверхности позволяет выполнять манипуляции с поверхностью средствами GF API.

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

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

По этой же причине приложение ответственно за освобождение памяти, ассоциированной с буфером памяти. Это должно быть сделано после завершения всех операций с поверхностями, ссылающимися на буфер, а также после освобождения самих поверхностей с помощью gf_surface_free().

Память этих поверхностей не может быть разделяемой между процессами средствами менеджера io-display. По этой причине доступ к таким поверхностям через gf_surface_attach_by_sid() невозможен.

Возвращаемое значение:

GF_ERR_OK: Успешное завершение.
GF_ERR_MEM: Выделение памяти не выполнено.
GF_ERR_PARM: Невозможно удовлетворить критерии создания поверхности; убедитесь, что формат поверхности соответствует требованиям, установленным флагами flags для данного оборудования. Также данный статус завершения возвращается, если значение параметра psurface или gdev или ptr равно NULL

Классификация:

Графическая подсистема ЗОСРВ «Нейтрино», Graphics Framework

Безопасность использования
Обработчик прерываний: Нет
Обработчик сигналов: Нет
В потоке: Да

Тематические ссылки:

gf_palette_t, gf_surface_create(), gf_surface_create_layer(), gf_surface_free(), gf_surface_reattach()

Предыдущий раздел: GF API