Формат файлов X (DirectX)

• Является универсальным форматом, предназначенным в том числе для хранения полигональных сеток (мешей) моделей и данных их анимации.
• Поддерживается всеми версиями DirectX (при условии применения его стандартных шаблонов).
• Для экспорта моделей из 3D-редакторов в .x-формат применяют специальные плагины.
• Подробнее о нём читаем здесь: https://dic.academic.ru/dic.nsf/ruwiki/755448/12648 .
• Построен на системе шаблонов данных (data templates).

• Написание кастомных шаблонов данных .x-файлов даёт множество преимуществ.
• Данные внутри .x-файла могут храниться в текстовом (text), двоичном (binary) и сжатом двоичном (compressed binary) виде.

Intro

Внутренняя структура .x-файла

xof 03 02txt 0032

//Declaration

template MY_GAME_INFO{
	<AA13 0 8FD-FF98-4f6e-9A55-CD0 83178672F>
	STRING GameName;
	STRING GameMaker;
	DWORD Version;
}

template MY_LEVEL{
	<0FC92315-68 97-4f03-B2BD-A6CE2 0 0 65 8 61>
	STRING Level Name; [...]
}

template MY_MEDI_KIT{
	<DACCED4A-4 3 3E-4fa3-91A6-2A8EA6B6D0 9 0>
	DWORD XPos;
	DWORD YPos;
	DWORD ZPos;
}

//Definition
MY_GAME_INFO Game0l {
	"My Test Game";
	"Alan Thorn";
	1;
}

MY_LEVEL Level101 {

	MY_MEDI_KIT{
		5;
		7;
		13;
	}

	MY_MEDI_KIT{
		435;
		757;
		139;
	}
}

Заголовок (Header)

Шаблоны (Templates)

...
//Declaration

template MY_GAME_INFO{
	<AA13 0 8FD-FF98-4f6e-9A55-CD0 83178672F>
	STRING GameName;
	STRING GameMaker;
	DWORD Version;
}
...

Примечание

