pixhunt 0.8.2

//! 高层封装:把"截图"和"匹配"拼成一步到位的 [`Finder`]。

use crate::capture::{Capture, XCapCapture};
use crate::color::{self, ColorBlob, ColorSpec};
use crate::frame::{Frame, Rect};
use crate::matcher::{Match, Matcher, RgbMatcher};
use crate::template::Template;
use crate::Result;

use std::time::{Duration, Instant};

#[cfg(all(windows, feature = "capture-dxgi"))]
use crate::Error;

#[cfg(feature = "match-corr")]
use crate::matcher_corr::{CorrConfig, CorrMatcher};

/// 可选的截图后端。
pub enum CaptureKind {
    /// 跨平台保底(基于 `xcap` 库,输出 RGBA;只绑主显示器)。
    Monitor,
    /// 复用型 GDI BitBlt(仅 Windows,输出 BGRA)。需 feature `capture-gdi`。
    #[cfg(all(windows, feature = "capture-gdi"))]
    Gdi,
    /// DXGI 桌面复制(仅 Windows,最快,输出 BGRA)。需 feature `capture-dxgi`。
    #[cfg(all(windows, feature = "capture-dxgi"))]
    Dxgi,
    /// PrintWindow 截指定窗口客户区(仅 Windows,遮挡也可截;坐标为窗口相对)。
    /// 需 feature `capture-window`。
    #[cfg(all(windows, feature = "capture-window"))]
    Window(crate::capture_window::WindowHandle),
    /// 按窗口标题(**精确匹配**)截单个窗口客户区(仅 Windows,坐标为窗口相对)。
    /// 需 feature `capture-window`。
    #[cfg(all(windows, feature = "capture-window"))]
    WindowByTitle(String),
    /// 自动选最快可用:DXGI → GDI → xcap。需至少一个 Windows 后端 feature。
    #[cfg(all(windows, any(feature = "capture-gdi", feature = "capture-dxgi")))]
    Auto,
}

/// 可选的匹配算法。
pub enum MatchKind {
    /// 极速 RGB 比对。`tolerance` 为每通道最大绝对差(0=精确,~25≈容差 0.1)。
    ///
    /// 命中结果的 `score` 恒为 `1.0`(通过/不通过判定),要相似度分数请用
    /// `MatchKind::Corr`(需 feature `match-corr`)。
    Rgb { tolerance: i32 },
    /// 基于 corrmatch 的 ZNCC(灰度,抗光照/轻微缩放变化)。需 feature `match-corr`。
    ///
    /// ⚠️ ZNCC 走的是 [`Template::to_gray`],那条路径**没有掩码接口**:`Template::load`
    /// 从 PNG alpha 自动做出来的掩码在这里不生效,透明区会连同其 RGB(灰度下通常是黑)
    /// 一起当成目标内容参与打分。同一张 PNG 可能 `Rgb` 命中而 `Corr` 落空——带透明的
    /// 模板请继续用 [`MatchKind::Rgb`]。
    #[cfg(feature = "match-corr")]
    Corr,
    /// 同上,但自定义搜索参数(金字塔层数/ROI/阈值/并行)。需 feature `match-corr`。
    ///
    /// 同样**不使用掩码**,见 [`MatchKind::Corr`] 的说明。
    #[cfg(feature = "match-corr")]
    CorrWith(CorrConfig),
}

/// 组装好的找图器。内部**复用一个 [`Frame`]**,逐帧查找不再重复分配像素缓冲。
pub struct Finder {
    capture: Box<dyn Capture>,
    matcher: Box<dyn Matcher>,
    region: Option<Rect>,
    frame: Frame,
    prev_frame: Option<Frame>,
    cache_key: Option<u64>,
    cache_result: Option<Option<Match>>,
    /// region 与画面不相交是否已经 warn 过(避免轮询刷屏)。
    region_offscreen_warned: bool,
}

impl Finder {
    pub fn builder() -> FinderBuilder {
        FinderBuilder {
            capture: None,
            matcher: None,
            region: None,
        }
    }

    /// 用现成的后端 + 匹配器组装(region 默认整屏)。
    pub fn new(capture: Box<dyn Capture>, matcher: Box<dyn Matcher>) -> Self {
        Finder {
            capture,
            matcher,
            region: None,
            frame: Frame::bgra8(0, 0, Vec::new()),
            prev_frame: None,
            cache_key: None,
            cache_result: None,
            region_offscreen_warned: false,
        }
    }

