Struct mutiny::scene::Scene

pub struct Scene { /* fields omitted */ }

The scene is the container for everything else in mutiny

Through it you can create other elements like models, lights... or add systems that will update those elements over time

To create a scene you need to first create a renderer and an events dispatcher. The scene will take ownership of them and run them later.

Once you have a scene you can use it to create all the entities in the application and their components.

Methods

impl Scene

pub fn new(renderer: Bundle, events_dispatcher: EventsDispatcher) -> Scene

Creates a new scene from a renderer and an events dispatcher

Also register the most basic components that are usually always used on any mutiny application and the main systems.

pub fn register_vertex_type<T>(&mut self) where     T: 'static + VertexFormat + Send + Clone + Copy + Debug + Serialize + Deserialize<'static>,

Explicitly register a vertex type

Vertex types are usually registered the first time we add a Geometry of that vertex type to the scene using add_mesh but in some special cases we might want to add geometries directly to an entity. In those cases it's necesary to call this method in order to register the corresponding components and create the renderer systems that allow to render this type of geometry

pub fn register_component<'a, C: Component + Send>(&'a mut self) where     <<C as Component>::Storage as Storage<'a, C>>::Get: DebugParameter,

Register a component in the system

When using a new component that is not defined by mutiny but by your own application it's necesary to register it in the scene using this method

This version only accepts thread safe components (Send)

pub fn register_component_thread_local<'a, C: Component>(&'a mut self) where     <<C as Component>::Storage as Storage<'a, C>>::Get: DebugParameter,

Register a component in the system

When using a new component that is not defined by mutiny but by your own application it's necesary to register it in the scene using this method

Use this version when registering components that can't be sent accross threads

pub fn register<B: Bundle>(&mut self)

Register a mutiny Bundle

A Bundle usually register it's own components and systems

You can create your own bundles implementing the Bundle trait

pub fn add<'a, B: Builder<'a, World>>(     &'a mut self,     settings: <B as Builder<'a, World>>::Settings ) -> B

Add an element to the scene through it's Builder and settings

Some modules implement the Builder trait and specify a settings struct that allows to add them to the scene using this method.

For example to add load a blender file you can use:

scene.add::<mutiny::blender::Blender>()
    .load("file_path.blend")
    .unwrap();

pub fn add_model(&mut self, name: &str) -> ModelBuilder

Add a new model to the scene

This method returns a ModelBuilder that allows to set the geometry, transformation and other components of the model.

To add geometry and materials to the model they have to be registered in the scene first and the handle that we get when registering them is really what use to set that geometry or material to a model, instead of the geometry and material themselves

This allows renderers to optimize drawing by instancing models with the same geometry and to batch geometries with the same properties

pub fn add_empty(&mut self, name: &str) -> EmptyBuilder

Add an empty node to the scene

Other objects like models, lights... can be created as children of an empty

pub fn add_mesh<T>(&mut self, geom: Mesh<T>) -> GeometryRef where     T: 'static + VertexFormat + Send + Clone + Copy + Debug + Serialize + Deserialize<'static>,

Adds a mesh to the system and returns a handle to the geometry

The returned GeometryRef can be used as geometry for models.

pub fn add_named_mesh<T>(&mut self, geom: Mesh<T>, name: &str) -> GeometryRef where     T: 'static + VertexFormat + Send + Clone + Copy + Debug + Serialize + Deserialize<'static>,

Adds a mesh with a name to the system and returns a handle to the geometry

The returned GeometryRef can be used as geometry for models.

Names are mostly useful for debugging and not considered an ID of the model

pub fn add_directional_light<'a>(     &'a mut self,     name: &'a str ) -> DirectionalLightBuilder<'a, World>

Create a directional light

This method returns a builder object that allows to set different parameter in the light before creating it.

When done setting all the parameters call build on the builder to finally create the light

pub fn add_spot_light<'a>(     &'a mut self,     name: &'a str ) -> SpotLightBuilder<'a, World>

Create a spot light

This method returns a builder object that allows to set different parameter in the light before creating it.

When done setting all the parameters call build on the builder to finally create the light

pub fn add_point_light<'a>(     &'a mut self,     name: &'a str ) -> PointLightBuilder<'a, World>

Create a point light

This method returns a builder object that allows to set different parameter in the light before creating it.

When done setting all the parameters call build on the builder to finally create the light

pub fn add_image_based_light<'a>(     &'a mut self,     name: &'a str ) -> ImageBasedLightBuilder<'a, World>

Create an imaged based light

