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
//! `Scene` and `SyncGuard` structures.
use node;
use color::Color;
use hub::{Hub, HubPtr, SubNode};
use object::{Base, DowncastObject, Group, Object};
use texture::{CubeMap, Texture};
use std::mem;
use std::marker::PhantomData;
use std::sync::MutexGuard;
/// Background type.
#[derive(Clone, Debug, PartialEq)]
pub enum Background {
/// Basic solid color background.
Color(Color),
/// Texture background, covers the whole screen.
// TODO: different wrap modes?
Texture(Texture<[f32; 4]>),
/// Skybox
Skybox(CubeMap<[f32; 4]>),
}
/// The root node of a tree of game objects that may be rendered by a [`Camera`].
///
/// [`Camera`]: ../camera/struct.Camera.html
pub struct Scene {
pub(crate) hub: HubPtr,
pub(crate) first_child: Option<node::NodePointer>,
/// See [`Background`](struct.Background.html).
pub background: Background,
}
impl Scene {
/// Add new [`Base`](struct.Base.html) to the scene.
pub fn add<P>(
&mut self,
child_base: P,
) where
P: AsRef<Base>,
{
let mut hub = self.hub.lock().unwrap();
let node_ptr = child_base.as_ref().node.clone();
let child = &mut hub[child_base];
if child.next_sibling.is_some() {
error!("Element {:?} is added to a scene while still having old parent - {}",
child.sub_node, "discarding siblings");
}
child.next_sibling = mem::replace(&mut self.first_child, Some(node_ptr));
}
/// Remove a previously added [`Base`](struct.Base.html) from the scene.
pub fn remove<P>(
&mut self,
child_base: P,
) where
P: AsRef<Base>,
{
let target_maybe = Some(child_base.as_ref().node.clone());
let mut hub = self.hub.lock().unwrap();
let next_sibling = hub[child_base].next_sibling.clone();
if self.first_child == target_maybe {
self.first_child = next_sibling;
return;
}
let mut cur_ptr = self.first_child.clone();
while let Some(ptr) = cur_ptr.take() {
let node = &mut hub.nodes[&ptr];
if node.next_sibling == target_maybe {
node.next_sibling = next_sibling;
return;
}
cur_ptr = node.next_sibling.clone(); //TODO: avoid clone
}
error!("Unable to find child for removal");
}
}
/// `SyncGuard` is used to obtain information about scene nodes in the most effective way.
///
/// # Examples
///
/// Imagine that you have your own helper type `Enemy`:
///
/// ```rust
/// # extern crate three;
/// struct Enemy {
/// mesh: three::Mesh,
/// is_visible: bool,
/// }
/// # fn main() {}
/// ```
///
/// You need this wrapper around `three::Mesh` to cache some information - in our case, visibility.
///
/// In your game you contain all your enemy objects in `Vec<Enemy>`. In the main loop you need
/// to iterate over all the enemies and make them visible or not, basing on current position.
/// The most obvious way is to use [`object::Base::sync`], but it's not the best idea from the side of
/// performance. Instead, you can create `SyncGuard` and use its `resolve` method to effectively
/// walk through every enemy in your game:
///
/// ```rust,no_run
/// # #[macro_use]
/// # extern crate three;
/// # #[derive(Clone)]
/// # struct Enemy {
/// # mesh: three::Mesh,
/// # is_visible: bool,
/// # }
/// #
/// # three_object!(Enemy::mesh);
/// #
/// # fn main() {
/// # use three::Object;
/// # let mut win = three::Window::new("SyncGuard example");
/// # let geometry = three::Geometry::default();
/// # let material = three::material::Basic { color: three::color::RED, map: None };
/// # let mesh = win.factory.mesh(geometry, material);
/// # let enemy = Enemy { mesh, is_visible: true };
/// # win.scene.add(&enemy);
/// # let mut enemies = vec![enemy];
/// # loop {
/// let mut sync = win.scene.sync_guard();
/// for mut enemy in &mut enemies {
/// let node = sync.resolve(enemy);
/// let position = node.transform.position;
/// if position.x > 10.0 {
/// enemy.is_visible = false;
/// enemy.set_visible(false);
/// } else {
/// enemy.is_visible = true;
/// enemy.set_visible(true);
/// }
/// }
/// # }}
/// ```
///
/// [`object::Base::sync`]: ../object/struct.Base.html#method.sync
pub struct SyncGuard<'a> {
pub(crate) scene: &'a Scene,
pub(crate) hub: MutexGuard<'a, Hub>,
}
impl<'a> SyncGuard<'a> {
/// Obtains `objects`'s local space [`Node`] in an effective way.
///
/// # Panics
/// Panics if `scene` doesn't have this `object::Base`.
///
/// [`Node`]: ../node/struct.Node.html
pub fn resolve<T: 'a + Object>(
&self,
object: &T,
) -> node::Node<node::Local> {
self.hub[object].to_node()
}
/// Obtains `objects`'s world [`Node`] by traversing the scene graph.
/// *Note*: this can be slow.
///
/// # Panics
/// Panics if the scene doesn't have this `object::Base`.
///
/// [`Node`]: ../node/struct.Node.html
pub fn resolve_world<T: 'a + Object>(
&self,
object: &T,
) -> node::Node<node::World> {
let internal = &self.hub[object] as *const _;
let wn = self.hub
.walk_all(&self.scene.first_child)
.find(|wn| wn.node as *const _ == internal)
.expect("Unable to find objects for world resolve!");
node::Node {
visible: wn.world_visible,
name: wn.node.name.clone(),
transform: wn.world_transform.into(),
material: match wn.node.sub_node {
SubNode::Visual(ref mat, _, _) => Some(mat.clone()),
_ => None,
},
_space: PhantomData,
}
}
/// Obtains internal state data for `object`.
///
/// Three-rs objects normally expose a write-only interface, making it possible to change
/// an object's internal values but not possible to read those values. `SyncGuard` allows
/// for that data to be read in a controlled way.
///
/// Each object type has its own internal data, and not all object types can provide access
/// to meaningful data. The following types provide specific data you can use:
///
/// * [`Base`]: Returns an [`ObjectType`], which provides access to the concrete object type
/// for `object`.
/// * [`Group`]: Returns a list of the group's direct children.
/// * [`Camera`]: Returns the [`Projection`] for the camera.
/// * [`Ambient`]: Returns the [`LightData`] for the light.
/// * [`Point`]: Returns the [`LightData`] for the light.
/// * [`Directional`]: Returns the [`LightData`] for the light.
/// * [`Hemisphere`]: Returns the [`HemisphereLightData`] for the light.
///
/// The other object types do not have a user-facing way to represent their internal data,
/// and so return `()`.
///
/// [`Base`]: ../object/struct.Base.html
/// [`ObjectType`]: ../object/enum.ObjectType.html
/// [`Group`]: ../struct.Group.html
/// [`Camera`]: ../camera/struct.Camera.html
/// [`Projection`]: ../camera/enum.Projection.html
/// [`LightData`]: ../light/struct.LightData.html
/// [`Ambient`]: ../light/struct.Ambient.html
/// [`Point`]: ../light/struct.Point.html
/// [`Directional`]: ../light/struct.Directional.html
/// [`Hemisphere`]: ../light/struct.Hemisphere.html
/// [`HemisphereLightData`]: ../light/struct.HemisphereLightData.html
pub fn resolve_data<T: 'a + Object>(
&self,
object: &T,
) -> T::Data {
object.resolve_data(self)
}
/// Returns an iterator that walks all the objects in `root`'s hierarchy.
///
/// Walks the children of `root`, recursively walking the children of any [`Group`] objects
/// found until all objects in the hierarchy have been visited. The hierarchy is walked
/// depth-first, and objects are yielded in the order they are visited.
///
/// [`Group`]: ../struct.Group.html
pub fn walk_hierarchy(&'a self, root: &Group) -> impl Iterator<Item = Base> + 'a {
let root = root.as_ref().node.clone();
let guard = &*self;
self
.hub
.walk_all(&Some(root))
.map(move |walked| guard.hub.upgrade_ptr(walked.node_ptr.clone()))
}
/// Finds a node in a group, or any of its children, by name.
///
/// Performs a depth-first search starting with `root` looking for an object with `name`.
/// Returns the [`Base`] for the first object found with a matching name, otherwise returns
/// `None` if no such object is found. Note that if more than one such object exists in the
/// hierarchy, then only the first one discovered will be returned.
///
/// [`Base`]: ../object/struct.Base.html
pub fn find_child_by_name(&self, root: &Group, name: &str) -> Option<Base> {
self.find_children_by_name(root, name).next()
}
/// Returns an iterator of all objects under `root` with the specified name.
///
/// Performs a depth-first search starting with `root`, yielding each object in the hierarchy
/// matching `name`.
///
/// [`Group`]: ../struct.Group.html
pub fn find_children_by_name(
&'a self,
root: &Group,
name: &'a str,
) -> impl Iterator<Item = Base> + 'a {
let root = root.as_ref().node.clone();
let guard = &*self;
self
.hub
.walk_all(&Some(root))
.filter(move |walked| {
walked
.node
.name
.as_ref()
.map(|node_name| node_name == name)
.unwrap_or(false)
})
.map(move |walked| guard.hub.upgrade_ptr(walked.node_ptr.clone()))
}
/// Finds the first object in a group, or any of its children, of type `T`.
///
/// Performs a depth-first search starting with `root`, recusively descending into any
/// [`Group`] objects found. Returns the first object of type `T` encountered in the
/// hierarchy.
///
/// [`Group`]: ../struct.Group.html
pub fn find_child_of_type<T: DowncastObject>(&'a self, root: &Group) -> Option<T> {
self.find_children_of_type::<T>(root).next()
}
/// Returns an iterator yielding all objects in the hierarchy of `root` of type `T`.
///
/// Performs a depth-first search starting with `root`, recursively descending into any
/// [`Group`] objects found, yielding each object of type `T` found in the hierarchy.
///
/// [`Group`]: ../struct.Group.html
pub fn find_children_of_type<T: DowncastObject>(
&'a self,
root: &Group,
) -> impl Iterator<Item = T> + 'a {
let root = root.as_ref().node.clone();
let guard = &*self;
self
.hub
.walk_all(&Some(root))
.map(move |walked| guard.hub.upgrade_ptr(walked.node_ptr.clone()))
.filter_map(move |base| guard.downcast(&base))
}
/// Attempts to find an object of type `T` in the group or any of its children.
///
/// Performs a depth-first search starting with `root`, recursively searching [`Group`]
/// objects, until an object of type `T` that matches `name` is found. Note that if `T` is
/// [`Group`] and `root` matches `name`, then it will be returned.
///
/// [`Group`]: ../struct.Group.html
pub fn find_child_of_type_by_name<T: DowncastObject>(
&'a self,
root: &Group,
name: &'a str,
) -> Option<T> {
self.find_children_of_type_by_name(root, name).next()
}
/// Returns an iterator yielding all children of `root` of type `T` named `name`.
///
/// Performs a depth-first search starting with `root`, recursively searching [`Group`]
/// objects, yielding any objects of `T` that match `name`. Note that if `T` is [`Group`]
/// and `root` matches `name`, then it will be the first object yielded by the iterator.
///
/// [`Group`]: ../struct.Group.html
pub fn find_children_of_type_by_name<T: DowncastObject>(
&'a self,
root: &Group,
name: &'a str,
) -> impl Iterator<Item = T> + 'a {
let guard = &*self;
self
.find_children_by_name(root, name)
.filter_map(move |base| guard.downcast(&base))
}
/// Attempts to downcast a [`Base`] to its concrete object type.
///
/// If the downcast succeeds, the concrete object is returned. Returns `None` if the
/// downcast fails.
///
/// [`Base`]: ../object/struct.Base.html
pub fn downcast<T: DowncastObject>(&self, base: &Base) -> Option<T> {
let object_type = self.resolve_data(base);
T::downcast(object_type)
}
}
impl Scene {
/// Create new [`SyncGuard`](struct.SyncGuard.html).
///
/// This is performance-costly operation, you should not use it many times per frame.
pub fn sync_guard(&mut self) -> SyncGuard {
let mut hub = self.hub.lock().unwrap();
hub.process_messages();
SyncGuard { scene: self, hub }
}
}