docs: rewrite MkDocs documentation
This commit is contained in:
@@ -0,0 +1,863 @@
|
||||
# V. Геометрия, материалы и рендер
|
||||
|
||||
Этот том описывает путь от загруженного игрового состояния до pixels в back
|
||||
buffer. Renderer не решает игровые правила: он получает transforms, geometry,
|
||||
материалы, свет, эффекты, камеру и список видимых объектов, затем превращает
|
||||
их в упорядоченный набор draw calls и fixed-function states.
|
||||
|
||||
Графический pipeline FParkan держится на нескольких слоях данных:
|
||||
|
||||
```text
|
||||
MSH node/slot/batch
|
||||
-> Batch20.material_index
|
||||
-> строка WEAR
|
||||
-> имя MAT0
|
||||
-> активная phase
|
||||
-> textureName и lightmap slot
|
||||
-> Texm payload
|
||||
-> LegacyRenderState
|
||||
-> draw item кадра
|
||||
```
|
||||
|
||||
Важное практическое правило: форматы ресурсов, runtime-состояние renderer-а и
|
||||
современный backend являются разными уровнями. Файл можно прочитать правильно и
|
||||
всё равно получить неверный кадр из-за другой сортировки, другого mip-skip,
|
||||
другой ветки material fallback или другого округления animation time.
|
||||
|
||||
## Контур рендера
|
||||
|
||||
Изображение является последней стадией длинного цикла. До renderer-а уже
|
||||
накоплен ввод, рассчитан simulation step, применены отложенные операции,
|
||||
обновлены animation states, выбрана camera и выставлен listener для 3D sound.
|
||||
|
||||
```text
|
||||
system messages and input
|
||||
-> simulation calculation
|
||||
-> deferred object operations
|
||||
-> animation and transforms
|
||||
-> camera and sound listener
|
||||
-> visibility and render queues
|
||||
-> materials and draw passes
|
||||
-> renderer completion
|
||||
-> end-of-render callbacks and UI
|
||||
```
|
||||
|
||||
CPU делает отбор объектов, сэмплирует animation, собирает matrices, выбирает
|
||||
LOD/slot, группирует batches и готовит состояния. Графический pipeline
|
||||
преобразует вершины из model space в screen space, rasterizes triangles,
|
||||
проверяет depth, применяет texture stages, lighting, alpha test/blend и пишет
|
||||
pixels.
|
||||
|
||||
Координатный путь вершины:
|
||||
|
||||
```text
|
||||
local/model space
|
||||
-> world space
|
||||
-> view/camera space
|
||||
-> clip space
|
||||
-> normalized device coordinates
|
||||
-> viewport pixels
|
||||
```
|
||||
|
||||
Порядок умножения матриц и соглашение о layout должны быть едины во всём
|
||||
движке. Ошибка транспонирования часто выглядит как сломанная анимация, хотя
|
||||
ключи модели прочитаны верно.
|
||||
|
||||
## Граница Ngi32
|
||||
|
||||
`Ngi32.dll` является платформенной границей Iron3D-era renderer-а. Она создаёт
|
||||
графический и звуковой interfaces, перечисляет устройства, хранит capability
|
||||
profile, предоставляет память, часы и быстрые математические процедуры.
|
||||
Высокоуровневые DLL должны обращаться к interface Ngi32, а не напрямую к
|
||||
конкретному DirectDraw/Direct3D device.
|
||||
|
||||
`iron_3d.ini` задаёт выбранный `CURRENT_D3DCARD`. Display layer перечисляет
|
||||
drivers и video modes, проверяет поддержку 3D, переводит native capabilities во
|
||||
внутренний профиль и создаёт render object. `niCreate3DRender` принимает
|
||||
выбранный driver/mode, window handle и flags владения, динамически получает
|
||||
функции DirectDraw/Direct3D семейства 5-7 и публикует refcounted renderer.
|
||||
`niGet3DRender` возвращает уже созданный объект и увеличивает число владельцев.
|
||||
|
||||
```text
|
||||
enumerate adapters and video modes
|
||||
-> choose CURRENT_D3DCARD
|
||||
-> translate native capabilities
|
||||
-> create DirectDraw surfaces and 3D interface
|
||||
-> construct engine renderer
|
||||
-> publish global refcounted pointer
|
||||
```
|
||||
|
||||
Старый API работает как state machine. Перед draw подсистема terrain/shade
|
||||
выбирает matrices, texture stages, filtering, depth test/write, culling, alpha
|
||||
test, blending и vertex format. Современный backend может собрать это в
|
||||
immutable pipeline key и реализовать через shaders, но compatibility layer
|
||||
должен видеть исходную fixed-function модель.
|
||||
|
||||
```c
|
||||
struct LegacyRenderState {
|
||||
Mat4 world, view, projection;
|
||||
TextureStage stages[2];
|
||||
BlendMode blend;
|
||||
DepthMode depth;
|
||||
CullMode cull;
|
||||
bool alpha_test;
|
||||
uint8_t alpha_ref;
|
||||
VertexFormat vertex_format;
|
||||
};
|
||||
```
|
||||
|
||||
Эта структура является переносимой моделью наблюдаемого контракта, а не
|
||||
утверждением о точном layout оригинального объекта renderer-а.
|
||||
|
||||
Отдельная часть ABI -- таблица `g_FastProc`. При запуске выбираются scalar,
|
||||
MMX, Katmai/SSE, 3DNow или PPro-реализации процедур, а `niGetProcAddress(index)`
|
||||
возвращает pointer из изменяемой таблицы. Номер slot является частью ABI:
|
||||
signature менять нельзя. Различия scalar/SIMD округления способны менять
|
||||
animation sampling, culling, particles и даже gameplay-adjacent decisions.
|
||||
|
||||
## MSH как граф модели
|
||||
|
||||
`*.msh` является nested NRes, а не одной монолитной структурой. Geometry,
|
||||
nodes, slots, batches, animation и служебные streams лежат в отдельных entries
|
||||
и связываются по `type_id`. Физический порядок entries сохраняется для
|
||||
roundtrip, но reader не должен выводить из него смысловую связь.
|
||||
|
||||
Карта основных entries:
|
||||
|
||||
```text
|
||||
type 1 узлы и выбор slot, обычно stride 38
|
||||
type 2 header 0x8C + slots по 68 байт
|
||||
type 3 positions float3, stride 12
|
||||
type 4 packed normals, stride 4
|
||||
type 5 packed UV0, stride 4
|
||||
type 6 index buffer, u16
|
||||
type 7 triangle descriptors, stride 16
|
||||
type 8 animation keys, stride 24
|
||||
type 9 служебный поток модели
|
||||
type 10 строки и имена узлов
|
||||
type 13 draw batches, stride 20
|
||||
type 15 дополнительный поток, stride 8
|
||||
type 17 вспомогательные данные
|
||||
type 18 редкий поток, stride 4
|
||||
type 19 animation frame map, u16
|
||||
type 20 редкая вспомогательная таблица
|
||||
```
|
||||
|
||||
Базовый набор types стабилен для проверенных моделей Частей 1 и 2. Расширенный
|
||||
вариант добавляет types 18 и 20. Редкий вариант `MTCHECK.MSH` имеет
|
||||
альтернативный атрибут type 1; его payload нужно поддерживать copy-through до
|
||||
закрытия layout.
|
||||
|
||||
### Узлы и slots
|
||||
|
||||
Type 1 обычно состоит из записей по 38 байт:
|
||||
|
||||
```c
|
||||
struct Node38 {
|
||||
uint16_t hdr0;
|
||||
uint16_t parent_or_link;
|
||||
uint16_t anim_map_start;
|
||||
uint16_t fallback_key;
|
||||
uint16_t slot_index[15];
|
||||
};
|
||||
```
|
||||
|
||||
`slot_index` образует матрицу `3 LOD x 5 groups`. Выбор выполняется как
|
||||
`slot_index[lod * 5 + group]`; `0xFFFF` означает отсутствие geometry для этой
|
||||
комбинации. Поле `parent_or_link` участвует в иерархии или связи узлов, но
|
||||
название остаётся описательным.
|
||||
|
||||
Type 2 начинается с header `0x8C`, затем содержит slots по 68 байт:
|
||||
|
||||
```c
|
||||
struct Slot68 {
|
||||
uint16_t tri_start;
|
||||
uint16_t tri_count;
|
||||
uint16_t batch_start;
|
||||
uint16_t batch_count;
|
||||
float aabb_min[3];
|
||||
float aabb_max[3];
|
||||
float sphere_center[3];
|
||||
float sphere_radius;
|
||||
uint32_t opaque[5];
|
||||
};
|
||||
```
|
||||
|
||||
Slot связывает диапазон triangle descriptors, диапазон draw batches, AABB и
|
||||
sphere bounds. AABB удобен для более точных осевых тестов, sphere -- для
|
||||
быстрого отбрасывания. Последние пять слов сохраняются без интерпретации.
|
||||
|
||||
Обязательные проверки:
|
||||
|
||||
- `type 2` имеет размер не меньше `0x8C`;
|
||||
- остаток после header кратен 68;
|
||||
- каждый `slot_index` либо `0xFFFF`, либо меньше числа slots;
|
||||
- `tri_start + tri_count` не выходит за type 7;
|
||||
- `batch_start + batch_count` не выходит за type 13.
|
||||
|
||||
### Vertex streams, triangles и batches
|
||||
|
||||
Основные vertex streams:
|
||||
|
||||
```text
|
||||
type 3: position = три float32
|
||||
type 4: normal = четыре int8
|
||||
type 5: UV0 = два int16
|
||||
type 6: index = uint16
|
||||
```
|
||||
|
||||
Normal XYZ декодируется как signed component / `127.0` с clamp в `[-1, 1]`.
|
||||
Четвёртый byte normal stream не отбрасывается при roundtrip. UV декодируется
|
||||
как `packed / 1024.0`. Index buffer адресует вершины относительно `base_vertex`
|
||||
batch-а, поэтому проверка допустимости всегда использует
|
||||
`base_vertex + index < vertex_count`.
|
||||
|
||||
Type 7 хранит descriptors triangles:
|
||||
|
||||
```c
|
||||
struct TriDesc16 {
|
||||
uint16_t tri_flags;
|
||||
uint16_t link0;
|
||||
uint16_t link1;
|
||||
uint16_t link2;
|
||||
int16_t nx;
|
||||
int16_t ny;
|
||||
int16_t nz;
|
||||
uint16_t sel_packed;
|
||||
};
|
||||
```
|
||||
|
||||
Descriptors используются коллизией, выбором и связями triangles. `sel_packed`
|
||||
содержит три двухбитовых selector-а; значение `3` преобразуется в отсутствие
|
||||
ссылки (`0xFFFF`). Полная семантика links и flags не закрывается одним layout.
|
||||
|
||||
Type 13 задаёт draw ranges:
|
||||
|
||||
```c
|
||||
#pragma pack(push, 1)
|
||||
struct Batch20 {
|
||||
uint16_t batch_flags; // +0x00
|
||||
uint16_t material_index; // +0x02
|
||||
uint16_t opaque4; // +0x04
|
||||
uint16_t opaque6; // +0x06
|
||||
uint16_t index_count; // +0x08
|
||||
uint32_t index_start; // +0x0A
|
||||
uint16_t opaque14; // +0x0E
|
||||
uint32_t base_vertex; // +0x10
|
||||
};
|
||||
#pragma pack(pop)
|
||||
static_assert(sizeof(Batch20) == 20);
|
||||
```
|
||||
|
||||
`material_index` выбирает строку WEAR. `index_start`, `index_count` и
|
||||
`base_vertex` описывают один indexed draw. Неизвестные поля могут влиять на
|
||||
редкие проходы или state grouping, поэтому writer сохраняет их 1:1.
|
||||
|
||||
Типовой обход модели:
|
||||
|
||||
```c
|
||||
for (Node& node : model.nodes) {
|
||||
Matrix node_world = parent_world * local_transform(node);
|
||||
uint16_t sid = node.slot_index[lod * 5 + group];
|
||||
if (sid == 0xFFFF) continue;
|
||||
|
||||
Slot& slot = model.slots[sid];
|
||||
if (camera.culls(transform(slot.bounds, node_world))) continue;
|
||||
|
||||
for (uint32_t i = 0; i < slot.batch_count; ++i) {
|
||||
Batch& b = model.batches[slot.batch_start + i];
|
||||
bind_wear_material(b.material_index);
|
||||
draw_indexed(b.base_vertex, b.index_start, b.index_count);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
В реальном кадре между culling и draw добавляются material resolve, lightmap,
|
||||
render queues и сортировка, но связи данных остаются такими.
|
||||
|
||||
## Иерархия и анимация
|
||||
|
||||
Анимация MSH меняет локальный transform узлов. Geometry streams не изменяются:
|
||||
для каждого узла на кадр строится matrix из position и quaternion. Дочерний
|
||||
узел наследует transform родителя, поэтому изменение корпуса переносит башню,
|
||||
точки крепления и все связанные slots.
|
||||
|
||||
Связка состоит из:
|
||||
|
||||
- type 8: пул animation keys;
|
||||
- type 19: карта кадров;
|
||||
- `anim_map_start` и `fallback_key` в `Node38`;
|
||||
- parent links, задающих порядок умножения matrices.
|
||||
|
||||
Ключ type 8 занимает 24 байта:
|
||||
|
||||
```c
|
||||
struct AnimKey24 {
|
||||
float position[3];
|
||||
float time;
|
||||
int16_t qx;
|
||||
int16_t qy;
|
||||
int16_t qz;
|
||||
int16_t qw;
|
||||
};
|
||||
```
|
||||
|
||||
Quaternion components декодируются как signed value / `32767.0`. На диске
|
||||
порядок полей XYZ-W, но runtime math использует логическое `[w, x, y, z]`.
|
||||
Безусловная современная нормализация после чтения не добавляется без parity
|
||||
проверки: она может изменить крайние кадры.
|
||||
|
||||
Type 19 является массивом `uint16_t`; его `attr2` задаёт общее число кадров
|
||||
timeline. Для конкретного узла `anim_map_start` указывает на блок длиной
|
||||
`frame_count` либо равен `0xFFFF`.
|
||||
|
||||
Выбор ключа:
|
||||
|
||||
1. вычислить frame index из времени;
|
||||
2. если frame вне диапазона, взять `fallback_key`;
|
||||
3. если `anim_map_start == 0xFFFF`, взять `fallback_key`;
|
||||
4. иначе прочитать `map_words[anim_map_start + frame]`;
|
||||
5. если значение не меньше `fallback_key`, снова использовать fallback;
|
||||
6. иначе использовать mapped key и следующий key для interpolation.
|
||||
|
||||
Fallback возвращается без interpolation. Это защищает статические узлы и конец
|
||||
track-а.
|
||||
|
||||
Для времени между двумя keys:
|
||||
|
||||
```text
|
||||
alpha = (t - k0.time) / (k1.time - k0.time)
|
||||
position = lerp(k0.position, k1.position, alpha)
|
||||
rotation = shortest-path quaternion blend
|
||||
```
|
||||
|
||||
Перед quaternion blend проверяется dot product. Если стороны находятся в
|
||||
противоположных полусферах, знак второй стороны меняется, чтобы пройти по
|
||||
короткому пути. При точном совпадении времени возвращается соответствующий key
|
||||
без вычисления alpha.
|
||||
|
||||
Объект может переходить между двумя animation states. Тогда для каждого узла
|
||||
сэмплируются позы A и B, затем position смешивается линейно, а quaternion --
|
||||
через shortest-path blend. Если одна сторона невалидна, используется другая.
|
||||
|
||||
```c
|
||||
Pose sample_node(Node n, float t);
|
||||
Pose blend_pose(Pose a, Pose b, float weight);
|
||||
Mat4 local = quaternion_matrix(pose.rotation);
|
||||
local.set_translation(pose.position);
|
||||
world[n] = world[parent(n)] * local;
|
||||
```
|
||||
|
||||
Для parity особенно важны x87-compatible округление при выборе frame index и
|
||||
порядок операций. Одинаковая формула на SSE может выбрать соседний кадр возле
|
||||
границы.
|
||||
|
||||
Проверки animation data:
|
||||
|
||||
- размер type 8 кратен 24;
|
||||
- размер type 19 кратен 2;
|
||||
- каждый `fallback_key` меньше числа keys;
|
||||
- блок карты узла полностью помещается в type 19;
|
||||
- времена keys внутри track возрастают;
|
||||
- parent links не образуют cycle;
|
||||
- quaternion components читаются как signed 16-bit.
|
||||
|
||||
## WEAR и MAT0
|
||||
|
||||
MSH batch хранит только числовой `material_index`. WEAR переводит позиционный
|
||||
slot в имя материала. MAT0 по этому имени описывает phases, parameters,
|
||||
texture names и animation blocks. Такое разделение позволяет одной geometry
|
||||
использовать разные appearances.
|
||||
|
||||
```text
|
||||
Batch20.material_index
|
||||
-> строка WEAR
|
||||
-> имя MAT0
|
||||
-> активная phase
|
||||
-> textureName и render parameters
|
||||
```
|
||||
|
||||
### WEAR
|
||||
|
||||
WEAR имеет type ID `0x52414557` и обычно хранится как `*.wea` рядом с моделью.
|
||||
Формат текстовый:
|
||||
|
||||
```text
|
||||
<wearCount>
|
||||
<legacyId> <materialName>
|
||||
... wearCount строк
|
||||
|
||||
[пустая строка]
|
||||
[LIGHTMAPS
|
||||
<lightmapCount>
|
||||
<legacyId> <lightmapName>
|
||||
... lightmapCount строк]
|
||||
```
|
||||
|
||||
`legacyId` читается и сохраняется, но material выбирается по позиции строки и
|
||||
имени. Пустая строка перед `LIGHTMAPS` является частью совместимого framing:
|
||||
parser paths по-разному обрабатывают переход, и отсутствие разделителя ломает
|
||||
совместимость. Material handle кодируется как `(table_index << 16) |
|
||||
wear_index`; manager поддерживает ограниченное число wear tables.
|
||||
|
||||
Fallback material resolve строго разделён:
|
||||
|
||||
1. имя из WEAR;
|
||||
2. `DEFAULT`;
|
||||
3. entry 0;
|
||||
4. для lightmap отсутствие означает slot `-1`, а не замену обычной texture.
|
||||
|
||||
Пустое имя texture внутри phase означает намеренно untextured surface.
|
||||
Lightmap ищется в отдельном cache и не подменяется diffuse texture.
|
||||
|
||||
### MAT0
|
||||
|
||||
MAT0 имеет type ID `0x3054414D` и обычно находится в `Material.lib`. `attr1`
|
||||
содержит runtime flags, `attr2` -- версию payload. Versioned metadata читается
|
||||
cursor-ом: старые версии получают runtime defaults, но reader не пытается
|
||||
насильно читать поля новой версии.
|
||||
|
||||
```c
|
||||
#pragma pack(push, 1)
|
||||
struct Mat0PrefixV4Plus {
|
||||
uint16_t phase_count; // +0x00
|
||||
uint16_t animation_block_count; // +0x02, меньше 20
|
||||
uint8_t metadata_a; // +0x04, attr2 >= 2
|
||||
uint8_t metadata_b; // +0x05, attr2 >= 2
|
||||
uint32_t metadata_c_raw; // +0x06, attr2 >= 3
|
||||
uint32_t metadata_d_raw; // +0x0A, attr2 >= 4
|
||||
};
|
||||
|
||||
struct Phase34 {
|
||||
uint8_t parameters[18];
|
||||
char texture_name[16];
|
||||
};
|
||||
#pragma pack(pop)
|
||||
static_assert(sizeof(Phase34) == 34);
|
||||
```
|
||||
|
||||
Если `attr2 < 2`, metadata A/B получают default `255`; при `attr2 < 3`
|
||||
значение C соответствует `1.0f`; при `attr2 < 4` D равно 0. C/D сохраняются
|
||||
как raw 32-bit values до полного подтверждения интерпретации. Phase parameters
|
||||
сохраняются как 18 raw bytes даже там, где часть bytes уже имеет понятный
|
||||
смысл.
|
||||
|
||||
Каждая phase разворачивается в runtime-запись примерно 76 байт: коэффициенты
|
||||
цвета, освещения и прозрачности, texture slot и служебные поля. Material time
|
||||
выбирает одну или две phases; только часть полей интерполируется, остальные
|
||||
копируются из активной записи.
|
||||
|
||||
Animation block MAT0 имеет плотный framing без 4-byte tail alignment:
|
||||
|
||||
```text
|
||||
u32 header_raw
|
||||
u16 key_count
|
||||
repeat key_count:
|
||||
u16 k0
|
||||
u16 k1
|
||||
u16 k2
|
||||
```
|
||||
|
||||
Младшие три бита `header_raw` задают числовой mode, остальные образуют mask
|
||||
interpolation. Наблюдаются modes 0, 1, 2 и 3, связанные с семействами loop,
|
||||
ping-pong, one-shot/clamp и random-offset, но точные boundary cases остаются
|
||||
предметом runtime parity. Поле `k2` сохраняется всегда.
|
||||
|
||||
Проверки MAT0:
|
||||
|
||||
- `animation_block_count < 20`;
|
||||
- все versioned metadata помещаются в payload;
|
||||
- секция phases имеет ровно `phase_count * 34` байта;
|
||||
- `texture_name` ограничено 16 байтами;
|
||||
- каждый animation block и его keys помещаются в payload;
|
||||
- parser заканчивает чтение на точном конце записи.
|
||||
|
||||
Material manager кэширует разобранный MAT0 и texture handles. Current phase
|
||||
лучше вычислять на экземпляр материала, если random offset или локальное время
|
||||
различаются между объектами; immutable phase data остаются общими.
|
||||
|
||||
## Texm: текстуры, mip-уровни и атласы
|
||||
|
||||
`Texm` -- основной формат изображений. Он хранится в `Textures.lib`,
|
||||
`LightMap.lib` и других NRes-архивах. Payload содержит header, необязательную
|
||||
palette, mip chain и иногда `Page` chunk для atlas rectangles.
|
||||
|
||||
```c
|
||||
struct TexmHeader32 {
|
||||
uint32_t magic; // 'Texm'
|
||||
uint32_t width;
|
||||
uint32_t height;
|
||||
uint32_t mip_count;
|
||||
uint32_t flags4;
|
||||
uint32_t flags5;
|
||||
uint32_t unknown6;
|
||||
uint32_t format;
|
||||
};
|
||||
```
|
||||
|
||||
Подтверждённые formats:
|
||||
|
||||
```text
|
||||
0 Indexed8 + palette 256 x 4 байта
|
||||
565 R5 G6 B5
|
||||
556 R5 G5 B6
|
||||
4444 A4 R4 G4 B4
|
||||
88 L8 A8
|
||||
888 RGB8 в четырёхбайтовом element
|
||||
8888 A8 R8 G8 B8
|
||||
```
|
||||
|
||||
Formats 556 и 88 являются loader-confirmed, но не corpus-verified для
|
||||
доступных игровых payload. CPU decoder расширяет короткие каналы до 8 bit через
|
||||
повторение значимых bit, а не простым shift. Для 888 служебный четвёртый byte
|
||||
сохраняется при roundtrip.
|
||||
|
||||
Layout:
|
||||
|
||||
```text
|
||||
TexmHeader32
|
||||
[palette 1024 байта, только для format 0]
|
||||
level 0 pixels
|
||||
level 1 pixels
|
||||
...
|
||||
level mip_count-1 pixels
|
||||
[optional Page chunk]
|
||||
```
|
||||
|
||||
Размер уровня `i` вычисляется из `max(1, width >> i)` и
|
||||
`max(1, height >> i)`. Bytes per pixel: 1 для indexed; 2 для 565, 556, 4444 и
|
||||
88; 4 для 888 и 8888. Parser суммирует размеры с проверкой overflow до чтения.
|
||||
|
||||
`Page` chunk:
|
||||
|
||||
```c
|
||||
struct PageHeader8 {
|
||||
uint32_t magic; // 'Page'
|
||||
uint32_t rect_count;
|
||||
};
|
||||
|
||||
struct PageRect8 {
|
||||
int16_t x;
|
||||
int16_t width;
|
||||
int16_t y;
|
||||
int16_t height;
|
||||
};
|
||||
```
|
||||
|
||||
Chunk обязан иметь размер `8 + rect_count * 8`; произвольный tail не
|
||||
допускается. Rectangles задаются в pixel space базового mip. Если loader
|
||||
пропускает верхние mip-уровни, rectangles масштабируются вместе с новым base
|
||||
level.
|
||||
|
||||
Mip-skip является поведением loader-а, а не offline-изменением файла. После
|
||||
skip меняются runtime width, height, mip count и pointer на первый загружаемый
|
||||
уровень. Современный renderer должен повторить выбор base level или
|
||||
эквивалентно эмулировать его upload policy; использование полной texture при
|
||||
тех же UV меняет резкость и atlas coordinates.
|
||||
|
||||
Indexed texture требует связанную palette. Часть palettes выбирается по suffix
|
||||
имени: буква `A..Z` и вариант пустой или `0..9`, всего 286 возможных slots.
|
||||
Невалидный suffix диагностируется явно.
|
||||
|
||||
Обычные textures и lightmaps находятся в разных managers. Обычный cache
|
||||
отслеживает refcount и время неиспользования, а eviction выполняется
|
||||
отложенно. Lightmap lifetime связан с world/mission и не должен попадать под
|
||||
ту же политику удаления.
|
||||
|
||||
Строгий Texm parser проверяет положительные dimensions, положительный
|
||||
`mip_count`, известный format, точный размер palette/mip chain, корректный
|
||||
`Page` и отсутствие лишних bytes. `flags4`, `flags5` и `unknown6` сохраняются
|
||||
1:1; участие `flags5` в mip-skip подтверждено, но полная семантика всех bits не
|
||||
закрыта.
|
||||
|
||||
## Свет, тени, атмосфера и сортировка
|
||||
|
||||
Свет является отдельной world-подсистемой. Terrain layer создаёт
|
||||
`LightManager`, `Shader` и primitive managers. Это не один глобальный
|
||||
коэффициент яркости: world управляет point lights, lightmaps, shadows,
|
||||
atmospheric objects и sort phases. Материал сообщает свойства поверхности, а
|
||||
CShade превращает их в states renderer-а.
|
||||
|
||||
Подтверждённые точки: `CreateLightManager`, `CreateShader`,
|
||||
`CreateAtmosphere`, `CreatePrimitives`, `CreatePrimitives2`,
|
||||
`CShade::StartMeshRender`, `CShade::EndMeshRender` и
|
||||
`CShade::ConfigureTextureAndAlphaBlendModes`.
|
||||
|
||||
CShade получает active MAT0 phase, capability profile устройства и pass
|
||||
context. Он выбирает texture mode, alpha blending, depth/cull behavior и способ
|
||||
освещения. Наличие fallback вроде `TEXTUREMODE_MODULATE not supported`
|
||||
означает, что material нельзя напрямую преобразовать в современный PBR.
|
||||
Сначала строится legacy state, затем он сопоставляется shader permutation.
|
||||
|
||||
CLightManager выдаёт numeric IDs источникам и проверяет допустимое количество.
|
||||
Ветка `EmulatePointLights()` позволяет воспроизводить point lights даже при
|
||||
ограничениях hardware lighting. Неизвестный type light должен давать отдельную
|
||||
ошибку.
|
||||
|
||||
Lightmap не является обычной diffuse texture. WEAR содержит отдельный блок
|
||||
`LIGHTMAPS`, manager открывает `LightMap.lib`, а shade path подаёт lightmap
|
||||
отдельным slot или texture stage. Замена lightmap предварительным умножением в
|
||||
diffuse texture ломает LOD, atlas coordinates и динамическую модуляцию.
|
||||
|
||||
Тени проходят отдельным render pass. Terrain содержит пути для теней зданий и
|
||||
роботов, ограничения максимального числа, detail level и smoothing. Доказаны
|
||||
shadow manager/pass, настройки detail/smoothing/count и зависимость от
|
||||
Terrain/CShade; полная формула projection geometry для каждого caster требует
|
||||
dynamic trace. Unknown settings из `shade.cfg` читаются и сохраняются по
|
||||
именам, а не заменяются произвольными modern defaults.
|
||||
|
||||
Atmosphere manager создаёт world objects для фоновых и погодных явлений.
|
||||
Отдельно подтверждены lightning, sun render, flare, `env_lightning`, rain
|
||||
background sound и обязательные ссылки на lightning effect. Эти объекты
|
||||
обновляются по игровому времени, но часть параметров зависит от camera: flare
|
||||
требует screen position и occlusion test, rain -- области рядом с observer,
|
||||
sound -- listener. Их нельзя один раз запечь в terrain.
|
||||
|
||||
RNG для lightning, atmosphere phases и FX должен иметь стабильный порядок.
|
||||
Даже правильный средний интервал не даёт повторяемый кадр, если random values
|
||||
запрашиваются в другой последовательности.
|
||||
|
||||
Согласованная модель sort phases:
|
||||
|
||||
```text
|
||||
opaque terrain and models
|
||||
-> lightmapped/state-grouped passes
|
||||
-> shadows and projected primitives
|
||||
-> alpha-tested surfaces
|
||||
-> transparent objects/effects back-to-front
|
||||
-> atmosphere, flares and overlays
|
||||
```
|
||||
|
||||
Точный взаимный порядок отдельных FX, shadow и atmosphere subpasses требует
|
||||
capture. Новый renderer должен хранить явный `RenderPhase` и стабильный
|
||||
secondary sort key, а не сортировать всё только по material ID.
|
||||
|
||||
## FXID: система эффектов
|
||||
|
||||
FXID -- не готовая картинка, а описание небольшого runtime command stream.
|
||||
Header задаёт lifetime, time mode, random shifts и transform. Затем идут
|
||||
команды разных types. При создании manager превращает disk-команды в runtime
|
||||
objects; во время кадра они обновляются и выпускают sounds, particles,
|
||||
materials или projected primitives.
|
||||
|
||||
Type ID равен `0x44495846`. Header занимает 60 байт:
|
||||
|
||||
```c
|
||||
struct FxHeader60 {
|
||||
uint32_t command_count;
|
||||
uint32_t time_mode;
|
||||
float duration_seconds;
|
||||
float phase_jitter;
|
||||
uint32_t flags;
|
||||
uint32_t settings_id;
|
||||
float random_shift[3];
|
||||
float pivot[3];
|
||||
float scale[3];
|
||||
};
|
||||
```
|
||||
|
||||
Поток команд начинается строго с offset `0x3C`. `duration_seconds`
|
||||
преобразуется runtime-ом во внутреннюю шкалу времени. `phase_jitter` и
|
||||
`random_shift` используются только при соответствующих flags. Pivot задаёт
|
||||
локальную точку опоры, scale -- базовый масштаб экземпляра. Unknown flags и
|
||||
settings ID сохраняются.
|
||||
|
||||
Каждая команда начинается с `uint32_t command_word`:
|
||||
|
||||
```text
|
||||
opcode = command_word & 0xFF
|
||||
enabled = (command_word >> 8) & 1
|
||||
```
|
||||
|
||||
Bits 9-31 являются частью данных и сохраняются. Между командами нет
|
||||
выравнивания. Размер команды, включая word:
|
||||
|
||||
```text
|
||||
opcode 1 224 байта
|
||||
opcode 2 148 байт
|
||||
opcode 3 200 байт
|
||||
opcode 4 204 байта
|
||||
opcode 5 112 байт
|
||||
opcode 6 4 байта
|
||||
opcode 7 208 байт
|
||||
opcode 8 248 байт
|
||||
opcode 9 208 байт
|
||||
opcode 10 208 байт
|
||||
```
|
||||
|
||||
Parser использует opcode только для выбора фиксированного размера. Неизвестный
|
||||
opcode отклоняется: попытка угадать длину потеряет синхронизацию всего stream.
|
||||
|
||||
Opcodes 2, 3, 4, 5, 7, 8, 9 и 10 содержат pair fixed strings:
|
||||
|
||||
```c
|
||||
struct FxResourceRef64 {
|
||||
char archive[32];
|
||||
char name[32];
|
||||
};
|
||||
```
|
||||
|
||||
Имена сравниваются case-insensitive по ASCII, а tail после первого nul byte
|
||||
сохраняется. Resolve выполняется при создании command object или лениво при
|
||||
первом запуске, но ошибка должна включать имя эффекта, номер команды, archive
|
||||
и resource name.
|
||||
|
||||
Базовый normalized age:
|
||||
|
||||
```text
|
||||
tn = (now - start_time) / (end_time - start_time)
|
||||
```
|
||||
|
||||
`time_mode` выбирает источник коэффициента: constant, forward/reverse age,
|
||||
cyclic phase, external world state и варианты с ограничением относительно
|
||||
предыдущего значения. Точные формулы редких modes являются parity-задачей.
|
||||
Flags могут умножать alpha на lifetime, применять triangular remap, случайно
|
||||
сдвигать phase/space, инвертировать active-state, фильтровать по времени суток
|
||||
или включать manager gates.
|
||||
|
||||
Lifecycle:
|
||||
|
||||
```text
|
||||
create instance
|
||||
-> copy header and external transform
|
||||
-> calculate end time and random offsets
|
||||
-> create command objects in disk order
|
||||
-> resolve required resources
|
||||
-> Start
|
||||
|
||||
on each calculation/render frame
|
||||
-> evaluate time coefficient and gates
|
||||
-> update commands in stable order
|
||||
-> emit active primitives or sounds
|
||||
-> collect render batches
|
||||
-> handle Stop / Restart / end-of-life
|
||||
```
|
||||
|
||||
Update и emit разделяются. Simulation может продолжаться в кадре без render, а
|
||||
emit не должен повторно менять игровое состояние. Для authoring безопасно
|
||||
типизировать header и resource references, а body редких commands сохранять raw
|
||||
до подтверждения field-level semantics.
|
||||
|
||||
## Полный кадр
|
||||
|
||||
Крупный вход в world render проходит через `World3D::stdRenderGame`. Доказан
|
||||
следующий порядок boundary операций:
|
||||
|
||||
1. передать camera в Terrain через `stdSetCurrentCamera2` и сохранить её как
|
||||
текущую;
|
||||
2. получить camera/view/viewport interfaces через virtual queries;
|
||||
3. обновить положение и ориентацию 3D sound listener;
|
||||
4. настроить renderer viewport и matrices;
|
||||
5. вызвать два renderer boundary slots перед traversal;
|
||||
6. установить глобальный флаг `in_render`;
|
||||
7. вызвать главный virtual метод camera/world traversal;
|
||||
8. выполнить дополнительную post queue при включённом режиме;
|
||||
9. завершить world/shade pass;
|
||||
10. вызвать renderer completion slot;
|
||||
11. снять `in_render`, восстановить viewport и разослать end-of-render.
|
||||
|
||||
Семантические имена нескольких slots перед и после traversal не подтверждены,
|
||||
поэтому в compatibility code их лучше временно называть
|
||||
`frame_boundary_0`, `frame_boundary_1`, `frame_boundary_2`.
|
||||
|
||||
Обход видимого мира:
|
||||
|
||||
```text
|
||||
проверить active/visible state
|
||||
-> выбрать LOD по расстоянию и настройкам
|
||||
-> получить node matrices из animation state
|
||||
-> выбрать slot для каждого node/group
|
||||
-> преобразовать bounds в world space
|
||||
-> выполнить culling
|
||||
-> добавить batches в подходящую render queue
|
||||
```
|
||||
|
||||
Material/texture resolve желательно выполнять после visibility и slot
|
||||
selection, чтобы невидимые объекты не меняли порядок обращений к caches и не
|
||||
создавали лишние side effects. Невидимость объекта и отсутствие slot являются
|
||||
разными причинами пропуска и диагностируются отдельно.
|
||||
|
||||
Подготовленный draw item содержит:
|
||||
|
||||
```text
|
||||
node world matrix
|
||||
batch flags and index range
|
||||
WEAR material handle
|
||||
MAT0 active phase and coefficients
|
||||
texture handle
|
||||
optional lightmap handle
|
||||
render phase and sorting key
|
||||
legacy pipeline state
|
||||
```
|
||||
|
||||
Draw item должен ссылаться на immutable данные кадра. Изменение phase или
|
||||
texture cache посреди прохода не должно менять уже собранную очередь.
|
||||
|
||||
Согласованная декомпозиция внутренних render phases:
|
||||
|
||||
1. подготовка frame state, camera и viewport;
|
||||
2. непрозрачный terrain;
|
||||
3. непрозрачные object batches;
|
||||
4. lightmap и дополнительные material passes;
|
||||
5. projected primitives и тени;
|
||||
6. alpha-tested geometry;
|
||||
7. transparent objects и FX в сортировочных слоях;
|
||||
8. atmosphere, sun, flare и weather;
|
||||
9. renderer completion boundary;
|
||||
10. end-of-render callbacks;
|
||||
11. shell/UI и post-render state.
|
||||
|
||||
Точный взаимный порядок пунктов 4-8 и связь completion slot с физическим
|
||||
DirectDraw flip/present требуют dynamic capture. Сортировка внутри каждой фазы
|
||||
должна быть стабильной: для opaque первичен pipeline/material key, для
|
||||
transparent -- distance layer и depth order, затем stable insertion ID.
|
||||
|
||||
Геометрический draw использует streams type 3/4/5, optional streams, index
|
||||
buffer type 6, `base_vertex`, `index_start` и `index_count`. Матрица узла
|
||||
устанавливается как world transform, затем CShade привязывает texture stages и
|
||||
fixed-function state.
|
||||
|
||||
```c
|
||||
set_world_matrix(item.node_world);
|
||||
bind_vertex_streams(model.streams);
|
||||
bind_index_buffer(model.indices);
|
||||
apply_legacy_state(item.pipeline);
|
||||
bind_texture(0, item.texture);
|
||||
bind_texture(1, item.lightmap);
|
||||
draw_indexed(item.batch.base_vertex,
|
||||
item.batch.index_start,
|
||||
item.batch.index_count);
|
||||
```
|
||||
|
||||
После последнего world pass renderer закрывает сцену и выводит back buffer.
|
||||
World3D снимает `in_render`, восстанавливает временный viewport state и вызывает
|
||||
`on_end_render` у active objects. Только после этого допустимо освобождать
|
||||
temporary vertex buffers или заменять render representation. UI/shell
|
||||
обслуживается верхним уровнем после возврата из world-render path; для
|
||||
диагностики полезно уметь сохранять world-only command list и финальный
|
||||
framebuffer отдельно.
|
||||
|
||||
## Проверки паритета
|
||||
|
||||
Главные риски совпадения кадра:
|
||||
|
||||
- x87 extended precision и правила округления;
|
||||
- различия scalar/SIMD slots `g_FastProc`;
|
||||
- порядок objects, batches и transparent primitives;
|
||||
- depth write/test, cull, alpha test и blend transitions;
|
||||
- mip-skip, palette и `Page` coordinates;
|
||||
- material fallback и выбор phase;
|
||||
- последовательность RNG для FX и atmosphere;
|
||||
- capability fallback конкретного устройства;
|
||||
- quantization времени и дополнительный simulation step;
|
||||
- eager/lazy resource resolve и cache side effects.
|
||||
|
||||
Минимальный deterministic frame capture должен включать camera state, viewport,
|
||||
visible object IDs, выбранные LOD/group/slot, draw-item list, material и texture
|
||||
handles, pipeline keys, matrices, render phase, sort key, причины culling и
|
||||
hashes промежуточных buffers. Без такой трассировки нельзя уверенно отделить
|
||||
ошибку формата MSH от ошибки state machine renderer-а или сортировки.
|
||||
|
||||
Связанные справочные страницы с таблицами форматов: [MSH](../reference/msh.md),
|
||||
[materials](../reference/materials.md), [Texm](../reference/texm.md) и
|
||||
[render frame](../reference/render-frame.md).
|
||||
Reference in New Issue
Block a user