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().

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

Библиотека:

Описание:

Функция позволяет создать новую поверхность, ассоциированную с буфером видео-памяти, доступной для рендеринга через соответствующий контекст рисования. Используйте ее для создания “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.

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

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

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

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