Jump to content

ShaderBuilder Documentation


Recommended Posts

You are too kind, Naz.  I haven't done much work at all.  Those docs look wonderful.  Nicely done.

But Naz, that documentation is not dynamically generated from the JS/TS, correct?  But shaderBuilder is somewhat complete, yes?  Probably easy maintenance of future changes.  I hope so.  :)  When/If you wish, I will smooth the English..  Maybe I will use a text file... a simple list of "what I would change"... and then you can pick and choose which changes to accept/reject.  We'll talk.

Those docs are NICE, though.  EASY for me to learn things, there. 

Once upon a time, I mentioned to Deltakosh... that I thought period usage like  .Black(1, BABYLONX.Helper().Map({index:'current'}).Build() ... scares new programmers.  With DK, we were talking about camera.input.webVR.OrientationDevice.etc.etc.  I still think... lots of periods... scares new users.

As a docs worker... I struggle to find a way to make it "seem" less scary.

When we first started with BJS, most users do scene.this, camera.that, light.whatever, and mesh.foo.  All ONE-PERIOD targets for both properties and methods. 

Then came { key: value, key: value, key: value }.  THIS was also new to the youngsters... and we are only about 50% toward a goal of making these parameter objects... no longer scare the newbies.

This new(er) system... this.that.foo.theOther.whatever... opens up a whole new area of fear and potential misunderstanding.  How do we teach this?  Some might say that teaching JS is not the job of BJS documentation... but in some ways, it is.  The playgrounds... maybe they are the savior.  The more demos, the better.

NasimiAsl listed "a basic knowledge of shaders" as one of the requirements of becoming a shaderBuilder pro.  Yet, I think ShaderBuilder docs will eventually need to teach some things about how shaders work.  When young users "land" on the shaderBuilder docs, I hope they land on a soft mattress with lots of cookies nearby.  :)  I worry about how to build that welcoming soft mattress.

I think about "soft mattresses" for all of our "not necessarily for children"-level systems.  ShaderBuilder has quite a bit of "not for children" feel to it.  Maybe many playgrounds, maybe diagrams and flow charts, maybe all of it.  I will be glad to make diagrams, but I need to learn more about shaderBuilder, first.  The new docs will help MUCH!  Nice work, Naz.

Link to comment
Share on other sites

  @Wingnut  my purpose of this documentation is Persuasion Experienced BJS Users for Use this Tools .

all Your words is right but  when  i see myself i am not good in English and Writing ( special)  i think i can make good Practical examples (step by Step) and Explain that with my poor writing . for Bjs New Users we have other option (in next version) we have tools for Used Shader Builder without writing source . i think this can be help a lot . in My estimation We can finish that for for 6 or 7 week (i hope) :) . I do my best for ShaderBuilder and after That I have GeometryBuilder Too :) when i see myself location (iran - tehran) . i am truly alone in this stuff but   i look here i see wonderful cooperation thanks all Members :)

  i need sleep Now :) 

Link to comment
Share on other sites

:)  Very nice, Naz.  You're truly amazing. 

Thank you for nice words, too.  You are not alone in Tehran or anywhere, but you are VERY smart.  Locations don't matter.  In my small town, a "computer guru" is someone who can do fast web search and can make a web page.  :D  If I speak "webGL", they think I am a scientist talking about DNA or brain neurons.  heh.

Here, in my town, they talk about weather, go fishing, drink beer, hunt deer, and eat, eat, eat.  I find no computer conversations. 

Maybe I am alien.  Maybe THEY are alien.  Even if I talk about geometry and no programming... I am a professor, according to them.  hehe. 

To make myself "normal", I must drink beer and talk about the weather.  So goofy.  We are alien because of our computer hobby.  For most people, a shader is an umbrella or oak tree.  :D  Funny world we live-in.  Everything is alien until it is familiar.  Whenever you feel alone, Naz, just drink beer and talk about the weather.  New beer/weather friends will be with you, but their conversation will be boring to you.  heh

ShaderBuilder is not so alien to me, but shaders are.  ShaderBuilder will become everyone's friend, with practice.  I predict... that if we make shaderBuilder be our friend, it will make shaders be our/my friend, too.  ShaderBuilder can teach shaders... I think.  Naz, your cool demos help us MUCH MUCH MUCH.  Thank you!  

