Формат меша (.ply)

Формат .ply используется для хранения мешей в движках семейства GEM RTS. Формат является chunk-based контейнером.

Размер chunk не хранится и должен вычисляться парсером на основе структуры данных chunk-а.

Файл может содержать информацию:

• статические меши;

• skinned mesh;

• большие меши карт;

• меши вспомогательных сеток поверхности земли;

• adjacency data;

• shadow data;

• multiple UV channels;

• tangent space;

• skinning;

• материалы и текстуры.

Структура бинарного файла

EPLY | BPLY | PM01
цикл chunk ID
    INDX | IND4
    VERT
    BAS2
    InfG
    BNDS
    ADJA
    SHDW
    MROR
    MARK
    SKIN
    MESH | SBM1 | SUBM

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

Заголовок файла

Файл .ply начинается с одного из следующих FourCC.

Название	Тип	Размер	Описание
EPLY	uint8[4]	4	Обычный меш с 16-битным индексом.
BPLY	uint8[4]	4	Большой меш с 32-битным индексом. Обычно используется для меша карты.
PM01	uint8[4]	4	GEM3 формат меша.

Стартовый FourCC является идентификатором формата файла и не является обычным chunk-ом. После чтения стартового FourCC парсер последовательно читает файл как набор chunk-ов.

Каталог chunk ID

FourCC	Назначение
INDX	Индексы (16 бит)
IND4	Индексы (32 бит)
VERT	Данные вертексов
BAS2	Базис ландшафтной сетки
InfG	Terrain grid
BNDS	Bounding box
ADJA	Adjacency
SHDW	Shadow data
MROR	Mirrored mesh flag
MARK	Markup data
SKIN	Карта костей
MESH	Сабмеш GEM2
SBM1	Сабмеш GEM RTS 1.1+
SUBM (GEM RTS)	Сабмеш GEM3 / GEM RTS
SUBM (AS2)	Сабмеш Assault Squad 2

Существует два несовместимых варианта чанка SUBM. Структура чанка зависит от стартового значения FourCC ресурса. Парсер должен выбирать соответствующий вариант SUBM в зависимости от значения стартового FourCC.

Chunk INDX | IND4

Структура данных

INDX | IND4
    index_count
    indices[index_count]

Chunk INDX

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	INDX. Индексы меша.
index_count	int32	4	Количество индексов.
indices	uint16[index_count]	2	Массив индексов. Размер индекса определяется стартовым Chunk ID.

Chunk IND4

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	IND4. Индексы меша.
index_count	int32	4	Количество индексов.
indices	uint32[index_count]	4	Массив индексов. Размер индекса определяется стартовым Chunk ID.

Chunk VERT

Структура данных

VERT
    vertex_count
    vertex_size
    vertex_flags
    vertices[vertex_count]
        vertex data

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	VERT
vertex_count	int32	4	Количество вершин
vertex_size	uint16	2	Размер одной вершины в байтах. Движок ориентируется прежде всего на это значение, даже если вычисленный по флагам размер меньше
vertex_flags	uint16	2	Битовая маска флагов вершин (FVF)
vertices	struct[vertex_count]		Массив вершин. Структура вершины зависит от формата сабмеша.

FVF

Флаги для вертексов собираются по битовой маске.

Bit	Описание
0x0001	Полный цвет. Если флаг отсутствует, цвет вершин после загрузки умножается на 2
0x0002	Оптимизированный порядок вершин. Если флаг отсутствует, движок может попытаться автоматически оптимизировать меш после загрузки.
0x0004	Цвет проверен. *)Не используется в GEM RTS

Vertices (struct[vertex_count])

Реальное наличие полей в файле определяется флагами формата вертексов.

Название	Тип	Размер	Описание
position	float[3]	12	Позиция вершины в локальной системе координат.
normal	float[3]	12	Нормаль в локальной системе координат.
tangent	float[3]	12	Касательная в локальной системе координат. Опционально.
uv	float[2]	8	UV координаты текстуры. Может быть несколько наборов UV.
bone_indices	uint8[4]	4	Индексы в локальный bone_remap сабмеша.
bone_weights	uint8[4]	4	Веса костей в формате UNORM8 (0..1).