    /// 截一屏并查找模板(若设了 `region` 则只在该区域内找)。
    ///
    /// 当后端报告画面自上次以来**未变化**、且模板与区域都和上次相同,则直接复用
    /// 上次结果、跳过搜索(静态桌面轮询的常见加速;结果与重新搜一遍完全一致)。
    /// 未变化有两种来源:后端自己报(DXGI 的 `WAIT_TIMEOUT`),以及设了 `region` 且
    /// 区域直抓([`Capture::grab_region`])到的帧与上一帧逐字节相同。
    ///
    /// 命中时 `Match::score` 的口径随匹配器不同:`MatchKind::Rgb` 恒为 `1.0`,只有
    /// `Corr`(ZNCC,需 feature `match-corr`)的分数才表示"有多像"。
    ///
    /// ⚠️ **屏幕上命中不止一处时,这里不告诉你"还有第二个"**。返回的一定是扫描序
    /// `(y, x)` 里的第一个(最靠上;同样靠上时最靠左)——确定性强,串行/并行、换后端都
    /// 一致,但它是"最上最左的那个",不是"唯一的那个"。同款按钮出现两次、或模板是从
    /// 大片纯色区域裁出来的时候,`Some` 照样会给你坐标。
    ///
    /// 在意唯一性就用 [`Finder::find_all_on_screen`] 取 2 个来判:
    ///
    /// ```no_run
    /// # use pixhunt::{Error, Finder, Template};
    /// # fn demo() -> Result<(), Error> {
    /// let tpl = Template::load("btn.png")?;
    /// let mut finder = Finder::builder().build()?;
    /// match finder.find_all_on_screen(&tpl, 2)?.len() {
    ///     0 => println!("没找到"),
    ///     1 => println!("唯一,可以放心点"),
    ///     _ => println!("不止一处,这个坐标不可信,考虑缩小 region"),
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// 这个守卫不额外贵:它扫到第二个命中就停,代价与再搜一遍同量级(1920x1200 有纹理
    /// 帧 + 48x48 模板、`--release` 纯匹配 15 次取中位:命中两处时 ~3.3ms 串行 / ~2.2ms
    /// 开 `parallel`;而"确实唯一"时必须扫完整帧才敢下结论,~4.7ms / ~3.1ms)。如果模板
    /// 是从大片纯色里裁的、屏幕上**到处**都匹配,它扫到第 2 行就收工,比上面还便宜三个
    /// 数量级(同尺寸纯色帧实测 ~1µs)。⚠️ 唯一的例外是 `MatchKind::Corr`:
    /// `CorrMatcher`(feature `match-corr`)没有覆写 [`Matcher::find_all`],
    /// 永远只返回 1 个,这个守卫在它下面**恒判"唯一"**。
    pub fn find_on_screen(&mut self, tpl: &Template) -> Result<Option<Match>> {
        let _t0 = px_timer!();
        let (changed, origin) = self.grab_scoped()?;
        let key = self.key_of(tpl);
        if !changed && self.cache_key == Some(key) {
            if let Some(prev) = self.cache_result {
                px_trace!(
                    op = "find_on_screen",
                    backend = self.capture.backend(),
                    cache_hit = true,
                    hit = prev.is_some(),
                    elapsed_us = _t0.map(|t| t.elapsed().as_micros() as u64).unwrap_or(0),
                );
                return Ok(prev);
            }
        }
        let m = self.search(tpl, origin);
        self.cache_key = Some(key);
        self.cache_result = Some(m);
        px_trace!(
            op = "find_on_screen",
            backend = self.capture.backend(),
            cache_hit = false,
            changed,
            frame = format!("{}x{}", self.frame.width, self.frame.height),
            tpl_key = format!("{:016x}", key),
            hit = m.is_some(),
            elapsed_us = _t0.map(|t| t.elapsed().as_micros() as u64).unwrap_or(0),
        );
        Ok(m)
    }

    /// 截一屏并按**颜色范围**找连通色块(不需要模板):`spec.tolerance` 为每
    /// 通道最大绝对差,`min_area` 过滤碎点;返回按 (y, x) 排序的 [`ColorBlob`]。
    /// 血条 / 状态灯 / 高亮区这类"只有颜色、没有模板"的场景用它。
    pub fn find_color_on_screen(
        &mut self,
        spec: &ColorSpec,
        min_area: usize,
    ) -> Result<Vec<ColorBlob>> {
        let _t0 = px_timer!();
        let (_, origin) = self.grab_scoped()?;
        let region = self.search_rect(origin);
        let mut blobs = color::find_blobs(&self.frame, spec, region, min_area);
        if origin != (0, 0) {
            // 区域帧里的坐标是相对区域左上角的,换回屏幕绝对坐标
            for b in &mut blobs {
                b.bounds.x += origin.0 as usize;
                b.bounds.y += origin.1 as usize;
            }
        }
        px_trace!(
            op = "find_color_on_screen",
            backend = self.capture.backend(),
            color = format!("{:?}±{}", spec.rgb, spec.tolerance),
            region = format!(
                "({},{},{}x{})",
                region.x, region.y, region.width, region.height
            ),
            blobs = blobs.len(),
            elapsed_us = _t0.map(|t| t.elapsed().as_micros() as u64).unwrap_or(0),
        );
        Ok(blobs)
    }

    /// 轮询等待模板**出现**:每 `interval` 查一次,命中立即返回;超过 `timeout`
    /// 仍未出现返回 `Ok(None)`。自动化脚本"等按钮出现"的标准姿势,配合后端的
    /// 静态帧跳过(以及区域直抓时的帧比对),等待期间开销极小。
    ///
    /// `timeout` 大到没法加进当前时刻(典型入参 `Duration::MAX`)时视为**永不超时**,
    /// 不会 panic。
    pub fn find_until(
        &mut self,
        tpl: &Template,
        timeout: Duration,
        interval: Duration,
    ) -> Result<Option<Match>> {
        let m = self.poll(tpl, timeout, interval, true)?;
        px_trace!(
            op = "find_until",
            result = if m.is_some() { "hit" } else { "timeout" },
            timeout = ?timeout,
        );
        Ok(m)
    }

    /// 轮询等待模板**消失**:在 `timeout` 内找不到即返回 `Ok(true)`,超时仍能找到
    /// 返回 `Ok(false)`(如等加载遮罩消失、等按钮置灰图标下屏)。
    ///
    /// 同 [`Finder::find_until`]:超大的 `timeout`(如 `Duration::MAX`)视为永不超时。
    pub fn wait_gone(
        &mut self,
        tpl: &Template,
        timeout: Duration,
        interval: Duration,
    ) -> Result<bool> {
        let hit = self.poll(tpl, timeout, interval, false)?;
        px_trace!(
            op = "wait_gone",
            result = if hit.is_none() { "gone" } else { "still_present" },
            timeout = ?timeout,
        );
        Ok(hit.is_none())
    }

