Struct Renderer

pub struct Renderer;

Do you need to draw something? Well, you’re probably in the right place! This static class includes a variety of different drawing methods, from rendering Models and Meshes, to setting rendering options and drawing to offscreen surfaces! Even better, it’s entirely a static class, so you can call it from anywhere :) https://stereokit.net/Pages/StereoKit/Renderer.html

Examples

use stereokit_rust::{system::{Renderer, RenderLayer}, maths::{Vec3, Matrix, Pose},
                     render_list::RenderList,
                     mesh::Mesh, model::Model, material::Material, util::named_colors};

let sun = Mesh::generate_sphere(5.0, None);
let material = Material::pbr();
let transform_sun = Matrix::t([-6.0, -4.0, -10.0]);

let plane = Model::from_file("plane.glb", None).expect("plane.glb should be there");
let transform_plane = Matrix::t_r_s([0.0, 0.2, -0.7], [0.0, 120.0, 0.0], [0.15, 0.15, 0.15]);

// We want to replace the gray background with a dark blue sky:
let mut primary = RenderList::primary();
assert_eq!(primary.get_count(), 0);
Renderer::clear_color(named_colors::BLUE);

filename_scr = "screenshots/renderer.jpeg";
test_steps!( // !!!! Get a proper main loop !!!!
     
    primary.clear();

    Renderer::add_mesh(token, &sun, &material, transform_sun,
        Some(named_colors::RED.into()), None);

    Renderer::add_model(token, &plane, transform_plane,
        Some(named_colors::PINK.into()), Some(RenderLayer::FirstPerson));

    Renderer::layer_filter(RenderLayer::All);
  
    if iter == number_of_steps {
        // This is the way test_screenshot!() works:
        Renderer::screenshot(token, filename_scr, 90, Pose::look_at(from_scr, at_scr),
            width_scr, height_scr, Some(fov_scr) );
    }
);

Implementations

impl Renderer

pub fn camera_root(transform: impl Into<Matrix>)

Sets the root transform of the camera! This will be the identity matrix by default. The user’s head location will then be relative to this point. This is great to use if you’re trying to do teleportation, redirected walking, or just shifting the floor around. https://stereokit.net/Pages/StereoKit/Renderer/CameraRoot.html

see also render_set_cam_root

Examples

use stereokit_rust::{maths::{Matrix, Vec3}, system::Renderer};

let camera_root = Renderer::get_camera_root();
assert_eq!(camera_root, Matrix::IDENTITY);

let transform = Matrix::t([0.0, 0.0, -1.0]);

test_steps!( // !!!! Get a proper main loop !!!!
    Renderer::camera_root(transform);
    let camera_root = Renderer::get_camera_root();
    assert_eq!(camera_root, transform);
);

pub fn clear_color(color_gamma: impl Into<Color128>)

This is the gamma space color the renderer will clear the screen to when beginning to draw a new frame. Color128::BLACK_TRANSPARENT is the default and is mandatory for some Passthrough solutions. https://stereokit.net/Pages/StereoKit/Renderer/ClearColor.html

see also render_set_clear_color

Examples

use stereokit_rust::{system::Renderer,
                     render_list::RenderList, util::{named_colors, Color128}};

// We want to replace the gray background with a dark blue sky:
let mut primary = RenderList::primary();
assert_eq!(primary.get_count(), 0);


assert_eq!(Renderer::get_clear_color(), Color128::BLACK_TRANSPARENT);
Renderer::clear_color(named_colors::BLUE);

filename_scr = "screenshots/renderer.jpeg";
test_steps!( // !!!! Get a proper main loop !!!!
     
    primary.clear();

    assert_eq!(Renderer::get_clear_color(), named_colors::BLUE.into());

);

pub fn enable_sky(enable: bool)

Enables or disables rendering of the skybox texture! It’s enabled by default on Opaque displays, and completely unavailable for transparent displays. https://stereokit.net/Pages/StereoKit/Renderer/EnableSky.html

see also render_enable_skytex Renderer::clear_color crate::tex::SHCubemap

Examples

use stereokit_rust::system::Renderer;

assert_eq!(Renderer::get_enable_sky(), true);

Renderer::enable_sky(false);
assert_eq!(Renderer::get_enable_sky(), false);

Renderer::enable_sky(true);
assert_eq!(Renderer::get_enable_sky(), true);

pub fn layer_filter(filter: RenderLayer)

By default, StereoKit renders all first-person layers. This is a bit flag that allows you to change which layers StereoKit renders for the primary viewpoint. To change what layers a visual is on, use a Draw method that includes a RenderLayer as a parameter. https://stereokit.net/Pages/StereoKit/Renderer/LayerFilter.html

