Справочник использованных функций

Возвращает указатель на интерфейс IDirect3D9. Функция использует только один макрос D3D_SDK_VERSION, который определен в заголовочном файле d3d9.h, указывающий на текущую версию SDK. Если функция возвратила NULL, то очевидно Direct3D не установлен на компьютере пользователя.

Возвращает текущий режим отображения адаптера.
Adapter – видеоадаптер дисплея, значение D3DADAPTER_DEFAULT использует всегда первичный адаптер по умолчанию.
pMode - указатель на структуру D3DDISPLAYMODE, которая содержит описание текущего режима адаптера. Возвращаемое значение. Если функция завершена успешно, тогда возвращается значение D3D_OK. Если Adapter или pMode неверен, тогда возвращается значение D3DERR_INVALIDCALL.

Описание текущего режима адаптера

typedef struct _D3DDISPLAYMODE
{
UINT Width;         //ширина рабочей поверхности экрана в пикселах
UINT Height;        //высота рабочей поверхности экрана в пикселах
UINT RefreshRate;   //частота регенерации, значение 0 – по умолчанию
D3DFORMAT Format;   //формат режима визуального отображения
} D3DDISPLAYMODE;

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

Флаг	Значение	Описание
D3DFMT_UNKNOWN	0	формат поверхности, используемый по умолчанию
D3DFMT_R8G8B8	20	24-битный формат RGB
D3DFMT_A8R8G8B8	21	32-битный формат АRGB
D3DFMT_D16_LOCKABLE	70	16-битный формат буфера глубины
D3DFMT_D32	71	32-битный формат буфера глубины
D3DFMT_D15S1	73	16-битный формат буфера глубины, где 15 бит – канал глубины, 1 бит – канал трафарета
D3DFMT_D24S8	75	32-битный формат буфера глубины, где 24 бита – канал глубины, 8 бит – канал трафарета
D3DFMT_D24X8	77	32-битный формат буфера глубины, где 24 бита – резервируются для канала глубины
D3DFMT_D24X4S4	79	32-битный формат буфера глубины, где 24 бита канал глубины, 4 бита – канал трафарета
D3DFMT_D16	80	16-битный формат буфера глубины
D3DFMT_VERTEXDATA	100	Формат поверхности буфера глубины
D3DFMT_INDEX16	101	16-битный индекс буфера глубины
D3DFMT_INDEX32	102	32-битный индекс буфера глубины

UINT BackBufferWidth;
UINT BackBufferHeight;
D3DFORMAT BackBufferFormat;
UINT BackBufferCount;
D3DMULTISAMPLE_TYPE MultiSampleType;
D3DSWAPEFFECT SwapEffect;
HWND hDeviceWindow;
BOOL Windowed;
BOOL EnableAutoDepthStencil;
D3DFORMAT AutoDepthStencilFormat;
DWORD Flags;
UINT FullScreen_RefreshRateInHz;
UINT FullScreen_PresentationInterval;
} D3DPRESENT_PARAMETERS;

Описание параметров.

BackBufferWidth и BackBufferHeight – ширина и высота новых задних буферов, в пикселях. Если флажок Windowed установлен в FALSE (для полноэкранного режима), тогда эти значения (ширина и высота) должны быть взяты из функции IDirect3D9::EnumAdapterModes. Если флажок Windowed установлен в TRUE и любое из этих значений нуль, тогда размеры берутся из области клиента hDeviceWindow (или фокуса окна, если hDeviceWindow равен NULL).

BackBufferFormat – это член структуры D3DFORMAT. Это значение одного из форматов визуализации, которое утверждается при помощи IDirect3D9::CheckDeviceType.
Если установлен флажок Windowed в TRUE, тогда BackBufferFormat устанавливается по умолчанию текущего режима отображения. Для этого используйте функцию IDirect3DDevice9::GetDisplayMode, чтобы получить текущий формат.

BackBufferCount – число задних буферов, их значение может быть 0, 1, 2, 3. Минимально считается наличие 1, поэтому при параметре 0, все равно создастся 1 задний буфер.

MultiSampleType – член структуры D3DMULTISAMPLE_TYPE. Это значение должно быть равно D3DMULTISAMPLE_NONE, если SwapEffect был установлен в D3DSWAPEFFECT_DISCARD. Multisampling поддерживается, если был определен эффект обмена D3DSWAPEFFECT_DISCARD.

SwapEffect – служит для определения обмена буферов. Член структуры D3DSWAPEFFECT. Если флажок Windowed установлен в TRUE и SwapEffect установлен в D3DSWAPEFFECT_FLIP, тогда добавится один дополнительный задний буфер и не будет отображаться, пока активен первичный буфер. D3DSWAPEFFECT_COPY и D3DSWAPEFFECT_COPY_VSYNC требует установить значение BackBufferCount в 1. D3DSWAPEFFECT_DISCARD – будет прописано управляемое время в отладчике, когда любой буфер может быть заполнен, когда другой виден на экране.

hDeviceWindow – если приложение работает в полноэкранном режиме, то задается вся поверхность экрана монитора.