Chunk BAS2

Базис сетки для карты

Структура данных

BAS2
    polygons
        center
        axis_x
        axis_y
    texture
        center
        axis_x
        axis_y

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	BAS2
polygons.center	float[2]	8	Центр координатной системы генерации треугольников.
polygons.axis_x	float[2]	8	Ось X координатной системы генерации треугольников.
polygons.axis_y	float[2]	8	Ось Y координатной системы генерации треугольников.
texture.center	float[2]	8	Центр координатной системы UV текстуры.
texture.axis_x	float[2]	8	Ось X UV пространства.
texture.axis_y	float[2]	8	Ось Y UV пространства.

Chunk InfG

Большая сетка треугольников для ландшафта.

Структура данных

InfG
    grid_start_xy
    grid_end_xy
    face_count
    faces[face_count]
        submesh : 15
        invalid : 1

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	InfG. Terrain grid.
grid_start_xy	int32[2]	8	Начальные координаты сетки
grid_end_xy	int32[2]	8	Конечные координаты сетки
face_count	uint32	4	Количество треугольников
faces	uint16[face_count]		Массив данных треугольников

Битовая структура faces

Bit	Описание / Значение
0x7FFF	Индекс сабмеша (submesh : 15)
0x8000	Флаг невалидного треугольника (invalid : 1)

Chunk BNDS

Axis-aligned bounding box меша.

Структура данных

BNDS
    min
    max

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	BNDS. Bounding box меша
min	float[3]	12	Минимумы по каждой из осей координат XYZ
max	float[3]	12	Максимумы по каждой из осей координат

Chunk ADJA

Информация о соседних треугольниках.

*)Не используется в GEM RTS.

Структура данных

ADJA
    face_count
    adjacencies[face_count]
        neighbours[3]

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	ADJA. Информация adjacency.
face_count	int32	4	Количество треугольников.
adjacencies	struct[face_count]		Информация о соседях треугольников

Adjacencies (struct)

Название	Тип	Размер	Описание
neighbours	uint16[3]	6	Индексы соседних треугольников. 0xFFFF означает отсутствие соседа.

Chunk SHDW

Информация о тенях.

*)Не используется в GEM RTS.

Структура данных

SHDW
    face_count
    shadow_info[face_count]

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	SHDW Информация о тенях.
face_count	int32	4	Количество треугольников.
shadow_infos	uint8[face_count]		Флаги отбрасывания теней: 0 - не отбрасывает тень 1 - отбрасывает тень

Chunk MROR

Признак отзеркаленного меша.

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	MROR Указывает на отзеркаленный меш

Chunk MARK

Разметка треугольников.

*)Не используется в GEM RTS.

Структура данных

MARK
    mark_size
    marks[mark_size]

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	MARK
mark_size	uint32	4	Размер данных разметки
marks	uint8[mark_size]		Бинарные данные разметки

Chunk SKIN

Карта костей skin-меша.

Структура данных

SKIN
    bone_count
    bone_names[bone_count]
        bone_name

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	SKIN
bone_count	uint32	4	Количество костей
bone_names	string8[bone_count]		Имена костей

Чанки сабмешей (SUBM, SBM1, MESH)

SUBM (GEM3 / GEM RTS, PM01)

Chunk SUBM

Формат описания сабмеша для моделей GEM3 и GEM RTS.

Используется в файлах .ply, если в начале файла указан формат PM01.

Структура данных