This method returns a builder object that allows to set different parameter in the light before creating it.

When done setting all the parameters call build on the builder to finally create the light

pub fn add_camera<C: CameraExt + Send + 'static>(&mut self, camera: C)

Add a camera to the scene

Right now there can only be one camera in the scene and adding a new one will replace the old one

pub fn add_bundle<B: Bundle>(&mut self, bundle: B)

Add a bundle to the scene

Adding a bundle adds all the systems of that bundle.

pub fn update_all_transformations(&mut self)

Manually update the full hierarchy of objects in the scene

pub fn register_material<M: Material + 'static>(     &mut self,     name: &str,     material: M ) -> MaterialRef

Register a new material

Takes ownership of the passed material and returns a handle to it that can be used to set it as a model material

pub fn find_material(&self, name: &str) -> Option<MaterialRef>

Find a material by name if it exists

pub fn register_texture(&mut self, texture: Texture) -> TextureRef

Register a texture to be used when setting up materials

pub fn register_texture_from_data_format<T: 'static>(     &mut self,     format: LoadDataFormat,     data: &[T] ) -> Result<TextureRef, Error>

Create a texture and register it from the image pixels and a format specification

pub fn register_image<I: Image>(&mut self, img: &I) -> Result<TextureRef, Error>

Create and register a texture from a loaded image

pub fn register_named_texture_from_data_format<T: 'static>(     &mut self,     name: &str,     format: LoadDataFormat,     data: &[T] ) -> Result<TextureRef, Error>

Create a texture and register it with a name from the image pixels and a format specification

pub fn register_named_image<I: Image>(     &mut self,     name: &str,     img: &I ) -> Result<TextureRef, Error>

Create and register a texture with a name from a loaded image

pub fn register_sampler(&mut self, sampler: Sampler) -> SamplerRef

Register a texture sampler (a texture + parameters of how it has to be used)

pub fn register_named_sampler(     &mut self,     name: &str,     sampler: Sampler ) -> SamplerRef

Register a texture sampler with a name (a texture + parameters of how it has to be used)

pub fn find_texture(&self, name: &str) -> Option<TextureRef>

Find a texture by it's name

pub fn add_renderer_systems(&mut self)

Create the renderer systems

Call this method after all the methods that might update geometry, transformations...

Usually after every other system and bundle but some systems like postprocessing might need to be inserted after the renderer

pub fn run_once(&mut self)

Run all the systems once

pub fn run_single_threaded(&mut self)

Run all the systems once without using multiple threads

pub fn run_multi_threaded(&mut self)

Run all the systems once in parallel when possible

pub fn resources(&self) -> Resources

Return the world resources

pub fn remove_resource<T: 'static>(&mut self) -> Option<T>

Remove a resource

pub fn add_resource<T: Send + 'static>(&mut self, resource: T)

Add a new resource

pub fn add_resource_thread_local<T: 'static>(&mut self, resource: T)

Add a new resource that can't be sent across threads

pub fn resource<T: 'static>(&self) -> Option<RwLockReadGuard<T>>

Returs a specific resource if it exists

pub fn resource_mut<T: 'static>(&self) -> Option<RwLockWriteGuard<T>>

Returs a specific resource for mutable access if it exists

pub fn resources_thread_local(&self) -> ResourcesThreadLocal

Returs a specific resource that can't be sent across threads if it exists

pub fn creation_proxy(&mut self) -> CreationProxy

pub fn add_system<S>(&mut self, system: S) -> &mut World where     S: System<'a> + 'static,

Adds a Send System that will be run in the order it was added.

Send systems will run in parallel with other Send systems and with thread local systems added in between barriers.

pub fn add_system_thread_local<S>(&mut self, system: S) -> &mut World where     S: SystemThreadLocal<'a> + 'static,

Adds a non Send System that will be run in the order it was added.

SystemThreadLocal will always run in the main thread but can run in parallel with Send systems.

pub fn add_creation_system<S>(&mut self, system: S) -> &mut World where     S: for<'a> CreationSystem<'a> + 'static,

Adds a CreationSystem that will be run in the order it was added.

CreationSystems run alone with no other system running in parallel.

pub fn add_debug_system<S>(&mut self, system: S) -> &mut World where     S: for<'a> SystemDebug<'a> + 'static,

Adds a SystemDebug that will be run in the order it was added.

SystemDebug run alone with no other system running in parallel.

pub fn add_system_with_name<S>(&mut self, system: S, name: &str) -> &mut World where     S: System<'a> + 'static,

