From 6763c0ad204fd49b388878de63b4b8d689468df2 Mon Sep 17 00:00:00 2001 From: IceSentry Date: Thu, 29 Jul 2021 01:28:24 -0400 Subject: [PATCH] #1934 WIP . --- crates/bevy_ecs/src/component.rs | 2 ++ crates/bevy_ecs/src/event.rs | 10 ++++++++++ crates/bevy_ecs/src/query/filter.rs | 6 ++++++ crates/bevy_input/src/keyboard.rs | 1 + crates/bevy_math/src/geometry.rs | 2 ++ crates/bevy_pbr/src/entity.rs | 2 ++ crates/bevy_pbr/src/light.rs | 1 + crates/bevy_pbr/src/material.rs | 1 + crates/bevy_render/src/entity.rs | 6 ++++++ crates/bevy_render/src/render_graph/base.rs | 3 +++ examples/README.md | 10 ++++++++++ 11 files changed, 44 insertions(+) diff --git a/crates/bevy_ecs/src/component.rs b/crates/bevy_ecs/src/component.rs index 6e71a1a7d93280..9c14f436964acf 100644 --- a/crates/bevy_ecs/src/component.rs +++ b/crates/bevy_ecs/src/component.rs @@ -35,6 +35,8 @@ impl Component for T {} /// let mut world = World::default(); /// world.register_component(ComponentDescriptor::new::(StorageType::SparseSet)); /// ``` +/// +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/component_storage.rs) #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub enum StorageType { /// Provides fast and cache-friendly iteration, but slower addition and removal of components. diff --git a/crates/bevy_ecs/src/event.rs b/crates/bevy_ecs/src/event.rs index f088b27f1060a7..a6a1ce6c72553a 100644 --- a/crates/bevy_ecs/src/event.rs +++ b/crates/bevy_ecs/src/event.rs @@ -118,6 +118,8 @@ enum State { /// but can be done by adding your event as a resource instead of using [`App::add_event`]. /// /// [`App::add_event`]: https://docs.rs/bevy/*/bevy/app/struct.App.html#method.add_event +/// +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/events.rs) #[derive(Debug)] pub struct Events { events_a: Vec>, @@ -150,6 +152,10 @@ fn map_instance_event(event_instance: &EventInstance) -> &T { } /// Reads events of type `T` in order and tracks which events have already been read. +/// +/// [Simple example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/event.rs) +/// +/// [Detailed example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/events.rs) #[derive(SystemParam)] pub struct EventReader<'w, 's, T: Component> { last_event_count: Local<'s, (usize, PhantomData)>, @@ -157,6 +163,10 @@ pub struct EventReader<'w, 's, T: Component> { } /// Sends events of type `T`. +/// +/// [Simple example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/event.rs) +/// +/// [Detailed example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/events.rs) #[derive(SystemParam)] pub struct EventWriter<'w, 's, T: Component> { events: ResMut<'w, Events>, diff --git a/crates/bevy_ecs/src/query/filter.rs b/crates/bevy_ecs/src/query/filter.rs index 69dd298cd31e00..dc05da5078160f 100644 --- a/crates/bevy_ecs/src/query/filter.rs +++ b/crates/bevy_ecs/src/query/filter.rs @@ -612,6 +612,8 @@ impl_tick_filter!( /// /// # print_add_name_component.system(); /// ``` + /// + /// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/change_detection.rs) Added, /// The [`FetchState`] of [`Added`]. AddedState, @@ -653,6 +655,10 @@ impl_tick_filter!( /// /// # print_moving_objects_system.system(); /// ``` + /// + /// [Simple example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/component_change_detection.rs) + /// + /// [Detailed example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/change_detection.rs) Changed, /// The [`FetchState`] of [`Changed`]. ChangedState, diff --git a/crates/bevy_input/src/keyboard.rs b/crates/bevy_input/src/keyboard.rs index 0d5bdb89f39037..c58a0b3fe29d63 100644 --- a/crates/bevy_input/src/keyboard.rs +++ b/crates/bevy_input/src/keyboard.rs @@ -3,6 +3,7 @@ use bevy_app::EventReader; use bevy_ecs::system::ResMut; /// A key input event from a keyboard device +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/input/keyboard_input_event.rs) #[derive(Debug, Clone)] pub struct KeyboardInput { pub scan_code: u32, diff --git a/crates/bevy_math/src/geometry.rs b/crates/bevy_math/src/geometry.rs index 0a449e5d026f9f..83bfe099b13191 100644 --- a/crates/bevy_math/src/geometry.rs +++ b/crates/bevy_math/src/geometry.rs @@ -3,6 +3,7 @@ use glam::Vec2; use std::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Sub, SubAssign}; /// A two dimensional "size" as defined by a width and height +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ui/ui.rs) #[derive(Copy, Clone, PartialEq, Debug, Reflect)] #[reflect(PartialEq)] pub struct Size { @@ -26,6 +27,7 @@ impl Default for Size { } /// A rect, as defined by its "side" locations +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ui/ui.rs) #[derive(Copy, Clone, PartialEq, Debug, Reflect)] #[reflect(PartialEq)] pub struct Rect { diff --git a/crates/bevy_pbr/src/entity.rs b/crates/bevy_pbr/src/entity.rs index 9b1d3c63147434..7c6d740b266cce 100644 --- a/crates/bevy_pbr/src/entity.rs +++ b/crates/bevy_pbr/src/entity.rs @@ -11,6 +11,7 @@ use bevy_render::{ use bevy_transform::prelude::{GlobalTransform, Transform}; /// A component bundle for "pbr mesh" entities +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/pbr.rs) #[derive(Bundle)] pub struct PbrBundle { pub mesh: Handle, @@ -41,6 +42,7 @@ impl Default for PbrBundle { } /// A component bundle for "light" entities +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/pbr.rs) #[derive(Debug, Bundle, Default)] pub struct PointLightBundle { pub point_light: PointLight, diff --git a/crates/bevy_pbr/src/light.rs b/crates/bevy_pbr/src/light.rs index 343bb6888f38dd..6329c2ec2a1ff2 100644 --- a/crates/bevy_pbr/src/light.rs +++ b/crates/bevy_pbr/src/light.rs @@ -153,6 +153,7 @@ impl DirectionalLightUniform { } // Ambient light color. +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/load_gltf.rs) #[derive(Debug)] pub struct AmbientLight { pub color: Color, diff --git a/crates/bevy_pbr/src/material.rs b/crates/bevy_pbr/src/material.rs index 73c1f80ac6a4e2..925ea265453025 100644 --- a/crates/bevy_pbr/src/material.rs +++ b/crates/bevy_pbr/src/material.rs @@ -4,6 +4,7 @@ use bevy_render::{color::Color, renderer::RenderResources, shader::ShaderDefs, t /// A material with "standard" properties used in PBR lighting /// Standard property values with pictures here https://google.github.io/filament/Material%20Properties.pdf +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/texture.rs) #[derive(Debug, RenderResources, ShaderDefs, TypeUuid)] #[uuid = "dace545e-4bc6-4595-a79d-c224fc694975"] pub struct StandardMaterial { diff --git a/crates/bevy_render/src/entity.rs b/crates/bevy_render/src/entity.rs index 7c6d4df1a93f0e..a3cd49522f89fd 100644 --- a/crates/bevy_render/src/entity.rs +++ b/crates/bevy_render/src/entity.rs @@ -14,6 +14,7 @@ use bevy_ecs::bundle::Bundle; use bevy_transform::components::{GlobalTransform, Transform}; /// A component bundle for "mesh" entities +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/shader/array_texture.rs) #[derive(Bundle, Default)] pub struct MeshBundle { pub mesh: Handle, @@ -28,6 +29,7 @@ pub struct MeshBundle { /// Component bundle for camera entities with perspective projection /// /// Use this for 3D rendering. +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/3d_scene.rs) #[derive(Bundle)] pub struct PerspectiveCameraBundle { pub camera: Camera, @@ -74,6 +76,8 @@ impl Default for PerspectiveCameraBundle { /// Component bundle for camera entities with orthographic projection /// /// Use this for 2D games, isometric games, CAD-like 3D views. +/// [Example usage in 2D.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/orthographic.rs) +/// [Example usage in 3D.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/orthographic.rs) #[derive(Bundle)] pub struct OrthographicCameraBundle { pub camera: Camera, @@ -84,6 +88,7 @@ pub struct OrthographicCameraBundle { } impl OrthographicCameraBundle { + /// [Example usage](https://github.com/bevyengine/bevy/blob/latest/examples/2d/sprite.rs) pub fn new_2d() -> Self { // we want 0 to be "closest" and +far to be "farthest" in 2d, so we offset // the camera's translation by far and use a right handed coordinate system @@ -104,6 +109,7 @@ impl OrthographicCameraBundle { } } + /// [Example usage](https://github.com/bevyengine/bevy/blob/latest/examples/3d/orthographic.rs) pub fn new_3d() -> Self { OrthographicCameraBundle { camera: Camera { diff --git a/crates/bevy_render/src/render_graph/base.rs b/crates/bevy_render/src/render_graph/base.rs index 6937c5b0a228a9..3b19e615fcb9e9 100644 --- a/crates/bevy_render/src/render_graph/base.rs +++ b/crates/bevy_render/src/render_graph/base.rs @@ -15,10 +15,12 @@ use bevy_reflect::Reflect; use bevy_window::WindowId; /// A component that indicates that an entity should be drawn in the "main pass" +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/window/multiple_windows.rs) #[derive(Clone, Debug, Default, Reflect)] #[reflect(Component)] pub struct MainPass; +/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/msaa.rs) #[derive(Debug)] pub struct Msaa { pub samples: u32, @@ -31,6 +33,7 @@ impl Default for Msaa { } impl Msaa { + /// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/window/multiple_windows.rs) pub fn color_attachment( &self, attachment: TextureAttachment, diff --git a/examples/README.md b/examples/README.md index 7796afdb162237..dd558fb508bb7d 100644 --- a/examples/README.md +++ b/examples/README.md @@ -45,6 +45,7 @@ git checkout v0.4.0 - [Audio](#audio) - [Diagnostics](#diagnostics) - [ECS (Entity Component System)](#ecs-entity-component-system) + - [Examples inside bevy_ecs sub-crate](#examples-inside-bevy_ecs-sub-crate) - [Games](#games) - [Input](#input) - [Reflection](#reflection) @@ -170,6 +171,15 @@ Example | File | Description `system_sets` | [`ecs/system_sets.rs`](./ecs/system_sets.rs) | Shows `SystemSet` use along with run criterion `timers` | [`ecs/timers.rs`](./ecs/timers.rs) | Illustrates ticking `Timer` resources inside systems and handling their state +## Examples inside bevy_ecs sub-crate + +Example | File | Description +--- | --- | --- +`change_detection` | [`crates/bevy_ecs/examples/change_detecion.rs`](../crates/bevy_ecs/examples/change_detecion.rs) | Detailed example of change detection +`component_storage` | [`crates/bevy_ecs/examples/component_storage.rs`](../crates/bevy_ecs/examples/component_storage.rs) | Detailed example of different storage mechanisms +`events` | [`crates/bevy_ecs/examples/events.rs`](../crates/bevy_ecs/examples/events.rs) | Illustrates event creation, activation, and reception +`resources` | [`crates/bevy_ecs/examples/resources.rs`](../crates/bevy_ecs/examples/resources.rs) | Detailed example of resource creation and usage + ## Games Example | File | Description