Struct Material

pub struct Material { /* private fields */ }

Material defines a set of resource bindings for a shader. It could be textures and property groups. Textures contains graphical information (such as diffuse, normal, height, emission, etc. maps), while property groups contains numerical values (matrices, vectors, numbers, etc.).

Each resource binding 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 to 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 the 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 resources. 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:

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

    material.bind(
        "diffuseTexture",
        resource_manager.request::<Texture>("Brick_DiffuseTexture.jpg")
    );

    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 (or create a shader in-place by embedding its source code in the binary) and then create the material and populate it with a set of property values.

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);

    material.set_property("windDirection", Vector3::new(1.0, 0.0, 0.5));

    material
}

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

Implementations

impl Material

pub const SHADER: &'static str = "shader"

pub const RESOURCE_BINDINGS: &'static str = "resource_bindings"

impl Material

pub fn standard() -> Self

Creates a new instance of material with the standard shader.

Example

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

    material.bind(
        "diffuseTexture",
        resource_manager.request::<Texture>("Brick_DiffuseTexture.jpg")
    );

    material
}

pub fn standard_2d() -> Self

Creates new instance of standard 2D material.

pub fn standard_particle_system() -> Self

Creates new instance of standard 2D material.

pub fn standard_sprite() -> Self

Creates new instance of standard sprite material.

pub fn standard_two_sides() -> Self

Creates new instance of standard material that renders both sides of a face.

pub fn standard_terrain() -> Self

Creates new instance of standard terrain material.

pub fn standard_tile() -> Self

Creates new instance of standard tile material.

pub fn from_shader(shader: ShaderResource) -> Self

Creates a new material instance with given shader. By default, a material does not store any resource bindings. In this case the renderer will use shader default values for rendering. Materials could be considered as container with values that overwrites shader values.

Example

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);

    material.set_property("windDirection", Vector3::new(1.0, 0.0, 0.5));

    material
}

pub async fn from_file<P>( path: P, io: &dyn ResourceIo, resource_manager: ResourceManager, ) -> Result<Self, MaterialError>

where P: AsRef<Path>,

Loads a material from file.

pub fn binding_ref( &self, name: impl Into<ImmutableString>, ) -> Option<&MaterialResourceBinding>

Searches for a resource binding with the given name and returns immutable reference to it (if any).

Complexity

O(1)

pub fn binding_mut( &mut self, name: impl Into<ImmutableString>, ) -> Option<&mut MaterialResourceBinding>

Searches for a resource binding with the given name and returns mutable reference to it, allowing you to modify the value.

Complexity

O(1)

pub fn texture_ref( &self, name: impl Into<ImmutableString>, ) -> Option<&MaterialTextureBinding>

Searches for a texture with the given name.

pub fn texture_mut( &mut self, name: impl Into<ImmutableString>, ) -> Option<&mut MaterialTextureBinding>

Searches for a texture with the given name.

pub fn property_group_ref( &self, name: impl Into<ImmutableString>, ) -> Option<&MaterialPropertyGroup>

Searches for a property group binding with the given name and returns immutable reference to it (if any).

Complexity

O(1)

Examples

let mut material = Material::standard();

let color = material
    .property_group_ref("properties")
    .unwrap()
    .property_ref("diffuseColor")
    .unwrap()
    .as_color();

pub fn property_group_mut( &mut self, name: impl Into<ImmutableString>, ) -> Option<&mut MaterialPropertyGroup>

Searches for a property group binding with the given name and returns immutable reference to it (if any).

Complexity

O(1)

Examples

use fyrox_impl::core::sstorage::ImmutableString;

let mut material = Material::standard();

let color = material
    .property_group_mut("properties")
    .unwrap()
    .set_property("diffuseColor", Color::RED);

pub fn try_get_or_insert_property_group( &mut self, name: impl Into<ImmutableString>, ) -> &mut MaterialPropertyGroup

Tries to find a property group with the given name, creates a new group with the given name if there’s no such group.

pub fn bind( &mut self, name: impl Into<ImmutableString>, new_value: impl Into<MaterialResourceBinding>, )

Sets new value of the resource binding with given name.

Type checking

A new value must have the same type as in shader, otherwise an error will be generated at attempt to render something with this material.

Example

let mut material = Material::standard();

material.set_property("diffuseColor", Color::WHITE);

pub fn unbind( &mut self, name: impl Into<ImmutableString>, ) -> Option<MaterialResourceBinding>