see also render_set_filter

Examples

use stereokit_rust::system::{Renderer, RenderLayer};

assert_eq!(Renderer::get_layer_filter(), RenderLayer::AllFirstPerson);

Renderer::layer_filter(RenderLayer::All);
assert_eq!(Renderer::get_layer_filter(), RenderLayer::All);

Renderer::layer_filter(RenderLayer::AllFirstPerson);
assert_eq!(Renderer::get_layer_filter(), RenderLayer::AllFirstPerson);

pub fn multisample(level: i32)

Allows you to set the multisample (MSAA) level of the render surface. Valid values are 1, 2, 4, 8, 16, though some OpenXR runtimes may clamp this to lower values. Note that while this can greatly smooth out edges, it also greatly increases RAM usage and fill rate, so use it sparingly. Only works in XR mode. If known in advance, set this via crate::sk::SkSettings in initialization. This is a very costly change to make. https://stereokit.net/Pages/StereoKit/Renderer/Multisample.html

see also render_set_multisample

Examples

use stereokit_rust::system::Renderer;

assert_eq!(Renderer::get_multisample(), 1);

Renderer::multisample(4);
assert_eq!(Renderer::get_multisample(), 4);

Renderer::multisample(1);
assert_eq!(Renderer::get_multisample(), 1);

pub fn projection(projection: Projection)

For flatscreen applications only! This allows you to change the camera projection between perspective and orthographic projection. This may be of interest for some category of UI work, but is generally a niche piece of functionality. Swapping between perspective and orthographic will also switch the clipping planes and field of view to the values associated with that mode. See set_clip/set_fov for perspective, and set_ortho_clip/set_ortho_size for orthographic. https://stereokit.net/Pages/StereoKit/Renderer/Projection.html

see also render_set_projection

Examples

use stereokit_rust::system::{Renderer, Projection};

assert_eq!(Renderer::get_projection(), Projection::Perspective);

Renderer::projection(Projection::Orthographic);
assert_eq!(Renderer::get_projection(), Projection::Orthographic);

Renderer::projection(Projection::Perspective);
assert_eq!(Renderer::get_projection(), Projection::Perspective);

pub fn scaling(scaling: f32)

OpenXR has a recommended default for the main render surface, this value allows you to set SK’s surface to a multiple of the recommended size. Note that the final resolution may also be clamped or quantized. Only works in XR mode. If known in advance, set this via crate::sk::SkSettings in initialization. This is a very costly change to make. Consider if Viewport_scaling will work for you instead, and prefer that. https://stereokit.net/Pages/StereoKit/Renderer/Scaling.html

see also render_set_scaling

Examples

use stereokit_rust::system::Renderer;

assert_eq!(Renderer::get_scaling(), 1.0);

Renderer::scaling(0.5);
assert_eq!(Renderer::get_scaling(), 0.5);

Renderer::scaling(1.0);
assert_eq!(Renderer::get_scaling(), 1.0);

pub fn viewport_scaling(scaling: f32)

This allows you to trivially scale down the area of the swapchain that StereoKit renders to! This can be used to boost performance in situations where full resolution is not needed, or to reduce GPU time. This value is locked to the 0-1 range https://stereokit.net/Pages/StereoKit/Renderer/ViewportScaling.html

see also render_set_viewport_scaling

Examples

use stereokit_rust::system::Renderer;

assert_eq!(Renderer::get_viewport_scaling(), 1.0);

Renderer::viewport_scaling(0.5);
assert_eq!(Renderer::get_viewport_scaling(), 0.5);

Renderer::viewport_scaling(1.0);
assert_eq!(Renderer::get_viewport_scaling(), 1.0);

pub fn sky_light(light_info: SphericalHarmonics)

Sets the lighting information for the scene! You can build one through SphericalHarmonics::from_lights, or grab one from crate::tex::SHCubemap https://stereokit.net/Pages/StereoKit/Renderer/SkyLight.html

see also render_set_skylight crate::tex::SHCubemap crate::util::SHLight

Examples

use stereokit_rust::{system::Renderer, maths::Vec3,
                     util::{named_colors, SphericalHarmonics, SHLight}};

let light1 = SHLight::new([0.0, 1.0, 0.0], named_colors::WHITE);
let light2 = SHLight::new([0.0, 0.0, 1.0], named_colors::WHITE);

let mut sh = SphericalHarmonics::from_lights(&[light1, light2]);

Renderer::sky_light(sh);
let sky_light = Renderer::get_sky_light();

assert_eq!(sky_light, sh);
assert_eq!(sh.get_dominent_light_direction(),
           Vec3 { x: -0.0, y: -1.0, z: -1.0 }.get_normalized())

