khora_core/renderer/traits/
render_system.rs

1// Copyright 2025 eraflo
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use std::sync::Arc;
16
17use super::CommandEncoder;
18use crate::platform::window::KhoraWindow;
19use crate::renderer::api::{
20    core::{GraphicsAdapterInfo, RenderContext, RenderSettings, RenderStats},
21    resource::ViewInfo,
22    scene::RenderObject,
23};
24use crate::renderer::error::RenderError;
25use crate::renderer::GraphicsDevice;
26use crate::telemetry::ResourceMonitor;
27
28/// Type alias for the render encoder closure.
29pub type RenderEncoderFn<'a> = Box<dyn FnOnce(&mut dyn CommandEncoder, &RenderContext) + Send + 'a>;
30
31/// A high-level trait representing the entire rendering subsystem.
32///
33/// This trait defines the primary interface for the engine to interact with the renderer.
34/// A concrete implementation of `RenderSystem` (likely in `khora-infra`) encapsulates
35/// all the state and logic needed to render a frame, including device management,
36/// swapchain handling, and the execution of render pipelines.
37///
38/// This can be considered the main "contract" for a `RenderAgent` to manage.
39pub trait RenderSystem: std::fmt::Debug + Send + Sync {
40    /// Initializes the rendering system with a given window.
41    ///
42    /// This method sets up the graphics device, swapchain, and any other necessary
43    /// backend resources. It should be called once at application startup.
44    ///
45    /// # Returns
46    ///
47    /// On success, it returns a `Vec` of `ResourceMonitor` trait objects that the
48    /// telemetry system can use to track GPU-specific resources like VRAM.
49    fn init(
50        &mut self,
51        window: &dyn KhoraWindow,
52    ) -> Result<Vec<Arc<dyn ResourceMonitor>>, RenderError>;
53
54    /// Notifies the rendering system that the output window has been resized.
55    ///
56    /// The implementation should handle recreating the swapchain and any other
57    /// size-dependent resources (like depth textures).
58    fn resize(&mut self, new_width: u32, new_height: u32);
59
60    /// Prepares for a new frame.
61    ///
62    /// This is typically called once per frame before `render`. It can be used
63    /// to update internal resources, like uniform buffers, based on the camera's
64    /// `ViewInfo`.
65    fn prepare_frame(&mut self, view_info: &ViewInfo);
66
67    /// Renders a single frame using agent-driven encoding.
68    ///
69    /// This method acquires the frame, creates an encoder, calls the provided
70    /// closure to encode commands (typically from RenderAgent), and submits.
71    ///
72    /// # Arguments
73    ///
74    /// * `clear_color`: The color to clear the framebuffer with
75    /// * `encoder_fn`: A boxed closure that encodes GPU commands
76    ///
77    /// # Returns
78    ///
79    /// On success, it returns `RenderStats` with performance metrics for the frame.
80    fn render_with_encoder(
81        &mut self,
82        clear_color: crate::math::LinearRgba,
83        encoder_fn: RenderEncoderFn<'_>,
84    ) -> Result<RenderStats, RenderError>;
85
86    /// Renders a single frame.
87    ///
88    /// This is the main workload function, responsible for executing all necessary
89    /// render passes to draw the provided `renderables` to the screen.
90    ///
91    /// # Arguments
92    ///
93    /// * `renderables`: A slice of `RenderObject`s representing the scene to be drawn.
94    /// * `view_info`: Contains camera and projection information for the frame.
95    /// * `settings`: Contains global rendering settings for the frame.
96    ///
97    /// # Returns
98    ///
99    /// On success, it returns `RenderStats` with performance metrics for the frame.
100    fn render(
101        &mut self,
102        renderables: &[RenderObject],
103        view_info: &ViewInfo,
104        settings: &RenderSettings,
105    ) -> Result<RenderStats, RenderError>;
106
107    /// Returns a reference to the statistics of the last successfully rendered frame.
108    fn get_last_frame_stats(&self) -> &RenderStats;
109
110    /// Checks if a specific, optional rendering feature is supported by the backend.
111    fn supports_feature(&self, feature_name: &str) -> bool;
112
113    /// Returns information about the active graphics adapter (GPU).
114    fn get_adapter_info(&self) -> Option<GraphicsAdapterInfo>;
115
116    /// Returns a shared, thread-safe reference to the underlying `GraphicsDevice`.
117    ///
118    /// This allows other parts of the engine (e.g., the asset system) to create
119    /// graphics resources like buffers and textures on the correct GPU device.
120    fn graphics_device(&self) -> Arc<dyn GraphicsDevice>;
121
122    /// Cleans up and releases all graphics resources.
123    /// This should be called once at application shutdown.
124    fn shutdown(&mut self);
125
126    /// Allows downcasting to a concrete `RenderSystem` type.
127    fn as_any(&self) -> &dyn std::any::Any;
128}
khora_core/renderer/traits/render_system.rs

khora_core/renderer/traits/
render_system.rs
