Struct Renderer

Source

pub struct Renderer<'a> { /* private fields */ }

Expand description

The renderer for the Grafo library. This is the main struct that is used to render shapes, images, and text.

§Examples

use grafo::{FontFamily, Renderer};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;
use grafo::{TextAlignment, TextLayout};
use grafo::MathRect;
use wgpu::Surface;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use std::sync::Arc;
use futures::executor::block_on;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.
struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        // Add a rectangle shape
        let rect = Shape::rect(
            [(0.0, 0.0), (200.0, 100.0)],
            Color::rgb(0, 128, 255), // Blue fill
            Stroke::new(2.0, Color::BLACK), // Black stroke with width 2.0
        );
        renderer.add_shape(rect, None, (100.0, 100.0), None);

        // Add some text
        let layout = TextLayout {
            font_size: 24.0,
            line_height: 30.0,
            color: Color::rgb(255, 255, 255), // White text
            area: MathRect {
                min: (50.0, 50.0).into(),
                max: (400.0, 100.0).into(),
            },
            horizontal_alignment: TextAlignment::Center,
            vertical_alignment: TextAlignment::Center,
        };
        renderer.add_text("Hello, Grafo!", layout, FontFamily::SansSerif , None, 0);

        // Render the frame
        match renderer.render() {
            Ok(_) => println!("Frame rendered successfully."),
            Err(e) => eprintln!("Rendering error: {:?}", e),
        }

        // Clear the draw queue after rendering
        renderer.clear_draw_queue();
    }
    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {}
}

Implementations§

Source §

impl<'a> Renderer<'a>

Source

pub async fn new( window: impl Into<SurfaceTarget<'static>>, physical_size: (u32, u32), scale_factor: f64, vsync: bool, transparent: bool, ) -> Self

Creates a new Renderer instance.

§Parameters

window: The surface target (e.g., window) where rendering will occur.
physical_size: The physical size of the window in pixels.
scale_factor: The scale factor for high-DPI displays.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use grafo::Renderer;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.
struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));
    }
    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {}
}

Source

pub async fn new_transparent( window: impl Into<SurfaceTarget<'static>>, physical_size: (u32, u32), scale_factor: f64, vsync: bool, ) -> Self

Creates a new transparent Renderer instance.

This is a convenience method that calls Renderer::new with transparent set to true.

§Parameters

window: The window surface target to render to.
physical_size: The physical size of the rendering surface in pixels.
scale_factor: The DPI scale factor of the window.
vsync: Whether to enable vertical synchronization.

§Example

use futures::executor::block_on;
use std::sync::Arc;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::{Window, WindowAttributes};

struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_attributes = Window::default_attributes().with_transparent(true);
        let window = Arc::new(
            event_loop.create_window(window_attributes).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        let mut renderer = block_on(grafo::Renderer::new_transparent(
            window.clone(),
            physical_size,
            scale_factor,
            true
        ));
    }
    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {}
}

Source

pub fn add_shape( &mut self, shape: impl Into<Shape>, clip_to_shape: Option<usize>, offset: (f32, f32), cache_key: Option<u64>, ) -> usize

Adds a shape to the draw queue.

§Parameters

shape: The shape to be rendered. It can be any type that implements Into<Shape>. If you’re going to render a lot of shapes with the same outline, it is recommended to start shapes at 0.0, 0.0 where possible and use offset to move them on the screen. This way, it is going to be possible to cache tesselation results for such shapes, which would increase rendering time. This is useful if you render a lot of buttons with rounded corners, for example. Caching requires supplying a cache key to cache tessellated shape.
clip_to_shape: Optional index of another shape to which this shape should be clipped.
offset: Offset to render the shape at.
cache_key: A key that is going to be used for tesselation caching.

§Returns

The unique identifier (usize) assigned to the added shape.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::Renderer;
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.
struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        let shape_id = renderer.add_shape(
            Shape::rect(
                [(0.0, 100.0), (100.0, 100.0)],
                Color::rgb(0, 128, 255), // Blue fill
                Stroke::new(2.0, Color::BLACK), // Black stroke with width 2.0
            ),
            None,
            // Shift rectangle by 100.0, 100.0
            (100.0, 100.0),
            None
        );
    }
    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {}
}

Source

pub fn add_rgba_image( &mut self, texture_rgba_data: &[u8], physical_image_dimensions: (u32, u32), draw_at: [(f32, f32); 2], clip_to_shape: Option<usize>, )

