array_viewer 0.1.0

Lightweight 2D pixel buffer + window viewer. ScreenArray owns heap pixels (ARGB, W x H at compile time); ArrayViewer renders them zero-copy on a background thread via minifb, with an ExchangeLayer for cross-thread input/window control.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
//! 定义主线程与显示线程之间的数据交换层。

pub(crate) use crate::viewer::exchange_layer::hook::{UpdateHook, box_hook};
use atomic_float::AtomicF32;
use key_state::{KeyState, KeyStateDirtyMap};
use minifb::{CursorStyle, MouseButton, MouseMode, Window};
use mouse_state::{MouseState, MouseStateDirtyMap};
use scroll_wheel::{ScrollWheel, ScrollWheelAccumulator};
use signal::{
    ApplyFlag, ApplySignal, ApplySignalNonAtomic, UpdateFlag, UpdateSignal, UpdateSignalNonAtomic,
};
use std::any::type_name;
use std::sync::Mutex;
use std::sync::atomic::{AtomicBool, AtomicIsize, AtomicU32, AtomicUsize, Ordering};
use std::thread;
use std::time::Duration;

mod hook;
pub mod key_state;
pub mod mouse_state;
mod scroll_wheel;
pub mod signal;

/// 用于在主线程和显示线程之间交换状态的结构体。
///
/// 该结构体包含:
/// - 原子变量:窗口尺寸、位置、帧率、鼠标坐标等。
/// - 互斥锁保护的字段:窗口标题、光标样式。
/// - 原子信号:`update_signal` 和 `apply_signal`,用于控制哪些字段需要同步。
///
/// # 并发模型
/// 该结构体被设计为在线程间共享(通常使用 `Arc<ExchangeLayer>`)。
/// 显示线程定期调用 `update_from_window` 和 `apply_to_window` 来同步状态。
/// 主线程可以随时修改原子字段或设置信号,以请求显示线程应用更改。
///
/// # 注意
/// 信号机制用于减少不必要的操作:主线程设置信号,显示线程在每帧检查并执行。
#[derive(Debug, Default)]
pub struct ExchangeLayer {
    /// 更新信号:指示显示线程应从窗口读取哪些状态(输入、位置等)。
    pub update_signal: UpdateSignal,
    /// 应用信号:指示显示线程应将哪些配置应用到窗口(标题、位置、光标等)。
    pub apply_signal: ApplySignal,

    /// 窗口尺寸(宽, 高),由显示线程更新。
    pub window_size: (AtomicUsize, AtomicUsize),
    /// 窗口位置(x, y),由显示线程更新,也可由主线程设置并触发应用。
    pub window_position: (AtomicIsize, AtomicIsize),
    /// 窗口标题(互斥锁),由主线程设置,显示线程应用。
    pub title: Mutex<Option<String>>,
    /// 窗口是否置顶(原子布尔)。
    pub topmost: AtomicBool,
    /// 背景颜色(ARGB),仅当窗口未更新像素时显示。
    pub background_color: AtomicU32,
    /// 光标可见性。
    pub cursor_visibility: AtomicBool,
    /// 目标帧率(0 表示无限制),由显示线程读取。
    pub target_fps: AtomicUsize,
    /// 实际帧率(由显示线程更新,主线程只读)。
    pub fps: AtomicUsize,
    /// 鼠标位置(未缩放,窗口坐标系)。
    pub mouse_pos: (AtomicF32, AtomicF32),
    /// 鼠标按键状态(左、中、右,含边沿检测)。
    mouse_state: MouseStateDirtyMap,
    /// 光标样式(互斥锁)。
    pub cursor_style: Mutex<Option<CursorStyle>>,
    /// 鼠标位置(缩放后,与物理像素对应)。
    pub scaled_mouse_pos: (AtomicF32, AtomicF32),
    /// 滚轮行程累积器:显示线程逐帧把窗口读到的滚轮增量
    /// [merge](ScrollWheelAccumulator::merge) 进来,主线程通过
    /// [`get_scroll_wheel`](Self::get_scroll_wheel) 按帧取走累计行程。
    scroll_wheel: ScrollWheelAccumulator,
    /// 键盘状态(含边沿检测)。
    key_state: KeyStateDirtyMap,
    /// 窗口是否处于激活状态(由显示线程更新)。
    pub is_active: AtomicBool,
    /// 运行标志:显示线程检查该标志以决定是否继续循环。
    /// 主线程可将其置为 `false` 以请求退出。
    pub is_running: AtomicBool,
    /// 更新钩子:显示线程每帧开始执行一次的用户闭包。
    ///
    /// 采用“邮箱 + 代数”模型:
    /// - 主线程通过 [`set_update_hook`](Self::set_update_hook) /
    ///   [`clear_update_hook`](Self::clear_update_hook) 写邮箱并递增 [`hook_epoch`](Self::hook_epoch);
    /// - 渲染线程只在代数变化时才取锁领取钩子(缓存在线程本地),因此绝大多数
    ///   帧都不会触碰这把锁;领取失败(`try_lock` 竞争)时沿用上一份缓存。
    pub(crate) update_hook: Mutex<Option<UpdateHook>>,
    /// 更新钩子的代数:每次设置 / 清除时递增,供渲染线程判断是否需要重新领取钩子。
    pub(crate) hook_epoch: AtomicUsize,
}

