Struct Text

pub struct Text;

A collection of functions for rendering and working with text. These are a lower level access to text rendering than the UI text functions, and are completely unaware of the UI code. https://stereokit.net/Pages/StereoKit/Text.html

Examples

use stereokit_rust::{system::{ Pivot, Align, TextFit, Text, Lines, Hierarchy },
                     font::Font, material::Material, mesh::Mesh, maths::{Vec3, Matrix},
                     util::named_colors::{WHITE, GOLD, GREEN, RED}};

let font = Font::default();
let style = Text::make_style(font, 0.28, WHITE);
let transform1 = Matrix::t([0.7, 0.7, 0.0]) * Matrix::Y_180;
let transform2 = Matrix::t([0.3, 0.1, 0.0]) * Matrix::Y_180;
let transform3 = Matrix::t([-0.1,-0.5, 0.0]) * Matrix::Y_180;

filename_scr = "screenshots/text.jpeg"; fov_scr=110.0;
test_screenshot!( // !!!! Get a proper main loop !!!!
   Text::add_at(token, "Many", transform1, Some(style), Some(GOLD.into()),
            Some(Pivot::TopCenter), Some(Align::TopLeft), None, None, None);
    
   let size = Text::add_in(token, "Texts!", transform2, [0.6, 0.6], TextFit::Squeeze,
            Some(style), Some(GREEN.into()), Some(Pivot::Center), Some(Align::TopLeft),
            None, Some(-0.3), Some(-0.3));
   assert_ne!(size , 0.0);

   Text::add_at(token, "----/****", transform3, Some(style), None,
            None, None, None, None, None);
);

Implementations

impl Text

pub fn make_style( font: impl AsRef<Font>, layout_height_meters: f32, color_gamma: impl Into<Color128>, ) -> TextStyle

Create a text style for use with other text functions! A text style is a font plus size/color/material parameters, and are used to keep text looking more consistent through the application by encouraging devs to re-use styles throughout the project.

This fn will create an unique Material for this style based on Default.ShaderFont. https://stereokit.net/Pages/StereoKit/Text/MakeStyle.html

• font - Font asset you want attached to this style.
• layout_height_meters- Height of a text glyph in meters. StereoKit currently bases this on CapHeight.
• color_gamma - The gamma space color of the text style. This will be embedded in the vertex color of the text mesh.

Returns a text style id for use with text rendering functions.

see also text_make_style same as TextStyle::from_font

Examples

use stereokit_rust::{system::Text, font::Font, util::named_colors};

let font = Font::default();

let text_style = Text::make_style(&font, 0.02, named_colors::WHITE);

assert_eq!(text_style.get_material().get_id(), "sk/text_style/2/material");
assert_eq!(text_style.get_layout_height(), 0.02);

pub fn make_style_with_shader( font: impl AsRef<Font>, layout_height_meters: f32, shader: impl AsRef<Shader>, color_gamma: impl Into<Color128>, ) -> TextStyle

Create a text style for use with other text functions! A text style is a font plus size/color/material parameters, and are used to keep text looking more consistent through the application by encouraging devs to re-use styles throughout the project.

This function will create an unique Material for this style based on the provided Shader. https://stereokit.net/Pages/StereoKit/Text/MakeStyle.html

• font - Font asset you want attached to this style.
• layout_height_meters- Height of a text glyph in meters. StereoKit currently bases this on CapHeight.
• shader - This style will create and use a unique Material based on the Shader that you provide here
• color_gamma - The gamma space color of the text style. This will be embedded in the vertex color of the text mesh.

Returns a text style id for use with text rendering functions.

see also text_make_style_shader same as TextStyle::from_font_and_shader

Examples

use stereokit_rust::{system::{Assets, Text}, font::Font,
                     util::named_colors, shader::Shader};

let font = Font::default();
let shader = Shader::from_file("shaders/water_pbr.hlsl.sks")
                         .expect("Brick_pbr should be a valid shader");
Assets::block_for_priority(i32::MAX);

let text_style = Text::make_style_with_shader(&font, 0.02, shader, named_colors::WHITE);

assert_eq!(text_style.get_material().get_id(), "sk/text_style/2/material");
assert_eq!(text_style.get_layout_height(), 0.02);

pub fn make_style_with_material( font: impl AsRef<Font>, layout_height_meters: f32, material: impl AsRef<Material>, color_gamma: impl Into<Color128>, ) -> TextStyle

Create a text style for use with other text functions! A text style is a font plus size/color/material parameters, and are used to keep text looking more consistent through the application by encouraging devs to re-use styles throughout the project.

This overload allows you to set the specific Material that is used. This can be helpful if you’re keeping styles similar enough to re-use the material and save on draw calls. If you don’t know what that means, then prefer using the overload that takes a Shader, or takes neither a Shader nor a Material! https://stereokit.net/Pages/StereoKit/Text/MakeStyle.html

