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

/*!
 * Mutiny is part of the rin ecosystem of rust crates for creative expression with code.
 *
 * ## Install
 *
 * Mutiny follows the same <a href="https://rin.rs/download.html" target="_blank">install instructions</a>
 * as rin. Just follow those to get everything you need to work with Mutiny installed.
 *
 * Once you have cargo rin installed you can create a new mutiny project by running:
 *
 * ```sh
 * cargo rin new --mutiny project_path
 * ```
 *
 * ## Introduction
 *
 * Mutiny is based on ideas of ECS (Entity Component System) or data driven programming. This
 * programming paradigm helps solving some problems of OO mostly when working with bigger
 * applications
 *
 * ## What is ECS?
 *
 * ECS, stands for Entity Component System. In an ECS application, there's three types of elements:
 *
 * ### Entities
 *
 * Entities are just ids that identify an object. An entity is just a number that identifies every
 * object in the world like models, lights, characters, a player in a game...
 *
 * An entity has no data but it has data associated to it which are it's components. Usually we
 * don't work directly with entities but with the components associated to them
 *
 * ### Components
 *
 * A component is the raw data for one specific aspect of an object. For example a component can be
 * the transformation of an object (it's position, orientation and scale), it's material, it's
 * geometry, it's velociy or any other piece of data associated with specific entities.
 *
 * ### Systems
 *
 * A system is the logic of the application. A system usually operates over a few components to
 * update them while the application is running. For example a system might update the position of
 * all the objects that have a velocity, to add the velocity to the position. Another system might be
 * resposible for detecting collisions and another one might render all the geometries with a
 * material and transformation.
 *
 * Systems run repeatedly every frame and many systems might run in parallel if we specify so.
 *
 * Mutiny uses rinecs as the basis of it's ECS architecture so rinecs documentation is surely useful
 * to look into to fully understand the most advanced concepts when developing your own systems.
 *
 * To show an example, let supppose we want to create an application that moves a sphere accross the
 * screen with a certain velocity.
 *
 * First we'll need to create the model for this sphere. Let's use a simple material that requires
 * no lights:
 *
 * ```
 * #[derive(Component, Debug, Serialize, Deserialize)]
 * struct Velocity(pub Vec3);
 *
 * fn register_components(scene: &mut mutiny::Scene) {
 *      scene.register_component::<Velocity>();
 * }
 *
 * fn create_entities(scene: &mut mutiny::Scene) {
 *      let sphere = rin::graphics::sphere(1., 20, 20);
 *      let sphere = scene.add_mesh(sphere);
 *
 *      let material = mutiny::material::basic_material::Builder::new()
 *          .color(RED)
 *          .build();
 *      let material = scene.register_material("material", material);
 *
 *      scene.add_model("sphere")
 *          .geometry(sphere)
 *          .material(material)
 *          .transformation(pnt3(0., 0., 0.))
 *          .add(Velocity(vec3!(1., 0., 0.)))
 *          .build();
 * }
 * ```
 *
 * If we run the application with the default template created by `cargo rin new --mutiny` we'll get
 * a sphere in the center of the screen.
 *
 * Once we add our geometry to the scene Mutiny will draw it for us optimizing for performance.
 * There's no need to do explicit draw calls.
 *
 * Let's see how to move the sphere. In order to modify the data in the scene we need to use systems.
 *
 * In the example above when creating our sphere we've added an element of type Velocity. This is a
 * custom type that we've created so mutiny won't recognize or do anything with it but we'll use it from
 * our system to update the position of our sphere or really any other object that we added that had
 * both a transformation and a velocity:
 *
 * ```
 * use rinecs::{Entities, Resources, Read, Write, Component};
 * use mutiny::time::Clock;
 * use mutiny::transformation::Transformation;
 *
 * fn update_position_system(entities: Entities, resources: Resources) {
 *      let elapsed = resources.get::<Clock>()
 *          .unwrap()
 *          .last_frame_time()
 *          .elapsed_game_time()
 *          .as_seconds() as f32;
 *      let iter = entities.iter_for::<(Write<Transformation>, Read<Velocity>)>();
 *      for (mut trafo, vel) in iter {
 *          let mut pos = trafo.position();
 *          pos += vel.0 * elapsed;
 *          trafo.set_position(pos);
 *      }
 * }
 *
 * fn setup_systems_and_bundles(scene: &mut mutiny::Scene) {
 *     scene.add_bundle(mutiny::Time);
 *     scene.add_system_with_name(update_position_system, "update pos from vel");
 *     scene.add_barrier();
 *     scene.add_system_with_name(mutiny::transformation::update_all, "update transformations");
 *     scene.add_renderer_systems();
 *     scene.add_system_with_name_thread_local(mutiny::time::fps_renderer, "draw fps");
 * }
 * ```
 *
 * The first function is our system. First it recovers the current frame delta in seconds from the
 * global clock in the system, then it iterates over every object in the scene that has both a
 * transformation and a velocity and adds the velocity multiplied by the delta to the position.
 *
 * The second function is the standard setup systems function we get from the template when creating
 * a new mutiny application but we've added our new system to the scene. Because we add our system
 * with a name if the stats and gui features are enabled when compiling we can later see how long
 * it takes for our system to run every frame on the cpu stats tab in the gui.
 *
 * If we run now the application we'll see how the ball moves to the right.
 *
 * We can begin to see here some of the differences of ECS or data driven programming with OO programming
 * while using object oriented programming each object would usually have been responsible for
 * updating it's own position from it's velocity, in ECS a system is responsible for updating all the
 * object's positions from their velocity no matter what kind of objects they are.
 *
 * This has several advantages. For one we are reusing the same code very easily to update position
 * from velocity. If we now create a cube or a car or a character that have a transformation and a
 * velocity they'll all behave the same without having to write any additional code. Also all
 * positions and all velocities are contiguous in memory not in objects scattered around which
 * makes it much faster to access them.
 *
 */