SUBM
    vertex_format
    face_start
    face_count
    vertex_start
    vertex_count
    mesh_flags

    [если mesh_flags содержит skin]
        bone_count
        bone_map[bone_count]
        material_name

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	SUBM
vertex_format	uint16	2	Битовая маска формата вершин
face_start	uint16	2	Индекс первого треугольника в сабмеше
face_count	uint16	2	Количество треугольников в сабмеше
vertex_start	uint16	2	Индекс первого вертекса в сабмеше. Не используется в GEM RTS
vertex_count	uint16	2	Количество вертексов в сабмеше. Не используется в GEM RTS
mesh_flags	uint16	2	Битовые флаги свойств меша
material_name	string8/24	1+	Имя материала

Битовая маска vertex_format

Значение	Тип	Коментарий
0x0001	float[3]	Позиция
0x0002	float[3]	Нормаль
0x0004	uint8[4]	Цвет 0, rgba
0x0008	uint8[4]	Цвет 1, rgba
0x0010	float[2]	Текстурные координаты 0
0x0020	float[2]	Текстурные координаты 1
0x0040	float[2]	Текстурные координаты 2
0x0080	float[2]	Текстурные координаты 3
0x0100	float[4]	Тангент
0x0200	uint8	Skin с 2 костями
0x0400	uint8[2]	Skin с 3 костями
0x0600	uint8[3]	Skin с 4 костями. Одновременно установлены признаки 0x0200 и 0x0400
0x0800	float	Амплитуда ветра

Битовая маска mesh_flags

Значение	Описание
0x0001	Двусторонний меш
0x0002	skin

Skin data

Присутствует только если в mesh_flags установлен флаг 0x0002 (skin)

Структура данных

bone_count
bone_map[bone_count]

Название	Тип	Размер	Описание
bone_count	uint8	1	Количество костей в skin-е
bone_map	uint8[bone_count]		Индексы костей в карте костей

SBM1 (GEM RTS 1.1+)

Chunk SBM1

Формат сабмеша GEM RTS 1.1+ для карт.

Структура данных

SBM1

цикл vertex_elements[]
    type_usage
    usage_index
    stream_index

цикл tags[]
    tag_index
    tag_chunk

face_start
face_count
mesh_flags
material_name

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	SBM1
vertex_elements	struct[]		Список элементов vertex info
tags	struct[]		Список пользовательских тегов вершины
face_start	int32	4	Индекс первого треугольника в сабмеше
face_count	int32	4	Количество треугольников в сабмеше
mesh_flags	uint32	4	Битовые флаги меша
material_name	string8/24	1+	Имя материала

Vertex format elements

Список vertex_elements[] содержит описание вертексов.

Список не имеет счетчика элементов и читается последовательно до элемента-терминатора.

Поле type_usage одновременно хранит тип элемента и его назначение:

• (type_usage & 0x0F) определяет тип элемента

• (type_usage & 0xF0) >> 4 определяет назначение элемента

Значение 0xFF используется как терминатор списка и завершает чтение элементов вершинного формата.

Структура элемента

Название	Тип	Размер	Описание
type_usage	uint8	1	Тип элемента и его назначение
usage_index	uint8	1	Индекс использования
stream_index	uint8	1	Индекс потока

Тип элемента

Определяется младшими четырьмя битами поля type_usage.

Значение	Название	Тип	Комментарий
0	FLOAT1	float
1	FLOAT2	float[2]
2	FLOAT3	float[3]
3	FLOAT4	float[4]
4	SHORT2	int16[2]
5	BYTE4	uint8[4]
6	COLOR	uint8[4]	RGBA
7	HALF4	float[4]	half-precision
8	BYTE4N	uint8[4]	unorm8

Назначение элемента

Определяется старшими четырьмя битами поля type_usage.

usage = high nibble of type_usage

Значение	Описание
0	POSITION
1	NORMAL
2	COLOR
3	TEXCOORD
4	BLEND WEIGHT
5	BLEND INDICES
6	TANGENT

Vertex tags

Список tags[] содержит дополнительные пользовательские теги элементов вершины.

Список не имеет счетчика элементов и читается последовательно до элемента-терминатора.

Значение 0xFF используется как терминатор списка тегов.

Структура тега

