viewport-lib-types 0.3.0

Pure-data types for viewport-lib: submission payloads, handles, and frame config, free of any GPU dependency.
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
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
//! Viewport events for the new input pipeline.

use std::path::PathBuf;

use super::binding::{KeyCode, Modifiers, MouseButton};

/// Button press or release state.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ButtonState {
    /// Button was pressed.
    Pressed,
    /// Button was released.
    Released,
}

/// OS colour theme.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Theme {
    /// Light theme.
    Light,
    /// Dark theme.
    Dark,
}

/// Scroll delta units.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ScrollUnits {
    /// Delta in logical line units (one notch ~ 1.0).
    Lines,
    /// Delta in physical pixels.
    Pixels,
    /// Delta in viewport pages (one unit = viewport height).
    Pages,
}

/// Identifies one finger or pen on a touch surface. Stable from the contact going
/// down to it lifting; reused freely after that, so it is not a handle to keep.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct TouchId(pub u64);

/// Where a touch contact is in its lifetime.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TouchPhase {
    /// The contact went down.
    Started,
    /// The contact moved, or one of its other properties changed.
    Moved,
    /// The contact lifted normally.
    Ended,
    /// The system took the contact away: a call arrived, a system gesture won it,
    /// the finger slid off a bezel. Whatever the contact was doing does not count
    /// as having happened.
    Cancelled,
}

/// What the platform input method reported, for composing text (Japanese,
/// Chinese, Korean, dead-key accents) into a text field.
///
/// Arrives only after the host turns composition on for the window (on
/// `ViewportApp`, `FrameCtx::set_ime_allowed`). While it is on, accepted text
/// comes as [`Commit`](ImeEvent::Commit); typing that never composed can still
/// arrive as [`ViewportEvent::Character`], so a text field takes both.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum ImeEvent {
    /// Composition is available for the window.
    Enabled,
    /// The provisional text being composed, to show in the field without
    /// writing it to the document. An empty `text` clears it.
    Preedit {
        /// The provisional text.
        text: String,
        /// The caret inside `text` as a byte range, or `None` to hide it.
        cursor: Option<(usize, usize)>,
    },
    /// Accepted text, to insert at the caret. Clears any preedit.
    Commit(String),
    /// Composition is off for the window. Drop any preedit still shown.
    Disabled,
}

/// An event delivered to the viewport input pipeline.
///
/// Host applications translate their native windowing events into
/// `ViewportEvent` values and push them to the `OrbitCameraController`
/// (or `ViewportInput` for direct input handling).
#[non_exhaustive]
#[derive(Debug, Clone)]
pub enum ViewportEvent {
    /// The pointer moved to the given viewport-local position.
    PointerMoved {
        /// Viewport-local position in logical pixels, origin at top-left.
        position: glam::Vec2,
    },
    /// A mouse button was pressed or released.
    MouseButton {
        /// Which button changed state.
        button: MouseButton,
        /// New button state.
        state: ButtonState,
    },
    /// The scroll wheel moved.
    Wheel {
        /// Scroll delta. Positive Y = scroll up / zoom in (conventional).
        delta: glam::Vec2,
        /// Whether the delta is in lines or pixels.
        units: ScrollUnits,
    },
    /// A keyboard key changed state.
    Key {
        /// Which key changed state, by position: the key in the US-layout `A`
        /// position is `KeyCode::A` whatever the layout prints on it. Bindings
        /// match on this, so WASD stays in place on AZERTY.
        key: KeyCode,
        /// New key state.
        state: ButtonState,
        /// True if the event is a key-repeat (key held down).
        repeat: bool,
        /// The character the layout gives this key, unshifted and lower case
        /// (`z` for the key labelled Z on any layout), or `None` for keys that
        /// produce no character (arrows, function keys). Match shortcuts such as
        /// Ctrl+Z on this to follow the layout.
        logical: Option<char>,
    },
    /// Modifier key state changed.
    ModifiersChanged(Modifiers),
    /// The pointer left the viewport area.
    ///
    /// **This releases every held button.** It exists to avoid a button being left
    /// stuck down when the pointer goes somewhere the viewport will never hear the
    /// release, so it ends any drag in flight.
    ///
    /// Send it when the pointer leaves the *window*, not every time it crosses the
    /// viewport's own edge. A drag whose press landed inside the viewport keeps
    /// resolving after the pointer leaves the rect, which is what lets a fast orbit
    /// run past the edge; forwarding this event at that boundary throws that away.
    /// Setting the pointer ownership in the
    /// [`ViewportContext`](crate::input::ViewportContext) to
    /// [`Elsewhere`](crate::input::PointerOwnership::Elsewhere) is the way to say
    /// "the pointer is no longer over us" without ending the drag.
    ///
    /// Under a pointer grab it should never be sent at all: a grabbed pointer has no
    /// rect to leave, and ending the gesture would end the look session.
    /// [`forward_to_viewport`](crate::input::forward_to_viewport) drops it for you
    /// under [`PointerOwnership::Grabbed`](crate::input::PointerOwnership::Grabbed).
    PointerLeft,
    /// The viewport lost keyboard focus.
    FocusLost,
    /// A character was typed (Unicode): the text a key press produced after
    /// layout, Shift and dead keys.
    ///
    /// winit puts it in `KeyEvent::text`, and the winit adapter's `translate`
    /// emits it after the key's [`Key`](ViewportEvent::Key) event. egui sends it
    /// as `Event::Text`, which the egui adapter's `translate` turns into one
    /// `Character` per character. The resolver keeps it only while the viewport
    /// owns the keyboard, like a key, and a manipulation session reads its
    /// digits, `.` and `-` for numeric entry.
    Character(char),