pub fn sky_tex(tex: impl AsRef<Tex>)

Set a cubemap skybox texture for rendering a background! This is only visible on Opaque displays, since transparent displays have the real world behind them already! StereoKit has a a default procedurally generated skybox. You can load one with crate::tex::SHCubemap. If you’re trying to affect the lighting, see Renderer::sky_light. https://stereokit.net/Pages/StereoKit/Renderer/SkyTex.html

see also render_set_skytex crate::tex::SHCubemap

Examples

use stereokit_rust::{system::{Renderer, Assets}, tex::{Tex, TexType}};

let sky_tex = Tex::from_file("hdri/sky_dawn.jpeg", true, None)
                       .expect("sky_tex should be created");

Assets::block_for_priority(i32::MAX);

Renderer::sky_tex(&sky_tex);
let sky_tex_get = Renderer::get_sky_tex();

assert_eq!(sky_tex_get, sky_tex);

pub fn sky_material(material: impl AsRef<Material>)

This is the Material that StereoKit is currently using to draw the skybox! It needs a special shader that’s tuned for a full-screen quad. If you just want to change the skybox image, try setting Renderer::sky_tex instead.

This value will never be null! If you try setting this to null, it will assign SK’s built-in default sky material. If you want to turn off the skybox, see Renderer::enable_sky instead.

Recommended Material settings would be:

• DepthWrite: false
• DepthTest: LessOrEq
• QueueOffset: 100

https://stereokit.net/Pages/StereoKit/Renderer/SkyMaterial.html

see also render_set_skymaterial crate::tex::SHCubemap

Examples

use stereokit_rust::{system::Renderer, material::Material, util::named_colors};

let material = Material::pbr().copy();
Renderer::sky_material(&material);

let same_material = Renderer::get_sky_material();
assert_eq!(same_material, material);

pub fn add_mesh( _token: &MainThreadToken, mesh: impl AsRef<Mesh>, material: impl AsRef<Material>, transform: impl Into<Matrix>, color: Option<Color128>, layer: Option<RenderLayer>, )

Adds a mesh to the render queue for this frame! If the Hierarchy has a transform on it, that transform is combined with the Matrix provided here. https://stereokit.net/Pages/StereoKit/Renderer/Add.html

• mesh - A valid Mesh you wish to draw.
• material - A Material to apply to the Mesh.
• transform - A Matrix that will transform the mesh from Model Space into the current Hierarchy Space.
• color - A per-instance linear space color value to pass into the shader! Normally this gets used like a material tint. If you’re adventurous and don’t need per-instance colors, this is a great spot to pack in extra per-instance data for the shader! If None has default value of WHITE
• layer - All visuals are rendered using a layer bit-flag. By default, all layers are rendered, but this can be useful for filtering out objects for different rendering purposes! For example: rendering a mesh over the user’s head from a 3rd person perspective, but filtering it out from the 1st person perspective.If None has default value of RenderLayer::Layer0

see also render_add_mesh Mesh::draw

Examples

use stereokit_rust::{system::{Renderer, RenderLayer}, maths::{Vec3, Matrix},
                     mesh::Mesh, material::Material, util::named_colors};

let sphere = Mesh::generate_sphere(0.5, None);
let material = Material::pbr();
let transform1 = Matrix::t([-0.5, 0.0, 0.0]);
let transform2 = Matrix::t([ 0.5, 0.0, -1.0]);

test_steps!( // !!!! Get a proper main loop !!!!

    Renderer::add_mesh(token, &sphere, &material, transform1,
        Some(named_colors::RED.into()), Some(RenderLayer::Layer0));

    Renderer::add_mesh(token, &sphere, &material, transform2, None, None);
);

pub fn add_model( _token: &MainThreadToken, model: impl AsRef<Model>, transform: impl Into<Matrix>, color: Option<Color128>, layer: Option<RenderLayer>, )

Adds a Model to the render queue for this frame! If the Hierarchy has a transform on it, that transform is combined with the Matrix provided here. https://stereokit.net/Pages/StereoKit/Renderer/Add.html

• model - A valid Model you wish to draw.
• transform - A Matrix that will transform the Model from Model Space into the current Hierarchy Space.
• color - A per-instance linear space color value to pass into the shader! Normally this gets used like a material tint. If you’re adventurous and don’t need per-instance colors, this is a great spot to pack in extra per-instance data for the shader! If None has default value of WHITE
• layer - All visuals are rendered using a layer bit-flag. By default, all layers are rendered, but this can be useful for filtering out objects for different rendering purposes! For example: rendering a mesh over the user’s head from a 3rd person perspective, but filtering it out from the 1st person perspective. If None has default value of RenderLayer::Layer0