Название	Тип	Размер	Описание
tag_index	uint8	1	Индекс элемента
tag_chunk	uint32	4	Идентификатор тега

Битовая маска mesh_flags

Значение	Описание
0x0001	Two sided mesh (render this mesh without culling)
0x0002	Use alpha (compatibility mode)
0x0004	Use realtime scene light
0x0008	Use player color light
0x0010	Skinned mesh
0x0020	Shadow volume mesh
0x0040	Mirrored (has negative scaling)
0x0080	Blend by second texture alpha
0x0100	Bump (compatibility mode)
0x0200	Specular color stored
0x0400	Format with material, not textures
0x0800	Sub-skin feature
0x1000	Two textures with one texcoord
0x2000	Using VD (compatibility mode)
0x4000	Has lightmap

SUBM (Assault Squad 2)

Chunk SUBM

Формат описания сабмеша для карт из Assault Squad 2.

Структура данных

SUBM

vertex_elements[]

type_usage

face_start

face_count

unknown[2]

mesh_flags

material_name

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	SUBM
vertex_elements	struct[]		Список элементов vertex info
face_start	uint32	4	Индекс первого треугольника в сабмеше
face_count	uint32	4	Количество треугольников в сабмеше
unknown[2]	uint32[2]	8	Неизвестные данные
mesh_flags	uint32	4	Битовые флаги для меша
material_name	string8	1+	Имя материала

Vertex elements info

Список vertex_elements[] содержит описание вертексов.

Список не имеет счетчика элементов и читается последовательно до элемента-терминатора.

Поле type_usage одновременно хранит тип элемента и его назначение.

• (type_usage & 0x0F) определяет тип элемента.

• (type_usage & 0xF0) >> 4 определяет назначение элемента.

Значение 0xFF используется как терминатор списка и завершает чтение элементов вершинного формата.

Структура элемента

Название	Тип	Размер	Описание
type_usage	uint8	1	Тип элемента и его назначение

Тип элемента

Определяется младшими четырьмя битами поля type_usage.

Значение	Название	Тип	Комментарий
0	FLOAT1	float
1	FLOAT2	float[2]
2	FLOAT3	float[3]
3	FLOAT4	float[4]
4	SHORT2	int16[2]
5	BYTE4	uint8[4]
6	COLOR	uint8[4]	RGBA
7	HALF4	float[4]	half-precision
8	BYTE4N	uint8[4]	unorm8

Назначение элемента

Определяется старшими четырьмя битами поля type_usage.

Значение	Описание
0	POSITION
1	NORMAL
2	COLOR
3	TEXCOORD
4	BLEND WEIGHT
5	BLEND INDICES
6	TANGENT

Битовая маска mesh_flags

Значение	Описание
0x0001	Two sided mesh (render this mesh without culling)
0x0002	Use alpha (compatibility mode)
0x0004	Use realtime scene light
0x0008	Use player color light
0x0010	Skinned mesh
0x0020	Shadow volume mesh
0x0040	Mirrored (has negative scaling)
0x0080	Blend by second texture alpha
0x0100	Bump (compatibility mode)
0x0200	Specular color stored
0x0400	Format with material, not textures
0x0800	Sub-skin feature
0x1000	Two textures with one texcoord
0x2000	Using VD (compatibility mode)
0x4000	Has lightmap

MESH (Legacy, Faces of War / Men of War)

Chunk MESH

Legacy формат сабмеша из Faces of War / Men of War.

Структура данных

MESH
    fvf
    face_start
    face_count
    mesh_flags

    [если mesh_flags содержит specular]
        specular_color
    [если mesh_flags содержит use material]
        material_name
    [иначе]
        texture data
            [если mesh_flags содержит specular | bump]
                diffuse
                [если mesh_flags содержит specular]
                    specular_texture
                [если mesh_flags содержит bump]
                    bump_texture
            [иначе]
                [если uv==2 | mesh_flags содержит флаг two textures with one texcoord]
                    diffuse_0
                    diffuse_1
                [иначе]
                    diffuse
    [если mesh_flags содержит флаг skinned mesh]
        bone_map_size
        bone_map[bone_map_size]

