Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-10 23:24:44 +00:00
Code Issues Projects Releases Packages Wiki Activity

Minor docs edit/add in bevy_render (#3447)

Browse source 
# Objective

Docs updates.

## Solution

- Detail what `OrthographicCameraBundle::new_2d()` creates.
- Fix a few renamed parameters in comments of `TrackedRenderPass`.
- Add missing comments for viewport and debug markers.

Co-authored-by: Jerome Humbert <djeedai@gmail.com>
This commit is contained in:
Jerome Humbert 2022-01-02 17:40:03 +00:00
parent 50b3f27a76
commit e43e36696d
2 changed files with 70 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
crates/bevy_render/src/camera/bundle.rs
View file

@ -75,6 +75,23 @@ pub struct OrthographicCameraBundle {
}
impl OrthographicCameraBundle {
/// Create an orthographic projection camera to render 2D content.
///
/// The projection creates a camera space where X points to the right of the screen,
/// Y points to the top of the screen, and Z points out of the screen (backward),
/// forming a right-handed coordinate system. The center of the screen is at `X=0` and
/// `Y=0`.
///
/// The default scaling mode is [`ScalingMode::WindowSize`], resulting in a resolution
/// where 1 unit in X and Y in camera space corresponds to 1 logical pixel on the screen.
/// That is, for a screen of 1920 pixels in width, the X coordinates visible on screen go
/// from `X=-960` to `X=+960` in world space, left to right. This can be changed by changing
/// the [`OrthographicProjection::scaling_mode`] field.
///
/// The camera is placed at `Z=+1000-0.1`, looking toward the world origin `(0,0,0)`.
/// Its orthographic projection extends from `0.0` to `-1000.0` in camera view space,
/// corresponding to `Z=+999.9` (closest to camera) to `Z=-0.1` (furthest away from
/// camera) in world space.
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

67
crates/bevy_render/src/render_phase/draw_state.rs
View file

@ -117,8 +117,7 @@ impl<'a> TrackedRenderPass<'a> {
}
/// Sets the active [`BindGroup`] for a given bind group index. The bind group layout in the
/// active pipeline when any `draw()` function is called must match the layout
/// of this `bind group`.
/// active pipeline when any `draw()` function is called must match the layout of this `bind group`.
pub fn set_bind_group(
&mut self,
index: usize,
@ -149,19 +148,19 @@ impl<'a> TrackedRenderPass<'a> {
/// Assign a vertex buffer to a slot.
///
/// Subsequent calls to [`TrackedRenderPass::draw`] and [`TrackedRenderPass::draw_indexed`]
/// will use the `buffer` as one of the source vertex buffers.
/// will use the buffer referenced by `buffer_slice` as one of the source vertex buffer(s).
///
/// The `slot` refers to the index of the matching descriptor in
/// The `slot_index` refers to the index of the matching descriptor in
/// [`VertexState::buffers`](crate::render_resource::VertexState::buffers).
pub fn set_vertex_buffer(&mut self, index: usize, buffer_slice: BufferSlice<'a>) {
pub fn set_vertex_buffer(&mut self, slot_index: usize, buffer_slice: BufferSlice<'a>) {
let offset = buffer_slice.offset();
if self
.state
.is_vertex_buffer_set(index, buffer_slice.id(), offset)
.is_vertex_buffer_set(slot_index, buffer_slice.id(), offset)
{
debug!(
"set vertex buffer {} (already set): {:?} ({})",
index,
slot_index,
buffer_slice.id(),
offset
);
@ -169,20 +168,21 @@ impl<'a> TrackedRenderPass<'a> {
} else {
debug!(
"set vertex buffer {}: {:?} ({})",
index,
slot_index,
buffer_slice.id(),
offset
);
}
self.pass.set_vertex_buffer(index as u32, *buffer_slice);
self.pass
.set_vertex_buffer(slot_index as u32, *buffer_slice);
self.state
.set_vertex_buffer(index, buffer_slice.id(), offset);
.set_vertex_buffer(slot_index, buffer_slice.id(), offset);
}
/// Sets the active index buffer.
///
/// Subsequent calls to [`TrackedRenderPass::draw_indexed`] will use the `buffer` as
/// the source index buffer.
/// Subsequent calls to [`TrackedRenderPass::draw_indexed`] will use the buffer referenced by
/// `buffer_slice` as the source index buffer.
pub fn set_index_buffer(
&mut self,
buffer_slice: BufferSlice<'a>,
@ -209,7 +209,7 @@ impl<'a> TrackedRenderPass<'a> {
/// Draws primitives from the active vertex buffer(s).
///
/// The active vertex buffers can be set with [`TrackedRenderPass::set_vertex_buffer`].
/// The active vertex buffer(s) can be set with [`TrackedRenderPass::set_vertex_buffer`].
pub fn draw(&mut self, vertices: Range<u32>, instances: Range<u32>) {
debug!("draw: {:?} {:?}", vertices, instances);
self.pass.draw(vertices, instances);
@ -218,7 +218,7 @@ impl<'a> TrackedRenderPass<'a> {
/// Draws indexed primitives using the active index buffer and the active vertex buffer(s).
///
/// The active index buffer can be set with [`TrackedRenderPass::set_index_buffer`], while the
/// active vertex buffers can be set with [`TrackedRenderPass::set_vertex_buffer`].
/// active vertex buffer(s) can be set with [`TrackedRenderPass::set_vertex_buffer`].
pub fn draw_indexed(&mut self, indices: Range<u32>, base_vertex: i32, instances: Range<u32>) {
debug!(
"draw indexed: {:?} {} {:?}",
@ -234,6 +234,7 @@ impl<'a> TrackedRenderPass<'a> {
}
/// Sets the scissor region.
///
/// Subsequent draw calls will discard any fragments that fall outside this region.
pub fn set_scissor_rect(&mut self, x: u32, y: u32, width: u32, height: u32) {
debug!("set_scissor_rect: {} {} {} {}", x, y, width, height);
@ -253,6 +254,9 @@ impl<'a> TrackedRenderPass<'a> {
self.pass.set_push_constants(stages, offset, data)
}
/// Set the rendering viewport.
///
/// Subsequent draw calls will be projected into that viewport.
pub fn set_viewport(
&mut self,
x: f32,
@ -270,16 +274,51 @@ impl<'a> TrackedRenderPass<'a> {
.set_viewport(x, y, width, height, min_depth, max_depth)
}
/// Insert a single debug marker.
///
/// This is a GPU debugging feature. This has no effect on the rendering itself.
pub fn insert_debug_marker(&mut self, label: &str) {
debug!("insert debug marker: {}", label);
self.pass.insert_debug_marker(label)
}
/// Start a new debug group.
///
/// Push a new debug group over the internal stack. Subsequent render commands and debug
/// markers are grouped into this new group, until [`pop_debug_group`] is called.
///
/// ```
/// # fn example(mut pass: bevy_render::render_phase::TrackedRenderPass<'static>) {
/// pass.push_debug_group("Render the car");
/// // [setup pipeline etc...]
/// pass.draw(0..64, 0..1);
/// pass.pop_debug_group();
/// # }
/// ```
///
/// Note that [`push_debug_group`] and [`pop_debug_group`] must always be called in pairs.
///
/// This is a GPU debugging feature. This has no effect on the rendering itself.
///
/// [`push_debug_group`]: TrackedRenderPass::push_debug_group
/// [`pop_debug_group`]: TrackedRenderPass::pop_debug_group
pub fn push_debug_group(&mut self, label: &str) {
debug!("push_debug_group marker: {}", label);
self.pass.push_debug_group(label)
}
/// End the current debug group.
///
/// Subsequent render commands and debug markers are not grouped anymore in
/// this group, but in the previous one (if any) or the default top-level one
/// if the debug group was the last one on the stack.
///
/// Note that [`push_debug_group`] and [`pop_debug_group`] must always be called in pairs.
///
/// This is a GPU debugging feature. This has no effect on the rendering itself.
///
/// [`push_debug_group`]: TrackedRenderPass::push_debug_group
/// [`pop_debug_group`]: TrackedRenderPass::pop_debug_group
pub fn pop_debug_group(&mut self) {
debug!("pop_debug_group");
self.pass.pop_debug_group()