#![cfg_attr(feature="async", feature(async_closure))]

#[cfg(all(feature="gl_forward_renderer", feature="gl_shader_source"))]
use proc_macro_hack::proc_macro_hack;

#[macro_export]
macro_rules! timed{
    ($descr: expr, $func: block) => (
        {
            use std::time;
            let then = time::Instant::now();
            let ret = $func;
            let duration = time::Instant::now() - then;
            println!("{}: {} -> {} time: {}ms", file!(), line!(), $descr, duration.as_secs() as f32 * 1000. + duration.subsec_nanos()  as f32/1000000f32);
            ret
        }
    );
}

pub mod components;
#[cfg(feature = "gl_forward_renderer")]
pub mod renderer;
pub mod transformation;
pub mod scene;
pub mod geometry;
pub mod time;
#[cfg(all(feature="postprocessing", feature="gl_forward_renderer"))]
pub mod postprocessing;
#[cfg(gui)]
pub mod gui;
#[cfg(feature="blender")]
pub mod blender;
mod bundle;
pub mod physics;
pub mod light;
#[cfg(any(feature="web", feature="desktop", feature="desktop_gles"))]
pub mod events;
#[cfg(feature = "animation")]
pub mod animation;
#[cfg(feature = "materials")]
pub mod skybox;
#[cfg(all(feature = "materials", image_enabled))]
pub mod water;
#[cfg(all(feature = "gl", any(feature="desktop", feature="desktop_gles", feature="web")))]
pub mod immediate_renderer;

#[doc(inline)]
pub use self::bundle::{
    Bundle, UpdateSystem, UpdateSystemThreadLocal, EventsSystem, EventsSystemThreadLocal
};

#[doc(inline)]
pub use self::bundle::{render_stage, RenderStage, RendersTo};

#[cfg(any(feature="desktop", feature="desktop_gles", feature="web"))]
#[doc(inline)]
pub use self::bundle::RendererBundle;

#[doc(inline)]
pub use self::scene::{Scene, DeferredScene, CreationProxy, CreationContext, Builder};

#[cfg(any(feature="desktop", feature="desktop_gles", feature="web"))]
#[doc(inline)]
pub use self::scene::SceneBuilder;

#[doc(inline)]
pub use self::physics::Physics;
#[doc(inline)]
pub use self::transformation::{Camera, CameraParts};
#[cfg(any(feature="web", feature="desktop", feature="desktop_gles"))]
#[doc(inline)]
pub use self::events::EventsDispatcher;
pub use mutiny_derive::*;
#[cfg(all(feature="gl_forward_renderer", feature="gl_shader_source"))]
#[proc_macro_hack]
pub use mutiny_derive::{vertex_shader_source, fragment_shader_source};
#[cfg(all(feature = "gl", any(feature="desktop", feature="desktop_gles", feature="web")))]
pub use immediate_renderer::*;

pub const DEFAULT_EVENTS_PRIORITY: usize = 200;
pub struct BackgroundColor(pub color::Rgb<f32>);