I still think you are a scientist or professor (genius), but don't feel lonely, please.  We really like scientists and professors, here.  :)  There are many geniuses nearby.  I am honored to be allowed to "hang out" with all you professors.  After 130 years of more study, I will become one, too.

Link to comment
Share on other sites

Hi guys.  As I learn important things about shaderBuilder, I want to pass them along.  Here I am, doing that.


Check out the heading called "Sample For Reference and Deep Fluent".  Pretty "deep" indenting, eh?  I'm not a big fan of things.that.have.lots.of.periods, but I guess it is the modern way or something.  Let's show the example...

1. mesh.material = new BABYLONX.ShaderBuilder()
2. .Map({ path: 'imagePath1' })
3. .Reference(1)
4. .Event(1, // hover
5. BABYLONX.Helper().Red(1,
6.     BABYLONX.Helper()
7.     .Map({ path: 'imagepath2', scaleX: 3., scaleY: 3 })
9.     .Reference(2)
10.    .Red(2,
11.        BABYLONX.Helper()
12.        .Map({ path: 'imagepath3', scaleX: 9., scaleY: 9 })
14.        .Reference(3)
15.        .Red(3,
16.            BABYLONX.Helper()
17.            .Map({ path: 'imagepath3', scaleX: 9., scaleY: 9 })
18.            .Build())
19.        .Build())
20.    .Build())
21. .Build()).BuildMaterial(scene); 

Some of you (including me) are not familiar with a "fluent interface".  (okay, okay, I did a little bit when I worked-with Amiga REXX.)   Anyway, here is a quick doc showing JS used "fluently".

If I suddenly wanted to change the scaleX to 8 in line 17 (sometime later, with a line of code), how does one do that?  How.would.a.user.know.the.path.to.that.map()?  Is there some kind of schema?  :)

They say this "fluent interface" makes code easier to read?  Really?  I think the jury is still in deliberation on THAT one.  :/  Thoughts, anyone?


Link to comment
Share on other sites

HI Wingnut,

my 2 cents: The babylon docs taught me a lot about the theory behind shaders and the fragment/vertex scripts etc... I'm now very comfortable working with these. Nasimi produces the ShaderBuilder which produces great results...but I have never attempted to do anything with it because I don't understand the structure of the logic (each individual line makes sense, but how it all fits together?....which I have now learnt is a 'fluent interface').

If you are still looking for the 'cookie-cushion' approach I would suggest we need at least an intro to this fluent way of writing, given that it ends up so different to anything else in Babylon currently (I think the wikipedia link on fluent language tells people what they don't know, but doesn't really support teaching it).

What would also help me (and I hope others) is some detail of how all of this feeds back to the vertex/fragment shader mindset. Put simply I don't currently see how to convert my vertex/fragment logic into shaderbuilder logic. :) 


Link to comment
Share on other sites


thanks to share your look about this

i hope my explain in this replay help to understand fluent interface about shaderBuilder

we need make 2 string one for vertex shader and the other for fragment shader

i define a simple class 'ShaderBuilder' and define 2 string property in that one for vertex and the other for fragment

class ShaderBuilder{
   string Body{ get;set;} // fragment shader
   string VertexBody{ get;set;} // vertex shader


and i append any result in this variables in each fluent step

class ShaderBuilder{
   string Body{ get;set;} // fragment shader
   string VertexBody{ get;set;} // vertex shader