Windowed – Равен TRUE, если приложение запущено в оконном режиме. FALSE - если приложение является полноэкранным.

EnableAutoDepthStencil – если значение TRUE, то Microsoft Direct3D может управлять буфером глубины. Устройство может создать трафарет буфера глубины. Трафарет буфера глубины автоматически устанавливается на устройство визуализации. Когда устройство сбрасывается, трафарет буфера глубины автоматически уничтожается и создается новый размер.
Если EnableAutoDepthStencil установлен в TRUE, тогда AutoDepthStencilFormat должен иметь формат трафарета глубины.

AutoDepthStencilFormat – может принимать значения из структуры D3DFORMAT. Создает формат поверхности трафарета глубины.

Flags – он может быть установлен в 0, или в следующие флажки:

D3DPRESENTFLAG_LOCKABLE_BACKBUFFER - устанавливаем флаг, если приложение требует непосредственный режим работы с задним буфером. Обратите внимание, задние буфера имеют доступ, если приложение имеет D3DPRESENTFLAG_LOCKABLE_BACKBUFFER, когда использует функцию IDirect3D9::CreateDevice или IDirect3DDevice9::Reset.

FullScreen_RefreshRateInHz – частота обновления экрана. Для оконного режима это значение должно быть 0. Иначе, это значение должен возвращать IDirect3D9::EnumAdapterModes. Можно использовать одно из следующих значений:

D3DPRESENT_RATE_DEFAULT - ставит по умолчанию, или текущему обновлению отображения окна.
D3DPRESENT_RATE_UNLIMITED - ставит самый быстрый рефреш, которое позволяет железо.

FullScreen_PresentationInterval – максимальный интервал переключений заднего буфера. Для оконного режима это значение можно установить в D3DPRESENT_INTERVAL_DEFAULT(0). Для полноэкранного устанавливается в D3DPRESENT_INTERVAL_DEFAULT или может равняться одному из ниже описанных флажков входящих в структуру D3DCAPS9:

D3DPRESENT_INTERVAL_IMMEDIATE - позволяет действовать немедленно. Драйвер не ждет возврата вертикального луча синхронизации.
D3DPRESENT_INTERVAL_ONE - драйвер ждет возврата вертикального луча синхронизации. Т.е. обновление происходит не быстрее чем обновление экрана.
D3DPRESENT_INTERVAL_TWO - драйвер ждет возврата вертикального луча синхронизации. Т.е. обновление происходит в два раза медленнее, чем обновление экрана.
D3DPRESENT_INTERVAL_THREE - драйвер ждет возврата вертикального луча синхронизации. Т.е. обновление происходит в три раза медленнее, чем обновление экрана.
D3DPRESENT_INTERVAL_FOUR - драйвер ждет возврата вертикального луча синхронизации. Т.е. обновление происходит в четыре раза медленнее, чем обновление экрана.

очищает окно, буфер глубины и буфер трафарета.

Count – количество прямоугольников в массиве pRects, если указано 0, то будет очищена вся поверхность.

pRects – указатель на массив структуры D3DRECT описывающий прямоугольную область очистки. Если Вам нужно очистить полностью экран укажите NULL.

typedef struct _D3DRECT
{
    LONG x1, y1;	//координаты верхнего левого угла
    LONG x2, y2;	//координаты нижнего правого угла
} D3DRECT;

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

D3DCLEAR_STENCIL - очищает буфер трафарета до значения Stencil.
D3DCLEAR_TARGET - очищает отображаемую часть экрана, цветом указанным в Color.
D3DCLEAR_ZBUFFER - очищает буфер глубины, значением указанным в Z.

Color – это значение имеет 32-битовый цвет, для очистки экрана приложения. Для задания используется макрос D3DCOLOR_XRGB(R, G, B)

Z – параметр задает значение для Z-буфера. 0.0 – самое близкое значение, 1.0 – дальнее расстояние

Stencil – значение буфера трафарета, может быть в диапазоне от 0 до 2 в степени n-1, где n разрядная глубина буфера трафарета.

Возвращаемое значение.
Если функция завершена успешно, тогда возвращается значение D3D_OK, иначе значение D3DERR_INVALIDCALL.

после этой функции начинается создание сцены.

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

pSourceRect – указатель на структуру RECT исходной поверхности. Если указатель NULL, то используется вся поверхность. Если прямоугольник имеет значения больше самой поверхности, то он подрезается до соответствующих размеров поверхности.

pDestRect – указатель на структуру RECT поверхности адресата. Если указатель равен NULL, если не были указаны D3DSWAPEFFECT_COPY или D3DSWAPEFFECT_COPY_VSYNC. pDestRect является указателем на структуру RECT, содержащая координаты прямоугольника клиентского окна. Если указатель NULL, то используется полная область клиента. Если прямоугольник имеет значения больше самой поверхности, то он подрезается до соответствующих размеров поверхности.