    /// 轮询到"是否命中"符合 `want_hit` 为止:满足立即返回,`timeout` 到点返回最后一次结果。
    ///
    /// 溢出**不当成错误也不截断成 0**,而是当成"不设截止点"——"我就一直等"是合法写法,
    /// 库不该用一个合法的 `Duration` 把调用方当场炸掉(`Instant + Duration` 溢出会 panic)。
    fn poll(
        &mut self,
        tpl: &Template,
        timeout: Duration,
        interval: Duration,
        want_hit: bool,
    ) -> Result<Option<Match>> {
        let deadline = Instant::now().checked_add(timeout);
        loop {
            let m = self.find_on_screen(tpl)?;
            if m.is_some() == want_hit {
                return Ok(m);
            }
            let now = Instant::now();
            if let Some(deadline) = deadline {
                if now >= deadline {
                    return Ok(m);
                }
                std::thread::sleep(interval.min(deadline - now));
            } else {
                std::thread::sleep(interval);
            }
        }
    }

    /// 截一屏并找全部不重叠匹配(至多 `max` 个,`max=0` 不限),按 `(y, x)` 升序
    /// 返回**屏幕绝对坐标**。
    ///
    /// 顺序与去重口径见 [`Matcher::find_all`];中心点可用 [`Match::center`] 折算。
    ///
    /// `max` 是**真上限**,攒够就停止扫描(不会先把整屏扫完再截断),所以拿它当
    /// "命中是否唯一"的守卫(`max = 2`)很便宜,见 [`Finder::find_on_screen`]。
    pub fn find_all_on_screen(&mut self, tpl: &Template, max: usize) -> Result<Vec<Match>> {
        let (_, origin) = self.grab_scoped()?;
        let region = self.search_rect(origin);
        let mut ms = self.matcher.find_all(&self.frame, tpl, region, max);
        if origin != (0, 0) {
            for m in &mut ms {
                m.x += origin.0;
                m.y += origin.1;
            }
        }
        Ok(ms)
    }

    /// 只截一屏,依次匹配多个模板(省掉重复截图)。
    pub fn find_many_on_screen(&mut self, tpls: &[&Template]) -> Result<Vec<Option<Match>>> {
        let (_, origin) = self.grab_scoped()?;
        Ok(tpls.iter().map(|t| self.search(t, origin)).collect())
    }

    /// 在给定帧里查找模板(不涉及截图,便于测试/离线;遵循已设 region)。
    pub fn find_in_frame(&self, frame: &Frame, tpl: &Template) -> Option<Match> {
        match self.region {
            Some(r) => self.matcher.find_in(frame, tpl, r),
            None => self.matcher.find(frame, tpl),
        }
    }

    /// 截一屏找模板,返回**模板中心**的屏幕坐标(省去手动加半尺寸)。
    ///
    /// 命中时 `Match.x`/`Match.y` = 左上角 + 宽高的一半(整数除法)。
    /// 适合"找到后直接点击中心"的场景。多结果要用中心点,请对 [`find_all_on_screen`]
    /// 的每个命中调用 [`Match::center`]。
    ///
    /// "命中不止一处时不告知"这一点与 [`Finder::find_on_screen`] 完全一致(它就是
    /// 在后者结果上折算坐标)。
    ///
    /// [`find_all_on_screen`]: Finder::find_all_on_screen
    pub fn find_center_on_screen(&mut self, tpl: &Template) -> Result<Option<Match>> {
        let m = self.find_on_screen(tpl)?;
        Ok(m.map(|m| {
            let (x, y) = m.center(tpl);
            Match {
                x,
                y,
                score: m.score,
            }
        }))
    }

    /// 截一屏,与上一次截图的帧在指定区域内逐像素对比,
    /// 返回**颜色有差异的像素数**。首次调用(无参考帧)返回区域内全部像素数。
    ///
    /// 用途:"这块区域变了吗?""动画是否还在跑?""有没有新消息图标闪了一下"。
    /// 比较时使用 R/G/B 三通道(忽略 Alpha),任一通道差值 !=0 即计为不同。
    ///
    /// 注意:两次截图之间**帧布局发生变化**(切换过 `region`、显示器分辨率改变、
    /// 换了后端)时,像素不再一一对应,此时保守返回区域内全部像素数(=整片都变),
    /// 并把当前帧立为新基线;下一次调用起恢复正常计数。
    ///
    /// 成本:为供下次对比,这里会保留**当前整帧**的一份副本(1080p 约 8 MB),
    /// 属于"每调用一次拷一份"的量级,不适合 60 fps 级高频轮询。
    pub fn diff_since_last(&mut self, rect: Rect) -> Result<u32> {
        let _ = self.grab_scoped()?;
        let r = self.frame.clamp(rect);
        let count = match self.prev_frame.as_ref() {
            // 两帧布局一致(尺寸 + 像素格式)时,下标才对应同一个屏幕位置,可逐像素比。
            Some(prev)
                if prev.width == self.frame.width
                    && prev.height == self.frame.height
                    && prev.format == self.frame.format =>
            {
                let (ro, go, bo) = self.frame.rgb_offsets();
                let (pro, pgo, pbo) = prev.rgb_offsets();
                let sw4 = self.frame.width * 4;
                let pw4 = prev.width * 4;
                let mut diff = 0u32;
                for y in r.y..r.y + r.height {
                    for x in r.x..r.x + r.width {
                        let ci = y * sw4 + x * 4;
                        let pi = y * pw4 + x * 4;
                        if self.frame.pixels[ci + ro] != prev.pixels[pi + pro]
                            || self.frame.pixels[ci + go] != prev.pixels[pi + pgo]
                            || self.frame.pixels[ci + bo] != prev.pixels[pi + pbo]
                        {
                            diff += 1;
                        }
                    }
                }
                diff
            }
            // 无基线,或布局变了(切换过 region、分辨率改变、换了后端):`r` 是按
            // 当前帧裁剪的,拿它去索引更小的上一帧会越界 panic,同下标也不再指向
            // 同一屏幕位置。保守视为"区域内全部像素都变化",并把当前帧立为新基线。
            _ => (r.width * r.height) as u32,
        };
        // 当前帧变为下次比较的基线
        // 基线就地更新:缓冲等长时复用上一帧那个 Vec,避免每帧重新分配整帧
        // (1080p BGRA 约 8 MB;实测这次分配+拷贝占了 diff_since_last 的大部分时间)。
        match self.prev_frame.as_mut() {
            Some(prev) if prev.pixels.len() == self.frame.pixels.len() => {
                prev.pixels.copy_from_slice(&self.frame.pixels);
                prev.width = self.frame.width;
                prev.height = self.frame.height;
                prev.format = self.frame.format;
            }
            _ => self.prev_frame = Some(self.frame.clone()),
        }
        Ok(count)
    }