see also render_add_model Model::draw Model::draw_with_material

Examples

use stereokit_rust::{system::{Renderer, RenderLayer}, maths::{Vec3, Matrix},
                     model::Model, util::named_colors};

let model = Model::from_file("plane.glb", None).expect("plane.glb should be there");
let transform1 = Matrix::t([-2.5, 0.0, -5.0]);
let transform2 = Matrix::t([ 2.5, 0.0, -5.0]);

test_steps!( // !!!! Get a proper main loop !!!!

    Renderer::add_model(token, &model, transform1,
        Some(named_colors::RED.into()), Some(RenderLayer::Layer0));

    Renderer::add_model(token, &model, transform2, None, None);
);

pub fn blit(to_render_target: impl AsRef<Tex>, material: impl AsRef<Material>)

Renders a Material onto a rendertarget texture! StereoKit uses a 4 vert quad stretched over the surface of the texture, and renders the material onto it to the texture. https://stereokit.net/Pages/StereoKit/Renderer/Blit.html

• to_render_target - A texture that’s been set up as a render target!
• material - This material is rendered onto the texture! Set it up like you would if you were applying it to a plane, or quad mesh.

see also render_blit

Examples

use stereokit_rust::{system::Renderer, material::Material, tex::Tex};

let material = Material::pbr();
let tex = Tex::render_target(200,200, None, None, None)
                   .expect("RenderTarget should be created");

test_steps!( // !!!! Get a proper main loop !!!!
    Renderer::blit(&tex, &material);
);

pub fn override_capture_filter( use_override_filter: bool, override_filter: RenderLayer, )

The capture_filter is a layer mask for Mixed Reality Capture, or 2nd person observer rendering. On HoloLens and WMR, this is the video rendering feature. This allows you to hide, or reveal certain draw calls when rendering video output.

By default, the capture_filter will always be the same as Renderer::layer_filter, overriding this will mean this filter no longer updates with layer_filter. https://stereokit.net/Pages/StereoKit/Renderer/OverrideCaptureFilter.html

• use_override_filter - Enables (true) or disables (false) the overridden filter value provided here.
• override_filter - The filter for capture rendering to use. This is ignored if useOverrideFilter is false.

see also render_override_capture_filter

Examples

use stereokit_rust::{system::{Renderer, RenderLayer},
                     maths::Matrix, mesh::Mesh, material::Material};

let sphere = Mesh::generate_sphere(0.2, None);
let material = Material::pbr();

assert_eq!(Renderer::has_capture_filter(), false);
assert_eq!(Renderer::get_capture_filter(), RenderLayer::AllFirstPerson);

Renderer::override_capture_filter(true, RenderLayer::Layer1);

assert_eq!(Renderer::has_capture_filter(), true);
assert_eq!(Renderer::get_capture_filter(), RenderLayer::Layer1);


test_steps!( // !!!! Get a proper main loop !!!!
    sphere.draw(token, &material, Matrix::IDENTITY, None, Some(RenderLayer::Layer1));
);

Renderer::override_capture_filter(false, RenderLayer::Layer0);
assert_eq!(Renderer::has_capture_filter(), false);

pub fn render_to<M: Into<Matrix>>( _token: &MainThreadToken, to_render_target: impl AsRef<Tex>, camera: M, projection: M, layer_filter: Option<RenderLayer>, clear: Option<RenderClear>, viewport: Option<Rect>, )

This renders the current scene to the indicated rendertarget texture, from the specified viewpoint. This call enqueues a render that occurs immediately before the screen itself is rendered. https://stereokit.net/Pages/StereoKit/Renderer/RenderTo.html

• to_render_target - The texture to which the scene will be rendered to. This must be a Rendertarget type texture.
• camera - A TRS matrix representing the location and orientation of the camera. This matrix gets inverted later on, so no need to do it yourself.
• projection - The projection matrix describes how the geometry is flattened onto the draw surface. Normally, you’d use Matrix::perspective, and occasionally Matrix::orthographic might be helpful as well.
• layer_filter - This is a bit flag that allows you to change which layers StereoKit renders for this particular render viewpoint. To change what layers a visual is on, use a Draw method that includes a RenderLayer as a parameter. If None has default value of RenderLayer::ALL
• clear - Describes if and how the rendertarget should be cleared before rendering. Note that clearing the target is unaffected by the viewport, so this will clean the entire surface! If None has default value of RenderClear::All
• vieport - Allows you to specify a region of the rendertarget to draw to! This is in normalized coordinates, 0-1. If the width of this value is zero, then this will render to the entire texture. If None has default value of (0, 0, 0, 0)

