hoplite 0.1.9

A creative coding framework for Rust that gets out of your way
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

//! Scene definition and identifier types.

use crate::Frame;
use crate::camera::Camera;
use crate::render_graph::{MeshQueue, RenderGraph};
use std::cell::RefCell;
use std::rc::Rc;

/// Unique identifier for a scene.
///
/// Scene IDs are strings that uniquely identify scenes within a [`SceneManager`](super::SceneManager).
/// They're used when switching between scenes via [`Frame::switch_to`] and [`Frame::switch_to_with`].
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct SceneId(pub(crate) String);

impl SceneId {
    /// Create a new scene ID from a string.
    pub fn new(name: impl Into<String>) -> Self {
        Self(name.into())
    }

    /// Get the scene ID as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl std::fmt::Display for SceneId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<&str> for SceneId {
    fn from(s: &str) -> Self {
        Self::new(s)
    }
}

impl From<String> for SceneId {
    fn from(s: String) -> Self {
        Self(s)
    }
}

/// A scene with its own camera, render graph, and frame logic.
///
/// Scenes are created via [`SetupContext::scene`] and managed by the [`SceneManager`](super::SceneManager).
/// Each scene maintains independent state that persists across scene switches (unless reset in `on_enter`).
pub struct Scene {
    /// Unique identifier for this scene.
    pub id: SceneId,

    /// Scene's camera (independent per scene).
    pub camera: Camera,

    /// Scene's render graph (can have different post-processing).
    pub render_graph: Option<RenderGraph>,

    /// Reference to the shared mesh queue (shared storage, per-scene draw queue).
    pub mesh_queue: Rc<RefCell<MeshQueue>>,

    /// The scene's frame update closure.
    pub(crate) frame_fn: Box<dyn FnMut(&mut Frame)>,

    /// Optional callback when entering this scene.
    pub(crate) on_enter: Option<Box<dyn FnMut()>>,

    /// Optional callback when exiting this scene.
    pub(crate) on_exit: Option<Box<dyn FnMut()>>,
}

impl Scene {
    /// Create a new scene with the given ID.
    pub(crate) fn new(
        id: SceneId,
        render_graph: Option<RenderGraph>,
        mesh_queue: Rc<RefCell<MeshQueue>>,
        frame_fn: Box<dyn FnMut(&mut Frame)>,
    ) -> Self {
        Self {
            id,
            camera: Camera::new(),
            render_graph,
            mesh_queue,
            frame_fn,
            on_enter: None,
            on_exit: None,
        }
    }

    /// Call the scene's enter callback if set.
    pub(crate) fn enter(&mut self) {
        if let Some(ref mut callback) = self.on_enter {
            callback();
        }
    }

    /// Call the scene's exit callback if set.
    pub(crate) fn exit(&mut self) {
        if let Some(ref mut callback) = self.on_exit {
            callback();
        }
    }
}

/// Builder for configuring scene lifecycle hooks.
///
/// Returned by [`SetupContext::scene`] to allow chaining `on_enter` and `on_exit` hooks.
///
/// # Example
///
/// ```ignore
/// ctx.scene("game", |scene| {
///     scene.enable_mesh_rendering();
///     let mut score = 0;
///
///     move |frame| {
///         frame.text(10.0, 10.0, &format!("Score: {}", score));
///     }
/// })
/// .on_enter(|| println!("Starting game!"))
/// .on_exit(|| println!("Leaving game..."));
/// ```
pub struct SceneBuilder<'a> {
    pub(crate) scene_id: SceneId,
    pub(crate) manager: &'a mut super::SceneManager,
}

impl<'a> SceneBuilder<'a> {
    /// Set a callback to run when entering this scene.
    ///
    /// Called after scene becomes active, before the first frame update.
    pub fn on_enter<F: FnMut() + 'static>(self, callback: F) -> Self {
        if let Some(scene) = self.manager.scenes.get_mut(&self.scene_id.0) {
            scene.on_enter = Some(Box::new(callback));
        }
        self
    }

    /// Set a callback to run when exiting this scene.
    ///
    /// Called before transition begins, while scene is still active.
    pub fn on_exit<F: FnMut() + 'static>(self, callback: F) -> Self {
        if let Some(scene) = self.manager.scenes.get_mut(&self.scene_id.0) {
            scene.on_exit = Some(Box::new(callback));
        }
        self
    }
}