
## Custom Frames

<Youtube id="_bxAQM0pnzs"/>

<Youtube id="9wL777qGpiI"/>

![NME](/img/how_to/Materials/custom_frames_1.jpg)

When using the node material editor we can create frames by holding shift and dragging the mouse across nodes within the graph.

A frame is an easy way to group several nodes together and collapse them into a smaller group to declutter the graph and allow you to reuse certain node branches. We can rename the frame, change its color, and even make a note/comment about it.

When we collapse the node, input and output ports that are linked to other nodes outside of the grame, will be exposed on the frame edges. (You can manually set a port to be exposed as well). Here we can edit the exposed ports by renaming them or even changing the order.

![NME](/img/how_to/Materials/custom_frames_2.jpg)

We can export a frame by using the “Export” button.

Once exported, we can load it back into our project for future use by clicking the “+” symbol on the “Custom Frames” tab of the node menu, in the left panel. 

![NME](/img/how_to/Materials/custom_frames_3.jpg)

By loading a custom frame, we can reuse it quickly just like any other node block. Custom frames will stay in this menu any time you open the node material editor. 

![NME](/img/how_to/Materials/custom_frames_4.jpg)

We also have a library of custom frames available for you to leverage here: https://github.com/BabylonJS/Assets/tree/master/nme/customFrames

### Tile and Offset

This custom frame is primarly used to tile and/or offset `UV`s, but you can use it to modify any `Vector2`.

Example setup (you have to set your texture to generate some visible output):

![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-setup.png)

Some example values and the results are provided in the following table:

 tileX | tileY | offsetX | offsetY | result                                                                       
 ----- | ----- | ------- | ------- | ---------------------------------------------------------------------------- 
 1     | 1     | 0       | 0       | ![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-1-1-0-0.jpg)  
 2     | 4     | 0       | 0       | ![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-2-4-0-0.jpg)  
 3     | 1     | 0       | 0       | ![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-3-1-0-0.jpg)  
 1     | 1     | 0       | 0.5     | ![Tile and Offset](/img/resources/nme-custom-frames/tile-offset-1-1-0-05.jpg) 

### UV Twirl

You can use this custom frame to twirl the UV's and create twirled textures.

Connect the custom frame:

![UV Twirl](/img/resources/nme-custom-frames/uv-twirl-setup.png)

The output is the original texture:

![UV Twirl](/img/resources/nme-custom-frames/uv-twirl-start.png)

By changing the `strength` value the image gets twirled around the `center`:

![UV Twirl](/img/resources/nme-custom-frames/uv-twirl-twirled.png)

### Screen Position

A normalized screen position from 0,0 (bottom left) to 1,1 (top, right)

![Screen Position](/img/resources/nme-custom-frames/screen-position-setup.png)

produces this output:

![Screen Position](/img/resources/nme-custom-frames/screen-position-output.png)


## Custom Blocks

Starting with v5.0 you can now create custom blocks by wrapping some plain GLSL code. It can come in handy when you have some complicated code that could be difficult to recreate with the existing node material blocks.

### Register Custom Blocks with the NME

At the time, a custom block is described by a .json file that you must provide when registering a new custom block in the node material editor:

![Register Custom Block](/img/how_to/Materials/customBlock_register.jpg)

When clicking on the "+" icon to add (register) a new custom block, you will be requested for the .json file that describes the block.

Here's how a **Multiply** custom block could be implemented:
```json
{
    "name": "CustomMultiply",
    "comments": "Multiplies the left and right inputs of the same type together",
    "target": "Neutral",
    "inParameters": [
        {
            "name": "left",
            "type": "AutoDetect"
        },
        {
            "name": "right",
            "type": "AutoDetect"
        }
    ],
    "outParameters": [
        {
            "name": "output",
            "type": "BasedOnInput",
            "typeFromInput": "left"
        }
    ],
    "inLinkedConnectionTypes" : [
        {
            "input1": "left",
            "input2": "right",
            "looseCoupling": false
        }
    ],
    "functionName": "multiply_{TYPE_left}",
    "code": [
        "{TYPE_output} myHelper_{TYPE_left}({TYPE_left} l, {TYPE_right} r) { return l * r; }",
        "void multiply_{TYPE_left}({TYPE_left} l, {TYPE_right} r, out {TYPE_output} result) {",
        "   result = myHelper_{TYPE_left}(l, r);",
        "}"
    ]    
}
```
Most of the properties should be self-explanatory. Here are the possible values for some of the properties:
* target: **Neutral**, **Vertex**, **Fragment**, **VertexAndFragment**
* in/out parameters: **Float**, **Int**, **Vector2**, **Vector3**, **Vector4**, **Color3**, **Color4**, **Matrix**, **Object**, **AutoDetect**, **BasedOnInput**