   ShaderBuilder SampleFluentStep(){  
      this.Body += " shader string source ";

       return  this; // return current instance


and make the last step for make needed shadermaterial 

i get this.Body for the fragmentShader and this.VertexBody for the Vertex Shader

i made the last result in BABYLON.Effect.ShadersStore by Auto Name You can get last result in this array and use that without shaderBuilder


class ShaderBuilder{
   string Body{ get;set;} // fragment shader
   string VertexBody{ get;set;} // vertex shader


   BABYLON.ShaderMaterial BuildMaterial(BABYLON.Scene scene ){
     ...  // source to build an new instance of material
      return ShaderMaterialInstance;


and the usage :

var material = new ShaderBuilder().SampleFluentStep().BuildMaterial(scene);

ask any more question about this i answer anything i know .

 trust me after learn this you have very flexible area in the webgl stuff .

this is not mean you can not have it before this is easy than write shader in any area you have before.

and thanks again for asking :)

Link to comment
Share on other sites

Thanks Nas!  And thanks for your 2-cents, @Xeonzinc.  Yep, many of us need to learn two things.  Fluent AND shaderBuilder... at the same time.  :)

Shaderbuilder is a string stacker, essentially.  It assembles vert and frag shader-strings... piece by piece.  And thus, no more hard-to-work-with huge concatenated strings for shader code.  But we get plenty of shaderbuilder JS code, in exchange.  :)

I think we will discover that shaderbuilder is much better at dynamic shader-code changing.  You can easily make a change in the shader PROGRAMATICALLY (later in the game), and then build it and install it (I think).  No problems with munging through a big string to find values to change.  Change one line of shaderbuilder's "string stacking sequence"... and then re-Build(), and install. Modifying a shader-code value... many times during a game... no problems with shaderbuilder-built shader-code.  Much harder modifying a huge string.

But, I am certainly not a pro, or even a decent beginner.  But I think I am starting to "see the light".  :)  I must say, Naz's demos certainly show amazing results.  If I MUST learn Fluent ways... to drive shaderbuilder nicely, then I think it is worthwhile.  (the demos alone say it is worthwhile) heh.  Nice stuff.  That giant building demo... where he used both geometryBuilder to "grow" the building, and then used shaderBuilder to paint it...  just too too cool.  Phew.  Scary.

Link to comment
Share on other sites

Hi guys.

Ok... in this doc... the word "terms" is used much.  ShaderBuilder Usage Terms.


6.  String result part of source you make with shader language and need to fill result variable.
Result is a vec4 variable and defined before your source and all methods use that like resource of before.
Samples : 'result = vec4(1.,0.,0.,1.);' or 'float v = noise(pos);result = vec4(vec3(v),1.);'

A little rough on the English, but not bad.  Pretty good English, actually.  But I don't quite understand result.

Result is... umm... the result of a previous step of shaderBuilder, and can be used as a resource in the next steps of building?

Does THAT sound right?  The result variable can be handed-along, ever-changing... from SB-step to SB-step... always containing the result of the previous step-activity?

Did I make it worse-sounding, now?  If it IS a hand-along variable... step-to-step... that's pretty cool, huh?  Remember the game called "hot potato"?   It was a "quickly-process-then-hand-on" game.  :D   ShaderBuilder might have a hot potato... called result.

Back in my moo days, I often built "transcluders".  Simple JS-like code that assemble a webpage, by continuously appending little strings onto a result variable.  I used a "generic query" to go "gleaning" values from moo objects, name, location, description, current temp in Idaho, users birthday, current time, blah blah blah.  Assembling little returned pieces of strings... into one big mega-string webpage (dynamic - assembled only when asked-for by a browsee).  Fun. 

But I don't think ShaderBuilder's result variable is the same.  But perhaps.  But perhaps not.   Still learning.  :)

Link to comment
Share on other sites

in the vertex shader and fragment shader we just need a vec4 value in last

gl_Position for Vertex

gl_FragColor for fragment

so when we wanna make shader we suspect to have this values and this is final output

 see the shader builder result :

   new BABYLONX .ShaderBuilder()                   // make Inistance
              .Solid({r:1})                      // Make Solid Color for Result
             .BuildMaterial(scene);              // Make ShaderMaterial


and builded fragment shader =>

void main(void) { 
     int discardState = 0;
     vec4 result = vec4(0.);
      result = vec4(1.,0.,0.,1.); 
     if(discardState == 0)gl_FragColor = result; 

maybe this can explain when used the result 

Link to comment
Share on other sites

Hey, thanks Naz!  That helps.

Recently, I made another buildings demo: http://www.babylonjs-playground.com/#FT2RY#78 

(uses nazpak.js which contains older versions of geometryBuilder and shaderBuilder)

Man, that is a LOT of building, with LITTLE mainline code.  It's just amazing.  I stare at it often, and always drool with envy.

A strange way of making buildings (geometryBuilder), a strange way of painting them (shaderBuilder), and a strange way of programming (Fluent style).  It is difficult to "swallow" all that "strange", but... the results...  wow.  The results are SO FRIGGIN' NICE, that a guy almost HAS TO learn it all.  It's a "technological imperative", it seems.  :)   (drooooool)

Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Recently Browsing   0 members

    • No registered users viewing this page.
  • Create New...