• font - Font asset you want attached to this style.
• layout_height_meters- Height of a text glyph in meters. StereoKit currently bases this on CapHeight.
• material - Which material should be used to render the text with? Note that this does NOT duplicate the material, so some parameters of this Material instance will get overwritten, like the texture used for the glyph atlas. You should either use a new Material, or a Material that was already used with this same font.
• color_gamma - The gamma space color of the text style. This will be embedded in the vertex color of the text mesh.

Returns a text style id for use with text rendering functions.

see also text_make_style_mat same as TextStyle::from_font_and_material same as TextStyle::from_font_and_material

Examples

use stereokit_rust::{system::Text, font::Font, util::named_colors, material::Material};

let font = Font::default();
let material = Material::pbr().copy();

let text_style = Text::make_style_with_material(&font, 0.02, &material, named_colors::WHITE);

assert_eq!(text_style.get_material(), material);
assert_eq!(text_style.get_layout_height(), 0.02);

pub fn add_at( _token: &MainThreadToken, text: impl AsRef<str>, transform: impl Into<Matrix>, text_style: Option<TextStyle>, vertex_tint_linear: Option<Color128>, position: Option<Pivot>, align: Option<Align>, off_x: Option<f32>, off_y: Option<f32>, off_z: Option<f32>, )

Renders text at the given location! Must be called every frame you want this text to be visible. https://stereokit.net/Pages/StereoKit/Text/Add.html

• text - What text should be drawn?
• transform - A Matrix representing the transform of the text mesh! Try Matrix::t_r_s().
• text_style - Style information for rendering, see Text.MakeStyle or the TextStyle object. If None will use the TextStyle::default()
• vertex_tint_linear - The vertex color of the text gets multiplied by this color. This is a linear color value, not a gamma corrected color value. If None will use Color128::WHITE
• position - How should the text’s bounding rectangle be positioned relative to the transform? If None will use Pivot::Center.
• align - How should the text be aligned within the text’s bounding rectangle? If None will use Align::Center.
• off_? - An additional offset on the given axis. If None will use 0.0.

see also text_add_at

Examples

use stereokit_rust::{system::{Pivot, Align, TextFit, Text},
                     font::Font, maths::{Vec3, Matrix},
                     util::named_colors::{WHITE, GOLD, GREEN}};

let font = Font::default();
let style = Text::make_style(font, 0.28, WHITE);
let transform1 = Matrix::t([0.7, 0.7, 0.0])  * Matrix::Y_180;
let transform2 = Matrix::t([0.3, 0.1, 0.0])  * Matrix::Y_180;
let transform3 = Matrix::t([-0.1,-0.5, 0.0]) * Matrix::Y_180;

test_steps!( // !!!! Get a proper main loop !!!!
   Text::add_at(token, "Many", transform1, Some(style), Some(GOLD.into()),
            Some(Pivot::TopCenter), Some(Align::TopLeft), None, None, None);
    
   Text::add_at(token, "Texts!", transform2, Some(style), Some(GREEN.into()),
            Some(Pivot::Center), Some(Align::TopLeft), None, None, Some(-0.3));

   Text::add_at(token, "----/****", transform3, Some(style), None,
            None, None, None, None, None);
);

pub fn add_in( _token: &MainThreadToken, text: impl AsRef<str>, transform: impl Into<Matrix>, size: impl Into<Vec2>, fit: TextFit, text_style: Option<TextStyle>, vertex_tint_linear: Option<Color128>, position: Option<Pivot>, align: Option<Align>, off_x: Option<f32>, off_y: Option<f32>, off_z: Option<f32>, ) -> f32

Renders text at the given location! Must be called every frame you want this text to be visible. https://stereokit.net/Pages/StereoKit/Text/Add.html

• text - What text should be drawn?
• transform - A Matrix representing the transform of the text mesh! Try Matrix::t_r_s().
• size - This is the Hierarchy space rectangle that the text should try to fit inside of. This allows for text wrapping or scaling based on the value provided to the ‘fit’ parameter.
• text_fit - Describe how the text should behave when one of its size dimensions conflicts with the provided ‘size’ parameter.
• text_style - Style information for rendering, see Text.MakeStyle or the TextStyle object. If None will use the TextStyle::default()
• vertex_tint_linear - The vertex color of the text gets multiplied by this color. This is a linear color value, not a gamma corrected color value. If None will use Color128::WHITE
• position - How should the text’s bounding rectangle be positioned relative to the transform? If None will use Pivot::Center.
• align - How should the text be aligned within the text’s bounding rectangle? If None will use Align::Center.
• off_? - An additional offset on the given axis. If None will use 0.0.

Returns the vertical space used by this text.

see also text_add_in

Examples