Adds an image to the draw queue. This is a shorthand method if you quickly want to render an image from the main thread; If you want to update texture data from a different thread, or want more control over allocating and updating texture data in general, you should use Renderer::texture_manager.

§Parameters

image: A byte slice representing the image data.
physical_image_dimensions: A tuple representing the image’s width and height in pixels.
area: An array containing two tuples representing the top-left and bottom-right coordinates where the image should be rendered.
clip_to_shape: Optional index of a shape to which this image should be clipped.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::Renderer;
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.
struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        let image_data = vec![0; 16]; // A 2x2 black image
        renderer.add_rgba_image(
            &image_data,
            (2, 2), // Image dimensions
            [(50.0, 50.0), (150.0, 150.0)], // Rendering rectangle
            Some(0), // Clip to shape with ID 0
        );
    }
    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {}
}

Source

pub fn add_texture_draw_to_queue( &mut self, texture_id: u64, draw_at: [(f32, f32); 2], clip_to_shape: Option<usize>, )

Adds a texture to the draw queue. The texture must be loaded with the Renderer::texture_manager first.

Source

pub fn texture_manager(&self) -> &TextureManager

A texture manager is a helper to allow more granular approach to drawing images. It can be cloned and passed to a different thread if you want to update texture

Source

pub fn add_text( &mut self, text: &str, layout: impl Into<TextLayout>, font_family: FontFamily<'_>, clip_to_shape: Option<usize>, buffer_id: usize, )

Adds text to the draw queue. If you want to use a custom font, you need to load it first using the Renderer::load_fonts or Renderer::load_font_from_bytes methods.

§Parameters

text: The string of text to be rendered.
layout: The layout configuration for the text.
font_family: The font family to be used for rendering the text.
clip_to_shape: Optional index of a shape to which this text should be clipped.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::{FontFamily, MathRect, Renderer, TextAlignment, TextLayout};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.
struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        let layout = TextLayout {
            font_size: 24.0,
            line_height: 30.0,
            color: Color::rgb(255, 255, 255), // White text
            area: MathRect {
                min: (50.0, 50.0).into(),
                max: (400.0, 100.0).into(),
            },
            horizontal_alignment: TextAlignment::Center,
            vertical_alignment: TextAlignment::Center,
        };
        renderer.add_text("Hello, Grafo!", layout, FontFamily::SansSerif, None, 0);
    }
    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {}
}

Source

pub fn add_text_with_custom_font_system( &mut self, text: &str, layout: impl Into<TextLayout>, font_family: FontFamily<'_>, clip_to_shape: Option<usize>, font_system: &mut FontSystem, buffer_id: usize, )

Same as Renderer::add_text, but allows to use a custom font system

Source

pub fn add_text_buffer( &mut self, text_buffer: impl IntoCowBuffer<'a>, area: MathRect, fallback_color: Color, vertical_offset: f32, buffer_metadata: usize, clip_to_shape: Option<usize>, )

This method adds the text buffer to the draw queue. This is useful when you want to use the text buffer somewhere else, for example to detect clicks on the text.

§Parameters

text_buffer: Text buffer to be rendered.
area: Where to render the text.
fallback_color: Color used as a fallback color.
vertical_offset: Vertical offset from the top of the canvas where to start rendering the text.

§NOTE

It is very important to set the metadata of the text buffer to be equal to the id of the shape that is going to be used for clipping, if you want the text to be clipped by a shape.

Source

pub fn render(&mut self) -> Result<(), SurfaceError>

Renders all items currently in the draw queue.

This method processes the draw commands for shapes and images, tessellates them, prepares GPU buffers, and executes the rendering pipelines to produce the final frame.

§Errors

Returns a wgpu::SurfaceError if acquiring the next frame fails.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::{MathRect, Renderer, TextAlignment, TextLayout};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.
struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        // Add shapes, images, and text...

        // Render the frame
        if let Err(e) = renderer.render() {
            eprintln!("Rendering error: {:?}", e);
        }
    }
    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {}
}

Source

pub fn render_with_custom_font_system<'b>( &mut self, font_system: &mut FontSystem, swash_cache: &mut SwashCache, text_instances: Option<impl Iterator<Item = TextDrawData<'b>>>, ) -> Result<(), SurfaceError>

Source

pub fn prepare_text_buffers<'b>( &mut self, custom_text_instances_iter: Option<impl Iterator<Item = TextDrawData<'b>>>, custom_font_system: Option<&mut FontSystem>, custom_swash_cache: Option<&mut SwashCache>, )