Название	Тип	Размер	Описание
FourCC	uint8[4]	4	MESH Legacy формат сабмеша.
fvf	uint32	4	Битовая маска формата вершин.
face_start	int32	4	Индекс первого треугольника.
face_count	int32	4	Количество треугольников.
mesh_flags	uint32	4	Битовые флаги меша.

Vertex Format Flags (FVF)

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

Bit	Описание
0x002	position float[3]
0x006	position float[3] blend_weight uint8 blend_indices uint8[4]
0x008	position float[3] blend_weight uint8[2] blend_indices uint8[4]
0x00A	position float[3] blend_weight uint8[3] blend_indices uint8[4]
0x010	normal float[3]
0x040	diffuse_color uint8[4]
0x080	specular_color uint8[4]
0xN00	texcoord_mask N*float[2]
0x8000E000	tangent float[4]

Битовая маска mesh_flags

Значение	Описание
0x0001	Two sided mesh (render this mesh without culling)
0x0002	Use alpha (compatibility mode)
0x0004	Use realtime scene light
0x0008	Use player color light
0x0010	Skinned mesh
0x0020	Shadow volume mesh
0x0040	Mirrored (has negative scaling)
0x0080	Blend by second texture alpha
0x0100	Bump (compatibility mode)
0x0200	Specular
0x0400	Use material
0x0800	Sub-skin feature
0x1000	Two textures with one texcoord
0x2000	Using VD (compatibility mode)
0x4000	Has lightmap

Specular color

Поле присутствует, если mesh_flags содержит 0x0200 (specular).

Название	Тип	Размер	Описание
specular_color	uint8[4]	4	Цвет для спекуляра

Material name

Поле присутствует, если mesh_flags содержит 0x0400 (use material).

Название	Тип	Размер	Описание
material_name	string8/24	1+	Имя материала

Texture data

Данные текстур загружаются, если mesh_flags не содержит 0x0400 (use material). Структура зависит от флагов specular, bump, количества текстурных координат (UV) и флага two textures with one texcoord.

Texture data для standard material

Используется, если mesh_flags содержит specular или bump.

Название	Тип	Размер	Описание
diffuse	string8/24	1+	Имя диффузной текстуры
specular_texture	string8/24	1+	Имя текстуры спекуляра. Поле присутствует, если mesh_flags содержит specular
bump_texture	string8/24	1+	Имя текстуры карты нормалей. Поле присутствует, если mesh_flags содержит bump

Texture data для материала из двух текстур

Используется, если standard material не загружается и выполняется одно из условий:

• uv == 2

• mesh_flags содержит two textures with one texcoord

Название	Тип	Размер	Описание
diffuse_0	string8/24	1+	Имя диффузной текстуры 0
diffuse_1	string8/24	1+	Имя диффузной текстуры 1

Texture data для одной текстуры

Используется, если standard material не загружается и условия для использования двух текстур не выполняются.

Название	Тип	Размер	Описание
diffuse	string8/24	1+	Имя диффузной текстуры

Skin data

Данные skin-а присутствуют, если mesh_flags содержит skinned mesh.

Название	Тип	Размер	Описание
bone_map_size	uint8	1	Размер таблицы локального ремаппинга костей
bone_map	uint8[bone_map_size]		Таблица локального ремаппинга костей.

Таблица bone_map используется для сопоставления костей сабмеша с общей картой костей модели, хранящейся в chunk SKIN.

Каждый элемент массива содержит индекс кости из SKIN, увеличенный на 1.

Значения vertex.bone_index в вершинах ссылаются на элементы массива bone_map, а не напрямую на кости в SKIN.

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

Значения bone_map:

• 0: указание использовать общую матрицу меша

• N > 0: указание использовать кость SKIN.bones[N - 1]