    /// Two-finger trackpad rotation gesture.
    ///
    /// `delta` is the change in angle this event, in radians.
    /// Positive = counter-clockwise (matches winit's `RotationGesture` convention,
    /// converted from degrees to radians by the host). egui's angle convention is the
    /// opposite, so its adapter negates; twist therefore turns the same way through
    /// either host.
    ///
    /// ## Platform-specific
    /// Only emitted on macOS (and iOS). Silently unused on Windows and Linux.
    TrackpadRotate(f32),

    /// Two-finger trackpad pinch (magnify) gesture.
    ///
    /// `delta` is the change in magnification this event, on a log scale: positive =
    /// pinch out / zoom in, and `0.0` is no change. This is winit's `PinchGesture`
    /// convention. A host whose framework reports a multiplicative factor instead
    /// (egui's `Event::Zoom`, where `1.0` is no change) converts with `ln`; the
    /// adapters do this, so the same physical pinch resolves the same way whichever
    /// shell hosts the viewport.
    ///
    /// Resolves into [`NavigationActions::zoom`](crate::input::NavigationActions::zoom),
    /// gated on the pointer being inside the viewport, like the wheel.
    ///
    /// ## Platform-specific
    /// Only emitted on macOS (and iOS). Silently unused on Windows and Linux.
    TrackpadPinch(f32),

    /// Two-finger trackpad pan gesture.
    ///
    /// `delta` is the pan this event in logical points. Resolves into
    /// [`NavigationActions::pan`](crate::input::NavigationActions::pan), gated on the
    /// pointer being inside the viewport.
    ///
    /// ## Platform-specific
    /// Only emitted on macOS (and iOS). Silently unused on Windows and Linux.
    TrackpadPan(glam::Vec2),

    /// A touch contact went down, moved, lifted, or was taken away.
    ///
    /// One event per contact per change, so a two-finger gesture arrives as two
    /// interleaved streams distinguished by `id`. The viewport tracks the contacts
    /// and recognises the gestures itself, rather than taking a host's derived
    /// pinch or pan, so that the same finger movement feels the same whichever
    /// shell hosts the viewport.
    ///
    /// A host that also synthesises mouse events from touch (most do) should send
    /// one or the other, not both, or every gesture counts twice.
    Touch {
        /// Which contact this is.
        id: TouchId,
        /// What the contact just did.
        phase: TouchPhase,
        /// Viewport-local position in logical pixels, origin at top-left. The same
        /// space as [`PointerMoved`](ViewportEvent::PointerMoved), which is what
        /// lets the two share the hit-testing an application already has.
        position: glam::Vec2,
    },

    /// Raw, unaccelerated relative pointer motion from the input device, not tied to
    /// the window or surface. `delta` is in raw device units. Use this for
    /// first-person / mouselook navigation while the cursor is grabbed; the ordinary
    /// cursor position comes from [`PointerMoved`](ViewportEvent::PointerMoved).
    RawMotion {
        /// Relative motion since the last event, in raw device units.
        delta: glam::Vec2,
    },

    /// The OS colour theme changed. A consumer can follow the system light/dark
    /// preference (for overlay UI colours, for example).
    ThemeChanged(Theme),

    /// The window's occlusion state changed. `true` when the window became fully
    /// hidden (behind others, or minimised); `false` when it is visible again. A
    /// consumer can pause rendering while occluded to save power.
    Occluded(bool),

