Документация Docs/ru/reference/image-format/validation.md

Проверка форматов изображений

Сгенерированный справочник. Не редактируйте его напрямую. Обновите BuildTools/ImageFormatInterface.json, затем выполните python BuildTools/docs_image_format.py --write.

Индекс

Форматы

Стабильный ID	Правило	Требование	Причина	Источник
`image-format.validation.fofrm-count`	Непустые ссылки FOFRM	Рецепт использует один непустой корневой Source либо непустую композицию Frame/Frames. Source разрешён только в корне и исключает Frame/Frames во всех секциях. Все режимы проверяют имена, смещения и размеры до выпуска выхода.	До существования runtime frame table descriptor должен разрешить хотя бы одну source reference.	Source/Tools/ImageBaker-Fofrm.cpp, Source/Tools/ImageRecipe.cpp
`image-format.validation.fofrm-directions`	Полные таблицы направлений	Композиция Frame/Frames требует безымянную последовательность либо полную индексную таблицу направлений активной геометрии; более поздняя секция без направления1 запрещена до разрешения. Source допускает переопределения существующих направлений без повторения ссылок. Итоговые число кадров и время могут различаться, но все таймлайны должны быть корректны.	Каждый direction sheet разделяет один frame-count и timing header.	Source/Tools/ImageRecipe.cpp, Source/Tools/ImageBaker-Fofrm.cpp
`image-format.validation.fofrm-nested-shared`	Безопасная материализация вложенных shared-кадров	До композиции разрешать цепочки общих пикселей, запрещая неверные индексы и циклы. Материализация копирует пиксели/размеры/флаги сохранности, оставляя собственные размещение, движение и время слота. Legacy SPR явно копирует прежние общие метаданные при построении слотов.	Общие слоты владеют размещением, движением и временем; материализация копирует конкретные пиксели без замены этих метаданных.	Source/Tools/ImageBaker-Fofrm.cpp
`image-format.validation.rgba-payload`	Точный размер RGBA payload	Отклоняйте каждый concrete frame, чья byte payload не равна в точности width, умноженной на height и четыре.	Client читает фиксированное число байтов RGBA8 без отдельного поля payload length.	Source/Tools/ImageBaker.cpp
`image-format.validation.tga-subset`	Поддерживаемое подмножество TGA	Не используйте image ID; задавайте bottom-left orientation, TrueColor type 2 или 10 и 24 либо 32 bpp. Indexed/grayscale/другие входы отклоняются или не соответствуют реализованным допущениям orientation.	Loader непосредственно потребляет фиксированный header, затем всегда переворачивает строки и не ветвится по descriptor origin.	Source/Tools/ImageBaker-Tga.cpp, Source/Tests/Test_ImageBaker.cpp
`image-format.validation.malformed-inputs`	Повреждённые входы decoder	Сохраняйте focused failure coverage для повреждённых PNG, TGA, FRM/FRx/RIX/ART/ZAR/TIL/MOS/BAM, SPR и вложенных FOFRM.	Legacy binary parsers должны детерминированно завершаться ошибкой, а не создавать усечённые runtime containers.	Source/Tests/Test_ImageBaker.cpp
`image-format.validation.runtime-container`	Guards runtime container	Требуются magic/version v3, положительные число кадров/время направления, положительные длительности слотов с проверенной суммой, положительные uint16 размеры конкретных кадров, корректные обратные ссылки, границы mesh/pixels и точный footer/конец. SpriteInfo требует схему2 и согласованные размеры плоских массивов.	Повреждённые baked bytes не должны достигать выделения atlas или обновления анимации.	Source/Common/SpriteResource.cpp
`image-format.validation.playback-timing`	Ненулевая длительность кадра	Положительное время логических кадров и проверенная сумма uint32 исключают деление на ноль коротких анимаций. Явный Duration меньше числа кадров запрещён. Нулевые часы raw legacy нормализуются до10fps, положительные периоды меньше ms — до1ms. Source сохраняет импортированный таймлайн; нормализованная фаза задаёт прямое/обратное/циклическое проигрывание и смену направления.	SpriteSheet изменяет нормализованную фазу по elapsed/whole duration и выбирает кадры по накопленным границам положительных длительностей.	Source/Tools/ImageImport.cpp, Source/Client/DefaultSprites.cpp, Source/Tests/Test_SpriteSheet.cpp
`image-format.validation.project-visible`	Визуальный gate встраиваемого проекта	После native/documentation checks перезапеките встраиваемый проект и в видимой сцене проверьте изменённые dimensions, alpha edges, mirrors, directions, cadence, offsets, hit masks и нужные client profiles.	Parser/container tests не доказывают framing графики, filtering, gait или выбор project resource pack.	Source/Tests/Test_ImageBaker.cpp, Source/Tests/Test_TextureAtlas.cpp
`image-format.validation.numeric-boundaries`	Знаковые величины и проверяемые границы формата	Используйте int32_t для импортированных размеров и индексов общих кадров, а для sprite v3 — типизированные длительности кадров с проверяемой суммой миллисекунд uint32. Проверяйте итоговые знаковые диапазоны и точное число байтов RGBA после преобразований FOFRM и до сериализации; сохраняйте проверяемые преобразования uint16/uint8 и ссылки на предыдущие общие кадры. Декодируйте размеры TGA uint16 в знаковые int32_t; отвергайте обрезанные данные и чрезмерные run-пакеты, сохраняя обрезку полного последнего raw-пакета. Внутренняя арифметика использует фиксированные целые типы; size_t предназначен для фактических целевых контейнеров, буферов или внешних API, а переходы между разными числовыми типами выполняются через numeric_cast.	Согласованные знаковые типы устраняют промежуточные сужения и не дают отрицательным размерам, переполненной длительности и размерам со старшим битом в исходном формате ошибочно попасть в выделение памяти или индексирование.	Source/Tools/ImageImport.h, Source/Tools/ImageBaker.cpp, Source/Tools/ImageBaker-Tga.cpp
`image-format.validation.fofrm-names`	Канонические имена FOFRM	До разрешения источников проверяются безымянный корень (направление 0), ненулевые HexDir/SquareDir активной геометрии, точные PascalCase-ключи и применимость полей. Source и Fps разрешены только в корне. Alias и Effect отклоняются с датированными маркерами миграции. Старые Dir-формы, именованный ноль, Count, прежние ключи кадров/дельт и неизвестные имена запрещены, без fallback.	Неперенесённые имена и опечатки должны останавливать запекание вместо молчаливого применения значений по умолчанию или обхода проверок через Source.	Source/Tools/ImageBaker-Fofrm.cpp, Source/Tools/ImageRecipe.cpp, Source/Tests/Test_ImageBaker.cpp

Команды проверки

python BuildTools\docs_image_format.py --check
python -m unittest BuildTools.tests.test_docs_image_format
cmake --build <build-dir> --config RelWithDebInfo --target RunUnitTests

Встраиваемый проект также должен перезапечь затронутые ресурсы и проверить каждую изменённую анимацию, направление, alpha edge, hit mask и поддерживаемый client profile.