Add more examples and explanations to "Material Plugins" doc?

Questions
1

I would like to say “material plugins” is a great feature! It opens the door to extend while keeps the solid implement of PBRMaterial.

But the document is not detailed enough to get more people like me to release the power of plugins.

For example, I want to create a plugin which adds a texture as a mask to PBRMaterial. And I struggled several hours but could not make it work. Until I saw this comment:

Because I followed the doc firstly. And the doc mentions “PBR material includes several complex plugins”. (at the end of link) So I opened the source code such as material.detailMapConfiguration.ts and lost my way.

We can compare the example in the comment and detailMapConfiguration. For learning purpose, detailMapConfiguration is too complex. Taking detailSampler for example:

First, it has no getCustomCode method. Which is main logic as usual. Though I found related code in the bumpFragment.fx, I cannot find where defined “uniform sampler2D detailSampler”. I even used Spector.js to check the fragment code. And since there are methods like getSamplers, I thought it will add the declaration for me.

Second, it lacks key point as an example. The code considers too many cases. Like, blocking before texture ready, texture dirty resolving, many operations between on and off, etc. It even has a special defines. They mislead me to think I have to handle all of logics.

Third, it is not a good resource to follow if I want to write the plugin as good as it. As I cannot know why I have to write code like that. Special case? Performance? Are there other cases I have to handle? As a result, I can only write something like a demo. It may be broken in the case I don’t know, or is not efficient.

To clarify, code insides getCustomCode should not be the main part of the doc. It is shader logic. And the doc should focus on the “plugin logic”.

BTW, as the plugin mechanism is like a “inject”, is it possible to open these inject point to node material? It is more convenient to deem PBRMaterial as blocks and we can add more. Yes there are PBRMetallicRoughnessBlock in node material right now. But it lacks some handles like fog. If I want to replace the imported gltf model’s PBRMaterial with node material, how many things I have to align with?

2

@yuqian I love your insights on this topic and would be great if you would be willing to contribute to the doc to enhance it ?

2 Likes
3

That would be cool! More doc is always a good thing

4

@sebavan @Deltakosh Hi, thanks for your interest but… but I mean I lack the background knowledge to write a good plugin :sweat_smile:

I still cannot figure out why detailMapConfiguration does not have to add the uniform sampler2D detailSampler manually.

About the doc, I think I can add a revise version of the PG by Evgeni_Popov. But I cannot tell more detials and cautions. Which is more important for a plugin.

In a word, I can just write some plugins “just work” according to the doc. I wonder if it is dev user’s duty to dig into the whole logic underneath. Or, someone can provide more details about every method of MaterialPluginBase and things like life-cycles. Without that details, the “plugin” is more like a innner abstraction instead of a plugin.

5

Ok feedback taken :wink: Maybe @sebavan we can track it with an issue to improve that doc (cc @PirateJC )

6

it does reference the sampler here: https://github.com/sebavan/Babylon.js/blob/master/packages/dev/core/src/Materials/material.detailMapConfiguration.ts#L186

If you wonder why they are not adding custom code, it is mainly because the shader code was already in our uber shader, we only extracted the JS code side.

And yes would be great to track it for @Evgeni_Popov :slight_smile:

7

@PirateJC do you want me to open an issue to track this? :slight_smile:

8

Sure thing! Thanks @carolhmj !

9

Add more examples and content to Material Plugins doc · Issue #600 · BabylonJS/Documentation (github.com) issue opened!

2 Likes