rust_widgets 2.7.0

// SPDX-FileCopyrightText: Copyright (c) 2026 Mike Li/Mikewolfli/Wei Li(mikewolfli@163.com)
// SPDX-License-Identifier: MIT

//! Rendering primitives and software surface baseline.
//!
//! # Coordinate System
//!
//! This module uses the framework's standard **screen coordinate system** with origin at **top-left**:
//!
//! - **X axis**: Increases from left to right (0 → width)
//! - **Y axis**: Increases from top to bottom (0 → height)
//!
//! All rendering operations (drawing text, shapes, images) expect coordinates in this system.
//! The rendering context automatically handles any necessary transformations when working with
//! widgets or other components that may use different coordinate systems internally.
//!
//! ## Drawing Operations
//!
//! - `draw_text()`: Draws text at the specified (x, y) position
//! - `draw_line()`: Draws a line from (x1, y1) to (x2, y2)
//! - `draw_rect()`: Draws a rectangle outline
//! - `fill_rect()`: Fills a rectangle with a solid color
//! - `draw_image()`: Draws an image at the specified position
//!
//! All coordinates are in logical pixels and use the screen coordinate system.
//!
//! # Module Structure (feature-layered)
//!
//! | Group | Path | Contents |
//! |-------|------|---------|
//! | **gpu** | `gpu/` | GPU-accelerated rendering traits and capability enums (gated behind `gpu-wgpu`) |
//! | **core** | `core/` | Data types (`TextMetrics`, `TextCluster`, `ShapedText`) and commands (`RenderCommand`) |
//! | **backend** | `backend/` | Rendering backends: software surface (`BackBuffer`, `SoftwareSurface`, `RenderContext`), paint trait (`PaintBackend`, `SoftwarePaintBackend`), batch (`BatchId`), scene (`SceneLayer`, `RenderScene`) |
//! | **pipeline** | `pipeline/` | Visual command pipeline for all widget types (controls, containers, dialogs, special, etc.) |
//! | **web** | `web/` | Web engine and web view rendering |
//! | **quality** | `quality/` | Adaptive rendering quality management |
//!
//! # Reachability
//!
//! **State:** Production callers: `src/widget/widget_trait.rs:1`; 181 files reference it (every control's `Draw` implementation).

// ─── Sub-module declarations ─────────────────────────────────────────────────

// Core data types and commands
mod core;
// Rendering backends
mod backend;
// (controls/ directory was migrated to pipeline/special.rs — see pipeline module)
// Visual command pipeline for all widget types
mod pipeline;
// Projection/presentation-mode rendering (BLUE8 P4-5b, gated behind `projection`)
#[cfg(feature = "projection")]
pub mod projection;
// GPU-accelerated rendering backend
#[cfg(feature = "gpu-wgpu")]
pub mod gpu;
// SVG rendering backend
pub mod svg;

// Text caching
#[cfg(test)]
mod tests;

// Text layer: glyph sources and the fallback stack (BLUE23 §0A.4 G-2b/G-4b)
pub mod text;

// Text shaping (pre-layout measurement)
pub mod text_shaper;

// Rich text rendering (multi-span styled text)
pub mod rich_text;

// Text overflow handling (ellipsis, clip, multi-line clamp)
pub mod text_overflow;

// Unicode grapheme cluster support (emoji, combining marks, ZWJ)
pub mod grapheme;

// ─── Re-exports ──────────────────────────────────────────────────────────────

// Core
pub use core::{BlendMode, RenderCommand, ShapedText, TextCluster, TextMetrics};

// SVG
pub use svg::SvgPaintBackend;

// Backend
#[cfg(feature = "quality-management")]
pub use backend::{average_frame_time, current_fps, current_quality_level, set_quality_level};
pub use backend::{
    default_software_render_config, last_auto_render_backend, set_default_software_render_config,
    text_line, AutoRenderBackend, BackBuffer, BatchCommand, BatchId, BatchRenderer, PaintBackend,
    RenderContext, RenderScene, SceneLayer, SoftwarePaintBackend, SoftwareRenderConfig,
    SoftwareSurface, VerticalAlignment, TEXT_FIT_MARGIN,
};

#[cfg(all(test, feature = "desktop", widgets_unstripped))]
pub(crate) use backend::software_render_config_test_lock;

// Pixel ops
pub use pipeline::{blend_pixel, fill_pixels};

// Text shaping
pub use text_shaper::{ShapedGlyphRun, SimpleTextShaper, TextShaper};

// The face-backed shaper, when a face is enabled (BLUE23 §0A.4, G-1).
#[cfg(feature = "text-shaping")]
pub use text::RustybuzzShaper;

// Rich text
pub use rich_text::{RichText, TextSpan, TextStyle};

// Text overflow
pub use text_overflow::{apply_text_clamp, apply_text_overflow, TextClamp, TextOverflow};

// Grapheme support
pub use grapheme::{GraphemeCluster, GraphemeProcessor};

// GPU — re-export only when feature is active
#[cfg(feature = "gpu-wgpu")]
pub use gpu::{GpuCapability, GpuRenderer};

// Projection types
#[cfg(feature = "projection")]
pub use projection::{PresentationController, ProjectionLayoutHelper, ProjectionRenderConfig};

/// Shared helper accessible to surface.rs and backend
pub(crate) use pipeline::pixel_bytes_len;

/// Advancing/text-shaping helpers shared with the SVG backend, so the vector
/// output and the software rasteriser agree on text metrics (principle #51: one
/// heuristic, not two drifting copies).
/// The glyph geometry both renderers read, and the cluster predicates they classify with.
pub(crate) use pipeline::glyph_rects;

/// Arc and circle drawing helpers.
pub mod arc_helpers;
pub use arc_helpers::{draw_arc_segments, point_on_circle};

// The bevel primitive: a face's light/shade pair and the edges it strokes. Added as its own module
// so a face's "which way is it turned" is one relationship rather than three copies — see the
// module docs for the two expressions it replaces and why the direction has to be explicit here.
pub mod bevel;
pub use bevel::{
    Bevel, BevelDirection, BEVEL_INNER_SHADE_WEIGHT, BEVEL_INNER_WEIGHT, BEVEL_WEIGHT,
};

// The surface declaration channel: what kind of face a control's rectangle is. Added as its own
// module — compiled in every profile, including `mini`/`embedded` — so a theme can say "this is a
// flat theme" or "this is a dimensional one" as data rather than every control deciding its own
// material. See the module docs for the three measurements that motivated it and the role table
// it replaces the fixed per-control shadow literal with.
pub mod surface;
pub use surface::{
    bevel_fits, default_shadow, role_surface_style, BevelSpec, Elevation, ElevationShadow,
    Hairline, Material, SurfaceShadow, SurfaceStyle,
};