Импорт изображений и текстур
Прозрачность, mipmaps, размер, каналы, фильтрация и диагностика дефектов материалов.
Для изображения в интерфейсе, спрайте или материале используйте Texture2D. Для работы с пикселями на процессоре — Image. Исходный файл, импортированная текстура и сэмплер материала — разные уровни: изменение одного не обязательно исправляет остальные.
Импортировать и показать PNG
- Поместите PNG в Images/plain.png внутри проекта.
- Выберите его в Content Browser. Оставьте импортер Texture2D, для первой проверки задайте compress/mode = Lossless и примените Reimport.
- Создайте TextureRect и прикрепите полный ImagePreview.cs:
using Reckfell;
public partial class ImagePreview : TextureRect
{
public override void _Ready()
{
Texture = ResourceLoader.Load<Texture2D>("asset://Images/plain.png");
TextureFilter = TextureFilterEnum.Nearest;
if (Texture == null)
ReckfellApi.PushError("Cannot load asset://Images/plain.png");
}
}Запустите уровень и задайте TextureRect нужный размер. Пример намеренно выбирает ближайший пиксель; для плавно масштабируемой графики выбирайте линейную фильтрацию. Загружайте исходный путь, а не имя сгенерированного кеша. Повторный импорт меняет ресурс отображения, не переписывая оригинальный PNG.
Выбрать ресурс и формат исходника
| Задача | Ресурс или подход |
|---|---|
| Интерфейс, спрайт, обычная карта материала 3D | Texture2D |
| Обработка пикселей на процессоре | Image либо Texture2D.GetImage с последующей обработкой Image |
| Двоичная маска нажатия | Bitmap; это не отображаемая цветная текстура |
| Шесть граней окружения | Cubemap с явно выбранной раскладкой граней импортера |
| Независимые слои изображений | Texture2DArray и подходящий шейдер |
| Данные объёма | Texture3D; это не обычная картинка на поверхности 3D-меша |
| Масштабируемый векторный интерфейс | SVG как текстура либо DPITexture, если нужна повторная растеризация во время работы |
Для растровой графики с прозрачностью используйте формат, который действительно хранит alpha, например PNG или WebP. JPEG не предоставляет alpha-канал. Для HDR используйте подход HDR/EXR, а не рассчитывайте сохранить радианс с плавающей точкой импортом PNG. Загрузчики и поддержка рендерера зависят от установленной сборки: распознанное расширение не доказывает поддержку каждого варианта, слоистого ресурса или видеокарты.
Обычная текстура SVG растеризуется при импорте; svg/scale задаёт размер. Проверяйте результат сложного SVG и переводите текст в контуры для переносимого векторного ресурса. Преобразование цветов темы и масштаб редактора предназначены для его значков, а не для общей цветокоррекции игровых картинок. Слоистые текстуры, HDR и SVG здесь сверены с исходниками, но не проверены запуском образцов PNG.
Сжатие: размер файла и память GPU — разные величины
| compress/mode | Назначение |
|---|---|
| 0: Lossless | Сохранить декодированные пиксели; удобная отправная точка диагностики |
| 1: Lossy | Уменьшить закодированный файл с возможными артефактами; это само по себе не означает меньший объём памяти GPU |
| 2: VRAM Compressed | Блочное сжатие GPU; проверяйте качество и поддержку целевого рендерера |
| 3: VRAM Uncompressed | Несжатые данные текстуры |
| 4: Basis Universal | Хранение с последующим транскодированием; оцените поддержку сборки, время импорта/загрузки и артефакты |
Выбор формата VRAM зависит от платформы, качества и каналов. Не считайте коэффициент сжатия постоянным, а High Quality — одинаково работающим на всех рендерерах. Повторное сжатие испорченного исходника не восстановит его: сначала сравните импорт Lossless с оригиналом.
Для HDR параметр compress/hdr_compression разрешает сжатие либо отбрасывание alpha в режиме Always. process/hdr_as_srgb исправляет неверно закодированный цвет HDR, а не служит общей регулировкой яркости. process/hdr_clamp_exposure меняет экстремальные значения HDR; проверьте отражения и экспозицию, прежде чем скрывать им проблему освещения.
Фильтрация, повтор и цвет
Фильтр и повтор задаются у CanvasItem в 2D, у материала в 3D или подсказками сэмплера в пользовательском шейдере. Они не заменяют параметры импорта.
- Nearest сохраняет отдельные тексели, Linear смешивает соседние. Фильтру с mipmaps нужна импортированная цепочка уменьшенных уровней.
- Для повтора нужны соответствующий сэмплер и UV. Чрезмерный тайлинг или растянутые UV не исправляются повышением разрешения текстуры.
- Цветовые и числовые карты имеют разные роли. В пользовательском цветовом сэмплере source_color задаёт нужное преобразование исходного цвета в пространство рендеринга. Не применяйте его без разбора к нормалям, шероховатости и маскам.
- Проверяйте канал упакованной карты. Выбор канала чтения в материале отличается от process/channel_remap, переписывающего каналы при импорте.
Встроенный материал разделяет цветные карты albedo/emission, нормали и скалярные карты. Правильные импортированные пиксели не доказывают правильность цвета шейдера, экспозиции и назначения карт.
Mipmaps и размер
Включайте mipmaps/generate, когда текстура отображается существенно меньше исходного размера. Образец 32×16 создаёт пять уменьшенных уровней до 1×1. Mipmaps требуют места и не добавляют детализацию исходнику. Выберите использующую их фильтрацию и оцените мерцание на реальной дистанции.
Известное ограничение текущей реализации: mipmaps/limit не обрезает загруженную цепочку. Проверка в движке задаёт 2, но получает пять уровней. Не используйте этот параметр как работающий способ ограничить память.
process/size_limit уменьшает длинную сторону и масштабирует другую с сохранением пропорций. В тесте 32×16 превращается в 8×4 при пределе 8; оригинал остаётся 32×16. Это уменьшает настоящую детализацию. Выбирайте предел по размеру на экране и плотности текселей, а не по универсальному правилу «любая платформа поддерживает 4K».
Detect 3D может включить mipmaps и поменять сжатие после использования текстуры в 3D. При изменении картинки проверьте итоговые параметры Import. Отключение обнаружения не возвращает автоматически все прежние значения.
Alpha и карты нормалей
| Параметр | Что меняет |
|---|---|
| process/fix_alpha_border | Заполняет цвет возле прозрачного края, сохраняя alpha; не включает прозрачность материала |
| process/premult_alpha | Умножает RGB на alpha; требует соответствующего режима смешивания с предумноженной alpha |
| process/normal_map_invert_y | Заменяет зелёный канал на 1−green для карты нормалей с противоположным направлением Y |
| compress/normal_map | Обнаруживает, включает или отключает обработку карты нормалей; не гарантирует неизменное сохранение всех сжатых каналов |
| process/channel_remap/* | Меняет источники каналов, включая инверсию и константы |
Для предумноженных текстур выберите соответствующий режим смешивания CanvasItemMaterial/BaseMaterial3D либо blend_premul_alpha в подходящем шейдере. Несовпадение соглашений может дать тёмный или светлый край. Инверсия Y нормалей не переворачивает картинку по вертикали и не служит общей цветокоррекцией.
Для вырезанной по маске листвы проверьте и alpha исходника, и режим/порог прозрачности материала. PNG с alpha всё ещё может выглядеть сплошным прямоугольником при непрозрачном материале. Для mipmaps с отсечением по alpha параметры preserve_alpha_test_coverage и его порог отделены от порога материала; оценивайте дальний силуэт. Для фильтрации шероховатости roughness/mode задаёт канал, roughness/src_normal — связанную карту нормалей; обработке нужны mipmaps.
Пиксели на процессоре и экспорт
Texture2D.GetImage возвращает копию Image и может потребовать чтения из GPU. Изменение копии не обновляет существующую текстуру. Для многократного доступа храните изображение на процессоре либо используйте явное обновление, а не считывайте текстуру каждый кадр.
Image.LoadFromFile читает исходные байты, обходя преобразования импорта. В тесте он видит оригинал 32×16, когда импортированная текстура имеет размер 8×4. Для ресурса проекта движок предупреждает, что такая сырая загрузка не является надёжным сценарием экспорта. Импортируйте файл как Image и загружайте ресурс, если нужны пиксели упакованного ресурса, либо явно включайте и обслуживайте сырой файл. Запуск из редактора не доказывает наличие исходника в экспорте.
Диагностика дефекта
| Симптом | Первая проверка |
|---|---|
| Белый прямоугольник вокруг листвы | Alpha файла, назначенный материал, режим/порог прозрачности |
| Тёмный или светлый край спрайта | RGB прозрачной границы и соответствие смешивания обычной/предумноженной alpha |
| Размытие | Ограничение размера импорта, фильтр, mip-уровень, исходное разрешение и масштаб отображения |
| Мерцание вдали | Генерация mipmaps, фильтрация и масштаб UV |
| Вмятины выглядят выпуклостями | Назначение карты нормалей и направление Y |
| Выцветший цвет или неправильная шероховатость | Преобразование цветового пространства, экспозиция и каналы упакованной карты |
| Изменение изображения на процессоре ничего не дало | GetImage вернул копию; обновите изменяемую текстуру явно |
В движке проверены настоящий импорт PNG и чтение пикселей Vulkan: Lossless/Raw, размер, mipmaps, предумножение, RGB края, операции с каналами и точный пример C#. Ожидаемое предупреждение экспорта при чтении сырого файла записано в отчёт. Это не проверка цвета после выборки шейдером, качества краёв на экране, HDR/Basis/VRAM/SVG, слоистого импорта, фильтрации покрытия alpha, всех GPU или экспортированных сборок.