Material Slot Filler

In this section you will learn how material slots can be filled automatically via MaterialSlotFiller tool.

Agenda:

• Material Slot Filler basics
• Material Slot Filler usage

Scene setup

Let's use custom scene composer to set up the scene.
Scene consists of:

• Room (MocapRoomAll_GEO) node in the scene split using nine material slots
• Bottle (Bottle_GEO) node with one material slot "Glass" covering the whole node, instanced three times

Material Slot Filler basics

MaterialSlotFiller is a tool allowing for automatic load of materials to the material slots
(check ASSETS_MaterialSlots). Automatic load may be done based on .json file with predefined parameters,
texture files (.png, .jpg, .tiff, etc.) and substance archives (.sbsar).

Predefined materials .json file

You could have noticed that the names for the material slots are self-explanatory. For example, it's obvious
that White Walls is what a CG engineer had in mind with the "WhiteWalls" name. Therefore, some common
self-explanatory material slot names are supported automatically without the need for additional specification.
These automatically supported material slots are saved in a .json file in the main asset directory. Let's print
first 5 materials present in the aforementioned file to see which slots you can expect to be filled
"out of the box":

Texture files and substance archives

Material slot filler has an additional feature: it also loads texture providers from assets
(both from files and Substance) that match the material slot name (e.g. assets from directory "Bricks"
are assigned automatically to the "Bricks" material slot).

Material Slot Filler usage

The MaterialSlotFiller is disabled by default - it needs to be manually enabled.
We can see that the most popular material slots names like "Glass", "WhiteWalls" and others are filled
automatically:

Recursive material search

By default, the MaterialSlotFiller looks for the texture provider matches only in the main assets directory
for the given provider type. To look into all the nested folders too, we can enable recursive material search.

Loading priority

As noted before, it is possible that one material slot matches texture providers in different directories.
It can also have a match both in substance archives and file textures.

The priority between texture provider types can be controlled by the user. It can be set using ordered
iterable of the provider classes (e.g. [SubstanceTextureProvider, FileTextureProvider]
or [FileTextureProvider]) or MaterialSlotLoadingPriority enum
(e.g. MaterialSlotLoadingPriority.SUBSTANCE_FIRST_FILE_TEXTURES_SECOND
or MaterialSlotLoadingPriority.ONLY_FILE_TEXTURES).

The default priority is [FileTextureProvider, SubstanceTextureProvider].

Since previously loaded parameters and texture providers still persist in the context registers, we'll reload
the scene with scene_composer's method that clears context, reloads the scene and enables MaterialSlotFiller.

When only one provider type is given, the other is disabled.

The recursive asset search combined with the loading priority is very useful for prototyping.
It allows to quickly fill the most common material slots with the providers from previous projects or use cases.
However, as it largely depends on the asset structure, it is not recommended to rely on it for the final versions
of your projects.
You can always disable the recursive search and switch back to the default loading priority, but previously
loaded parameters and texture providers still persist in the context registers, so we'll reload the scene.

Defined subdirectories

Often, the assets for a given project are prepared in subdirectories of the assets folder. Instead of enabling the
recursive global search, we can limit the search to these subfolders (one or more).

For even more control, we can disable the search in the main directory. This way the user can limit the search
to the defined subfolders and be sure that only the dedicated materials have been loaded. We can assign subfolders
specifically per asset type using AssetsTypes.TEXTURES or AssetsTypes.SUBSTANCES enum.

Custom predefined material parameters

At the beginning of this tutorial, we printed out the contents of the json file with the default predefined
material parameters.

It is possible to expand this predefined list or to overwrite parameters of some of the material slots -
later definition of the parameters with the same name overwrites previous ones.

Custom parameters must match the predefined_material_parameters.json content format.
The parameters that are default can be omitted.

Randomized predefined material parameters

It is possible to define randomized parameters using this feature. Since randomization is deterministic in
SkyRenderer, we will render two frames and see how base color values change for the bottles. To learn more about
randomization, see the INTRO_Randomization tutorial.

Material Slot Filler usage recap

Part of material slot filler configuration was done with a helper, so now we'll clear the renderer context and
perform the whole configuration explicitly to make it clear what options were used for the image rendered above.

Summary

In this section you have learnt:

• MaterialSlotFiller can be used to load automatically materials from predefined .json file, file textures and
  substance archives.
• MaterialSlotFiller is disabled by default, hence has to be enabled explicitly.
• MaterialSlotFiller can perform recursive search and can use only provided subfolders.
• Loading priority of providers can be changed accordingly from the default FileTexture and Substance order.
• We can customize and randomize predefined material parameters used by MaterialSlotFiller.