gf_surface_create()

Создание новой поверхности

Прототип:

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

Аргументы:

psurface
Указатель на память, куда будет сохранен дескриптор создаваемой поверхности.
gdev
Дескриптор графического устройства, полученный с помощью вызова функции gf_dev_attach(), который будет обслуживать поверхность.
w,h
Ширина и высота поверхности в пикселях.
format
Формат поверхности типа gf_format_t. Если используется упакованный формат, лучше использовать не endianness-специфичные варианты. Это приведет к лучшей портируемости приложения.
palette
Указатель на палитру поверхности типа gf_palette_t. Вы можете передать NULL только в том случае, если формат поверхности не предколагает наличия палитры (отличные от GF_FORMAT_PAL8 форматы).
flags
Флаги, характеризующие особенности создаваемой поверхности:
GF_SURFACE_CREATE_2D_ACCESSIBLE
поверхность должна быть доступна 2D ускрителю (в первую очередь блиттеру).
GF_SURFACE_CREATE_3D_ACCESSIBLE
поверхность должна быть доступна 3D ускрителю (флаг не носит практического характера и сохранен лишь из соображений обратной совместимости).
GF_SURFACE_CREATE_ALPHA_MAP
поверхность может быть использована в качестве альфа карты 2D ускорителем.
GF_SURFACE_CREATE_CPU_FAST_ACCESS
поверхность должна быть оптимизирована по скорости доступа со стороны CPU. Установка этого флага обычно исключает возможность аппаратной акселерации. Отдавать предпочтение стоит в первую очередь аппаратному рендерингу, нежели программному со сторогны CPU.
GF_SURFACE_CREATE_CPU_LINEAR_ACCESSIBLE
память, ассоциированная с поверхностью должна быть линейно адресуема. Установка этого флага может исключать возможность аппаратной акселерации в случае, например, если оборудование подразумевает тайловую адресацию видео-памяти.
GF_SURFACE_CREATE_PHYS_CONTIG
память, ассоциированная с поверхностью должна быть физически непрерывной. Обычно этот флаг не является обязательным, но некторые внешние относительно графической подсистемы устройства (например, платы видео-захвата) могут иметь такие требования.
GF_SURFACE_CREATE_PAGE_ALIGNED
память, создаваемой поверхности должна быть выровнена по границе страницы. Этот флаг может потребоваться в случае, если выолняются дополнительные манипуляции с выделенной памятью, либо внешнее оборудование имеет дополнительные ограничения.
GF_SURFACE_CREATE_SHAREABLE
позволяет поверхности быть разделяемой между процессами-клиентами менеджера io-display. Флаг подразумевает создание объекта разделяемой памяти, что позволяет адресоваться к поверхности через уникальный идентификатор (SID), возвращаемый функцией gf_surface_get_info().


Note: Фактический перечень доступных форматов и флагов определяется графическим контроллером и драйверным обеспечением. Если указанные формат или флаги не поддерживаются оборудованием, будет возвращена ошибка.

Библиотека:

gf

Описание:

Функция позволяет создать новую поверхность, ассоциированную с буфером видео-памяти, доступной для рендеринга через соответствующий контекст рисования. Используйте ее для создания “offscreen” поверхностей, которые не ассоциированы с конкретным слоем (рендеринг в них осуществляется без вывода на экран). Это позволяет управлять моментом и параметрами вывода на экран посредством операций блиттинга. При необходимости ассоциации поверхности со слоем рекомендуется создавать ее с помощью функции gf_surface_create_layer().

Если драйвер отказал в создании поверхности с указанными параметрами, поведение функции зависит от драйверных интерфейсов get_alloc_info() и get_alloc_layer_info(), а также от флага GF_SURFACE_CREATE_SHAREABLE. В общем случае отказ драйвера в создании поверхности не означает невозможность создания поверхности.

Если флаг GF_SURFACE_CREATE_SHAREABLE не был установлен, библиотека Graphics Framework создаст поверхность самостоятельно и установит ей GF_SID_INVALID в качестве SID. Если поверхности требуется действительный SID, необходимо в обязательном порядке установить флаг GF_SURFACE_CREATE_SHAREABLE, который обеспечит создание объекта разделяемой памяти для дсотупа к поверхности. В этом случае другие процессы смогут адресоваться к этой поверхности через ее SID.


Warning: Потоки не должны вызывать эту функцию между вызовами gf_draw_begin() и gf_draw_end(). В противном случае возможна взаимная блокировка потоков.

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

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

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

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

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

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

gf_format_t, gf_palette_t, gf_surface_attach(), gf_surface_create_layer(), gf_surface_free()




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