    /// A file was dropped onto the window, at the OS level (not viewport-local).
    FileDropped(PathBuf),

    /// A file is being dragged over the window but not yet dropped. May arrive more
    /// than once as the drag moves; a consumer uses it to show a drop target.
    FileHovered(PathBuf),

    /// A file drag left the window without dropping, cancelling a prior
    /// [`FileHovered`](ViewportEvent::FileHovered).
    FileHoverCancelled,

    /// The platform input method reported composition. For text fields; the
    /// viewport itself ignores it.
    Ime(ImeEvent),
}

/// The variant names of [`ViewportEvent`], listed once so the name table and the
/// match in `variant_name` cannot drift apart. The match has no wildcard, so a new
/// variant fails to compile here until it is listed.
macro_rules! viewport_event_variants {
    ($($name:ident),* $(,)?) => {
        impl ViewportEvent {
            /// Every variant's name, for tests that walk the event vocabulary (an
            /// adapter checking it carries each one).
            #[doc(hidden)]
            pub const VARIANTS: &'static [&'static str] = &[$(stringify!($name)),*];

            /// This event's variant name, one of [`VARIANTS`](Self::VARIANTS).
            #[doc(hidden)]
            pub fn variant_name(&self) -> &'static str {
                match self {
                    $(ViewportEvent::$name { .. } => stringify!($name),)*
                }
            }
        }
    };
}

viewport_event_variants! {
    PointerMoved,
    MouseButton,
    Wheel,
    Key,
    ModifiersChanged,
    PointerLeft,
    FocusLost,
    Character,
    TrackpadRotate,
    TrackpadPinch,
    TrackpadPan,
    Touch,
    RawMotion,
    ThemeChanged,
    Occluded,
    FileDropped,
    FileHovered,
    FileHoverCancelled,
    Ime,
}

impl ViewportEvent {
    /// Whether this event would be claimed by both the viewport and anything drawn
    /// over it, so at most one of them may act on it.
    ///
    /// A left press, the pointer motion after it, and a touch contact landing are
    /// contested: a press-and-move is exactly what a camera orbit, a gizmo drag and
    /// a UI drag would all claim, so it has to belong to one of them. Touch is
    /// contested for the same reason: a finger is the only pointer a touch device
    /// has, so a control that takes the contact takes all of it. Everything else is
    /// **ambient**: the wheel, the other buttons and the modifiers can be acted on
    /// by more than one claimant in the same frame. Releases and contact ends are
    /// teardown, not claims, and are never contested: a resolver that saw the
    /// press must see its release, and one that did not ignores it. A contact's
    /// later moves are left to the resolver, which follows the contacts it saw
    /// land.
    ///
    /// That asymmetry is deliberate. Withholding the whole event stream whenever
    /// something over the viewport holds the pointer is the obvious implementation
    /// and it fails in the most visible place: the moment the cursor crosses a gizmo
    /// handle, scrolling stops zooming, which is exactly where someone is most likely
    /// to scroll.
    ///
    /// The set is fixed and does not consult the active bindings. Right and middle
    /// presses stay ambient even though the default scheme binds them to camera
    /// navigation, because chrome overwhelmingly uses the primary button. The
    /// resolver starts a drag from one only when it arrives while the viewport
    /// owns the input, so a right press on chrome over the viewport does not
    /// orbit.
    ///
    /// Used by [`forward_to_viewport`](super::context::forward_to_viewport), which is
    /// what most callers want.
    pub fn is_contested(&self) -> bool {
        matches!(
            self,
            ViewportEvent::MouseButton {
                button: MouseButton::Left,
                state: ButtonState::Pressed,
            } | ViewportEvent::PointerMoved { .. }
                | ViewportEvent::Touch {
                    phase: TouchPhase::Started,
                    ..
                }
        )
    }