    /// 当前限定区域(若有)。
    pub fn region(&self) -> Option<Rect> {
        self.region
    }

    /// 抓一帧供本次查找使用,返回(画面相对上次是否变化, 该帧左上角的屏幕坐标)。
    ///
    /// 设了 region 且后端支持直接区域抓取([`Capture::grab_region`] 返回
    /// `Some`)时只截该区域——省掉一次整屏拷贝与后续裁剪。此时帧内坐标是**区域
    /// 相对**的,第二个返回值就是需要加回的偏移;不支持则为 `(changed, (0, 0))`,
    /// 行为与旧版"截全屏再按 region 裁剪"完全一致。
    ///
    /// 区域直抓拿的是新缓冲,后端无从报告"这屏和上次一样",所以这里**就地逐字节
    /// 比对补齐**:布局(尺寸 + 通道序)一致且像素全同就回报未变化 —— 否则
    /// "盯着一小块区域反复轮询"这条最该吃到静态帧跳过的路径会让缓存 100% 失效
    /// (实测:连续 3 次查找从 1 次搜索退化成 3 次)。内容相同时留用旧帧,省一次
    /// 整帧写回;代价是这一帧新缓冲白 allocate 一次,由 `grab_region` 的 API 形状决定。
    fn grab_scoped(&mut self) -> Result<(bool, (i32, i32))> {
        if let Some(r) = self.region {
            if let Some(f) = self.capture.grab_region(r)? {
                let changed = frame_differs(&self.frame, &f);
                if changed {
                    self.frame = f;
                }
                self.warn_if_region_offscreen();
                return Ok((changed, (r.x as i32, r.y as i32)));
            }
        }
        let changed = self.capture.grab_into(&mut self.frame)?;
        self.warn_if_region_offscreen();
        Ok((changed, (0, 0)))
    }

    /// region 与刚抓到的画面**完全不相交**时提示一次(开 feature `tracing` 才有输出)。
    ///
    /// 这是"region 坐标写错了"最典型的表现:结果只是安静的 `None`,与"屏幕上确实
    /// 没有该模板"无从区分。这里**不返回 `Err`**:`None` 本来就是合法结果,而副屏 /
    /// 窗口后端的坐标原点未必从 (0,0) 开始,把"暂时不相交"判成错误会打断合法的轮询脚本。
    fn warn_if_region_offscreen(&mut self) {
        let Some(r) = self.region else {
            return;
        };
        if self.frame.width == 0 || self.frame.height == 0 {
            return; // 还没抓到有效帧,谈不上"不相交"
        }
        let c = self.frame.clamp(r);
        if (c.width != 0 && c.height != 0) || self.region_offscreen_warned {
            return;
        }
        self.region_offscreen_warned = true;
        px_warn!(
            region = format!("({},{},{}x{})", r.x, r.y, r.width, r.height),
            frame = format!("{}x{}", self.frame.width, self.frame.height),
            backend = self.capture.backend(),
            "region 与抓到的画面完全不相交,该区域不会有任何命中:检查坐标是否写错,或目标是否在另一块显示器上",
        );
    }

    /// 本次搜索应在帧内哪个矩形上进行。
    fn search_rect(&self, origin: (i32, i32)) -> Rect {
        if origin == (0, 0) {
            self.region.unwrap_or_else(|| self.frame.full_rect())
        } else {
            // 帧本身就是 region,整帧搜索即等价于旧的"全屏 + region 裁剪"
            self.frame.full_rect()
        }
    }

    /// 在 [`grab_scoped`](Self::grab_scoped) 产出的帧上查模板,结果换算为屏幕绝对坐标。
    ///
    /// 能走 [`Matcher::find`] 就走:`find_in` 的**默认实现**是"裁剪子帧 + 拷贝",
    /// 没覆写它的匹配器(如 `CorrMatcher`)在整屏帧上会白拷一帧(1080p 约 8MB)。
    /// 只有"全屏帧 + 限定区域"才真的需要 `find_in` 收窄范围。
    fn search(&self, tpl: &Template, origin: (i32, i32)) -> Option<Match> {
        let mut m = if origin != (0, 0) {
            // 帧本身就是 region,整帧搜即等价于旧的"全屏 + region 裁剪"
            self.matcher.find(&self.frame, tpl)?
        } else {
            match self.region {
                Some(r) => self.matcher.find_in(&self.frame, tpl, r)?,
                None => self.matcher.find(&self.frame, tpl)?,
            }
        };
        m.x += origin.0;
        m.y += origin.1;
        Some(m)
    }