see also render_to

Examples

use stereokit_rust::{system::{Renderer, RenderLayer}, maths::{Vec3, Quat, Matrix},
                     render_list::RenderList, tex::{Tex, TexType, TexFormat},
                     mesh::Mesh, model::Model, material::Material, util::named_colors};

let sun = Mesh::generate_sphere(5.0, None);
let material = Material::pbr();
let transform_sun = Matrix::t([-6.0, -1.0, -10.0]);

let plane = Mesh::generate_plane_up([1.0,1.0], None, true);
let mut material = Material::unlit().copy();
let tex = Tex::render_target(200,200, None, None, None)
                   .expect("RenderTarget should be created");
material.diffuse_tex(&tex);
let transform_plane = Matrix::t([0.0, -0.55, 0.0]);

let camera = Matrix::t_r(Vec3::Z * 2.0, Quat::look_at(Vec3::Z, Vec3::ZERO, None));
let projection = Matrix::perspective(90.0, 1.0, 0.1, 20.0);

test_steps!( // !!!! Get a proper main loop !!!!
     
    Renderer::add_mesh(token, &sun, &material, transform_sun,
        Some(named_colors::RED.into()), None);

    Renderer::add_mesh(token, &plane, &material, transform_plane,
        None, None);

    Renderer::render_to(token, &tex, camera, projection, None, None, None);
);

pub fn set_global_texture( _token: &MainThreadToken, texture_register: i32, tex: Option<&Tex>, )

This attaches a texture resource globally across all shaders. StereoKit uses this to attach the sky cubemap for use in reflections across all materials (register 11). It can be used for things like shadowmaps, wind data, etc. Prefer a higher registers (11+) to prevent conflicting with normal Material textures. https://stereokit.net/Pages/StereoKit/Renderer/SetGlobalTexture.html

• texture_register - The texture resource register the texture will bind to. SK uses register 11 already, so values above that should be fine.
• tex - The texture to assign globally. Setting None here will clear any texture that is currently bound.

see also render_global_texture

Examples

use stereokit_rust::{system::{Renderer, RenderLayer}, tex::{Tex, TexFormat},
                     maths::Matrix, util::named_colors};

let tex = Tex::from_file("hdri/sky_dawn.jpeg", true, None)
                   .expect("tex should be created");

test_steps!( // !!!! Get a proper main loop !!!!
    if iter < 2 {
        Renderer::set_global_texture(token, 12, Some(&tex));
    } else {
        Renderer::set_global_texture(token, 12, None);
    }
);

pub fn screenshot( _token: &MainThreadToken, filename: impl AsRef<Path>, file_quality: i32, viewpoint: Pose, width: i32, height: i32, field_of_view: Option<f32>, )

Schedules a screenshot for the end of the frame! The view will be rendered from the given pose, with a resolution the same size as the screen’s surface. It’ll be saved as a JPEG or PNG file depending on the filename extension provided. https://stereokit.net/Pages/StereoKit/Renderer/Screenshot.html

• filename - Filename to write the screenshot to! This will be a PNG if the extension ends with (case insensitive) “.png”, and will be a 90 quality JPEG if it ends with anything else.
• file_quality - For JPEG files, this is the compression quality of the file from 0-100, 100 being highest quality, 0 being smallest size. SK uses a default of 90 here.
• viewpoint - is Pose::look_at(from_point, looking_at_point)
• width - Size of the screenshot horizontally, in pixels.
• height- Size of the screenshot vertically, in pixels
• field_of_view - The angle of the viewport, in degrees. If None will use default value of 90°

see also render_screenshot see example in Renderer

pub fn screenshot_capture<F: FnMut(&[Color32], usize, usize)>( _token: &MainThreadToken, on_screenshot: F, viewpoint: Pose, width: i32, height: i32, field_of_view: Option<f32>, tex_format: Option<TexFormat>, )

Schedules a screenshot for the end of the frame! The view will be rendered from the given position at the given point, with a resolution the same size as the screen’s surface. This overload allows for retrieval of the color data directly from the render thread! You can use the color data directly by saving/processing it inside your callback, or you can keep the data alive for as long as it is referenced. https://stereokit.net/Pages/StereoKit/Renderer/Screenshot.html

• on_screenshot : closure |&Color32, width:usize, height:usize|
• viewpoint - is Pose::look_at(from_point, looking_at_point)
• width - Size of the screenshot horizontally, in pixels.
• height- Size of the screenshot vertically, in pixels
• field_of_view - The angle of the viewport, in degrees. If None will use default value of 90°
• tex_format - The pixel format of the color data. If None will use default value of TexFormat::RGBA32