Tries to remove a resource bound to the given name.

pub fn set_property( &mut self, name: impl Into<ImmutableString>, new_value: impl Into<MaterialProperty>, )

Sets new value of the property with given name to the property group with properties name. It is a standard property group, that could be used to store pretty much any values.

Type checking

A new value must have the same type as in shader, otherwise an error will be generated at attempt to render something with this material.

Example

let mut material = Material::standard();

material.set_property("diffuseColor", Color::WHITE);

// A full equivalent of the above:
material.try_get_or_insert_property_group("properties")
        .set_property("diffuseColor", Color::WHITE);

pub fn shader(&self) -> &ShaderResource

Returns a reference to current shader.

pub fn bindings(&self) -> &FxHashMap<ImmutableString, MaterialResourceBinding>

Returns immutable reference to internal property storage.

pub fn texture( &self, name: impl Into<ImmutableString>, ) -> Option<TextureResource>

Tries to find a sampler with the given name and returns its texture (if any).

Trait Implementations

impl Clone for Material

fn clone(&self) -> Material

Returns a duplicate 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() -> Self

Returns the “default value” for a type.

impl Reflect for Material

where Self: 'static, ShaderResource: Reflect, FxHashMap<ImmutableString, MaterialResourceBinding>: Reflect,

fn source_path() -> &'static str

fn type_name(&self) -> &'static str

fn doc(&self) -> &'static str

fn assembly_name(&self) -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn type_assembly_name() -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn fields_info(&self, func: &mut dyn FnMut(&[FieldInfo<'_, '_>]))

fn into_any(self: Box<Self>) -> Box<dyn Any>

fn set( &mut self, value: Box<dyn Reflect>, ) -> Result<Box<dyn Reflect>, Box<dyn Reflect>>

fn as_any(&self, func: &mut dyn FnMut(&dyn Any))

fn as_any_mut(&mut self, func: &mut dyn FnMut(&mut dyn Any))

fn as_reflect(&self, func: &mut dyn FnMut(&dyn Reflect))

fn as_reflect_mut(&mut self, func: &mut dyn FnMut(&mut dyn Reflect))

fn fields(&self, func: &mut dyn FnMut(&[&dyn Reflect]))

fn fields_mut(&mut self, func: &mut dyn FnMut(&mut [&mut dyn Reflect]))

fn field(&self, name: &str, func: &mut dyn FnMut(Option<&dyn Reflect>))

fn field_mut( &mut self, name: &str, func: &mut dyn FnMut(Option<&mut dyn Reflect>), )

fn set_field( &mut self, field: &str, value: Box<dyn Reflect>, func: &mut dyn FnMut(Result<Box<dyn Reflect>, Box<dyn Reflect>>), )

Calls user method specified with #[reflect(setter = ..)] or falls back to Reflect::field_mut

fn as_array(&self, func: &mut dyn FnMut(Option<&(dyn ReflectArray + 'static)>))

fn as_array_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectArray + 'static)>), )

fn as_list(&self, func: &mut dyn FnMut(Option<&(dyn ReflectList + 'static)>))

fn as_list_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectList + 'static)>), )

fn as_inheritable_variable( &self, func: &mut dyn FnMut(Option<&(dyn ReflectInheritableVariable + 'static)>), )

fn as_inheritable_variable_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectInheritableVariable + 'static)>), )

fn as_hash_map( &self, func: &mut dyn FnMut(Option<&(dyn ReflectHashMap + 'static)>), )

fn as_hash_map_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectHashMap + 'static)>), )

impl ResourceData for Material

fn type_uuid(&self) -> Uuid

Returns unique data type id.

fn save(&mut self, path: &Path) -> Result<(), Box<dyn Error>>

Saves the resource data a file at the specified path. This method is free to decide how the resource data is saved. This is needed, because there are multiple formats that defines various kinds of resources. For example, a rectangular texture could be saved into a bunch of formats, such as png, bmp, tga, jpg etc., but in the engine it is single Texture resource. In any case, produced file should be compatible with a respective resource loader.

fn can_be_saved(&self) -> bool

Returns true if the resource data can be saved to a file, false - otherwise. Not every resource type supports saving, for example there might be temporary resource type that is used only at runtime which does not need saving at all.

impl TypeUuidProvider for Material

fn type_uuid() -> Uuid

Return type UUID.

impl Visit for Material

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

Read or write this value, depending on whether Visitor::is_reading() is true or false.