TextureOptions

Immutable texture sampling configuration defining min/mag filtering, UV wrapping, mipmaps, and premultiplied alpha.

Overview & Immutable Design

TextureOptions defines how GPU hardware samples a texture when rendering quads, meshes, and nine-slice panels.

Immutable Semantics

TextureOptions does not own the underlying GPU resource; it only describes the desired sampler behavior. Every modifier method returns a new TextureOptions instance (or returns this if the requested value is already present), preventing accidental side-effects:

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

Filtering Modes (Nearest vs Linear)

TextureFilter determines pixel interpolation when scaling textures:

Mode	Behavior	Best Used For
`NEAREST`	Samples nearest discrete pixel without interpolation.	Pixel-art Minecraft textures, crisp item icons, UI borders.
`LINEAR`	Bilinear interpolation smoothly blending 4 adjacent texels.	High-res art, vector rasters, rotating elements, smooth scales.
`NEAREST_MIPMAP_NEAREST`	Nearest-neighbor filtering using nearest precomputed mipmap.	Heavily downscaled pixel-art surfaces.
`LINEAR_MIPMAP_LINEAR`	Trilinear filtering smoothly blending between mipmap levels.	3D world projections, distant UI planes, elimination of moiré.

UV Wrapping & Tiling (`TextureWrap`)

Controls sampling when UV coordinates fall outside the standard 0.0..1.0 range:

CLAMP_TO_EDGE: Clamps coordinates to the outermost border pixels. Default in UniGUI; prevents bleeding of opposite edges on textured panels.
REPEAT: Tiles the texture infinitely. Ideal for animated scrolling backgrounds, striped caution tape, and procedural wallpapers.
MIRRORED_REPEAT: Tiles the texture, mirroring orientation on alternating tiles. Ideal for symmetric organic patterns.

Premultiplied Alpha & Mipmaps

Premultiplied Alpha

When textures with transparent edges undergo bilinear filtering, standard straight alpha can produce dark halo artifacts because RGB channels bleed into zero-alpha black. Setting premultipliedAlpha(true) instructs the backend shader to blend using premultiplied alpha math (src + dst * (1 - srcAlpha)).

Mipmaps

Enables automatic selection of pre-filtered lower-resolution texture copies during downscaling, eliminating crawling aliasing and shimmer artifacts.

10-Bit Packed Key Architecture

All sampling and wrapping parameters fit cleanly into a compact 10-bit integer key (packed()):

Bits 0-1: MinFilter (NEAREST=0, LINEAR=1, NEAREST_MIP=2, LINEAR_MIP=3)
Bits 2-3: MagFilter (NEAREST=0, LINEAR=1)
Bits 4-5: WrapS (CLAMP=0, REPEAT=1, MIRRORED=2)
Bits 6-7: WrapT (CLAMP=0, REPEAT=1, MIRRORED=2)
Bit 8:    Mipmaps flag (0/1)
Bit 9:    Premultiplied Alpha flag (0/1)

Because packed() is a 10-bit integer, backends use a direct primitive array table (SamplerState[1024]) or fast switch statements, achieving O(1) cache lookups with zero heap allocations.

Seamless Tiling Wallpaper Pattern

// Create repeating pattern options for background panel
TextureOptions tiledOptions = TextureOptions.defaults()
        .wrap(TextureWrap.REPEAT);

TextureHandle tiledTexture = new SimpleTextureHandle("custom:wallpaper", 32, 32, null, tiledOptions);
// Draws 5x3 repeated tiles across target rect
scope.texture(tiledTexture, x, y, width, height, 0.0f, 0.0f, 5.0f, 3.0f, Paint.NONE);

Smooth Scaled Vector Icon with Mipmaps

// Smooth trilinear filtered options for UI icons
TextureOptions smoothOptions = TextureOptions.linear()
        .mipmaps(true)
        .premultipliedAlpha(true);

API

Presets & Default Factories

Method	Description
`defaults()`	Returns standard UniGUI defaults: nearest filtering, clamp-to-edge wrap, no mipmaps.
`nearest()`	Returns options configured for pixel-perfect nearest neighbor sampling.
`linear()`	Returns options configured for smooth linear sampling and clamp-to-edge wrap.
`isDefault()`	Returns true if this instance matches default nearest/clamp options.

TextureOptions::`defaults()`

Get Default Options

Returns standard UniGUI defaults: nearest filtering, clamp-to-edge wrap, no mipmaps.

Returns TextureOptions: Cached default TextureOptions instance..

TextureOptions::`nearest()`

Get Nearest Options

Returns options configured for pixel-perfect nearest neighbor sampling.

Returns TextureOptions: TextureOptions with nearest filtering..

TextureOptions::`linear()`

Get Linear Options

Returns options configured for smooth linear sampling and clamp-to-edge wrap.

Returns TextureOptions: TextureOptions with linear filtering..

TextureOptions::`isDefault()`

Check Default Configuration

Returns true if this instance matches default nearest/clamp options.

Returns boolean: True if identical to TextureOptions.defaults()..

Sampler Properties

Method	Description
`minFilter()`	Returns the texture filter used when scaling down below native dimensions.
`magFilter()`	Returns the texture filter used when scaling up above native dimensions.
`wrapS()`	Returns horizontal wrapping mode along the U axis.
`wrapT()`	Returns vertical wrapping mode along the V axis.
`mipmaps()`	Returns true if mipmaps are enabled for minification filtering.
`premultipliedAlpha()`	Returns true if texture data contains premultiplied alpha channels.

TextureOptions::`minFilter()`

Get Minification Filter

Returns the texture filter used when scaling down below native dimensions.

Returns TextureFilter: Active minification TextureFilter..

TextureOptions::`magFilter()`

Get Magnification Filter

Returns the texture filter used when scaling up above native dimensions.

Returns TextureFilter: Active magnification TextureFilter..

TextureOptions::`wrapS()`

Get Wrap S

Returns horizontal wrapping mode along the U axis.

Returns TextureWrap: Horizontal TextureWrap mode..

TextureOptions::`wrapT()`

Get Wrap T

Returns vertical wrapping mode along the V axis.

Returns TextureWrap: Vertical TextureWrap mode..

TextureOptions::`mipmaps()`

Check Mipmaps Enabled

Returns true if mipmaps are enabled for minification filtering.

Returns boolean: True if mipmaps are enabled..

TextureOptions::`premultipliedAlpha()`

Check Premultiplied Alpha

Returns true if texture data contains premultiplied alpha channels.

Returns boolean: True if premultiplied alpha is configured..

Configuration Modifiers

Method	Description
`minFilter(TextureFilter)`	Returns a TextureOptions copy configured with the specified minification filter.
`magFilter(TextureFilter)`	Returns a TextureOptions copy configured with the specified magnification filter.
`sampling(TextureFilter)`	Sets both minification and magnification filters simultaneously.
`wrap(TextureWrap)`	Applies the specified wrap mode to both horizontal and vertical axes.
`wrap(TextureWrap, TextureWrap)`	Applies independent wrap modes along the U (S) and V (T) axes.
`mipmaps(boolean)`	Enables or disables mipmap generation and sampling.
`premultipliedAlpha(boolean)`	Configures whether texture color data uses premultiplied alpha.