Mewa User's Guide/Extending Mewa with custom shaders

This chapter explains how to extend Mewa with custom GLSL shaders. In Mewa a GLSL shader is held by a node.

At the core of Mewa is a script engine that executes Mewa script files. Mewa scripts are text files with .mw file extension. Nodes are created through the execution of a script.

The available scripts are listed in the nodes menu. The names shown in the menu are the scripts' file name. Clicking in a menu entry will execute the respective script.



When creating Mewa nodes it is a good idea to look at examples and modify them. Mewa script files are located in the scripts directory. Open any script file, apply some changes and execute it to observe the result.

Example
Let's start with a simple script.

In this example, we will create a script that will generate a new node called MyImage. To create the script make a new text file named MyImage.mw and paste the text below into the file.

The Mewa script file above contains the GLSL shader code, within quotation marks, and a Mewa API call to create the Mewa node.

The shader code implements the mainImage function. This function is called once per pixel. The fragCoord argument contains the pixel coordinate in normalized coordinates. fragCoord values range always from 0 to 1, and covers the whole viewport. The output color for each pixel is stored in fragColor.

The variable iTime is an input variable provided by Mewa.

Now let's install it and run it.

The Scripts directory
Mewa script files are located in one directory, which we call the scripts directory. Its location depends on the platform Mewa is running on.

To find the scripts directory, on Mewa's main window click. The general information window will open showing the scripts directory.

Run the script
To run our newly created script open the nodes menu clicking the nodes button. A list of all the scripts located inside the scripts directory is shown.



The names shown in the nodes menu are the scripts' file names. To start the execution of our script click in MyImage entry. A node called MyImage0 is added to the node-graph. Clicking on the output button, the squared button on the right side of the node, opens the output window showing the output of our node. See screenshot below.



Shader inputs
Below is the list of all input variables that Mewa makes available to all shaders:

Add node inputs
In the example we've created above, the result node has no inputs.

To produce a shader node that takes an input image we introduce the variable iChannel0 to our shader source.

Let's now create a new text file named MyFilter.mw with the following content:

Place the MyFilter.mw file in scripts directory and run it from the nodes menu.



MyFilter node now offers 1 input and 1 output.

The shader simply renders the input texture into its output.

Add GUI Controls
Now that we have a node running a shader let's add an input variable to the shader and change its value using a GUI control.

The script below adds the input variable uNumber into the shader source and a uiControl to control the value of the uNumber variable.

The last 4 lines of the script set up the GUI control.

addFloatControl creates the GUI widget and adds it to the node parameters window. Its arguments are the variable name, used inside the shader source, and its 2nd argument is its initial value.

The GUI controls are visible in Mewa through the node parameters. To open the node parameters click on the circular button on the right side of the node.



Change the parameter value and watch the result in the output window.

Set Shader Render Area
As we build the node-graph, translating/scaling images is a common operation and the ability to limit the shader processing area inside the image rectangle is important to prevent the whole viewport from being rendered.

Depending on the use case of a node, we have to choose 1 of 3 options:


 * "iResolution"
 * The main function mainImage( fragColor, fragCoord ) accepts 2 input arguments, where fragCoord goes always from 0 to 1, and covers the whole viewport.
 * Used to generate procedural images by computing the color for each pixel.
 * "iChannel0"
 * In this option the shader processes only the area covered by the image iChannel0. The main function mainImage( fragColor, fragCoord ) takes 2 input arguments with fragCoord holding the texture coordinates of the input image. fragCoord range does not necessarily starts at 0 and ends at 1, but it will be in any range within the 0 and 1 limits.
 * Used to apply an image processing filters on an image
 * "iChannel0+iChannel1"
 * The main function mainImage( fragColor, fragCoord0, fragCoord1 ) accepts 3 input arguments, with fragCoord0 and fragCoord1 the texture coordinates of the 2 input images
 * Used to blend/merge 2 input images

The chosen option is set with the setRenderArea function.



For an example on how to use the "iChannel0+iChannel1" option see OverlayBlend.mw script located in your scripts directory.

Develop with ShaderToy
ShaderToy is an in-browser environment to create shaders. Shaders developed in ShaderToy can be easily used in Mewa by applying small changes.

Some differences between Mewa shaders and ShaderToy shaders are:
 * The fragColor argument passed in main function holds pixels values. In Mewa fragColor contains normalized pixel values, within the 0 to 1 limits.
 * While ShaderToy uses texture function to retrieve the color of an input texture, Mewa uses the GLSL function texture2D.

Publish Your Script
Scripts can be published in Mewatools WebStore, an online repository of Mewa Addons.