see also render_screenshot_capture

Examples

use stereokit_rust::{system::{Renderer, RenderLayer}, maths::{Vec3, Quat, Pose, Matrix},
                     render_list::RenderList, tex::{Tex, TexType, TexFormat},
                     mesh::Mesh, model::Model, material::Material, util::named_colors};

let sun = Mesh::generate_sphere(7.0, None);
let material_sun = Material::pbr();
let transform_sun = Matrix::t([-6.0, 3.0, -10.0]);

let plane = Mesh::generate_plane_up([1.0,1.0], None, true);
let mut material = Material::unlit().copy();
let mut tex = Tex::render_target(200,200, None, None, None)
                   .expect("RenderTarget should be created");
tex.id("CAPTURE_TEXTURE_ID");
material.diffuse_tex(&tex);
let transform_plane = Matrix::t([0.0, -0.55, 0.0]);

let camera_pose = Pose::new([0.0, 0.0, 1.0], None);

number_of_steps = 20;
filename_scr = "screenshots/screenshot_capture.jpeg";
test_screenshot!( // !!!! Get a proper main loop !!!!
     
    Renderer::add_mesh(token, &sun, &material_sun, transform_sun,
        Some(named_colors::RED.into()), None);

    Renderer::add_mesh(token, &plane, &material, transform_plane,
        None, None);

    Renderer::screenshot_capture( token,
        move |dots, width, height| {
            let tex = Tex::find("CAPTURE_TEXTURE_ID").ok();
            match tex {
                Some(mut tex) => tex.set_colors32(width, height, dots),
                None => panic!("CAPTURE_TEXTURE_ID not found!"),
            };
        },
        camera_pose, 200, 200, None, None
    );
);

pub fn screenshot_viewpoint<M: Into<Matrix>, F: FnMut(&[Color32], usize, usize)>( _token: &MainThreadToken, on_screenshot: F, camera: M, projection: M, width: i32, height: i32, render_layer: Option<RenderLayer>, clear: Option<RenderClear>, viewport: Option<Rect>, tex_format: Option<TexFormat>, )

Schedules a screenshot for the end of the frame! The view will be rendered from the given position at the given point, with a resolution the same size as the screen’s surface. This overload allows for retrieval of the color data directly from the render thread! You can use the color data directly by saving/processing it inside your callback, or you can keep the data alive for as long as it is referenced. https://stereokit.net/Pages/StereoKit/Renderer/Screenshot.html

• on_screenshot : closure |&Color32, width:usize, height:usize|
• camera - A TRS matrix representing the location and orientation of the camera. This matrix gets inverted later on, so no need to do it yourself.
• projection - The projection matrix describes how the geometry is flattened onto the draw surface. Normally, you’d use Matrix::perspective, and occasionally Matrix::orthographic might be helpful as well.
• width - Size of the screenshot horizontally, in pixels.
• height- Size of the screenshot vertically, in pixels
• render_layer - This is a bit flag that allows you to change which layers StereoKit renders for this particular render viewpoint. To change what layers a visual is on, use a Draw method that includes a RenderLayer as a parameter. If None will use default value of All
• clear - Describes if and how the rendertarget should be cleared before rendering. Note that clearing the target is unaffected by the viewport, so this will clean the entire surface! If None wille use default value of All
• viewport - Allows you to specify a region of the rendertarget to draw to! This is in normalized coordinates, 0-1. If the width of this value is zero, then this will render to the entire texture. If None has default value of (0, 0, 0, 0)
• tex_format - The pixel format of the color data. If None will use default value of TexFormat::RGBA32

see also render_screenshot_viewpoint

Examples

use stereokit_rust::{system::{Renderer, RenderLayer}, maths::{Vec3, Quat, Pose, Matrix},
                     render_list::RenderList, tex::{Tex, TexType, TexFormat},
                     mesh::Mesh, model::Model, material::Material, util::named_colors};

let sun = Mesh::generate_sphere(7.0, None);
let material_sun = Material::pbr();
let transform_sun = Matrix::t([6.0, 3.0, -10.0]);

let plane = Mesh::generate_plane_up([1.0,1.0], None, true);
let mut material = Material::unlit().copy();
let mut tex = Tex::gen_color(named_colors::VIOLET, 200, 200, TexType::Rendertarget, TexFormat::RGBA32);

tex.id("CAPTURE_TEXTURE_ID");
material.diffuse_tex(&tex);
let transform_plane = Matrix::t([0.0, -0.55, 0.0]);

