Multi-pass Shader

Description

This extension allows you to use and have more control over multi-pass shaders.

In this extension, multi-pass shaders refer to shaders that the output of the shader is used for an input for the next frame. The number of passes can be limited or unlimited depending on your needs.

Good example for multi-pass shaders can be simulation shaders (cellular automata, reaction diffusion, fluid simulation etc.)

Package contains 2 demo rooms.

1. Generating maps on GPU using Cellular Automata
2. Reaction Diffusion on GPU (Images created with this: http://cembaspinar.com/reaction-diffusion.html )

NOTE: Multipass shaders should have these uniforms for the extension to work properly:

    uniform sampler2D u_sample; // output of prev frame
    uniform vec2 u_resolution;
    uniform float u_iteration; // current pass no

Setting of these uniforms are done by the extension automatically. Use sha_multipass_blank as a template for your shaders.

NOTE2: Only tested on Windows.

HOW TO USE IT

Creates a multi-pass shader output using surfaces, backgrounds or sprites.

Basic Usage:

// ON CREATE EVENT:
multipass_shader_init(); // Sets required enums

mps = multipass_shader_create_from_sprite(shader, 
                                          spr);
// or use these depending on your source:
// mps = multipass_shader_create_from_surface(surface);
// mps = multipass_shader_create_from_background(bg); 
// these will create a multipass object.

// ON DRAW EVENT:
// Draw it with desired width and height.
// Use 1 to increment passes one by one.
// If you use 5, passes will advance 5 by 5. (0, 5, ...)
multipass_shader_draw_result(mps, 1, x, y, w, h);

// ON GAME/ROOM END EVENT:
multipass_shader_free(mps); // frees cached surfaces.

Advanced Example:

On some occasions you may need to split step and draw actions. For example, this will be the case if you are using a second shader that is just used while drawing.

// CREATE EVENT
mps = multipass_shader_create_from_background(shader, 
        somebg, 
        width,   
        height, 
        10,      // pass_limit: Will apply only 10 times
        true,    // draw even between 0-9 passes
        scr_rd_get_uniforms,  // script to get uniforms
        scr_rd_set_uniforms); // script to set uniforms

// STEP EVENT
if (playing) { // Optional boolean to play and stop
    for (var i=0; i<pass_inc; i++) {  // Let's say 5
        // Calculates 5 times
        multipass_shader_step(mps);
    }
}

// DRAW EVENT
shader_set(some_other_shader); // just to show it is possible
    // Draws once
    multipass_shader_draw(mps, x, y, 
                          room_width, room_height);
shader_reset();

// GAME END EVENT
// Always clean after you are done.
multipass_shader_free(mps);

EXTRAS

*multipass_shader_create_from_sprite(shader, [optional parameters..]);*

multipass_shader_create_from_*() scripts takes several 
optional parameters. Here is the list:


    width:     width of the input. Gets from the asset
               if left blank.

    height:    height of the input. Gets from the asset
               if left blank.

    num_of_passes_int: 
               How many passes you want it to apply the 
               shader? Use -1 if you don't want a limit.

    show_after_limit_bool:      
               Draw results before the pass limit is
               reached? If you are not sure what to 
               enter, use 'true'.

    custom_get_uniform_script: 
               If the multipass shader requires you to
               use uniforms, create a script and use
               the script as an argument here.

    custom_set_uniform_script:
               If the multipass shader requires you to
               use uniforms, create a script and use
               it as an argument here.


*multipass_shader_get_surface(mps);*

Returns the current surface that multipass is going to
apply the shader to.

*multipass_shader_get_surface_previous(mps);*

Returns the previous surface that multipass has applied
the shader to.

Always remember to clean up memory after you are done:
multipass_shader_free(mps);

EXTENSION FILES

The package contains files related to the demonstration application. You don't need every file for the extension to function. Required files are GPU_Toolkit>Multi-pass Shader scripts.

OPEN SOURCE

The project will also be available Github which you may use to ask questions, report bugs or contribute any other way. All the scripts and shaders are licensed under MIT.

End User Licence Agreement (EULA).

Age Rating: 4+