Source

pub fn clear_draw_queue(&mut self)

Clears all items currently in the draw queue.

This method removes all shapes, images, and text instances from the draw queue, preparing the renderer for the next frame.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::{MathRect, Renderer, TextAlignment, TextLayout};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.

struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        // Add shapes, images, and text...

        // Clear the draw queue
        renderer.clear_draw_queue();
    }

    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {
        // Handle window events (stub for doc test)
    }
}

Source

pub fn size(&self) -> (u32, u32)

Retrieves the current size of the rendering surface.

§Returns

A tuple (u32, u32) representing the width and height of the window in pixels.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::{MathRect, Renderer, TextAlignment, TextLayout};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.

struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        let size = renderer.size();
        println!("Rendering surface size: {}x{}", size.0, size.1);
    }

    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {
        // Handle window events (stub for doc test)
    }
}

Source

pub fn change_scale_factor(&mut self, new_scale_factor: f64)

Changes the scale factor of the renderer (e.g., for DPI scaling).

This method updates the scale factor and resizes the renderer accordingly.

§Parameters

new_scale_factor: The new scale factor to apply.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::{MathRect, Renderer, TextAlignment, TextLayout};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.

struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        // Change the scale factor to 2.0 for high-DPI rendering
        renderer.change_scale_factor(2.0);
    }

    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {
        // Handle window events (stub for doc test)
    }
}

Source

pub fn scale_factor(&self) -> f64

Source

pub fn resize(&mut self, new_physical_size: (u32, u32))

Resizes the renderer to the specified physical size.

This method updates the renderer’s configuration to match the new window size, reconfigures the surface, and updates all relevant pipelines and bind groups.

§Parameters

new_physical_size: A tuple (u32, u32) representing the new width and height in pixels.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::{MathRect, Renderer, TextAlignment, TextLayout};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.

struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        // Resize the renderer to 1024x768 pixels
        renderer.resize((1024, 768));
    }

    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {
        // Handle window events (stub for doc test)
    }
}

Source

pub fn set_vsync(&mut self, vsync: bool)

Source

pub fn load_fonts(&mut self, fonts: impl Iterator<Item = Source>)

Loads fonts from the specified sources.

Loaded fonts can be later used to render text using the Renderer::add_text method.

§Parameters

fonts: An iterator of fontdb::Source objects representing the font sources to load.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::{MathRect, Renderer, TextAlignment, TextLayout};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;
use grafo::fontdb;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.

struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        let roboto_font_ttf = include_bytes!("../examples/assets/Roboto-Regular.ttf").to_vec();
        let roboto_font_source = fontdb::Source::Binary(Arc::new(roboto_font_ttf));
        renderer.load_fonts([roboto_font_source].into_iter());
    }

    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {
        // Handle window events (stub for doc test)
    }
}

Source

pub fn load_fonts_with_custom_font_system( &mut self, fonts: impl Iterator<Item = Source>, font_system: &mut FontSystem, )

Same as Renderer::load_fonts, but allows to use a custom font system.

Source

pub fn load_font_from_bytes(&mut self, font_bytes: &[u8])

Loads a font from a byte slice.

Loaded fonts can be later used to render text using the Renderer::add_text method.

§Parameters

font_bytes: A slice of bytes representing the font file.

§Examples

use std::sync::Arc;
use futures::executor::block_on;
use winit::application::ApplicationHandler;
use winit::event_loop::{ActiveEventLoop, EventLoop};
use winit::window::Window;
use grafo::{MathRect, Renderer, TextAlignment, TextLayout};
use grafo::Shape;
use grafo::Color;
use grafo::Stroke;
use grafo::fontdb;

// This is for demonstration purposes only. If you want a working example with winit, please
// refer to the example in the "examples" folder.

struct App;
impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_surface = Arc::new(
            event_loop.create_window(Window::default_attributes()).unwrap()
        );
        let physical_size = (800, 600);
        let scale_factor = 1.0;

        // Initialize the renderer
        let mut renderer = block_on(Renderer::new(window_surface, physical_size, scale_factor, true, false));

        let roboto_font_ttf = include_bytes!("../examples/assets/Roboto-Regular.ttf");
        renderer.load_font_from_bytes(roboto_font_ttf);
    }

    fn window_event(&mut self, _: &ActiveEventLoop, _: winit::window::WindowId, _: winit::event::WindowEvent) {
        // Handle window events (stub for doc test)
    }
}