let camera = Matrix::t_r(Vec3::Z * 2.0, Quat::look_at(Vec3::Z, Vec3::ZERO, None));
let projection = Matrix::perspective(90.0, 1.0, 0.1, 20.0);

number_of_steps = 200;
filename_scr = "screenshots/screenshot_viewpoint.jpeg";
test_screenshot!( // !!!! Get a proper main loop !!!!
     
    Renderer::add_mesh(token, &sun, &material_sun, transform_sun,
        Some(named_colors::RED.into()), None);

    Renderer::add_mesh(token, &plane, &material, transform_plane,
        None, None);

    Renderer::screenshot_viewpoint( token,
        move |dots, width, height| {
            let tex = Tex::find("CAPTURE_TEXTURE_ID").ok();
            match tex {
                Some(mut tex) => tex.set_colors32(width, height, dots),
                None => panic!("CAPTURE_TEXTURE_ID not found!"),
            };
        },
        camera, projection, 200, 200, None, None, None, None
    );
);

pub fn set_clip(near_plane: f32, far_plane: f32)

Set the near and far clipping planes of the camera! These are important to z-buffer quality, especially when using low bit depth z-buffers as recommended for devices like the HoloLens. The smaller the range between the near and far planes, the better your z-buffer will look! If you see flickering on objects that are overlapping, try making the range smaller.

These values only affect perspective mode projection, which is the default projection mode. https://stereokit.net/Pages/StereoKit/Renderer/SetClip.html

• near_plane - The GPU discards pixels that are too close to the camera, this is that distance! It must be larger than zero, due to the projection math, which also means that numbers too close to zero will produce z-fighting artifacts. This has an enforced minimum of 0.001, but you should probably stay closer to 0.1.
• far_plane - At what distance from the camera does the GPU discard pixel? This is not true distance, but rather Z-axis distance from zero in View Space coordinates!

see also render_set_clip

Examples

use stereokit_rust::system::Renderer;

Renderer::set_clip(0.01, 10.0);

pub fn set_fov(field_of_view: f32)

Only works for flatscreen! This updates the camera’s projection matrix with a new field of view.

This value only affects perspective mode projection, which is the default projection mode. https://stereokit.net/Pages/StereoKit/Renderer/SetFOV.html

