~~NOTOC~~

====== Batch Renderer ======

---- dataentry extension ----
author_mail   : lazarecki@gmail.com Łukasz Łazarecki
description   : Batch Renderer lets you create custom display object, post processing effects and custom shaders in a easy to learn, quick and pleasant way :) If you need to render a custom geometry (not a Quad) or do a custom texture processing, it may be just the thing for you. Visit its GitHub page for more details and a tutorial.

lastupdate_dt : 2014-01-23 # the date you created the extension
compatible    : v1.4.1     # the Starling version you tested the extension with
depends       : Starling, EasyAGAL# if the ext. depends on others, list them here
tags          : batch,renderer,shader,AGAL,EasyAGAL
homepage_url  : https://github.com/b005t3r/Starling-Extension-BatchRenderer
download_url  : https://github.com/b005t3r/Starling-Extension-BatchRenderer
----

===== Overview =====

Please visit [[https://github.com/b005t3r/Starling-Extension-BatchRenderer/|BatchRenderer GitHub page]] for a more detailed description.

To use it, first you need to subclass BatchRenderer class:

<code as3>
use namespace renderer_internal;

public class TexturedGeometryRenderer extends BatchRenderer {
    public static const POSITION:String         = "position";
    public static const UV:String               = "uv";

    public static const INPUT_TEXTURE:String    = "inputTexture";

    private var _positionID:int, _uvID:int;

    // shader variables
    private var uv:IRegister = VARYING[0];  // v0 is used to pass interpolated uv from vertex to fragment shader

    public function TexturedGeometryRenderer() {
        setVertexFormat(createVertexFormat());
    }

    public function get inputTexture():Texture { return getInputTexture(INPUT_TEXTURE); }
    public function set inputTexture(value:Texture):void { setInputTexture(INPUT_TEXTURE, value); }

    public function getVertexPosition(vertex:int, position:Vector.<Number> = null):Vector.<Number> { return getVertexData(vertex, _positionID, position); }
    public function setVertexPosition(vertex:int, x:Number, y:Number):void { setVertexData(vertex, _positionID, x, y); }

    public function getVertexUV(vertex:int, uv:Vector.<Number> = null):Vector.<Number> { return getVertexData(vertex, _uvID, uv); }
    public function setVertexUV(vertex:int, u:Number, v:Number):void { setVertexData(vertex, _uvID, u, v); }

    override protected function vertexShaderCode():void {
        comment("output vertex position");
        multiply4x4(OUTPUT, getVertexAttribute(POSITION), getRegisterConstant(PROJECTION_MATRIX));

        comment("pass uv to fragment shader");
        move(uv, getVertexAttribute(UV));
    }

    override protected function fragmentShaderCode():void {
        var input:ISampler = getTextureSampler(INPUT_TEXTURE);

        comment("sample the texture and send resulting color to the output");
        sampleTexture(OUTPUT, uv, input, [TextureFlag.TYPE_2D, TextureFlag.MODE_CLAMP, TextureFlag.FILTER_LINEAR, TextureFlag.MIP_NONE]);
    }

    private function createVertexFormat():VertexFormat {
        var format:VertexFormat = new VertexFormat();

        _positionID = format.addProperty(POSITION, 2);  // x, y; id: 0
        _uvID       = format.addProperty(UV, 2);        // u, v; id: 1

        return format;
    }
}
</code>

Then you set up your geometry, set its vertex data and input textures and/or constants, if your shader requires you to:

<code as3>
// add a new quad
var vertex:int = BatchRendererUtil.addQuad(texturedRenderer);

// setup Quad's vertices position...
texturedRenderer.setVertexPosition(vertex    ,  0,    0);
texturedRenderer.setVertexPosition(vertex + 1, 100,   0);
texturedRenderer.setVertexPosition(vertex + 2,   0, 100);
texturedRenderer.setVertexPosition(vertex + 3, 100, 100);

// ... UV mapping...
texturedRenderer.setVertexUV(vertex    , 0, 0);
texturedRenderer.setVertexUV(vertex + 1, 1, 0);
texturedRenderer.setVertexUV(vertex + 2, 0, 1);
texturedRenderer.setVertexUV(vertex + 3, 1, 1);

// ... and an input texture
texturedRenderer.inputTexture = Texture.fromBitmap(new AmazingBitmap());
</code>

And finally you make it render stuff either to a texture:

<code as3>
// create rendering settings to be used
settings               = new RenderingSettings();
settings.blendMode     = BlendMode.NORMAL;
settings.clearColor    = 0xcccccc;
settings.clearAlpha    = 1.0;

// and render!
var outputTexture:RenderTexture = new RenderTexture(1024, 1024, false);
texturedRenderer.renderToTexture(renderTexture, settings);
</code>

... or the back buffer (using a wrapper DisplayObject):

<code as3>
var wrapper:BatchRendererWrapper = new BatchRendererWrapper(texturedRenderer);
addChild(wrapper);
</code>

That's it :) Once again, visit the [[https://github.com/b005t3r/Starling-Extension-BatchRenderer/|BatchRenderer GitHub page]] for a more detailed tutorial.

===== Changelog =====

  * //2014/01/23 12:58//: First public version

===== Source Code =====

[[https://github.com/b005t3r/Starling-Extension-BatchRenderer/|BatchRenderer GitHub page]]