    /// 设置/清除限定区域(`None`=整屏)。会作废内部结果缓存。
    pub fn set_region(&mut self, region: Option<Rect>) {
        self.region = region;
        self.cache_key = None;
        self.cache_result = None;
        // 新区域重新给一次不相交提示的机会(见 `warn_if_region_offscreen`)。
        self.region_offscreen_warned = false;
    }

    /// 缓存键 = 模板内容指纹 ^ 区域指纹。
    fn key_of(&self, tpl: &Template) -> u64 {
        let rk = match self.region {
            None => 0u64,
            Some(r) => {
                (r.x as u64).wrapping_mul(1000003)
                    ^ (r.y as u64).wrapping_mul(7349287)
                    ^ (r.width as u64).wrapping_mul(911)
                    ^ (r.height as u64)
            }
        };
        tpl.content_key() ^ rk.rotate_left(32)
    }
}

/// 两帧内容是否不同。
///
/// 布局(尺寸 + 通道序)不一致时**必然算不同**:下标不再一一对应,没有可比性
/// (与 [`Finder::diff_since_last`] 遇到布局变化时"保守视为全变"同一口径)。
fn frame_differs(prev: &Frame, next: &Frame) -> bool {
    prev.width != next.width
        || prev.height != next.height
        || prev.format != next.format
        || prev.pixels != next.pixels
}

/// [`Finder`] 的构建器。
pub struct FinderBuilder {
    capture: Option<CaptureKind>,
    matcher: Option<MatchKind>,
    region: Option<Rect>,
}

impl FinderBuilder {
    pub fn capture(mut self, k: CaptureKind) -> Self {
        self.capture = Some(k);
        self
    }
    pub fn matcher(mut self, k: MatchKind) -> Self {
        self.matcher = Some(k);
        self
    }
    /// 限定查找区域(绝对像素坐标),之后的 `find_*` 只在此范围内搜索。
    /// 接受 [`Rect`] 或 `(x, y, width, height)` 元组。
    pub fn region(mut self, r: impl Into<Rect>) -> Self {
        self.region = Some(r.into());
        self
    }
    pub fn build(self) -> Result<Finder> {
        let capture: Box<dyn Capture> = match self.capture.unwrap_or(CaptureKind::Monitor) {
            CaptureKind::Monitor => Box::new(XCapCapture::primary()?),
            #[cfg(all(windows, feature = "capture-gdi"))]
            CaptureKind::Gdi => Box::new(crate::capture_gdi::GdiCapture::new_primary()),
            #[cfg(all(windows, feature = "capture-dxgi"))]
            CaptureKind::Dxgi => Box::new(
                crate::capture_dxgi::DxgiCapture::new_primary()
                    .ok_or_else(|| Error::capture("DXGI desktop duplication unavailable"))?,
            ),
            #[cfg(all(windows, feature = "capture-window"))]
            CaptureKind::Window(h) => Box::new(crate::capture_window::WindowCapture::new(h)),
            #[cfg(all(windows, feature = "capture-window"))]
            CaptureKind::WindowByTitle(ref title) => {
                Box::new(crate::capture_window::WindowCapture::from_title(title)?)
            }
            #[cfg(all(windows, any(feature = "capture-gdi", feature = "capture-dxgi")))]
            CaptureKind::Auto => auto_capture()?,
        };
        let matcher: Box<dyn Matcher> =
            match self.matcher.unwrap_or(MatchKind::Rgb { tolerance: 25 }) {
                MatchKind::Rgb { tolerance } => Box::new(RgbMatcher::new(tolerance)),
                #[cfg(feature = "match-corr")]
                MatchKind::Corr => Box::new(CorrMatcher::new()),
                #[cfg(feature = "match-corr")]
                MatchKind::CorrWith(cfg) => Box::new(CorrMatcher::with_config(cfg)),
            };
        let mut f = Finder::new(capture, matcher);
        f.region = self.region;
        Ok(f)
    }
}

/// 依次尝试 DXGI → GDI → xcap,返回第一个可用的。
#[cfg(all(windows, any(feature = "capture-gdi", feature = "capture-dxgi")))]
fn auto_capture() -> Result<Box<dyn Capture>> {
    #[cfg(feature = "capture-dxgi")]
    if let Some(c) = crate::capture_dxgi::DxgiCapture::new_primary() {
        return Ok(Box::new(c));
    }
    #[cfg(feature = "capture-gdi")]
    {
        return Ok(Box::new(crate::capture_gdi::GdiCapture::new_primary()));
    }
    #[allow(unreachable_code)]
    Ok(Box::new(XCapCapture::primary()?))
}

#[cfg(test)]
mod tests {
    use super::*;

    use std::cell::Cell;
    use std::rc::Rc;

    const W: usize = 32;
    const H: usize = 32;

    /// 造一帧:可选在 (10,10) 贴一块 8x8 纯红(全部平台可跑,不碰真屏幕)。
    fn frame(with_target: bool) -> Frame {
        let mut px = vec![0u8; W * H * 4];
        if with_target {
            for y in 10..18 {
                for x in 10..18 {
                    let i = (y * W + x) * 4;
                    px[i] = 255;
                    px[i + 1] = 0;
                    px[i + 2] = 0;
                    px[i + 3] = 255;
                }
            }
        }
        Frame::rgba8(W, H, px)
    }