use stereokit_rust::{system::{ Align, Pivot, TextFit, Text},
                     font::Font, maths::{Vec3, Matrix},
                     util::named_colors::{WHITE, GOLD, GREEN}};

let font = Font::default();
let style = Text::make_style(font, 0.28, WHITE);
let transform1 = Matrix::Y_180;

test_steps!( // !!!! Get a proper main loop !!!!
   let size = Text::add_in(token, "Many", transform1, [1.1, 1.0], TextFit::Wrap,
            Some(style), Some(GOLD.into()), Some(Pivot::BottomRight),
            Some(Align::TopLeft), None, None, None);
    
   let size = Text::add_in(token, "Texts!", transform1, [1.0, 1.0-size], TextFit::Clip,
            Some(style),None, None,
            None, None, None, None);

   Text::add_in(token, "----/****", transform1, [0.3, 1.0-size], TextFit::Squeeze,
            Some(style), Some(GREEN.into()), Some(Pivot::YTop),
            Some(Align::Center),None, None, Some(-0.7));
);

pub fn size( text: impl AsRef<str>, text_style: Option<TextStyle>, max_width: Option<f32>, ) -> Vec2

👎Deprecated since 0.40.0: please Text::use size_layout

Sometimes you just need to know how much room some text takes up! This finds the size of the text in meters when using the indicated style! https://stereokit.net/Pages/StereoKit/Text/Size.html

• text_style - if None will use the TextStyle::default()
• max_width - Width of the available space in meters.

Returns size of the text in meters

see also text_size_layout text_size_layout_constrained

pub fn size_layout( text: impl AsRef<str>, text_style: Option<TextStyle>, max_width: Option<f32>, ) -> Vec2

Sometimes you just need to know how much room some text takes up! This finds the layout size of the text in meters when using the indicated style! This does not include ascender and descender size, so rendering using this as a clipping size will result in ascenders and descenders getting clipped. https://stereokit.net/Pages/StereoKit/Text/SizeLayout.html

• text - Text you want to find the size of.
• text_style - if None will use the TextStyle::default()
• max_width - Width of the available space in meters if you need to know how much layout space text will take when constrained to a certain width? This will find it using the indicated text style!

Returns size of the text in meters

see also text_size_layout text_size_layout_constrained

Examples

use stereokit_rust::{system::{Text, TextStyle}, font::Font,
                     util::named_colors::{WHITE, GOLD, GREEN},
                     mesh::Mesh, material::{Material, Cull}, maths::Matrix};

let font = Font::default();
let style = Text::make_style(font, 0.70, WHITE);
let transform1 = Matrix::Y_180;
let text = "Yo!";

let size = Text::size_layout(text, Some(style), None);
let cube = Mesh::generate_cube([size.x, size.y, size.y], None);
let mut material = Material::pbr().copy();
material.face_cull(Cull::Front);

test_steps!( // !!!! Get a proper main loop !!!!
   Text::add_at(token, text, transform1, Some(style), Some(GOLD.into()),
            None, None, None, None, None);
    
   cube.draw(token, &material, transform1, Some(GREEN.into()), None);
);

pub fn size_render( size_layout: impl Into<Vec2>, text_style: Option<TextStyle>, y_offset: &mut f32, ) -> Vec2

This modifies a text layout size to include the tallest and lowest possible values for the glyphs in this font. This is for when you need to be careful about avoiding clipping that would happen if you only used the layout size. https://stereokit.net/Pages/StereoKit/Text/SizeRender.html

• size_layout - A size previously calculated using Text.SizeLayout.
• text_style -The same style as used for calculating the sizeLayout. If None will use the TextStyle::default()
• y_offset - Since the render size will ascend from the initial position, this will be the offset from the initial position upwards. You should add it to your Y position.

Returns the sizeLayout modified to account for the size of the most extreme glyphs.

see also text_size_layout text_size_layout_constrained

Examples

use stereokit_rust::{system::{Text, TextStyle}, font::Font,
                     util::named_colors::{WHITE, GOLD, GREEN},
                     mesh::Mesh, material::{Material, Cull}, maths::Matrix};

let font = Font::default();
let style = Text::make_style(font, 0.45, WHITE);
let transform_text = Matrix::Y_180;
let text = "Yo!";

let size = Text::size_layout(text, Some(style), None);
let mut render_yoff = 0.0;
let render_size = Text::size_render(size, Some(style), &mut render_yoff);
let cube = Mesh::generate_cube([render_size.x, render_size.y, render_size.y], None);
let transform_cube = Matrix::t([0.0, render_yoff/2.0, 0.0]);
let mut material = Material::pbr().copy();
material.face_cull(Cull::Front);

test_steps!( // !!!! Get a proper main loop !!!!
   Text::add_at(token, text, transform_text, Some(style), Some(GOLD.into()),
            None, None, None, None, None);
    
   cube.draw(token, &material, transform_cube, Some(GREEN.into()), None);
);