Struct rin::gl::renderer::Renderer

#[must_use = "Calling with on a renderer doesn't change that renderer, it returns a new one with the properties applied. Instead of calling `gl.with(...)` do `let gl = gl.with(...)`"]
pub struct Renderer<'c, R = Screen> where
    R: 'c + RenderSurface,  { /* fields omitted */ }

Object needed to render any rin object using OpenGL

It also contains a GL context, using gling which initializes all the OpenGL function calls

The renderer contains a state and new copies with different states can be created using the different with* methods.

The Renderer state keeps track of the GL properties as well as the camera and model matrices so when a new Renderer is created using any of the with methods drawing with afterwards will apply that state to whatever is being drawn.

The state changes are done by generating a diff of the current state with the Renderer state so the calls as are less as possible but grouping all the calls that use the same renderer is always a good idea since it reduces the number of state changes.

let gl = gl::Renderer::new(&mut window);
let gl_depth = gl.with_properties(&[gl::Property::DepthTest(true)]);

// draw without depth test:
gl.draw(&something);

// draw with depth test:
gl_depth.draw(&something);

Implementations

impl<'c> Renderer<'c, Screen>

pub fn new<W>(window: &'w mut W) -> Result<Renderer<'static, Screen>, Error> where
    W: WindowExt + GlWindow, 

Creates a new renderer using a window that implments GLWindow so it can load the GL context using it

pub fn with_default_properties<W>(
    window: &'w mut W,
    default_properties: &[Property]
) -> Result<Renderer<'static, Screen>, Error> where
    W: WindowExt + GlWindow, 

Creates a new renderer with a set of default properties that will be applied over the GL defaults

pub unsafe fn reset_default_state(&mut self, state: State<'static>)

Sets the current state to the one passed as parameter.

Used to reset the current state, for example, after altering it doing external gl calls

impl<'c, R> Renderer<'c, R> where
    R: 'c + RenderSurface, 

pub fn resolution_factor(&self) -> f32

pub fn clear_color<C>(&self, color: &C) where
    C: ToRgba, 

Clear the color buffer with the specified color

pub fn clear_depth(&self, depth: f64)

Clear the depth buffer with the specified color

pub fn clear_stencil(&self, stencil: i32)

Clear the stencil buffer with the specified color

pub fn clear_all<C>(
    &self,
    color: Option<C>,
    depth: Option<f64>,
    stencil: Option<i32>
) where
    C: ToRgba, 

Optionally clear color, depth and stencil in one gl call

pub fn mvp(&self) -> &Mvp

Returns the current Mvp (Camera + Model matrices)

pub fn with_camera_viewport<C>(
    &self,
    camera: &C,
    viewport: &Rect<i32>
) -> Renderer<'_, R> where
    C: CameraExt + ?Sized, 

Create a copy of this renderer with new camera matrices using the passed camera and viewport

pub fn with_mvp<M>(&self, mvp: M) -> Renderer<'_, R> where
    M: Into<Mvp>, 

Create a copy of this renderer with a new Mvp (camera + model matrices)

pub fn with_model<M>(&self, model: M) -> Renderer<'_, R> where
    M: Into<Model>, 

Create a copy of this renderer with a new model matrix

The model parameter can be anything that can be converted into a model matrix like:

• a Pnt3
• a Node
• a Mat4
• a UnitQuat
• an Isometry2 or 3
• a Translation2 or 3
• a Rotation2 or 3

For example if we want to draw an object in 10, 10, 10 rotated 30 degrees along the z axis we could do:

let position = pnt3!(10.);
let angle = Deg(30.).to_rad().value();
let orientation = UnitQuat::from_axis_angle(Vec3::z_axis(), angle);
let node = Node::new(position, angle, one());
let gl = gl.with_model(&node);
gl.draw(&object);

or:

let position = pnt3!(10.);
let angle = Deg(30.).to_rad().value();
let orientation = UnitQuat::from_axis_angle(Vec3::z_axis(), angle);
let node = Isometry3::from_parts(position, angle);
let gl = gl.with_model(&node);
gl.draw(&object);

Model matrices don’t accumulate when calling with_model over an exisiting renderer, the new renderer just replaces the old model matrices so if you need to accumulate model transformations it has to be done outside the renderer by combining the transformations into one

pub fn with_properties<'a, P>(&self, properties: P) -> Renderer<'_, R> where
    P: IntoIterator<Item = &'a Property>, 

Creates a copy of this renderer with the current properties + the passed ones

See also Property for more info about available properties

pub fn with_model_matrices_as_attributes(&self) -> Renderer<'_, R>

Creates a new renderer which with a flag to upload model matrices as per instance vertex attributes instead of uniforms

This can speed up drawing by avoiding one upload per draw call and instead having the matrices in vaos as a per instance attribute

pub fn with_material<M>(
    &'m mut self,
    material: &'m M
) -> RendererWithMaterial<'m, R> where
    M: Material, 

pub fn id(&self) -> usize

Id of this renderer

Mostly used internally to differentiate resources created by each renderer since some resources can only be used with the renderer they where originally created with

pub fn context(&self) -> &Context<'c, R>

Returns the internal glin context for more advanced usages

pub fn context_mut(&mut self) -> &mut Context<'c, R>

Returns the internal glin context for more advanced usages

pub fn new_texture(&self) -> Builder<'_>

Creates a new texture

Returns a texture::Builder that allows to configure the texture creation further

pub fn new_cubemap(&self) -> Builder<'_>

Creates a new cubemap

Returns a cubemap::Builder that allows to configure the cubemap creation further

pub fn new_buffer(&self) -> Builder<'_>

Creates a new buffer in gpu memory

Returns a buffer::Builder that allows to configure the buffer creation further

pub fn new_shared_buffer(&self) -> SharedBuilder<'_>

Creates a new shared buffer in gpu memory

Returns a buffer::SharedBuilder that allows to configure the buffer creation further

Shared buffers are reference counted so they can be shared from several owners

pub fn new_vao(&self) -> Builder

Creates a new VAO

Returns a vao::Builder that allows to configure the vao creation further

pub fn new_simple_vao(&self) -> Builder<'_>

Creates a new SimpleVao

Returns a simple_vao::Builder that allows to configure the vao creation further

pub fn new_program(&self) -> Builder<'_>

Creates a new glsl program

Returns a program::Builder that allows to configure the program creation further

pub fn new_sampler(&self) -> Sampler

Creates a new texture sampler

Directly returns a Sampler that can be configured through it’s own methods

pub fn new_timestamp_query(&self) -> TimeStamp

Creates a new counter query

Directly returns a TimeStamp query

pub fn new_duration_query(&self) -> Duration

Creates a new counter query

Directly returns a Duration query

pub fn new_fence(&self) -> Fence

pub fn new_debug_group(&self, id: u32, message: &str) -> DebugGroup

pub fn new_ttf(&'a self, path: &'a str, pt_height: f32) -> Builder<'a>

Creates a new ttf font

Returns a ttf::Builder that allows to configure the font creation further

Requires a path and a font height in pt as mandatory arguments

pub fn new_ttf_from_bytes(
    &'a self,
    bytes: &'a [u8],
    pt_height: f32
) -> Builder<'a>

Creates a new ttf font

Returns a ttf::Builder that allows to configure the font creation further

Requires a memory buffer with the ttf definition and a font height in pt as mandatory arguments

pub fn new_ttf_material(&self, ttf: &'a Ttf) -> MaterialBuilder<'a>

Creates a ttf material from a font

Returns a ttf::MaterialBuilder that allows to configure the font material creation further.

pub fn new_vao_mesh(&self) -> Builder

Creates a new VaoMesh

Returns a vao_mesh::Builder that allows to configure the VaoMesh creation further

pub fn new_vao_path(&self) -> Builder

Creates a new VaoPath

Returns a vao_path::Builder that allows to configure the VaoPath creation further

pub fn new_auto_program<P>(
    &self,
    settings: ProgramSettings<P>
) -> AutoLoader<Program> where
    P: 'static + AsRef<Path> + Clone, 

Creates a glsl program that can reload itself when the source changes

Directly returns a AutoLoader from the passed settings.

The AutoLoader watches the filesystem for changes in the original source for the shaders including any possible includes and reloads the program if any of them changes

pub fn new_object(&self) -> Builder

Creates a new ringl Object

Returns an object::Builder that allows to configure the Object further

An object is just a gpu geometry, usually a VAO and a Node to represent it’s model transformation

pub fn to_simple_vao<T, U, M>(&self, mesh: &M) -> Result<SimpleVao<T>, Error> where
    M: ToSimpleVao<T, U>, 

Returns a SimpleVao from a Mesh

let mesh = rin::graphics::sphere(10., 20, 20);
let sphere_vao = gl.to_simple_vao(&mesh);

Allows to easily create a VAO, needed to draw any geometry, from a Mesh in RAM

pub fn to_simple_vao_bindings<T, U, M, B>(
    &self,
    mesh: &M,
    bindings: &B
) -> Result<SimpleVao<T>, Error> where
    B: Bindings,
    M: ToSimpleVao<T, U>, 

Returns a SimpleVao from a Mesh

let mesh = rin::graphics::sphere(10., 20, 20);
let sphere_vao = gl.to_simple_vao(&mesh);

Allows to easily create a VAO, needed to draw any geometry, from a Mesh in RAM

pub fn to_simple_vao_usage<T, U, M>(
    &self,
    mesh: &M,
    usage: u32,
    program: &Program
) -> Result<SimpleVao<T>, Error> where
    M: ToSimpleVao<T, U>, 

Returns a SimpleVao from a Mesh

let mesh = rin::graphics::sphere(10., 20, 20);
let sphere_vao = gl.to_simple_vao(&mesh);

Allows to easily create a VAO, needed to draw any geometry, from a Mesh in RAM

pub fn to_simple_vao_usage_bindings<T, U, M, B>(
    &self,
    mesh: &M,
    usage: u32,
    bindings: &B
) -> Result<SimpleVao<T>, Error> where
    B: Bindings,
    M: ToSimpleVao<T, U>, 

Returns a SimpleVao from a Mesh

let mesh = rin::graphics::sphere(10., 20, 20);
let sphere_vao = gl.to_simple_vao(&mesh);

Allows to easily create a VAO, needed to draw any geometry, from a Mesh in RAM

pub fn creation_proxy(&self) -> CreationProxy

Returns a creation proxy that can be stored to create new gl objects from anywhere without needing a full Renderer

pub fn model_matrices_as_attributes(&self) -> bool

Returns true if this renderer is set to use model matrices as attributes instead of uniforms.

Usually used by materials to setup the shaders accordingly

pub fn clear<C>(&self, color: &C) where
    C: ToRgba, 

Clears the color buffer with the passed color and the depth buffer with the defailt value

pub fn draw_mesh<T, U, M>(&self, mesh: &M) where
    T: VertexFormat + Clone + 'static,
    M: ToSimpleVao<T, U>, 

Draws a mesh using a VAO from the internal pool and a default basic material

The mesh parameter can be anything that implements the ToSimpleVao trait, by default a graphics::Mesh of any of the supported VertexFormats but also a tuple of (&[Vertex], PrimitiveType) or (&[Vertex], &[IndexT], PrimitiveType)

pub fn draw_string<C>(
    &self,
    font: &Ttf,
    string: &str,
    pos: &Point<f32, U2>,
    color: &C
) where
    C: ToRgba, 

Draws the passed string with the passed font

pub fn draw_string_box<C>(
    &self,
    font: &Ttf,
    string: &str,
    pos: &Point<f32, U2>,
    w: BoxCoordinatesX,
    h: BoxCoordinatesY,
    flags: BoxFlags,
    color: &C
) -> Point<f32, U2> where
    C: ToRgba, 

Draws the passed string with the passed font in a box of the dimensions indicated by x, y, w, h

Also returns the next position whe text should start to be drawn to be next to this one

pub fn draw_bitmap_string<C>(
    &self,
    string: &str,
    pos: &Point<f32, U2>,
    color: &C
) where
    C: ToRgba, 

Draws the passed string using a bitmap font

pub fn draw_line<C>(
    &self,
    from: &Point<f32, U2>,
    to: &Point<f32, U2>,
    color: &C
) where
    C: ToRgba, 

Draws a 1px width line segment between from and to

pub fn draw_rectangle_fill<C>(
    &self,
    pos: &Point<f32, U2>,
    w: f32,
    h: f32,
    color: &C
) where
    C: ToRgba, 

Draws a filled rectangle at the passed position and size

pub fn draw_rectangle_lines<C>(
    &self,
    pos: &Point<f32, U2>,
    w: f32,
    h: f32,
    color: &C
) where
    C: ToRgba, 

Draws a rectangle contour at the passed position and size

pub fn draw_circle_fill<C>(
    &self,
    pos: &Point<f32, U2>,
    radius: f32,
    resolution: u32,
    color: &C
) where
    C: ToRgba, 

Draws a filled circle

pub fn draw_circle_lines<C>(
    &self,
    pos: &Point<f32, U2>,
    radius: f32,
    resolution: u32,
    color: &C
) where
    C: ToRgba, 

Draws a cicle contour

pub fn draw_ellipse_fill<C>(
    &self,
    pos: &Point<f32, U2>,
    w: f32,
    h: f32,
    resolution: u32,
    color: &C
) where
    C: ToRgba, 

Draws a filled ellipse

pub fn draw_ellipse_lines<C>(
    &self,
    pos: &Point<f32, U2>,
    w: f32,
    h: f32,
    resolution: u32,
    color: &C
) where
    C: ToRgba, 

Dreas an ellipse contour

pub fn origin(&self) -> CoordinateOrigin

Returns the current coordinate origin of these renderer

impl<'c> Renderer<'c, Screen>

pub fn with_fbo<F>(&self, fbo: F) -> Renderer<'_, F> where
    F: UntypedOffscreenBuffer + Clone, 

Creates a copy of this Renderer but drawing to the passed fbo instead of to the screen

pub fn new_fbo(&self) -> Builder<'_>

Creates a new FBO

Returns an fbo::Builder that allows to configure the fbo further

pub fn new_fbo_color_attachment(&self) -> ColorAttachmentBuilder<'_>

Creates a new FBO color attachment

Returns an fbo::ColorAttachmentBuilder that allows to configure the attachment further

pub fn new_fbo_depth_attachment(&self) -> DepthAttachmentBuilder<'_>

Creates a new FBO depth attachment

Returns an fbo::DepthAttachmentBuilder that allows to configure the attachment further

pub fn new_render_buffer(&self) -> RenderBufferBuilder<'_>

Creates a new FBO render buffer

Returns an fbo::RenderBufferBuilder that allows to configure the render buffer further

pub fn new_simple_fbo(
    &self,
    w: u32,
    h: u32,
    format: ColorFormat
) -> Result<SimpleFbo, Error>

Creates a new SimpleFbo

Directly returns a SimpleFbo if it could be created or the corresponding error

pub fn new_simple_fbo_multisampled(
    &self,
    w: u32,
    h: u32,
    samples: u32,
    format: ColorFormat
) -> Result<SimpleFbo, Error>

Creates a new mutlisampled SimpleFbo

Directly returns a SimpleFbo if it could be created or the corresponding error

pub fn dispatch_compute<U, I>(
    &self,
    program: &Program,
    x: u32,
    y: u32,
    z: u32,
    uniforms: I
) -> Result<(), Error> where
    I: IntoIterator<Item = U>,
    U: Borrow<Uniform>, 

Trait Implementations

impl<'c, R> CreationContext for Renderer<'c, R> where
    R: RenderSurface, 

pub fn new_ttf(&'a self, path: &'a str, pt_height: f32) -> Builder<'a>

pub fn new_ttf_from_bytes(
    &'a self,
    bytes: &'a [u8],
    pt_height: f32
) -> Builder<'a>

pub fn new_ttf_material(&self, ttf: &'a Ttf) -> MaterialBuilder<'a>

pub fn new_vao_mesh(&self) -> Builder

pub fn new_vao_path(&self) -> Builder

pub fn new_auto_program<P>(
    &self,
    settings: ProgramSettings<P>
) -> AutoLoader<Program> where
    P: 'static + AsRef<Path> + Clone, 

pub fn new_object(&self) -> Builder

pub fn to_simple_vao<T, U, M>(&self, mesh: &M) -> Result<SimpleVao<T>, Error> where
    M: ToSimpleVao<T, U>, 

impl<'c, R> CreationContext for Renderer<'c, R> where
    R: RenderSurface, 

pub fn capabilities(&self) -> &Capabilities

pub fn new_texture(&self) -> Builder<'_>

pub fn new_cubemap(&self) -> Builder<'_>

pub fn new_buffer(&self) -> Builder<'_>

pub fn new_shared_buffer(&self) -> SharedBuilder<'_>

pub fn new_vao(&self) -> Builder

pub fn new_simple_vao(&self) -> Builder<'_>

pub fn new_program(&self) -> Builder<'_>

pub fn new_sampler(&self) -> Sampler

pub fn new_timestamp_query(&self) -> TimeStamp

pub fn new_duration_query(&self) -> Duration

pub fn new_fence(&self) -> Fence

pub fn creation_proxy(&self) -> &Rc<CreationProxy>

impl<'c, R> Renderer2d for Renderer<'c, R> where
    R: 'c + RenderSurface, 

pub fn draw_mesh_with_material<T, U, M, G>(&self, mesh: &G, material: &M) where
    T: VertexFormat + Clone + 'static,
    G: ToSimpleVao<T, U>,
    M: Material, 

Draws a mesh in RAM using the passed material

pub fn draw_meshes_with_material<T, U, M, G, I>(&self, meshes: I, material: &M) where
    T: VertexFormat + Clone + 'static,
    G: ToSimpleVao<T, U>,
    I: IntoIterator<Item = G>,
    M: Material, 

Draws several meshes in RAM using the passed material

pub fn draw_meshes_with_trafos_and_material<V, U, M, G, T, I>(
    &self,
    meshes: I,
    material: &M
) where
    T: Into<Model>,
    V: VertexFormat + Clone + 'static,
    G: ToSimpleVao<V, U>,
    I: IntoIterator<Item = (G, T)>,
    M: Material, 

Draws several meshes in RAM using the passed material

pub fn draw_mesh_with_trafos_and_material<V, U, M, G, T, I>(
    &self,
    mesh: &G,
    trafos: I,
    material: &M
) where
    T: Into<Model>,
    V: VertexFormat + Clone + 'static,
    G: ToSimpleVao<V, U>,
    I: IntoIterator<Item = T>,
    M: Material, 

Draws several meshes in RAM using the passed material

pub fn draw_pos<M, O>(&self, obj: O, pos: &Point<f32, U2>) where
    M: Material,
    O: Render2d<Material = M>, 

Draws any Render2d at the passed position

pub fn draw_size<M, O>(
    &self,
    obj: O,
    pos: &Point<f32, U2>,
    size: &Matrix<f32, U2, U1, <DefaultAllocator as Allocator<f32, U2, U1>>::Buffer>
) where
    M: Material,
    O: Render2d<Material = M>, 

Draws any Render2d at the passed position and size

pub fn draw_rect<M, O>(&self, obj: O, rect: &Rect<f32>) where
    M: Material,
    O: Render2d<Material = M>, 

Draws any Render2d at the position of the passed rectangle and it’s size

pub fn draw_pos_with_material<M, M2, O>(
    &self,
    obj: O,
    pos: &Point<f32, U2>,
    mat: &M2
) where
    M: Material,
    O: Render2d<Material = M>,
    M2: Material, 

Draws any Render2d at the passed position with the passed material

pub fn draw_size_with_material<M, M2, O>(
    &self,
    obj: O,
    pos: &Point<f32, U2>,
    size: &Matrix<f32, U2, U1, <DefaultAllocator as Allocator<f32, U2, U1>>::Buffer>,
    mat: &M2
) where
    M: Material,
    O: Render2d<Material = M>,
    M2: Material, 

Draws any Render2d at the passed position and size with the passed material

pub fn draw_rect_with_material<M, M2, O>(
    &self,
    obj: O,
    rect: &Rect<f32>,
    mat: &M2
) where
    M: Material,
    O: Render2d<Material = M>,
    M2: Material, 

Draws any Render2d at the position of the passed rectangle and it’s size with the passed material

impl<'c, R> Renderer3d for Renderer<'c, R> where
    R: 'c + RenderSurface, 

pub fn draw<O>(&self, obj: &O) where
    O: Render3d, 

Draw a Render3d

pub fn draw_with_material<V, M>(&self, obj: &Object<V>, material: &M) where
    M: Material,
    &'a V: for<'a> VaoDraw, 

Draw a Render3d with the passed material

pub fn draw_vao_with_material<V, M>(&self, vao: V, material: &M) where
    V: VaoDraw,
    M: Material, 

Draw a VAO with the passed material

pub fn draw_vao_with_model_material<V, M, MO>(
    &self,
    vao: V,
    model: MO,
    material: &M
) where
    V: VaoDraw,
    M: Material,
    MO: Into<Model>, 

Draw a VAO with the passed material and Into model matrix

pub fn draw_instanced_vao_with_material<V, M>(
    &self,
    vao: V,
    num_instances: usize,
    material: &M
) where
    V: VaoDraw,
    M: Material, 

Draw several instances of the passed VAO with the passed materlal

pub fn draw_vao_with_model<'a, V, M, U>(
    &self,
    vao_range: V,
    model: M,
    program: &Program,
    uniforms: U
) where
    V: VaoDraw,
    M: Into<Model>,
    U: IntoIterator<Item = &'a Uniform>, 

Draw a VAO with the passed Into model matrix, program and uniforms

pub fn draw_vao<'a, V, U>(&self, vao_range: V, program: &Program, uniforms: U) where
    V: VaoDraw,
    U: IntoIterator<Item = &'a Uniform>, 

Draw a VAO with the passed program and uniforms

pub fn draw_instanced_vao<'a, V, U>(
    &self,
    vao_range: V,
    num_instances: usize,
    program: &Program,
    uniforms: U
) where
    V: VaoDraw,
    U: IntoIterator<Item = &'a Uniform>, 

Draw several instances of the passed VAO with the passed program and uniforms

impl<'c> SurfaceCreationContext for Renderer<'c, Screen>

pub fn new_fbo(&self) -> Builder<'_>

pub fn new_fbo_color_attachment(&self) -> ColorAttachmentBuilder<'_>

pub fn new_fbo_depth_attachment(&self) -> DepthAttachmentBuilder<'_>

pub fn new_render_buffer(&self) -> RenderBufferBuilder<'_>