Adds a Send System with a custom name.

Useful mostly when stats are enabeld. Only systems with name will show up in stats.

Send systems will run in parallel with other Send systems and with thread local systems added in between barriers.

pub fn add_system_with_name_thread_local<S>(     &mut self,     system: S,     name: &str ) -> &mut World where     S: SystemThreadLocal<'a> + 'static,

Adds a SystemThreadLocal with a custom name.

Useful mostly when stats are enabeld. Only systems with name will show up in stats.

SystemThreadLocal will always run in the main thread but can run in parallel with Send systems.

pub fn add_system_with_name_thread_local_gpu<S>(     &mut self,     system: S,     name: &str ) -> &mut World where     S: SystemThreadLocal<'a> + 'static,

Adds a SystemThreadLocal with a custom name.

Useful mostly when stats are enabeld. Only systems with name will show up in stats.

This system will have both cpu and gpu stats

SystemThreadLocal will always run in the main thread but can run in parallel with Send systems.

pub fn add_creation_system_with_name<S>(     &mut self,     system: S,     name: &str ) -> &mut World where     S: CreationSystem<'a> + 'static,

Adds a CreationSystem with a custom name.

Useful mostly when stats are enabeld. Only systems with name will show up in stats.

CreationSystems run alone with no other system running in parallel.

pub fn add_debug_system_with_name<S>(     &mut self,     system: S,     name: &str ) -> &mut World where     S: for<'a> SystemDebug<'a> + 'static,

Adds a SystemDebug with a custom name and data that will be passed to the system as first parameter.

Useful mostly when stats are enabeld. Only systems with name will show up in stats.

SystemDebug run alone with no other system running in parallel.

pub fn add_barrier(&mut self) -> &mut World

Delimits all the systems that will run in parallel.

Only systems between barriers (or creation and debug systems) will run in parallel with each other.

Barriers allow to create groups of systems that run in parallel including thread local systems that run one by one in the main thread but in parallel with Send systems.

pub fn add_component_to<C: ComponentSend>(     &mut self,     entity: &Entity,     component: C )

Adds a Send Component to an already existing Entity.

pub fn add_component_to_thread_local<C: ComponentThreadLocal>(     &mut self,     entity: &Entity,     component: C )

Adds a non Send Component to an already existing Entity.

pub fn add_slice_component_to<C, I>(&mut self, entity: &Entity, component: I) where     C: OneToNComponentSend,     <C as Component>::Storage: OneToNStorage<'a, C>,     I: IntoIterator<Item = C>,

Adds a Send OneToNComponent to an already existing Entity.

This allows to add a slice of components to an entity instead of only one component. This components are stored contiguously in memory for all the entities.

pub fn add_slice_component_to_thread_local<C, I>(     &mut self,     entity: &Entity,     component: I ) where     C: OneToNComponentThreadLocal,     <C as Component>::Storage: OneToNStorage<'a, C>,     I: IntoIterator<Item = C>,

Adds a non Send OneToNComponent to an already existing Entity.

This allows to add a slice of components to an entity instead of only one component. This components are stored contiguously in memory for all the entities.

pub fn remove_component_from<C: Component>(&mut self, entity: &Entity)

Removes a compoenent of the specified type from an entity.

pub fn remove_entity(&mut self, entity: &Entity)

Removes an Entity and all it's compoenents.

pub fn entities(&self) -> Entities

Returns an Entities object that allows to iterate over all the Send components of entities in this world.

pub fn entities_thread_local(&self) -> EntitiesThreadLocal

Returns an EntitiesThreadLocal object that allows to iterate over all the Send and non Send components of entities in this world.

pub fn component_for<C: Component>(&self, entity: &Entity) -> Option<Ptr<C>>

Returns a component for reading for the passed entity

let e1 = world.new_entity()
    .add(Position{x: 0., y: 0.})
    .build();
let entities = world.entities();
let pos = entities.component_for::<Position>(&e1).unwrap();

pub fn component_for_mut<C: Component>(     &self,     entity: &Entity ) -> Option<PtrMut<C>>

Returns a component for writing for the passed entity

let e1 = world.new_entity()
    .add(Position{x: 0., y: 0.})
    .build();
let entities = world.entities();
let mut pos = entities.component_for_mut::<Position>(&e1).unwrap();