hDestWindowOverride – указатель указывающий на окно клиента, которая предназначена для визуализации сцены. Если этот параметр равен NULL, тогда hWndDeviceWindow входящий в структуру D3DPRESENT_PARAMETERS будет принят.
pDirtyRegion – этот параметр не используется и должен быть установлен в NULL (использовался в предыдущих версиях, оставлен для совместимости).

Возвращаемое значение. Если функция завершена успешно, тогда возвращается значение D3D_OK.
В случае ошибки возвращается одно из следующих значений:
D3DERR_INVALIDCALL
D3DERR_DEVICELOST

создание буфера вершин

Length – размер буфера вершин в байтах.

Usage – способ применения буфера вершин, в большинстве случаев используется 0, но можно использовать одно или несколько значений констант D3DUSAGE:

D3DUSAGE_DONOTCLIP - указывает на то, что буфер вершин никогда не будет требовать переключение. Когда Вам нужно будет отобразить содержимое буфера, установите флажок D3DRS_CLIPPING в false (ложь).

D3DUSAGE_DYNAMIC - указывает когда вершинам или буферу требует использование динамической памяти. Это разрешает драйверу самому решать куда разместить. Так, статический буфер вершин помещается в видео память, а динамический в AGP память. Если Вы не используете флажок D3DUSAGE_DYNAMIC, Вы тем самым назначаете использование статической памяти. D3DUSAGE_DYNAMIC строго прописывается через D3DLOCK_DISCARD и D3DLOCK_NOOVERWRITE. Флажки D3DLOCK_DISCARD и D3DLOCK_NOOVERWRITE влияют на вершины и буфер созданные при помощи D3DUSAGE_DYNAMIC; они не могут влиять на статический буфер вершин.

D3DUSAGE_RTPATCHES - указывает, когда буфер вершин должен использовать прорисовку высококачественного примитива.

D3DUSAGE_NPATCHES - указывает, когда буфер вершин использует прорисовку N кусков.
D3DUSAGE_POINTS - указывает, когда буфер вершин использует прорисовку указателя на спрайт или список указателей.

D3DUSAGE_SOFTWAREPROCESSING - указывает, когда буфер вершин использует программную обработку вершин.

D3DUSAGE_WRITEONLY - сообщает системе, что пишет только буфер вершин. Использование этого флажка разрешает драйверу оптимизировать память для эффективной записи операций и визуализации. Пытается прочитать буфер вершин и затем создать.

FVF – указывается формат вершин.

Pool – описание формата вершин для размещения в памяти используя член перечисляемого типа.

typedef enum _D3DPOOL
{
  D3DPOOL_DEFAULT = 0,    //по умолчанию
  D3DPOOL_MANAGED = 1,    //ресурсы копируются автоматически в доступную для устройств память
  D3DPOOL_SYSTEMMEM = 2,  //использует системную оперативную память
  D3DPOOL_SCRATCH = 3,    //ресурс помещается в системную память и не обновляется 
                          //при потере устройства
  D3DPOOL_FORCE_DWORD = 0x7fffffff  //не используется
} D3DPOOL;

ppVertexBuffer – указатель на адрес в котором будет храниться адрес создаваемого буфера вершин.

pHandle – всегда устанавливайте в 0, это зарезервированный параметр.

Возвращаемое значение. Если функция завершена успешно, тогда возвращается значение D3D_OK, иначе:
  D3DERR_INVALIDCALL
  D3DERR_OUTOFVIDEOMEMORY
  E_OUTOFMEMORY

блокировка диапазона вершин для получения указателя на память буфера вершин.

OffsetToLock – указывает на границу данных вершин для блокировки, измеряется в байтах. Для того что бы заблокировать весь буфер используется значение 0.

SizeToLock – размер буфера для блокировки, если оба параметра установлены в NULL – блокируется весь буфер вершин.

ppbData – означает адрес указателя на указатель с данными буфера вершин.

Flags – описывает тип блокировки.
  D3DLOCK_DISCARD – блокируется каждое положение в пределах блокируемой области.
  D3DLOCK_NO_DIRTY_UPDATE – происходит «добавление» данных в память.
  D3DLOCK_NO_SYSLOCK – блокирует систему на большой промежуток времени.
  D3DLOCK_READONLY – приложение не будет записано в буфер.
  D3DLOCK_NOOVERWRITE – этот флаг исключает запись в буфер вершин при уже имеющихся данных в буфере.

разблокировка буфера вершин.

связывание буфера вершин с потоком данных устройства.

StreamNumber – определяет проток данных от 0 до -1.

pStreamData – указатель на создаваемый буфер вершин, который связывается с потоком данных.

OffsetInBytes – смещение от начала потока, да начала вершин в байтах. Если установить в 0, вывод будет происходить начиная с первой вершины.

Stride – размер структуры задающей вершину.

установка формата вершин.

PrimitiveType – перечисляемый тип D3DPRIMITIVETYPE, описывающий тип примитива для вывода на экран.
typedef enum _D3DPRIMITIVETYPE

StartVertex – индекс первой вершины для загрузки.

PrimitiveCount – количество выводимых примитивов.