TextureOptions

Неизменяемая конфигурация сэмплирования текстур: min/mag фильтрация, wrap-режимы UV, mipmaps и premultiplied alpha.

Обзор и неизменяемый дизайн

TextureOptions определяет, как графический ускоритель сэмплирует текстуру при отрисовке полигонов, мешей и 9-slice панелей.

Неизменяемая семантика

TextureOptions не владеет ресурсами видеокарты, а лишь описывает параметры сэмплера. Все методы-модификаторы возвращают новый экземпляр TextureOptions (или текущий объект, если значение не изменилось), что исключает случайные побочные эффекты:

TextureOptions base = TextureOptions.defaults();
TextureOptions linearWithRepeat = base.sampling(TextureFilter.LINEAR).wrap(TextureWrap.REPEAT);

Режимы фильтрации (Nearest против Linear)

Режимы TextureFilter управляют интерполяцией пикселей при масштабировании:

Режим	Поведение	Где использовать
`NEAREST`	Выбирает ближайший пиксель без интерполяции.	Pixel-art текстуры Minecraft, чёткие иконки предметов, рамки UI.
`LINEAR`	Билинейная интерполяция между 4 соседними текселями.	Высокодетализированный арт, векторная графика, плавный зум.
`NEAREST_MIPMAP_NEAREST`	Nearest-выборка из ближайшего mipmap-уровня.	Сильно уменьшенные pixel-art поверхности.
`LINEAR_MIPMAP_LINEAR`	Трилинейная фильтрация с плавным переходом между уровнями.	3D-проекции в мире, удалённые плоскости, защита от муара.

Режимы повторения UV (`TextureWrap`)

Определяет поведение сэмплера при выходе UV-координат за пределы диапазона 0.0..1.0:

CLAMP_TO_EDGE: Прижимает координаты к крайним пикселям. Стандартный режим UniGUI; исключает паразитные цветные полосы по краям рамок.
REPEAT: Бесконечно повторяет текстуру плиткой (тайлинг). Идеально для фоновых узоров, бегущих текстур кабелей и полос.
MIRRORED_REPEAT: Повторяет текстуру с зеркальным отражением каждого второго тайла для создания симметричных паттернов.

Premultiplied Alpha и Mipmaps

Premultiplied Alpha

При билинейной фильтрации полупрозрачных текстур стандартный straight alpha может давать тёмные грязные ореолы вокруг контуров из-за смешивания RGB с чёрным цветом при alpha=0. Опция premultipliedAlpha(true) переключает шейдер бэкенда на математику premultiplied alpha (src + dst * (1 - srcAlpha)).

Mipmaps

Включает использование предварительно отфильтрованных уменьшенных копий текстуры, устраняя мерцание и рябь (алиасинг) при сильном удалении или сжатии.

10-битный сжатый ключ

Все параметры сэмплирования и wrap-режимов упакованы в компактный 10-битный целочисленный ключ (packed()):

Биты 0-1: MinFilter (NEAREST=0, LINEAR=1, NEAREST_MIP=2, LINEAR_MIP=3)
Биты 2-3: MagFilter (NEAREST=0, LINEAR=1)
Биты 4-5: WrapS (CLAMP=0, REPEAT=1, MIRRORED=2)
Биты 6-7: WrapT (CLAMP=0, REPEAT=1, MIRRORED=2)
Бит 8:    Флаг Mipmaps (0/1)
Бит 9:    Флаг Premultiplied Alpha (0/1)

Благодаря тому, что ключ занимает всего 10 бит (значения от 0 до 1023), бэкенды используют прямой массив (SamplerState[1024]) или быстрый switch, обеспечивая мгновенный поиск O(1) без выделения памяти.

Бесшовный тайлинг фона

// Настройка повторяющегося фона
TextureOptions tiledOptions = TextureOptions.defaults()
        .wrap(TextureWrap.REPEAT);

TextureHandle tiledTexture = new SimpleTextureHandle("custom:wallpaper", 32, 32, null, tiledOptions);
// Отрисовка 5x3 плиток по ширине и высоте
scope.texture(tiledTexture, x, y, width, height, 0.0f, 0.0f, 5.0f, 3.0f, Paint.NONE);