• field_of_view - Vertical field of view in degrees.`

see also render_set_fov

Examples

use stereokit_rust::system::Renderer;

Renderer::set_fov(120.0);

pub fn set_ortho_clip(near_plane: f32, far_plane: f32)

Set the near and far clipping planes of the camera! These are important to z-buffer quality, especially when using low bit depth z-buffers as recommended for devices like the HoloLens. The smaller the range between the near and far planes, the better your z-buffer will look! If you see flickering on objects that are overlapping, try making the range smaller.

These values only affect orthographic mode projection, which is only available in flatscreen. https://stereokit.net/Pages/StereoKit/Renderer/SetOrthoClip.html

• near_plane - The GPU discards pixels that are too close to the camera, this is that distance! It must be larger than zero, due to the projection math, which also means that numbers too close to zero will produce z-fighting artifacts. This has an enforced minimum of 0.001, but you should probably stay closer to 0.1.
• far_plane - At what distance from the camera does the GPU discard pixel? This is not true distance, but rather Z-axis distance from zero in View Space coordinates!

see also render_set_ortho_clip

Examples

use stereokit_rust::system::Renderer;

Renderer::set_ortho_clip(0.01, 5.0);

pub fn set_ortho_size(view_port_height_meters: f32)

This sets the size of the orthographic projection’s viewport. You can use this feature to zoom in and out of the scene.

This value only affects orthographic mode projection, which is only available in flatscreen. https://stereokit.net/Pages/StereoKit/Renderer/SetOrthoSize.html

• viewport_height_meters - The vertical size of the projection’s viewport, in meters.

see also render_set_ortho_size

Examples

use stereokit_rust::system::Renderer;

Renderer::set_ortho_size(12.0);

pub fn get_camera_root() -> Matrix

Gets the root transform of the camera! This will be the identity matrix by default. The user’s head location will then be relative to this point. This is great to use if you’re trying to do teleportation, redirected walking, or just shifting the floor around. https://stereokit.net/Pages/StereoKit/Renderer/CameraRoot.html

see also render_get_cam_root see example in Renderer::camera_root

pub fn get_capture_filter() -> RenderLayer

This is the current render layer mask for Mixed Reality Capture, or 2nd person observer rendering. By default, this is directly linked to Renderer::layer_filter, but this behavior can be overridden via Renderer::override_capture_filter. https://stereokit.net/Pages/StereoKit/Renderer/CaptureFilter.html

see also render_get_capture_filter see example in Renderer::override_capture_filter

pub fn get_clear_color() -> Color128

This is the gamma space color the renderer will clear the screen to when beginning to draw a new frame. https://stereokit.net/Pages/StereoKit/Renderer/ClearColor.html

see also render_get_clear_color see example in Renderer::clear_color

pub fn get_enable_sky() -> bool

Enables or disables rendering of the skybox texture! It’s enabled by default on Opaque displays, and completely unavailable for transparent displays. https://stereokit.net/Pages/StereoKit/Renderer/EnableSky.html

see also render_enabled_skytex see example in Renderer::enable_sky

pub fn has_capture_filter() -> bool

This tells if capture_filter has been overridden to a specific value via Renderer::override_capture_filter. https://stereokit.net/Pages/StereoKit/Renderer/HasCaptureFilter.html

see also render_has_capture_filter see example in Renderer::override_capture_filter

pub fn get_layer_filter() -> RenderLayer

By default, StereoKit renders all first-person layers. This is a bit flag that allows you to change which layers StereoKit renders for the primary viewpoint. To change what layers a visual is on, use a Draw method that includes a RenderLayer as a parameter. https://stereokit.net/Pages/StereoKit/Renderer/LayerFilter.html

see also render_get_filter see example in Renderer::layer_filter

pub fn get_multisample() -> i32

Get the multisample (MSAA) level of the render surface. Valid values are 1, 2, 4, 8, 16, though some OpenXR runtimes may clamp this to lower values. Note that while this can greatly smooth out edges, it also greatly increases RAM usage and fill rate, so use it sparingly. Only works in XR mode. If known in advance, set this via crate::sk::SkSettings in initialization. This is a very costly change to make. https://stereokit.net/Pages/StereoKit/Renderer/Multisample.html

see also render_get_multisample see example in Renderer::multisample

pub fn get_projection() -> Projection

For flatscreen applications only! This allows you to get the camera projection between perspective and orthographic projection. This may be of interest for some category of UI work, but is generally a niche piece of functionality. Swapping between perspective and orthographic will also switch the clipping planes and field of view to the values associated with that mode. See set_clip/set_fov for perspective, and set_ortho_clip/set_ortho_size for orthographic. https://stereokit.net/Pages/StereoKit/Renderer/Projection.html

see also render_get_projection see example in Renderer::projection

pub fn get_scaling() -> f32

OpenXR has a recommended default for the main render surface, this value allows you to set SK’s surface to a multiple of the recommended size. Note that the final resolution may also be clamped or quantized. Only works in XR mode. If known in advance, set this via SKSettings in initialization. This is a very costly change to make. Consider if viewport_caling will work for you instead, and prefer that. https://stereokit.net/Pages/StereoKit/Renderer/Scaling.html

see also render_get_scaling see example in Renderer::scaling

pub fn get_viewport_scaling() -> f32

This allows you to trivially scale down the area of the swapchain that StereoKit renders to! This can be used to boost performance in situations where full resolution is not needed, or to reduce GPU time. This value is locked to the 0-1 range https://stereokit.net/Pages/StereoKit/Renderer/ViewportScaling.html

see also render_get_viewport_scaling see example in Renderer::viewport_scaling

pub fn get_sky_light() -> SphericalHarmonics

Gets the lighting information for the scene! You can build one through SphericalHarmonics::from_lights, or grab one from crate::tex::SHCubemap. https://stereokit.net/Pages/StereoKit/Renderer/SkyLight.html

see also render_get_skylight see example in Renderer::sky_light

pub fn get_sky_tex() -> Tex

Get the cubemap skybox texture for rendering a background! This is only visible on Opaque displays, since transparent displays have the real world behind them already! StereoKit has a a default procedurally generated skybox. You can load one with crate::tex::SHCubemap. If you’re trying to affect the lighting, see Renderer::sky_light. https://stereokit.net/Pages/StereoKit/Renderer/SkyTex.html

see also render_get_skytex see example in Renderer::sky_tex

pub fn get_sky_material() -> Material

This is the Material that StereoKit is currently using to draw the skybox! It needs a special shader that’s tuned for a full-screen quad. If you just want to change the skybox image, try setting Renderer::sky_tex instead.

This value will never be null! If you try setting this to null, it will assign SK’s built-in default sky material. If you want to turn off the skybox, see Renderer::enable_sky instead.

Recommended Material settings would be:

• DepthWrite: false
• DepthTest: LessOrEq
• QueueOffset: 100

https://stereokit.net/Pages/StereoKit/Renderer/SkyMaterial.html

see also render_get_skymaterial see example in Renderer::sky_material