Mewa User's Guide/Extending Mewa with custom shaders

From Wikibooks, open books for an open world
Jump to navigation Jump to search

This chapter explains how to extend the out-of-the-box feature set of Mewa with MFX files. MFX files encapsulate GLSL source code and GUI controls description that can be used to create specific image processing algorithms. Once a MFX file is imported it become accessible to the node graph through nodes toolbar, like any other node.

To create MFX files you might need knowledge on GLSL programming. For those who don't know, GLSL is a programming language used to create programs that run on graphics hardware.

MFX Advantages[edit]

Mfx files are text based files containing only GLSL source code and a GUI description. This makes Mfx files cross-platform, able to run on any computer or mobile device with modern hardware.

Mfx files execution happens in the graphics hardware, where processing power is high and is scalable.

Containing only GLSL source code and a description of the GUI controls, creating MFX files is easy and quick. Using it as a node inside Mewa environment the possibilities are endless.

An example[edit]

The best way to start creating MFX effects is to look at examples. MFX files are located in the MFX folder which location depends on the platform running Mewa. On Mewa's main window click on File:InfoButton.png to open the general information window. The MFX folder path is shown in it. You can open any .mfx file in the MFX folder with a text editor and modify it, save the changes and restart Mewa for the changes to take effect. In Mewa the MFX file name is shown in the nodes list.

Node library button

Let's have a look at the HexPixelate effect which pixelates an image with hexagon shaped pixels. Below is the content of HexPixelate.mfx.

Image:
    iChannel0: *
        tip: Pixelates using an hexagonal pattern making each pixel look more like a large dot
        
  Uniform: float
  Name: pixelCount
  UIText: Pixels
  Step: 1
  Min: 3
  Max: 1024
  Default: 120   
  Shader:
    vec2 hexagon(vec2 uv)
    {
        uv *= vec2(0.577350278, 1.0); // hexagonal ratio
        float z = clamp(abs(mod(uv.x+floor(uv.y), 2.0)-1.0)*3.141592653-1.047197551, 0.0, 1.0);
        uv.y = floor(uv.y + z);
        uv.x = (floor(uv.x*0.5 + mod(uv.y, 2.0)*0.5) - mod(uv.y, 2.0)*0.5 + 0.5)*3.464101665; // convert back from hexagonal ratio
        return uv;
    }
    
    void mainImage(out vec4 fragColor, in vec2 fragCoord)
    {
        vec4 tex = texture2D(iChannel0, hexagon(fragCoord * pixelCount)/pixelCount);
        fragColor = vec4(tex.rgb, 1.0);
    }
  • WebPage element contains the web page link to the node's help page.

All Mewa web pages are hosted in wikibooks.org. We want anyone to be able to create an Mfx and publish it. Share your thoughts and ideas through any of the contacts available in www.mewatools.com.

  • iChannel

The element iChannel0 represents the first input, the first node input starting from the left. There can be multiple inputs, with the first one being iChannel0, the second iChannel1 and so on.

The * after iChannel0: means the input will be shown as an node input. Instead of the * an image filename can be set to the iChannel element.

The tip element holds an help message shown in the status bar when the mouse is over the node input.


MFX GUI Controls[edit]

After a description of the inputs comes a description of GUI controls. GUI controls are used to update shader's uniform variables. The GUI controls are visible in Mewa through the node parameters.

Currently, the GLSL data types that are available to use with Mewa GUI controls are:

  • float
  • vec2
  • vec3
  • vec4