    /// 按脚本序列出帧的 mock 后端:第 i 次 grab 用 `present[i]` 决定有无目标,
    /// 序列耗尽后重复最后一项;同时统计被调用了多少次。
    struct SeqCapture {
        present: Vec<bool>,
        grabs: usize,
    }

    impl Capture for SeqCapture {
        fn grab(&mut self) -> Result<Frame> {
            let i = self.grabs.min(self.present.len() - 1);
            self.grabs += 1;
            Ok(frame(self.present[i]))
        }

        fn backend(&self) -> &'static str {
            "mock"
        }
    }

    fn target_tpl() -> Template {
        Template::from_rgb([255, 0, 0].repeat(8 * 8), 8, 8)
    }

    fn finder_with(present: Vec<bool>) -> Finder {
        Finder::new(
            Box::new(SeqCapture { present, grabs: 0 }),
            Box::new(RgbMatcher::new(0)),
        )
    }

    #[test]
    fn find_until_hits_after_a_few_misses() {
        let mut f = finder_with(vec![false, false, true]);
        let m = f
            .find_until(
                &target_tpl(),
                Duration::from_secs(5),
                Duration::from_millis(2),
            )
            .expect("mock 不会出错")
            .expect("第 3 帧应命中");
        assert_eq!((m.x, m.y), (10, 10));
    }

    #[test]
    fn find_until_times_out() {
        let mut f = finder_with(vec![false]);
        let m = f
            .find_until(
                &target_tpl(),
                Duration::from_millis(30),
                Duration::from_millis(5),
            )
            .expect("mock 不会出错");
        assert!(m.is_none(), "一直找不到应在超时后返回 None");
    }

    #[test]
    fn wait_gone_returns_true_and_false() {
        // 目标先出现后消失 -> 等消失成功
        let mut f = finder_with(vec![true, true, false]);
        assert!(f
            .wait_gone(
                &target_tpl(),
                Duration::from_secs(5),
                Duration::from_millis(2)
            )
            .unwrap());
        // 目标一直在 -> 超时失败
        let mut f2 = finder_with(vec![true]);
        assert!(!f2
            .wait_gone(
                &target_tpl(),
                Duration::from_millis(30),
                Duration::from_millis(5)
            )
            .unwrap());
    }

    #[test]
    fn find_color_on_screen_high_level_entry() {
        let mut f = finder_with(vec![true]);
        let blobs = f
            .find_color_on_screen(&ColorSpec::new(255, 0, 0, 10), 32)
            .unwrap();
        assert_eq!(blobs.len(), 1);
        assert_eq!(blobs[0].bounds, Rect::new(10, 10, 8, 8));
        assert_eq!(blobs[0].area, 64);
        // region 限定时,区域外的色块不可见
        f.set_region(Some(Rect::new(0, 20, 32, 12)));
        assert!(f
            .find_color_on_screen(&ColorSpec::new(255, 0, 0, 10), 1)
            .unwrap()
            .is_empty());
    }

    /// 区域帧:24x24,一块 8x8 纯红贴在帧内 (4,5)。
    fn region_frame() -> Frame {
        let (w, h) = (24usize, 24usize);
        let mut px = vec![0u8; w * h * 4];
        for y in 5..13 {
            for x in 4..12 {
                let i = (y * w + x) * 4;
                px[i] = 255;
                px[i + 3] = 255;
            }
        }
        Frame::rgba8(w, h, px)
    }

    /// 支持区域截取的后端:全屏帧里故意没有目标,只有区域帧里有。
    struct RegionCap {
        region_grabs: Rc<Cell<usize>>,
        full_grabs: Rc<Cell<usize>>,
    }

    impl Capture for RegionCap {
        fn grab(&mut self) -> Result<Frame> {
            self.full_grabs.set(self.full_grabs.get() + 1);
            Ok(frame(false))
        }

        fn grab_region(&mut self, r: Rect) -> Result<Option<Frame>> {
            assert_eq!(
                (r.x, r.y, r.width, r.height),
                (20, 16, 24, 24),
                "应收到屏幕绝对坐标区域"
            );
            self.region_grabs.set(self.region_grabs.get() + 1);
            Ok(Some(region_frame()))
        }

        fn backend(&self) -> &'static str {
            "mock-region"
        }
    }

    fn region_finder() -> (Finder, Rc<Cell<usize>>, Rc<Cell<usize>>) {
        let (rg, fg) = (Rc::new(Cell::new(0)), Rc::new(Cell::new(0)));
        let mut f = Finder::new(
            Box::new(RegionCap {
                region_grabs: rg.clone(),
                full_grabs: fg.clone(),
            }),
            Box::new(RgbMatcher::new(0)),
        );
        f.set_region(Some(Rect::new(20, 16, 24, 24)));
        (f, rg, fg)
    }

    /// region + 支持区域截取的后端:只截区域,且结果换算回屏幕绝对坐标。
    #[test]
    fn region_prefers_backend_region_grab() {
        let (mut f, rg, fg) = region_finder();
        let m = f
            .find_on_screen(&target_tpl())
            .unwrap()
            .expect("区域内应命中");
        // 帧内 (4,5) + 区域原点 (20,16)
        assert_eq!((m.x, m.y), (24, 21), "应返回屏幕绝对坐标");
        assert_eq!(rg.get(), 1);
        assert_eq!(fg.get(), 0, "能只截区域时不应再截全屏");
    }

    /// find_all / find_color 两条入口在区域截图下也必须给出绝对坐标。
    #[test]
    fn region_grab_shifts_all_and_color_results() {
        let (mut f, rg, _) = region_finder();

        let all = f.find_all_on_screen(&target_tpl(), 0).unwrap();
        assert_eq!(all.len(), 1);
        assert_eq!((all[0].x, all[0].y), (24, 21));

        let blobs = f
            .find_color_on_screen(&ColorSpec::new(255, 0, 0, 10), 32)
            .unwrap();
        assert_eq!(blobs.len(), 1);
        assert_eq!(blobs[0].bounds, Rect::new(24, 21, 8, 8));
        assert_eq!(blobs[0].area, 64);
        assert_eq!(rg.get(), 2, "两次入口都应走区域路径");
    }

    /// 只记录走了哪个入口的匹配器(没覆写 `find_in` 的匹配器走它会整帧拷贝)。
    struct SpyMatcher {
        finds: Rc<Cell<usize>>,
        find_ins: Rc<Cell<usize>>,
    }

    impl Matcher for SpyMatcher {
        fn find(&self, _frame: &Frame, _tpl: &Template) -> Option<Match> {
            self.finds.set(self.finds.get() + 1);
            Some(Match {
                x: 1,
                y: 2,
                score: 1.0,
            })
        }

        fn find_in(&self, _frame: &Frame, _tpl: &Template, _region: Rect) -> Option<Match> {
            self.find_ins.set(self.find_ins.get() + 1);
            Some(Match {
                x: 1,
                y: 2,
                score: 1.0,
            })
        }
    }

    fn spy() -> (SpyMatcher, Rc<Cell<usize>>, Rc<Cell<usize>>) {
        let (f, i) = (Rc::new(Cell::new(0)), Rc::new(Cell::new(0)));
        (
            SpyMatcher {
                finds: f.clone(),
                find_ins: i.clone(),
            },
            f,
            i,
        )
    }

    /// 未设 region 时必须走 `find`:走 `find_in` 会让没覆写它的匹配器(如
    /// `CorrMatcher`)白拷一整帧。
    #[test]
    fn no_region_uses_find_not_find_in() {
        let (m, finds, find_ins) = spy();
        let mut f = Finder::new(
            Box::new(SeqCapture {
                present: vec![true],
                grabs: 0,
            }),
            Box::new(m),
        );
        assert!(f.find_on_screen(&target_tpl()).unwrap().is_some());
        assert_eq!((finds.get(), find_ins.get()), (1, 0));
    }

    /// 全屏帧 + 限定区域(后端不支持区域直抓):必须用 `find_in` 收窄范围。
    #[test]
    fn region_without_backend_support_uses_find_in() {
        let (m, finds, find_ins) = spy();
        let mut f = Finder::new(
            Box::new(SeqCapture {
                present: vec![true],
                grabs: 0,
            }),
            Box::new(m),
        );
        f.set_region(Some(Rect::new(2, 3, 8, 8)));
        assert!(f.find_on_screen(&target_tpl()).unwrap().is_some());
        assert_eq!((finds.get(), find_ins.get()), (0, 1));
    }

    /// 区域直抓时帧本身就是 region,再走 `find_in(整帧)` 就是多余的一次拷贝;
    /// 同时坐标仍要换算回屏幕绝对位置。
    #[test]
    fn region_grab_searches_whole_frame_with_find() {
        let (m, finds, find_ins) = spy();
        let mut f = Finder::new(
            Box::new(RegionCap {
                region_grabs: Rc::new(Cell::new(0)),
                full_grabs: Rc::new(Cell::new(0)),
            }),
            Box::new(m),
        );
        f.set_region(Some(Rect::new(20, 16, 24, 24)));
        let hit = f.find_on_screen(&target_tpl()).unwrap().unwrap();
        // 帧内 (1,2) + 区域原点 (20,16)
        assert_eq!((hit.x, hit.y), (21, 18));
        assert_eq!((finds.get(), find_ins.get()), (1, 0));
    }

    /// 区域直抓、内容恒定不变的后端(模拟"盯着一小块静态区域轮询")。
    struct StaticRegion;
    impl Capture for StaticRegion {
        fn grab(&mut self) -> Result<Frame> {
            Ok(Frame::bgra8(32, 32, vec![9u8; 32 * 32 * 4]))
        }
        fn grab_region(&mut self, r: Rect) -> Result<Option<Frame>> {
            Ok(Some(Frame::bgra8(
                r.width,
                r.height,
                vec![9u8; r.width * r.height * 4],
            )))
        }
        fn backend(&self) -> &'static str {
            "mock-static-region"
        }
    }

    /// 回归:region 直抓时后端报不出"没新帧",缓存不能因此 100% 失效。
    #[test]
    fn region_grab_still_uses_static_frame_cache() {
        let (m, finds, find_ins) = spy();
        let mut f = Finder::new(Box::new(StaticRegion), Box::new(m));
        f.set_region(Some(Rect::new(4, 4, 24, 24)));
        assert!(f.find_on_screen(&target_tpl()).unwrap().is_some());
        assert!(f.find_on_screen(&target_tpl()).unwrap().is_some());
        assert!(f.find_on_screen(&target_tpl()).unwrap().is_some());
        assert_eq!(
            (finds.get(), find_ins.get()),
            (1, 0),
            "画面逐字节未变,后两次应复用缓存"
        );
    }

    /// 反过来:帧内容真的变了,绝不能因为"尺寸一样"就当成没变。
    #[test]
    fn region_grab_researches_when_pixels_change() {
        struct TogglingRegion {
            n: usize,
        }
        impl Capture for TogglingRegion {
            fn grab(&mut self) -> Result<Frame> {
                Ok(Frame::bgra8(24, 24, vec![9u8; 24 * 24 * 4]))
            }
            fn grab_region(&mut self, r: Rect) -> Result<Option<Frame>> {
                self.n += 1;
                let v = if self.n.is_multiple_of(2) { 8 } else { 9 };
                Ok(Some(Frame::bgra8(
                    r.width,
                    r.height,
                    vec![v; r.width * r.height * 4],
                )))
            }
        }
        let (m, finds, _) = spy();
        let mut f = Finder::new(Box::new(TogglingRegion { n: 0 }), Box::new(m));
        f.set_region(Some(Rect::new(4, 4, 24, 24)));
        for _ in 0..3 {
            assert!(f.find_on_screen(&target_tpl()).unwrap().is_some());
        }
        assert_eq!(finds.get(), 3, "帧内容交替变化,每次都该重搜");
    }

    /// region 完全落在画面外:语义仍是"没有命中",不是错误(提示走 tracing warn)。
    #[test]
    fn region_fully_offscreen_is_none_not_error() {
        let mut f = finder_with(vec![true]);
        f.set_region(Some(Rect::new(5000, 5000, 64, 64)));
        assert!(
            f.find_on_screen(&target_tpl()).unwrap().is_none(),
            "越界区域应报告无命中,而不是 panic 或 Err"
        );
    }

    /// 回归:`Duration::MAX` 这类加不进当前时刻的超时不该 panic,而是"一直等"。
    /// 目标在第 3 帧出现,所以两条轮询都能自己结束。
    #[test]
    fn oversized_timeout_means_wait_forever_not_panic() {
        let mut f = finder_with(vec![false, false, true]);
        let m = f
            .find_until(&target_tpl(), Duration::MAX, Duration::from_millis(2))
            .expect("mock 不会出错")
            .expect("超时的语义是不限,等到就该返回命中");
        assert_eq!((m.x, m.y), (10, 10));

        let mut f2 = finder_with(vec![true, false]);
        assert!(
            f2.wait_gone(&target_tpl(), Duration::MAX, Duration::from_millis(2))
                .unwrap(),
            "目标消失即返回 true,不应被超大 timeout 炸掉"
        );
    }

    #[test]
    fn find_center_returns_center_coords() {
        // 目标 8x8 贴在 (10,10),中心 = (14, 14)
        let mut f = finder_with(vec![true]);
        let m = f
            .find_center_on_screen(&target_tpl())
            .unwrap()
            .expect("应命中");
        assert_eq!((m.x, m.y), (10 + 8 / 2, 10 + 8 / 2));
    }

    #[test]
    fn diff_since_last_first_call_returns_area() {
        // 首次无基线,应返回全部像素数
        let mut f = finder_with(vec![true]);
        let d = f.diff_since_last(Rect::new(0, 0, 10, 10)).unwrap();
        assert_eq!(d, 100);
    }

    #[test]
    fn diff_since_last_same_frame_returns_zero() {
        // 同一帧连续两次 diff:无变化应为 0
        let mut f = finder_with(vec![true]);
        let _ = f.diff_since_last(Rect::new(0, 0, 32, 32)).unwrap();
        let d = f.diff_since_last(Rect::new(0, 0, 32, 32)).unwrap();
        assert_eq!(d, 0);
    }

    #[test]
    fn diff_since_last_detects_change() {
        // 第一帧无目标(全黑),第二帧有目标(红色块)→ diff > 0
        let mut f = finder_with(vec![false, true]);
        let _ = f.diff_since_last(Rect::new(0, 0, 32, 32)).unwrap();
        let d = f.diff_since_last(Rect::new(0, 0, 32, 32)).unwrap();
        assert!(d > 0, "两帧不同应检出变化,got {}", d);
    }

    /// 支持 `grab_region`、按请求尺寸给帧的 mock(真实后端切换区域时帧尺寸会变)。
    struct RegionCapture;
    impl Capture for RegionCapture {
        fn grab(&mut self) -> Result<Frame> {
            Ok(Frame::bgra8(64, 64, vec![9u8; 64 * 64 * 4]))
        }
        fn grab_region(&mut self, r: Rect) -> Result<Option<Frame>> {
            Ok(Some(Frame::bgra8(
                r.width,
                r.height,
                vec![9u8; r.width * r.height * 4],
            )))
        }
    }

    #[test]
    fn diff_since_last_survives_region_resize() {
        // 回归:先在 8x8 小区域建基线(上一帧仅 256 像素),再切到 64x64 大区域,
        // 用大帧的下标去索引小帧缓冲会越界 panic。
        let mut f = Finder::new(Box::new(RegionCapture), Box::new(RgbMatcher::new(0)));
        f.set_region(Some(Rect::new(0, 0, 8, 8)));
        let _ = f.diff_since_last(Rect::new(0, 0, 8, 8)).unwrap();

        f.set_region(Some(Rect::new(0, 0, 64, 64)));
        let d = f.diff_since_last(Rect::new(0, 0, 16, 16)).unwrap();
        assert_eq!(d, 16 * 16, "两帧布局不同应保守报告整片变化");

        // 基线已重建为同一布局,内容未变时应回到 0
        let d2 = f.diff_since_last(Rect::new(0, 0, 16, 16)).unwrap();
        assert_eq!(d2, 0);
    }
}