impl ExchangeLayer {
    const RETRY_TIMES: usize = 2;
    const RETRY_DELAY: Duration = Duration::from_millis(100);

    /// 创建一个新的 `ExchangeLayer`,所有字段为默认值。
    pub fn new() -> ExchangeLayer {
        ExchangeLayer {
            update_signal: Default::default(),
            apply_signal: Default::default(),

            window_size: (Default::default(), Default::default()),
            window_position: (Default::default(), Default::default()),
            title: Mutex::new(None),
            topmost: Default::default(),
            background_color: Default::default(),
            cursor_visibility: AtomicBool::new(true),
            target_fps: AtomicUsize::new(60), // 0 为无限制
            fps: Default::default(),
            mouse_pos: (Default::default(), Default::default()),
            mouse_state: Default::default(),
            cursor_style: Mutex::new(None),
            scaled_mouse_pos: (Default::default(), Default::default()),
            scroll_wheel: ScrollWheelAccumulator::new(),
            key_state: Default::default(),
            is_active: Default::default(),
            is_running: Default::default(),
            update_hook: Mutex::new(None),
            hook_epoch: AtomicUsize::new(0),
        }
    }

    pub fn get_key_state(&self) -> KeyState<'_> {
        KeyState::new(&self.key_state)
    }
    pub fn get_mouse_state(&self) -> MouseState<'_> {
        MouseState::new(&self.mouse_state)
    }

    /// 获取滚轮行程的帧视图。
    ///
    /// 用法与 [`get_key_state`](Self::get_key_state) 一致:主线程每帧先调用
    /// [`update`](ScrollWheel::update) 取走自上次取走以来累计的总行程,再通过
    /// `x()` / `y()` 查询本周期内的水平 / 垂直滚动量。
    pub fn get_scroll_wheel(&self) -> ScrollWheel<'_> {
        ScrollWheel::new(&self.scroll_wheel)
    }

    /// 设置显示线程每帧开始执行的更新钩子。
    ///
    /// 与早期把钩子作为 `ArrayViewer::run` 参数传递的方式不同,钩子存放在
    /// 交换层中,可以在显示线程启动前**预先注册**,也可以在运行期间随时
    /// **替换**或清除,无需重启窗口。
    ///
    /// # 参数
    /// - `hook`: 一段 `Fn(&mut Window)` 闭包,显示线程每帧调用时传入当前窗口的
    ///   可变引用。钩子可直接读写窗口(读取键鼠输入、修改标题等);若还需要
    ///   访问交换层,请在创建闭包时通过 `get_exchange_layer()` 自行捕获。
    ///
    /// # 线程安全
    /// 闭包只需满足 `Send`(不必 `Sync`)。钩子被渲染线程以“邮箱 + 代数”方式
    /// 领取后由该线程独占调用,不会发生并发调用。
    pub fn set_update_hook(&self, hook: impl Fn(&mut Window) + Send + 'static) {
        {
            let mut guard = self
                .update_hook
                .lock()
                .expect("[ExchangeLayer::set_update_hook] update_hook mutex poisoned");
            *guard = Some(box_hook(hook));
        }
        // 递增代数,通知渲染线程换用新钩子
        self.hook_epoch.fetch_add(1, Ordering::Relaxed);
    }

    /// 清除当前更新钩子,渲染线程在后续帧将不再执行任何钩子。
    pub fn clear_update_hook(&self) {
        {
            let mut guard = self
                .update_hook
                .lock()
                .expect("[ExchangeLayer::clear_update_hook] update_hook mutex poisoned");
            *guard = None;
        }
        self.hook_epoch.fetch_add(1, Ordering::Relaxed);
    }

    // ---------- 公共入口 ----------
    /// 从窗口读取当前状态,更新交换层的输入相关字段。
    ///
    /// 该方法由显示线程在每帧调用,根据 `update_signal` 决定读取哪些字段。
    /// 读取后会自动清除 `update_signal`。
    ///
    /// # 参数
    /// - `window`:可变引用到 minifb 窗口。
    pub(crate) fn update_from_window(&self, window: &mut Window) {
        let update_signal: UpdateSignalNonAtomic =
            self.update_signal.bits.load(Ordering::Relaxed).into();
        if update_signal.get(UpdateFlag::WindowSize) {
            self.update_window_size(window);
        }
        if update_signal.get(UpdateFlag::WindowPosition) {
            self.update_window_position(window);
        }
        if update_signal.get(UpdateFlag::MousePos) {
            self.update_mouse_pos(window);
        }
        if update_signal.get(UpdateFlag::ScaledMousePos) {
            self.update_scaled_mouse_pos(window);
        }
        if update_signal.get(UpdateFlag::MouseState) {
            self.update_mouse_state(window);
        }
        if update_signal.get(UpdateFlag::ScrollWheel) {
            self.update_scroll_wheel(window);
        }
        if update_signal.get(UpdateFlag::KeyState) {
            self.update_key_state(window);
        }
        if update_signal.get(UpdateFlag::IsActive) {
            self.update_is_active(window);
        }
    }

    /// 将交换层中的配置数据应用到窗口。
    ///
    /// 该方法由显示线程在每帧调用,根据 `apply_signal` 决定应用哪些字段。
    /// 应用后会自动清除 `apply_signal`。
    ///
    /// # 参数
    /// - `window`:可变引用到 minifb 窗口。
    pub(crate) fn apply_to_window(&self, window: &mut Window) {
        let apply_signal: ApplySignalNonAtomic =
            self.apply_signal.bits.load(Ordering::Relaxed).into();
        if apply_signal.get(ApplyFlag::WindowPosition) {
            self.apply_window_position(window);
        }
        // if apply_signal.get(ApplyFlag::Title)               { self.apply_title(window);             }
        self.apply_title(window);
        if apply_signal.get(ApplyFlag::Topmost) {
            self.apply_topmost(window);
        }
        if apply_signal.get(ApplyFlag::BackgroundColor) {
            self.apply_background_color(window);
        }
        if apply_signal.get(ApplyFlag::CursorVisibility) {
            self.apply_cursor_visibility(window);
        }
        if apply_signal.get(ApplyFlag::TargetFps) {
            self.apply_target_fps(window);
        }
        if apply_signal.get(ApplyFlag::CursorStyle) {
            self.apply_cursor_style(window);
        }
        self.apply_signal.reset();
    }

    // ---------- 更新方法(从窗口读取)----------
    pub(crate) fn update_window_size(&self, window: &Window) {
        let (w, h) = window.get_size();
        self.window_size.0.store(w, Ordering::Relaxed);
        self.window_size.1.store(h, Ordering::Relaxed);
    }

    pub(crate) fn update_window_position(&self, window: &Window) {
        let (x, y) = window.get_position();
        self.window_position.0.store(x, Ordering::Relaxed);
        self.window_position.1.store(y, Ordering::Relaxed);
    }

    pub(crate) fn update_mouse_pos(&self, window: &Window) {
        if let Some((x, y)) = window.get_unscaled_mouse_pos(MouseMode::Discard) {
            self.mouse_pos.0.store(x, Ordering::Relaxed);
            self.mouse_pos.1.store(y, Ordering::Relaxed);
        }
    }

    pub(crate) fn update_scaled_mouse_pos(&self, window: &Window) {
        if let Some((x, y)) = window.get_mouse_pos(MouseMode::Discard) {
            self.scaled_mouse_pos.0.store(x, Ordering::Relaxed);
            self.scaled_mouse_pos.1.store(y, Ordering::Relaxed);
        }
    }

    pub(crate) fn update_mouse_state(&self, window: &Window) {
        let mouse_state: u8 = u8::from(window.get_mouse_down(MouseButton::Left))
            | u8::from(window.get_mouse_down(MouseButton::Middle)) << 1
            | u8::from(window.get_mouse_down(MouseButton::Right)) << 2;
        // 注意:mouse_state.merge() 是原子操作,将当前帧的按键状态合并到内部状态中。
        // 在每帧显示线程调用 update_from_window 之前,MouseState.update() 已被调用(由主线程或逻辑线程),
        // 以将上一帧的按键状态移动到 prev,并清空当前帧。因此这里 merge 的是本帧的新按键。
        self.mouse_state.merge(mouse_state);
    }

    pub(crate) fn update_scroll_wheel(&self, window: &Window) {
        if let Some((x, y)) = window.get_scroll_wheel() {
            // 累加本帧的滚轮增量(原子操作);主线程按需取走,避免在两次读取间丢失行程。
            self.scroll_wheel.merge(x, y);
        }
    }

    pub(crate) fn update_key_state(&self, window: &Window) {
        let keys = window.get_keys();
        // 同样,KeyState.merge() 合并本帧按下的按键。
        self.key_state.merge(&keys);
    }

    pub(crate) fn update_is_active(&self, window: &mut Window) {
        self.is_active.store(window.is_active(), Ordering::Relaxed);
    }

    // ---------- 应用方法(应用到窗口)----------
    pub(crate) fn apply_window_position(&self, window: &mut Window) {
        let x = self.window_position.0.load(Ordering::Relaxed);
        let y = self.window_position.1.load(Ordering::Relaxed);
        window.set_position(x, y);
    }

    pub(crate) fn apply_title(&self, window: &mut Window) {
        self.apply_option_field(&self.title, |opt| {
            if let Some(title) = opt {
                window.set_title(title);
            } else {
                window.set_title(&format!("fps: {}", self.fps.load(Ordering::Relaxed)));
            }
        });
    }

    pub(crate) fn apply_topmost(&self, window: &mut Window) {
        window.topmost(self.topmost.load(Ordering::Relaxed));
    }

    pub(crate) fn apply_background_color(&self, window: &mut Window) {
        let color = self.background_color.load(Ordering::Relaxed);
        let r = ((color >> 16) & 0xFF) as u8;
        let g = ((color >> 8) & 0xFF) as u8;
        let b = (color & 0xFF) as u8;
        window.set_background_color(r, g, b);
    }

    pub(crate) fn apply_cursor_visibility(&self, window: &mut Window) {
        window.set_cursor_visibility(self.cursor_visibility.load(Ordering::Relaxed));
    }

    pub(crate) fn apply_target_fps(&self, window: &mut Window) {
        window.set_target_fps(self.target_fps.load(Ordering::Relaxed));
    }

    pub(crate) fn apply_cursor_style(&self, window: &mut Window) {
        self.apply_option_field(&self.cursor_style, |opt| {
            if let Some(style) = opt {
                window.set_cursor_style(*style);
            }
        });
    }

    // ---------- 辅助:带重试的锁操作 ----------
    /// 尝试获取互斥锁,最多重试3次,每次间隔50ms。
    /// 成功获取后调用 `apply` 闭包,传入 `Option<&T>`。
    /// 若三次均失败则静默忽略并输出警告。
    fn apply_option_field<T, F>(&self, mutex: &Mutex<Option<T>>, mut apply: F)
    where
        F: FnMut(Option<&T>),
    {
        for attempt in 0..=Self::RETRY_TIMES {
            if let Ok(guard) = mutex.try_lock() {
                apply(guard.as_ref());
                break;
            } else if attempt == Self::RETRY_TIMES {
                eprintln!(
                    "[warning] The mutex lock of type:{} object in thread:{} is over delay",
                    type_name::<T>(),
                    thread::current()
                        .name()
                        .unwrap_or(&*format!("id:{:?}", thread::current().id()))
                );
                break;
            }
            thread::sleep(Self::RETRY_DELAY);
        }
    }
}

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

    /// 构造一个空钩子:接收窗口可变引用但不做任何事。
    fn dummy_hook() -> impl Fn(&mut Window) + Send {
        |_window: &mut Window| {}
    }

    /// 模拟渲染线程的“邮箱 + 代数”领取逻辑:代数变化时领取并更新本地缓存。
    fn adopt(layer: &ExchangeLayer, cache: &mut Option<UpdateHook>, epoch: &mut usize) {
        let e = layer.hook_epoch.load(Ordering::Relaxed);
        if e != *epoch {
            *cache = layer.update_hook.try_lock().unwrap().take();
            *epoch = layer.hook_epoch.load(Ordering::Relaxed);
        }
    }

    #[test]
    fn update_hook_default_empty_epoch_zero() {
        let layer = ExchangeLayer::new();
        assert!(layer.update_hook.try_lock().unwrap().is_none());
        assert_eq!(layer.hook_epoch.load(Ordering::Relaxed), 0);
    }

    #[test]
    fn update_hook_set_then_clear_bumps_epoch() {
        let layer = ExchangeLayer::new();

        layer.set_update_hook(dummy_hook());
        assert!(layer.update_hook.try_lock().unwrap().is_some());
        assert_eq!(layer.hook_epoch.load(Ordering::Relaxed), 1);

        layer.clear_update_hook();
        assert!(layer.update_hook.try_lock().unwrap().is_none());
        assert_eq!(layer.hook_epoch.load(Ordering::Relaxed), 2);
    }

    #[test]
    fn renderer_adopts_replace_and_clear() {
        let layer = ExchangeLayer::new();
        let mut cache: Option<UpdateHook> = None;
        let mut epoch = 0usize;

        // 设置 → 领取:邮箱被清空,缓存持有钩子
        layer.set_update_hook(dummy_hook());
        adopt(&layer, &mut cache, &mut epoch);
        assert!(cache.is_some());
        assert!(layer.update_hook.try_lock().unwrap().is_none());

        // 替换 → 代数递增,可再次领取新钩子
        layer.set_update_hook(dummy_hook());
        adopt(&layer, &mut cache, &mut epoch);
        assert!(cache.is_some());
        assert_eq!(epoch, 2);

        // 清除 → 领取到 None,缓存被清空
        layer.clear_update_hook();
        adopt(&layer, &mut cache, &mut epoch);
        assert!(cache.is_none());
        assert_eq!(epoch, 3);
    }
}