    /// This event with any viewport-local position shifted by `-origin`, and
    /// everything else unchanged.
    ///
    /// For a viewport embedded in a larger window: the adapters produce positions
    /// relative to the window, and the viewport wants them relative to its own rect.
    /// Subtract the rect's top-left corner, in the same logical pixels the positions
    /// are already in.
    ///
    /// ```
    /// # use viewport_lib_types::input::ViewportEvent;
    /// let ev = ViewportEvent::PointerMoved { position: glam::Vec2::new(300.0, 120.0) };
    /// let local = ev.offset_by(glam::Vec2::new(200.0, 100.0));
    /// assert!(matches!(local, ViewportEvent::PointerMoved { position } if position == glam::Vec2::new(100.0, 20.0)));
    /// ```
    ///
    /// Worth using rather than matching the position-carrying variants yourself:
    /// that list grows (touch contacts joined it), and a host that enumerated it by
    /// hand keeps compiling while quietly leaving the new ones in window space.
    /// Deltas are not positions and are left alone: the wheel, the trackpad
    /// gestures, and raw motion all mean the same thing wherever the rect is.
    pub fn offset_by(&self, origin: glam::Vec2) -> ViewportEvent {
        match self {
            ViewportEvent::PointerMoved { position } => ViewportEvent::PointerMoved {
                position: *position - origin,
            },
            ViewportEvent::Touch {
                id,
                phase,
                position,
            } => ViewportEvent::Touch {
                id: *id,
                phase: *phase,
                position: *position - origin,
            },
            other => other.clone(),
        }
    }
}

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

    #[test]
    fn every_variant_has_a_listed_name() {
        assert!(ViewportEvent::VARIANTS.contains(&ViewportEvent::PointerLeft.variant_name()));
        assert_eq!(ViewportEvent::FocusLost.variant_name(), "FocusLost");
        assert_eq!(ViewportEvent::Character('a').variant_name(), "Character");
        let unique: std::collections::HashSet<_> = ViewportEvent::VARIANTS.iter().collect();
        assert_eq!(unique.len(), ViewportEvent::VARIANTS.len());
    }

    #[test]
    fn only_positions_are_offset() {
        let origin = glam::Vec2::new(200.0, 100.0);

        let moved = ViewportEvent::PointerMoved {
            position: glam::Vec2::new(300.0, 120.0),
        }
        .offset_by(origin);
        assert!(
            matches!(moved, ViewportEvent::PointerMoved { position } if position == glam::Vec2::new(100.0, 20.0))
        );

        let touch = ViewportEvent::Touch {
            id: TouchId(3),
            phase: TouchPhase::Moved,
            position: glam::Vec2::new(300.0, 120.0),
        }
        .offset_by(origin);
        match touch {
            ViewportEvent::Touch {
                id,
                phase,
                position,
            } => {
                assert_eq!(id, TouchId(3));
                assert_eq!(phase, TouchPhase::Moved);
                assert_eq!(position, glam::Vec2::new(100.0, 20.0));
            }
            other => panic!("expected Touch, got {other:?}"),
        }

        // A delta means the same thing wherever the rect is.
        let wheel = ViewportEvent::Wheel {
            delta: glam::Vec2::Y,
            units: ScrollUnits::Lines,
        }
        .offset_by(origin);
        assert!(matches!(wheel, ViewportEvent::Wheel { delta, .. } if delta == glam::Vec2::Y));
        assert!(matches!(
            ViewportEvent::PointerLeft.offset_by(origin),
            ViewportEvent::PointerLeft
        ));
    }

    #[test]
    fn only_the_left_press_pointer_motion_and_a_landing_are_contested() {
        assert!(
            ViewportEvent::PointerMoved {
                position: glam::Vec2::ZERO
            }
            .is_contested()
        );
        assert!(
            ViewportEvent::MouseButton {
                button: MouseButton::Left,
                state: ButtonState::Pressed
            }
            .is_contested()
        );
        assert!(
            !ViewportEvent::MouseButton {
                button: MouseButton::Left,
                state: ButtonState::Released
            }
            .is_contested(),
            "a release is teardown"
        );
        let touch = |phase| ViewportEvent::Touch {
            id: TouchId(1),
            phase,
            position: glam::Vec2::ZERO,
        };
        assert!(touch(TouchPhase::Started).is_contested());
        for phase in [TouchPhase::Moved, TouchPhase::Ended, TouchPhase::Cancelled] {
            assert!(!touch(phase).is_contested(), "{phase:?}");
        }

        // Ambient: acted on by the camera even while something over it holds the pointer.
        for button in [MouseButton::Right, MouseButton::Middle] {
            assert!(
                !ViewportEvent::MouseButton {
                    button,
                    state: ButtonState::Pressed
                }
                .is_contested(),
                "{button:?} must stay ambient"
            );
        }
        assert!(
            !ViewportEvent::Wheel {
                delta: glam::Vec2::Y,
                units: ScrollUnits::Lines
            }
            .is_contested()
        );
        assert!(!ViewportEvent::ModifiersChanged(Modifiers::NONE).is_contested());
        assert!(!ViewportEvent::PointerLeft.is_contested());
    }
}