Строка комментария обозначается двойной косой чертой (//) и игнорируется DirectX. Многострочные комментарии предваряются символом "решётка" (#).

Шаблоны-потомки

...
template MY_LEVEL{
	<0FC92315-68 97-4f03-B2BD-A6CE2 0 0 65 8 61>
	STRING Level Name; [...]
}
...

Объекты данных (Data Objects)

• Обычно составляют львиную долю содержимого .x-файлов.
• Представляют собой "инстансы" шаблонов, объявленных в начале .x-файла.
• В теле объекта (или инстанса шаблона) членам шаблона присваиваются конкретные значения:

...
//Definition
MY_GAME_INFO Game0l {
	"My Test Game";
	"Alan Thorn";
	1;
}
...

Родительские (parent) и дочерние (child) объекты

...
MY_LEVEL Level101 {

	MY_MEDI_KIT{
		5;
		7;
		13;
	}

	MY_MEDI_KIT{
		435;
		757;
		139;
	}
}
...

Объекты данных и ссылки (Data Objects and References)

//Definition
MY_GAME_INFO Game0l {
	"My Test Game";
	"Alan Thorn";
	1;
}

MY_LEVEL Level101 {

	MY_MEDI_KIT{
		5;
		7;
		13;
	}

	MY_MEDI_KIT{
		435;
		757;
		139;
	}

	[Game01]
}

Стандартные шаблоны

• Созданы разработчиками DirectX.

template Animation {
<	3D82AB4F-62DA-llcf-AB39-0020AF71E433 >
		[... ]
}

template AnimationKey {
<	10DD4 6A8-775B-11CF-8F52-00403335 94A3 >
	DWORD keyType;
	DWORD nKeys;
	array TimedFloatKeys keys[nKeys];
}

template AnimationOptions {
<	E2BF56C0-840F-llcf-8F52-00403335 94A3 >
	DWORD openclosed;
	DWORD positionquality;
}

template AnimationSet {
<	3D82AB50-62DA-1lcf-AB39-0020AF71E433 >
	[ Animation < 3D8 2AB4F-62DA-llcf-AB3 9-0 02 0AF71E4 33 > ]
}

template AnimTicksPerSecond {
<	9E415A43-7BA6-4a73-8743-B73D47E88476 >
	DWORD AnimTicksPerSecond;
}

template Boolean {
<	537da6a0-ca37-lld0-941c-0080c80cfa7b >
	DWORD truefalse;
}

template Boolean2d {
<	4 8 8 5AE63-7 8E8-llcf-8F52-00403335 94A3 >
	Boolean u;
	Boolean v;
}

template ColorRGB {
<	D3E16E81-7835-llcf-8F52-00403335 94A3 >
	float red;
	float green;
	float blue;
}

template ColorRGBA {
<	35FF44E0-6C7C-llcf-8F52-00403335 94A3 >
	float red;
	float green;
	float blue;
	float alpha;
}

template Coords2d {
<	F6F23F44-7686-llcf-8F52-00403335 94A3 >
	float u;
	float v;
}

template DeclData {
<	BF22E553-292C-4781-9FEA-62BD554BDD93 >
	DWORD nElements;
	array VertexElement Elements[nElements];
	DWORD nDWords;
	array DWORD data[nDWords];
}

template EffectDWord {
<	622C0ED0-956E-4da9-90 8A-2AF94F3CE716 >
	DWORD Value;
}

template EffectFloats {
<	F1CFE2B3-0DE3-4e28-AFAl-155A7 50A282D >
	DWORD nFloats;
	array float F1oats[nFloats];
}

template EffectInstance {
<	E331F7E4-0559-4cc2-8E99-lCEC1657928F >
	STRING EffectFilename;
	[ ... ]
}

template EffectParamDWord {
<	E13963BC-AE51-4c5d-B00F-CFA3A9D97CE5 >
	STRING ParamName;
	DWORD Value;
}

template EffectParamFloats {
<	3014B9A0-62F5-478C-9B86-E4AC9F4E418B >
	STRING ParamName;
	DWORD nFloats;
	array float F1oats[nFloats];
}

template EffectParamString {
<	1DBC4C8 8- 94C1-4 6ee-907 6-2C28818C94 81 >
	STRING ParamName;
	STRING Value;
}

template EffectString {
<	D55B097E-BDB6-4c52-B03D-6051C89D0E42 >
	STRING Value;
}

template FaceAdjacency {
<	A64C844A-E282-4756-8B80-250CDE04398C >
	DWORD nlndices;
	array DWORD indices[nlndices];
}

template FloatKeys {
<	10DD4 6A9-775B-llcf-8F52-00403335 94A3 >
	DWORD nValues;
	array f1oat values[nValues];
}

template Frame {
<	3D82AB46-62DA-11CF-AB39-0020AF71E433 >
	[... ]
}

template FrameTransformMatrix {
<	F6F23F41-7686-llcf-8F52-00403335 94A3 >
	Matrix4x4 frameMatrix;
}

template FVFData {
<	B6E7 0A0E-8EF9-4e8 3-94AD-ECC8B0C0 4 8 97 >
	DWORD dwFVF;
	DWORD nDWords;
	array DWORD data[nDWords];
}

template Guid {
<	a42790e0-7810-llcf-8f52-0040333594a3 >
	DWORD datal;
	WORD data2;
	WORD data3;
	array UCHAR data4[8];
}

template IndexedColor {
<	1630B820-7842-llcf-8F52-00403335 94A3 >
	DWORD index;
	ColorRGBA indexColor;
}

template Material {
<	3D82AB4D-62DA-11CF-AB39-0020AF71E433 >
	ColorRGBA faceColor;
	FLOAT power;
	ColorRGB specularColor;
	ColorRGB emissiveColor;
	[...]
}

template MaterialWrap {
<	4885ae60-78e8-llcf-8f52-0040333594a3 >
	Boolean u;
	Boolean v;
}

template Matrix4x4 {
<	F6F23F45-7686-1lcf-8F52-00403335 94A3 >
	array float matrix[16];
}

template Mesh {
<	3D82AB44-62DA-11CF-AB39-0020AF71E433 >
	DWORD nVertices;
	array Vector vertices[nVertices];
	DWORD nFaces;
	array MeshFace faces[nFaces];
	[... ]
}

template MeshFace{
<	3D82AB5F-62DA-llcf-AB39-0020AF71E433 >
	DWORD nFaceVertexIndices;
	array DWORD faceVertexIndices[nFaceVertexIndices];
}

template MeshFaceWraps {
<	ED1EC5C0-C0A8-11D0-941C-008 0C8 0CFA7B >
	DWORD nFaceWrapValues;
	array Boolean2d faceWrapValues[nFaceWrapValues];
}

template MeshMaterialList {
<	F6F23 F42-7686-11CF-8F52-0040333594A3 >
	DWORD nMaterials;
	DWORD nFaceIndexes;
	array DWORD faceIndexes[nFaceIndexes];
	[Material <3D8 2AB4D-62DA-11CF-AB3 9-0 02 0AF71E4 3 3>]
}

template MeshNormals {
	<	F6F23F43-7686-llcf-8F52-00403335 94A3 > DWORD nNormals;
	array Vector normals[nNormals];
	DWORD nFaceNormals;
	array MeshFace meshFaces[nFaceNormals];
}

template MeshTextureCoords {
<	F6F23F40-7686-llcf-8F52-00403335 94A3 >
	DWORD nTextureCoords;
	array Coords2d textureCoords[nTextureCoords];
}

template MeshVertexColors {
<	1630B821-7842-1lcf-8F52-00403335 94A3 >
	DWORD nVertexColors;
	array IndexColor vertexColors[nVertexColors];
}

template Patch {
<	A3EB5D4 4-FC22-429D-9AFB-3221CB9719A6 >
	DWORD nControlIndices;
	array DWORD control Indices[nControlIndices];
}

template PatchMesh {
<	D02C95CC-EDBA-4305-9B5D-1820D7704BBF >
	DWORD nVertices;
	array Vector vertices[nVertices];
	DWORD nPatches;
	array Patch patches [nPatches];
	[ ... ]
}

template PatchMesh9 {
<	B9EC9 4E1-B9A6-4 251-BA18-94 8 93F02C0EA >
	DWORD Type;
	DWORD Degree;
	DWORD Basis;
	DWORD nVertices;
	array Vector vertices[nVertices];
	DWORD nPatches;
	array Patch patches [nPatches];
	[ ... ]
}

template PMAttributeRange {
<	917E0427-C61E-4al4-9C64-AFE 65F9E9844 >
	DWORD iFaceOffset;
	DWORD nFacesMin;
	DWORD nFacesMax;
	DWORD iVertexOffset;
	DWORD nVerticesMin;
	DWORD nVerticesMax;
}

template PMInfo {
<	B6C3E656-EC8B-4b92-9B62-681659522947 >
	DWORD nAttributes;
	array PMAttributeRange attributeRanges[nAttributes];
	DWORD nMaxValence;
	DWORD nMinLogicalVertices;
	DWORD nMaxLogicalVertices;
	DWORD nVSplits;
	array PMVSplitRecord splitRecords[nVSplits];
	DWORD nAttributeMispredicts;
	array DWORD attributeMispredicts[nAttributeMispredicts];
}

template PMVSplitRecord {
<	574CCC14-F0B3-4333-822D-93E8A8A08E4C >
	DWORD iFaceCLW;
	DWORD iVlrOffset;
	DWORD iCode;
}

template SkinWeights {
<	6F0D123B-BAD2-4167-A0D0-80224F25FABB >
	STRING transformNodeName;
	DWORD nWeights;
	array DWORD vertexlndices[nWeights];
	array f1oat weights[nWeights];
	Matrix4x4 matrixOffset;
}

template TextureFilename {
<	A42790El-7810-llcf-8F52-00403335 94A3 >
	string filename;
}

template TimedFloatKeys {
<	F406B180-7B3B-llcf-8F52-00403335 94A3 >
	DWORD time;
	FloatKeys tfkeys;
}

template Vector {
<	3D82AB5E-62DA-llcf-AB39-0020AF71E433 >
	float x;
	float y;
	float z;
}

template VertexDuplicationIndices {
<	B8D65549-D7C9-4995-89CF-53A9A8B031E3 >
	DWORD nIndices;
	DWORD nOriginalVertices;
	array DWORD indices [nIndices];
}

template VertexElement {
<	F752461C-lE23-48f6-B9F8-8350850F336F >
	DWORD Type;
	DWORD Method;
	DWORD Usage;
	DWORD Usagelndex;
}

template XSkinMeshHeader {
<	3CF169CE-FF7C-44ab-93C0-F78F62D172E2 >
	WORD nMaxSkinWeightsPerVertex;
	WORD nMaxSkinWeightsPerFace;
	WORD nBones;
}

Пользовательские шаблоны (Custom Templates)

• В них можно хранить любые пользовательские данные.
• Создаются по аналогии с шаблонами DirectX

Читаем .x-файлы средствами DirectX

• Для этого DirectX предоставляет ряд специальных интерфейсов.

Подготовка

STDAPI D3DXFileCreate(LPD3DXFILE *lplpDirectXFile);

LPDIRECTXFILE File = NULL;
if(FAILED(D3DXFileCreate(&File))) return;

Регистрируем шаблоны

Примечание

Регистрация шаблонов в коде приложения также не требуется, если они уже зарегистрированы в самом .x-файле, так, как показано в гигантском листинге в подпункте "Стандартные шаблоны", расположенном чуть выше. В этом случае указываются только те шаблоны, с которыми будет работать игрокодер.

HRESULT RegisterTemplates (
	LPVOID pvData, // Указатель на строку, содержащую шаблон .x-файла, который надо зарегистрировать.
	DWORD cbSize // Размер строки в байтах.
	);

char *szTemplates = "xof 0302txt 0032"\
					
template MY_GAME_INFO{\
<AA13 0 8FD-FF98-4f6e-9A55-CD0 83178672F>\
	STRING GameName;\
	STRING GameMaker;\
	DWORD Version;\
}\

template MY_LEVEL{\
<0FC92315-6897-4f03-B2BD-A6CE20065861>\
	STRING Level Name;\
}\

template MY_MEDI_KIT{\
<DACC ED4A-433 E-4fa3-91A6-2A8EA6B6D090>\
	DWORD XPos;\
	DWORD YPos;\
	DWORD ZPos;\
};\

File->RegisterTemplates(szTemplates, strlen(s zTemplates));

File->RegisterTemplates((LPVOID)D3DRM_XTEMPLATES, D3DRM_XTEMPLATE_BYTES);

Открытие .x-файла

HRESULT CreateEnumObject (
	LPVOID pvSource, // Имя .x-файла адрес в памяти или указатель на источник данных.
	DXFILELOADOPTIONS dwLoadOptions, // Указывает, откуда именно загружается .x-файл. См. Табоицу 1.
	ID3DXFileEnumObject **ppEnumObj // Адрес указателья типа enumeration (перечисление), по которому
								// будет храниться созданный в памяти объект.
	);

LPD3DXFILEENUMOBJECT EnumObject = NULL;
File->CreateEnumObject("MyFile.x", DXFILELOAD FROMFILE, &EnumObject);

Энумерация объектов на вершине иерархии (Enumerating Top Objects)

HRESULT GetChildren(SIZE_T *puiChildren); // Переменная, в которую запишем кол-во топ-объектов.

HRESULT GetChild (
	SIZE_T id, // Индекс потомка, который надо получить.
	ID3DXFileData **ppObj // Адрес, куда будет помещён найденный объект данных.
	);

SIZE_T Size = 0;
Enum->GetChildren(&Size);

for(SIZE_T Counter = 0; Counter < Size; Counter++)
{
	LPD3DXFILEDATA DataObject = NULL;
	Enum->GetChild(Counter, &DataObject); // Делаем дела здесь.
	DataObject->Release() ;
}

Enum->Release() ;

Энумерация дочерних объектов (Enumerating Child Objects)

SIZE_T Size = 0;
Data->GetChildren(&Size);

for(SIZE_T Counter = 0; Counter < Size; Counter++)
{
	LPD3DXFILEDATA DataObject = NULL;
	Data->GetChild(Counter, &DataObject); // Делаем дела здесь.
	DataObject->Release() ;
}

Data->Release() ;

Обработка дочерних объектов (Processing Child Objects)

• объекты-инстансы,
• ссылки (references).

bool IsReference = Data->IsReference();

Полный код энумерирования объектов (Enumeration Overview)

VOID OpenXFile(CString FileName)
{
	LPD3DXFILE File = NULL;
	
	if(FAILED(D3DXFi1eCreate(&File)))
		return;
	
	Fi1e->RegisterTemplates((LPVOID)D3DRM_XTEMPLATES, D3DRM_XTEMPLATE_BYTES);
	LPD3DXFILEENUMOBJECT EnumObject = NULL;
	
	if(FAILED(Fi1e->CreateEnumObject(Fi1eName, DXFILELOAD FROMFILE, &EnumObject)))
		return;
	
	SIZE_T Size = 0;
	EnumObject ->GetChildren(&Size);
	for(SIZE_T Counter = 0; Counter < Size; Counter++)
	{
		LPD3DXFILEDATA DataObject = NULL;
		EnumObject->GetChild(Counter, &DataObject); //Do stuff here
		DataObject->Release() ;
	}
	
	EnumObject->Release();
	Fi1e->Release();
}

VOID ProcessChildObjects(LPD3DXFILEDATA Data)
{
	if(!Data) return;
	SIZE T Size = 0;
	Data->GetChildren(&Size);
	
	for(SIZE_T Counter = 0; Counter < 0; Counter++)
	{
		LPD3DXFILEDATA DataObject = NULL;
		Data->GetChild(Counter, &DataObject); //Do stuff here
		DataObject->Release() ;
	}
}

Получаем данные объекта (Getting Object Data)

Имя объекта

• Берётся их загруженного объекта .x-файла.
• Является необязательным свойством.

HRESULT GetName (
	LPSTR szName, // Указатель на предварительно созданную строку (корректного размера),
				// в которую сохраним имя объекта.
	SIZE_T *puiSize // Размер строки имени в байтах.
	);

SIZE_T Size = 0;
Data->GetName(NULL, &Size);
char* String = new char[Size];
Data->GetName(String, &Size);

Тип объекта

• Берётся их загруженного объекта .x-файла.

HRESULT GetType(const GUID *pType);

...
template MY_GAME_INFO{
<AA13 0 8FD-FF98-4f6e-9A55-CD0 83178672F>
STRING GameName;
STRING GameMaker;
DWORD Version;
}
...

DEFINE_GUID(GUID_MYGAMEINFO, 0xceld5996, Oxcald, 0x4832, 0xa6, 0xd9, 0xc9, 0x23, Oxec, 0x39, Oxfc, Oxf);

GUID ObjectGUID;
Data->GetType(&ObjectGUID);

if(ObjectGUID == GUID_MYGAMEINFO)
{
	// Итерируемый объект имеет искомый тип (шаблон) MY_GAME_INF0
}

Данные объекта (Object Data)

HRESULT Lock (
	SIZE_T *pSize, // Переменная, куда записывается размер буфера данных.
	const VOID **ppData // Указатель предварительно созданной переменной, хранящей данные.
	);

HRESULT Unlock (
	SIZE_T *pSize, // Переменная, куда записывается размер буфера данных.
	const VOID **ppData // Указатель предварительно созданной переменной, хранящей данные.
	);

//Структура данных повторяет оную шаблона MY_GAME_INFO в .x-файле.
struct MY_GAME_INFO {
	char* GameName;
	char* GameMaker;
	DWORD Version;
}

SIZE T Size = 0;
MY_GAME_INFO* MyData = NULL;

Object->Lock((const void**)&MyData, &Size);

// Здесь получаем доступ к данным.

Object->Unlock();

Сохраняем объект данных в .x-файл

HRESULT CreateSaveObject (
	LPCVOID pData, // Имя файла, куда будут сохранены данные. Если нет, создаём.
	D3DXF_FILESAVEOPTIONS flags, // Формат строки имени файла.
		// Возможные значения: D3DXF_FILESAVE_TOFILE и D3DXF_FILESAVE_TOWFILE (строка имени имеет тип wide character).
	D3DXF_FILEFORMAT dwFileFormat, // Формат сохраняемого .x-файла.
		// Возможные значения: D3DXF_FILEFORMAT_BINARY (двоичный), D3DXF_FILEFORMAT_COMPRESSED (сжатый двоичный),
		// D3DXF_FILEFORMAT_TEXT (текстовый).
	ID3DXFileSaveObject **ppSaveObj // Указатель на объект данных, в который временно запишем сохраняемые данные.
	);

LPD3DXFILESAVEOBJECT Save = NULL;
pDXFile->CreateSaveObject("test.x", DXFILEFORMAT_TEXT, &Save);

Подготовка

char *szTemplates = "xof 0302txt 0032"
	template MY_GAME_INFO{\
	<AA13 0 8FD-FF98-4f6e-9A55-CD0 83178672F>\
	STRING GameName;\
	STRING GameMaker;\
	DWORD Version;\ }\

template MY_LEVEL{\
<0FC92315-6897-4f03-B2BD-A6CE20065861>\
STRING Level Name;\
[...]\
}\

template MY_MEDI_KIT{\
<DACC ED4A-433 E-4fa3-91A6-2A8EA6B6D090>\
DWORD XPos;\
DWORD YPos;\
DWORD ZPos;\
};\

File->RegisterTemplates(szTemplates, strlen(s zTemplates));

Сохранение данных

HRESULT CreateDataObject (
	REFGUID rguidTemplate, // GUID выбранного шаблона данных.
	LPCSTR szName, // Имя сохраняемого объекта. Может быть NULL.
	const GUID *pguid, // Обычно здесь ставят NULL.
	DWORD cbSize, // Размер объекта данных в байтах.
	LPVOID pvData, // Указатель на буфер данных, которые будем сохранять.
	ID3DXFileSaveData **ppObj // Адрес, куда сохраним корректный указатель на сохранённый объект данных.
	);

MYGAMEINFO Info;
ZeroMemory(&Info, sizeof(MYGAMEINFO));
Info.Name = "Test";

Save->CreateDataObject(GUID_MYGAMEINFO, "Test", NULL, sizeof(Test), &T, &Data);

Строим дерево иерархии

HRESULT AddDataObject (
	REFGUID rguidTemplate,
	LPCSTR szName,
	const GUID *pld,
	SIZE_T cbSize,
	LPCVOID pvData,
	ID3DXFileSaveData **ppObj
	);

// Добавляем новый объект в качестве потомка к уже существующему объекту в .x-файле.
Data->AddDataObject(ChildData);

Подтверждение сохранения данных (Committing Data)

pSave->Save();

Заключение

Источники