Struct fyrox::material::Material

pub struct Material { /* private fields */ }

Material defines a set of values for a shader. Materials usually contains textures (diffuse, normal, height, emission, etc. maps), numerical values (floats, integers), vectors, booleans, matrices and arrays of each type, except textures. Each parameter can be changed in runtime giving you the ability to create animated materials. However in practice, most materials are static, this means that once it created, it won’t be changed anymore.

Please keep in mind that the actual “rules” of drawing an entity are stored in the shader, material is only a storage for specific uses of the shader.

Multiple materials can share the same shader, for example standard shader covers 95% of most common use cases and it is shared across multiple materials. The only difference are property values, for example you can draw multiple cubes using the same shader, but with different textures.

Material itself can be shared across multiple places as well as the shader. This gives you the ability to render multiple objects with the same material efficiently.

Performance

It is very important re-use materials as much as possible, because the amount of materials used per frame significantly correlates with performance. The more unique materials you have per frame, the more work has to be done by the renderer and video driver to render a frame and the more time the frame will require for rendering, thus lowering your FPS.

Examples

A material can only be created using a shader instance, every material must have a shader. The shader provides information about its properties, and this information is used to populate a set of properties with default values. Default values of each property defined in the shader.

Standard material

Usually standard shader is enough for most cases, Material even has a Material::standard() method to create a material with standard shader:

use fyrox::{
    material::shader::{Shader, SamplerFallback},
    engine::resource_manager::ResourceManager,
    material::{Material, PropertyValue},
    core::sstorage::ImmutableString,
};

fn create_brick_material(resource_manager: ResourceManager) -> Material {
    let mut material = Material::standard();

    material.set_property(
        &ImmutableString::new("diffuseTexture"),
        PropertyValue::Sampler {
            value: Some(resource_manager.request_texture("Brick_DiffuseTexture.jpg")),
            fallback: SamplerFallback::White
        })
        .unwrap();

    material
}

As you can see it is pretty simple with standard material, all you need is to set values to desired properties and you good to go. All you need to do is to apply the material, for example it could be mesh surface or some other place that supports materials. For the full list of properties of the standard shader see shader module docs.

Custom material

Custom materials is a bit more complex, you need to get a shader instance using the resource manager and then create the material and populate it with a set of property values.

use fyrox::{
    engine::resource_manager::ResourceManager,
    material::{Material, PropertyValue},
    core::{sstorage::ImmutableString, algebra::Vector3}
};

async fn create_grass_material(resource_manager: ResourceManager) -> Material {
    let shader = resource_manager.request_shader("my_grass_shader.ron").await.unwrap();

    // Here we assume that the material really has the properties defined below.
    let mut material = Material::from_shader(shader, Some(resource_manager));

    material.set_property(
        &ImmutableString::new("windDirection"),
        PropertyValue::Vector3(Vector3::new(1.0, 0.0, 0.5))
        )
        .unwrap();

    material
}

As you can see it is only a bit more hard that with the standard shader. The main difference here is that we using resource manager to get shader instance and the we just use the instance to create material instance. Then we populate properties as usual.

Implementations

impl Material

pub fn standard() -> Self

Creates a new instance of material with the standard shader. For the full list of properties of the standard material see shader module docs.

Example

use fyrox::{
    material::shader::{Shader, SamplerFallback},
    engine::resource_manager::ResourceManager,
    material::{Material, PropertyValue},
    core::sstorage::ImmutableString
};

fn create_brick_material(resource_manager: ResourceManager) -> Material {
    let mut material = Material::standard();

    material.set_property(
        &ImmutableString::new("diffuseTexture"),
        PropertyValue::Sampler {
            value: Some(resource_manager.request_texture("Brick_DiffuseTexture.jpg")),
            fallback: SamplerFallback::White
        })
        .unwrap();

    material
}

pub fn standard_terrain() -> Self

Creates new instance of standard terrain material.

pub fn from_shader(
    shader: Shader,
    resource_manager: Option<ResourceManager>
) -> Self

Creates a new material instance with given shader. Each property will have default values defined in the shader.

It is possible to pass resource manager as a second argument, it is needed to correctly resolve default values of samplers in case if they are bound to some resources - shader’s definition stores only paths to textures. If you pass None, no resolving will be done and every sampler will have None as default value, which in its turn will force engine to use fallback sampler value.

Example

use fyrox::{
    engine::resource_manager::ResourceManager,
    material::{Material, PropertyValue},
    core::{sstorage::ImmutableString, algebra::Vector3}
};

async fn create_grass_material(resource_manager: ResourceManager) -> Material {
    let shader = resource_manager.request_shader("my_grass_shader.ron").await.unwrap();

    // Here we assume that the material really has the properties defined below.
    let mut material = Material::from_shader(shader, Some(resource_manager));

    material.set_property(
        &ImmutableString::new("windDirection"),
        PropertyValue::Vector3(Vector3::new(1.0, 0.0, 0.5))
        )
        .unwrap();

    material
}

pub fn property_ref(&self, name: &ImmutableString) -> Option<&PropertyValue>

Searches for a property with given name.

Complexity

O(1)

Examples

use fyrox::material::Material;

let mut material = Material::standard();

let color = material.property_ref(&ImmutableString::new("diffuseColor")).unwrap().as_color();

pub fn set_property(
    &mut self,
    name: &ImmutableString,
    new_value: PropertyValue
) -> Result<(), MaterialError>

Sets new value of the property with given name.

Type checking

A new value must have the same type as in shader, otherwise an error will be generated. This helps to catch subtle bugs when you passing “almost” identical values to shader, like signed and unsigned integers - both have positive values, but GPU is very strict of what it expects as input value.

Example

let mut material = Material::standard();

assert!(material.set_property(&ImmutableString::new("diffuseColor"), PropertyValue::Color(Color::WHITE)).is_ok());

pub fn shader(&self) -> &Shader

Returns a reference to current shader.

pub fn properties(&self) -> &FxHashMap<ImmutableString, PropertyValue>

Returns immutable reference to internal property storage.

Trait Implementations

impl Clone for Material

fn clone(&self) -> Material

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Material

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Material

fn default() -> Material

Returns the “default value” for a type.

impl Visit for Material where
    Shader: Visit,
    DrawParameters: Visit,
    FxHashMap<ImmutableString, PropertyValue>: Visit, 

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> VisitResult