Сглаженная иконка с mipmaps

// Сглаженные трилинейные опции для иконок интерфейса
TextureOptions smoothOptions = TextureOptions.linear()
        .mipmaps(true)
        .premultipliedAlpha(true);

API

Предустановки и стандартные фабрики

Метод	Описание
`defaults()`	Возвращает стандартные настройки: nearest-фильтрация, clamp-to-edge, без mipmaps.
`nearest()`	Возвращает настройки для pixel-perfect выборки без сглаживания.
`linear()`	Возвращает настройки для сглаженной линейной фильтрации.
`isDefault()`	Возвращает true, если опции совпадают со стандартными.

TextureOptions::`defaults()`

Получить опции по умолчанию

Возвращает стандартные настройки: nearest-фильтрация, clamp-to-edge, без mipmaps.

Возвращает TextureOptions: Кэшированный стандартный экземпляр TextureOptions..

TextureOptions::`nearest()`

Получить Nearest опции

Возвращает настройки для pixel-perfect выборки без сглаживания.

Возвращает TextureOptions: Экземпляр TextureOptions с nearest-фильтрацией..

TextureOptions::`linear()`

Получить Linear опции

Возвращает настройки для сглаженной линейной фильтрации.

Возвращает TextureOptions: Экземпляр TextureOptions с linear-фильтрацией..

TextureOptions::`isDefault()`

Проверить настройки по умолчанию

Возвращает true, если опции совпадают со стандартными.

Возвращает boolean: True, если идентично TextureOptions.defaults()..

Свойства сэмплера

Метод	Описание
`minFilter()`	Возвращает фильтр при отрисовке текстуры меньше её размера.
`magFilter()`	Возвращает фильтр при отрисовке текстуры больше её размера.
`wrapS()`	Возвращает режим повторения по горизонтали (ось U).
`wrapT()`	Возвращает режим повторения по вертикали (ось V).
`mipmaps()`	Возвращает true, если включены mipmaps.
`premultipliedAlpha()`	Возвращает true, если текстура использует premultiplied alpha.

TextureOptions::`minFilter()`

Получить фильтр уменьшения

Возвращает фильтр при отрисовке текстуры меньше её размера.

Возвращает TextureFilter: Установленный minification TextureFilter..

TextureOptions::`magFilter()`

Получить фильтр увеличения

Возвращает фильтр при отрисовке текстуры больше её размера.

Возвращает TextureFilter: Установленный magnification TextureFilter..

TextureOptions::`wrapS()`

Получить Wrap S

Возвращает режим повторения по горизонтали (ось U).

Возвращает TextureWrap: Режим повторения TextureWrap по горизонтали..

TextureOptions::`wrapT()`

Получить Wrap T

Возвращает режим повторения по вертикали (ось V).

Возвращает TextureWrap: Режим повторения TextureWrap по вертикали..

TextureOptions::`mipmaps()`

Проверить включение Mipmaps

Возвращает true, если включены mipmaps.

Возвращает boolean: True, если mipmaps активны..

TextureOptions::`premultipliedAlpha()`

Проверить Premultiplied Alpha

Возвращает true, если текстура использует premultiplied alpha.

Возвращает boolean: True, если используется premultiplied alpha..

Методы конфигурации

Метод	Описание
`minFilter(TextureFilter)`	Возвращает копию TextureOptions с заданным фильтром уменьшения.
`magFilter(TextureFilter)`	Возвращает копию TextureOptions с заданным фильтром увеличения.
`sampling(TextureFilter)`	Устанавливает один фильтр для уменьшения и увеличения одновременно.
`wrap(TextureWrap)`	Применяет wrap-режим одновременно к обеим осям (U и V).
`wrap(TextureWrap, TextureWrap)`	Применяет независимые wrap-режимы для осей U (S) и V (T).
`mipmaps(boolean)`	Включает или выключает использование mipmaps.
`premultipliedAlpha(boolean)`	Указывает, содержат ли данные текстуры premultiplied alpha.