As this block allows any type of input (**Float**, **Vector3**, etc as the **AutoDetect** value shows for the **left** and **right** parameter types), the type of **output** is set to `BasedOnInput` to inherit the value of the input that will be plugged to **left** (value of `typeFromInput`) at runtime. Also, we want the types of the **left** and **right** inputs to be the same (once an input is plugged, the other one should inherit the same type), that's why we have a `inLinkedConnectionTypes` section in the file.

As the types are not known at the time we create the .json file, we must reference them in the GLSL code by using the special syntax `{TYPE_XXX}` where **XXX** is the name of an input/output: at runtime, these constructs will be replaced by the right type (**float**, **vec2**, etc).

Note that we used a `myHelper_{TYPE_left}` helper function only to demonstrate that you can use other functions in the code, you don't have to write all your code in the main function.

Last thing, the main function (the one which is exported in the **functionName** property) must return `void` and the output parameter(s) that it returns must be declared as **out** parameters of the function (see example).

### Using Custom Blocks

Custom blocks are no different from the other blocks, so you simply need to drag&drop a block from the list on the left to the main area:

![Register Custom Block](/img/how_to/Materials/customBlock_use.jpg)

Here, the `myPerlin2D` block is a `Perlin2D` custom block (see the list of custom blocks in the left menu).

This block has been imported into the NME with this .json file:
```json
{
    "name": "Perlin2D",
    "comments": "Generates a Perlin noise single value given a vec2 and time",
    "target": "Neutral",
    "inParameters": [
        {
            "name": "p",
            "type": "Vector2"
        },
        {
            "name": "dim",
            "type": "Float"
        },
        {
            "name": "time",
            "type": "Float"
        }
    ],
    "outParameters": [
        {
            "name": "output",
            "type": "Float"
        }
    ],
    "functionName": "perlin",
    "code": [
        "float rand(vec2 co){return fract(sin(dot(co.xy ,vec2(12.9898,78.233))) * 43758.5453);}", 
        "float rand(vec2 co, float l) {return rand(vec2(rand(co), l));}", 
        "float rand(vec2 co, float l, float t) {return rand(vec2(rand(co, l), t));}", 
        "", 
        "void perlin(vec2 p, float dim, float time, out float result) {", 
        "   vec2 pos = floor(p * dim);", 
        "   vec2 posx = pos + vec2(1.0, 0.0);", 
        "   vec2 posy = pos + vec2(0.0, 1.0);", 
        "   vec2 posxy = pos + vec2(1.0);", 
        "   ", 
        "   float c = rand(pos, dim, time);", 
        "   float cx = rand(posx, dim, time);", 
        "   float cy = rand(posy, dim, time);", 
        "   float cxy = rand(posxy, dim, time);", 
        "   ", 
        "   vec2 d = fract(p * dim);", 
        "   d = -0.5 * cos(d * 3.14159265358979323846) + 0.5;", 
        "   ", 
        "   float ccx = mix(c, cx, d.x);", 
        "   float cycxy = mix(cy, cxy, d.x);", 
        "   float center = mix(ccx, cycxy, d.y);", 
        "   ", 
        "   result = center * 2.0 - 1.0;", 
        "}"
    ]    
}
```

Here's the link to the NME: <NME id="#3WEKUZ#1" title="Custom Perlin2D block" description="A node material which is using a custom Perlin2D block" image="/img/playgroundsAndNMEs/NMEPerlin2DCustomBlock.jpg"/>


## Creating Shaders The Easy Way

Creating shaders can be a very dense and complicated process, often requiring knowledge of glsl and a strong understanding of how shaders work. Starting with Babylon.js 4.1, the Node Material Editor was introduced. This amazing tool is a visual editor allowing you to connect blocks together to make shaders. It's really that simple. 

<img src="/img/how_to/Materials/nme1.jpg" title="Babylon.js Node Material Editor"/>

You can jump in and play around with it here: <NME id="" title="Node Material Editor" description="The starting basic template for creating Node Materials."/>

For an introductory look at the Node Material Editor, check out where it all started with this video:

<Youtube id="34uIGJH0ySU"/>

When you're ready to learn more, head on over to the [Node Material Documentation](/features/divingDeeper/materials/node_material/nodeMaterial) for more info.

You can also dive into the API that powers it all here: [API documentation.](/typedoc/classes/babylon.nodematerial)

tileX	tileY	offsetX	offsetY	result
tileX 1	tileY 1	offsetX 0	offsetY 0	result
tileX 2	tileY 4	offsetX 0	offsetY 0	result
tileX 3	tileY 1	offsetX 0	offsetY 0	result
tileX 1	tileY 1	offsetX 0	offsetY 0.5	result

Node Material Editor Custom Frames

Custom Frames

Tile and Offset

UV Twirl

Screen Position