[Feature] Add anisotropic filtering controls to SamplerBuilder

[vmarcella]

Overview

Samplers do not expose anisotropy controls, preventing users from enabling anisotropic filtering for improved texture quality at oblique viewing angles. Anisotropic filtering is a quality/performance tradeoff that should be configurable by the user.

Current State

SamplerBuilder` lacks any anisotropy configuration:

// crates/lambda-rs-platform/src/wgpu/texture.rs
pub struct SamplerBuilder {
  label: Option<String>,
  min_filter: FilterMode,
  mag_filter: FilterMode,
  mipmap_filter: FilterMode,
  address_u: AddressMode,
  address_v: AddressMode,
  address_w: AddressMode,
  lod_min: f32,
  lod_max: f32,
  // No anisotropy_clamp field
}

impl SamplerBuilder {
  pub fn new() -> Self {
    return Self {
      label: None,
      min_filter: FilterMode::Nearest,
      mag_filter: FilterMode::Nearest,
      mipmap_filter: FilterMode::Nearest,
      address_u: AddressMode::ClampToEdge,
      address_v: AddressMode::ClampToEdge,
      address_w: AddressMode::ClampToEdge,
      lod_min: 0.0,
      lod_max: 32.0,
      // anisotropy_clamp not set
    };
  }
  // ... no with_anisotropy method ...
}

The wgpu::SamplerDescriptor supports anisotropy_clamp for enabling anisotropic filtering, but this is not exposed through the platform abstraction.

Scope

Goals:

• Add with_anisotropy_clamp(u16) to SamplerBuilder
• Plumb the value to wgpu::SamplerDescriptor::anisotropy_clamp
• Document the quality/performance tradeoffs
• Validate that the clamp value is within device limits

Non-Goals:

• Automatic anisotropy level selection based on quality presets
• Per-texture anisotropy override (handled at sampler level)

Proposed API

// In crates/lambda-rs-platform/src/wgpu/texture.rs
pub struct SamplerBuilder {
  label: Option<String>,
  min_filter: FilterMode,
  mag_filter: FilterMode,
  mipmap_filter: FilterMode,
  address_u: AddressMode,
  address_v: AddressMode,
  address_w: AddressMode,
  lod_min: f32,
  lod_max: f32,
  anisotropy_clamp: u16,  // New field, default 1 (disabled)
}

impl SamplerBuilder {
  /// Set the maximum anisotropic filtering level.
  ///
  /// Valid values are 1 (disabled) through 16. Values outside this range
  /// will be clamped. Higher values improve texture quality at oblique
  /// viewing angles but increase GPU cost.
  ///
  /// Common values:
  /// - 1: Disabled (default)
  /// - 4: Good balance of quality and performance
  /// - 8: High quality
  /// - 16: Maximum quality
  ///
  /// Note: Anisotropic filtering is most effective with linear filtering
  /// and mipmapped textures.
  pub fn with_anisotropy_clamp(mut self, clamp: u16) -> Self {
    self.anisotropy_clamp = clamp.clamp(1, 16);
    return self;
  }
}

Example Usage:

// High-quality sampler for floor/wall textures viewed at angles
let aniso_sampler = SamplerBuilder::new()
  .linear_clamp()
  .with_mip_filter(FilterMode::Linear)
  .with_anisotropy_clamp(8)
  .build(&gpu);

// Default sampler (no anisotropy) for UI textures
let ui_sampler = SamplerBuilder::new()
  .linear_clamp()
  .build(&gpu);

Acceptance Criteria

• SamplerBuilder has anisotropy_clamp: u16 field defaulting to 1
• with_anisotropy_clamp(u16) method added
• Value clamped to valid range (1-16)
• build() passes anisotropy_clamp to wgpu::SamplerDescriptor
• Documentation explains anisotropy quality/performance tradeoffs
• Example updated to demonstrate anisotropic filtering
• Unit test verifying builder correctly sets anisotropy

Affected Crates

lambda-rs-platform

Notes

• Anisotropic filtering requires linear filtering to be effective
• Maximum supported anisotropy varies by GPU (most support 16)
• Consider a quality preset API in future (e.g., SamplerPreset::HighQuality)
• Device limits can be queried via wgpu::Limits::max_sampler_anisotropy if validation is needed