pub fn stats(     &mut self ) -> impl Iterator<Item = (&str, Property<'static, Duration>)>

Returns an iterator over all the statistics of the running systems.

This properties can be added to for example a gui to monitor the running times for each system.

pub fn gpu_stats<'g, C>(     &'g mut self,     gl: &'g C ) -> impl Iterator<Item = (&str, Property<'static, Duration>)> + 'g where     C: CreationContext,

Returns an iterator over all the gpu statistics of the running systems.

This properties can be added to for example a gui to monitor the running times for each system.

pub fn enabled_systems(     &mut self ) -> impl Iterator<Item = (&str, Property<'static, bool>)>

Returns an iterator over all the enable system properties.

This properties allow to enable and disable individual systems at run time from for example a gui.

Trait Implementations

impl CreationContext for Scene

fn iter_for<'e, S: UnorderedDataLocal<'e> + 'e>(     &'e self ) -> <S as UnorderedDataLocal<'e>>::Iter

Iterator over all the components that match the operator

fn ordered_iter_for<'e, S: OrderedDataLocal<'e> + 'e>(     &'e self ) -> <S as OrderedDataLocal<'e>>::Iter

Iterator over ordered data

fn iter_for_entities<'e, S, E>(     &'e self,     entities: E ) -> <S as EntitiesDataLocal<'e, E>>::Iter where     S: UnorderedDataLocal<'e> + 'e,     E: IntoIterator<Item = Entity>,

Iterator for the specified operators over a set of entities instead of every entity in the world

fn entity_components<'e, S>(     &'e self,     entity: &Entity ) -> Option<<S as EntitiesComponentsLocal<'e>>::Components> where     S: UnorderedDataLocal<'e> + 'e,

Similar to iter_for_entities but for one entity instead of several

fn component_for<C: Component>(&self, entity: &Entity) -> Option<Ptr<C>>

Returns a component for reading for the passed entity

fn component_for_mut<C: Component>(&self, entity: &Entity) -> Option<PtrMut<C>>

Returns a component for writing for the passed entity

fn tree_node_for<'e, C: Component>(     &'e self,     entity: &Entity ) -> Option<NodePtr<'e, C>> where     <C as Component>::Storage: HierarchicalStorage<'e, C>,

Returns the node for a hierarchical component

fn tree_node_for_mut<'e, C: Component>(     &'e self,     entity: &Entity ) -> Option<NodePtrMut<'e, C>> where     <C as Component>::Storage: HierarchicalStorage<'e, C>,

Returns the node for a hierarchical component for writing

fn new_entity(&mut self) -> EntityBuilder

Returns an EntityBuilder that allows to create an entity and it's components.

fn add_component_to<C: ComponentSend>(&mut self, entity: &Entity, component: C)

Adds a Send Component to an already existing Entity.

fn add_component_to_thread_local<C: ComponentThreadLocal>(     &mut self,     entity: &Entity,     component: C )

Adds a non Send Component to an already existing Entity.

fn add_slice_component_to<C, I>(&mut self, entity: &Entity, component: I) where     C: OneToNComponentSend,     <C as Component>::Storage: OneToNStorage<'b, C>,     I: IntoIterator<Item = C>,

Adds a Send OneToNComponent to an already existing Entity.

fn add_slice_component_to_thread_local<C, I>(     &mut self,     entity: &Entity,     component: I ) where     C: OneToNComponentThreadLocal,     <C as Component>::Storage: OneToNStorage<'b, C>,     I: IntoIterator<Item = C>,

Adds a non Send OneToNComponent to an already existing Entity.

fn remove_component_from<C: Component>(&mut self, entity: &Entity)

Removes a compoenent of the specified type from an entity.

fn remove_entity(&mut self, entity: &Entity)

Removes an Entity and all it's compoenents.

fn resource<T: 'static>(&self) -> Option<RwLockReadGuard<T>>

Returns a resource of the specified type if it exists for reading.

fn resource_mut<T: 'static>(&self) -> Option<RwLockWriteGuard<T>>

Returns a resource of the specified type if it exists for writing.

fn add_resource<T: 'static + Send>(&mut self, resource: T)

Adds a Send resource to the world.

fn add_resource_thread_local<T: 'static>(&mut self, resource: T)

Adds a non Send resource to the world.

fn remove_resource<T: 'static>(&mut self) -> Option<T>

Removes a resource of the specified type.

fn register<'e, T: ComponentSend>(&'e mut self) where     <<T as Component>::Storage as Storage<'e, T>>::Get: DebugParameter,

fn register_thread_local<'e, T: ComponentThreadLocal>(&'e mut self) where     <<T as Component>::Storage as Storage<'e, T>>::Get: DebugParameter,