#FOAM - A WebGL toolkit

Foam is a condensed collection of tools for building procedural graphics in WebGL. It tries to be as 'low'-level as possible (in a browser/js sense) whilst handling and abstracting repetitive tasks such as scene, animation loop and user input setup. Foam provides thin abstractions for commonly used scene-related objects such as cameras, textures, basic geometry, light and material representations as well as WebGL objects like shader programs, vbos, fbos and others.

Foam requires strong knowledge in WebGL and shader development. If you don't want to deal with shaders and just quickly display your mesh using some predefined material and lighting, this might not be the right tool for you.

Advantages & Disadvantages – Goals – Structure – Install - Usage – Templates – Build – Documentation – Dependencies – License

##Advantages & Disadvantages

• Foam has a very thin abstraction layer, which allows you to safely access any 'bare-bone' WebGL functionality you need (except shader program binding) without breaking any Foam internal states.
• Foam focuses on writing shaders. Unlike other libraries or frameworks you won't find any prepackaged materials, complex lighting and shadowing setups or post-processing filters. That's your job. – But there are small shader templates to help get you started.
• Although you can load external models, Foam mainly focuses on generating geometry programmatically.
• Loading every resource asynchronously on scene init can be quite cumbersome, especially when dealing with multiple glsl files, texture images and additional resources. Foam uses a resource bundle loader which you can feed with a list of resources. It will load all of them, report errors and after completely processing the list init your program with a resource dictionary. This is not mandatory, you can still load and process every single resource on its own.
• Foam offers wrappers around WebGL base objects such as programs, vertex and index buffers, framebuffers and textures.
• Foam reintroduces the fixed pipeline matrix stack model. Welcome back: glTranslate, glScale, glRotate, glMultMatrix, glPushMatrix and glPopMatrix as well as some additional matrix transformation methods.
• It is sometimes necessary to quickly test a visual idea. Therefore, Foam offers an optional 'immediate mode' style, which allows drawing mesh data and 2d & 3d primitives without previously allocating any object.
• Solid text rendering of generated BitmapFonts using the wonderful opentype.js – An OpenType and TrueType font parser.
• Foam uses the common.js module pattern via browserify

##Goals

Foam tries to be as generic and structurally open as possible by not forcing you to adopt a certain way of building your scenes or managing the objects within it. You may choose to use the built-in geometry or light representations or simply drop them and just use Foam for setting up your app and resources and write everything with raw WebGL calls. If you need a scene graph, build it on top. – This flexibility is a core idea of Foam. – Therefore Foam will never compete with WebGL frameworks like Three.js or others.

Additional functionalities may be added with extensions.

##Structure

• App core – Canvas setup, user input, resource bundle handling and update loop setup
• Graphics – Offers aforementioned cameras (perspective, orthographic, frustum and arcball rotation), generic material & light representations and geometric models which can be extended with custom attributes and uniforms, as well as text rendering, 'immediate mode' drawing via glDraw, and matrix stack manipulation via glTrans. Basic access to drawing methods, transformations and raw WebGL can be gained by inheriting from glObject.
• WebGL objects – Shader program, vbo, fbo, textures
• Geometry – Axis aligned bounding boxes, planes, rectangles, to be extended
• Math – 2d & 3d vectors, matrices, quaternions and utilities
• Extras – Colour representation, Filewatcher, WebWorker console

##Install

Context Node (not yet published)

npm install foam-gl

Context html (browserified standalone)

<script type="text/javascript" src="foam.js"></script>

##Usage

A typical project structure is as follows:

project/
|
|-- src/
|   |-- app.js        //your application
|   |-- program.glsl  //the main shader
|
|-- index.html  //minimum html
|-- bundle.js   //browserified app.js

With a minimum html boilerplate:

<!DOCTYPE html>
<html>
<head>
    <title></title>
    <script src="bundle.js"></script>
    <style>
        html,body{margin: 0;padding: 0;}
        canvas{vertical-align: bottom;}
    </style>
</head>
<body>
</body>
</html>

And app.js:

var Foam = require('foam-gl');

var CameraPersp = Foam.CameraPersp,
    Program     = Foam.Program,
    Texture     = Foam.Texture,
    Vec3        = Foam.Vec3;

//inits app with ressources on window load 
Foam.App.newOnLoadWithResources({ 
    // Resource obj
    shader : {path:pathToShader},
    image  : {path:pathToImage,type:'image'},
},{ 
    // App obj
    setup : function(resources){
        this.setFPS(60); 
        this.setWindowSize(800,600);
        
        this._program = new Program(resources.shader);
        this._program.bind();
        
        this._texture = Texture.fromImage(resources.image);
        
        this._program.uniform1i('uTexture', this._texture.getUnit());
            
        this._camera = new CameraPersp();
        this._camera.setAspectRatio(this.getAspectRatio());
        this._camera.lookAt(Vec3.one(),Vec3.zero());
        this._camera.updateMatrices();
        
        var gl = this._gl;
        
        gl.viewport(0,0,this.getWindowWidth(),this.getWindowHeight());    
        gl.clearColor(0.25,0.25,0.25,1.0);
        gl.enable(gl.DEPTH_TEST);    
    },
    
    update : function(){
        var gl      = this._gl,
            glTrans = this._glTrans,
            glDraw  = this._glDraw;
        
        var camera  = this._camera;
        var program = this._program;
        var t = this.getSecondsElapsed();
        
        gl.clear(gl.BUFFER_BIT | gl.DEPTH_BIT);
        
        camera.setDistance((0.5 + Math.sin(t) * 0.5) * 2.0);
        camera.updateViewMatrix();
        
        glTrans.setCameraMatrices(camera);
            
        program.uniform1f('uUseTexture',0.0);
            
        glDraw.drawPivot();
        
        program.uniform1f('uUseTexture',1.0);
        
        glTrans.pushMatrix();
        glTrans.translate3f(0,Math.sin(t * 0.5),0);
        glTrans.rotate3f(t,0,0);
        glDraw.drawCubeColored(); // draw test cube
        glTrans.popMatrix();
    }
});

Which equals (regarding application initialisation):

var Foam = require('foam-gl');

function App(canvas,resources){
    Foam.App.apply(this,arguments);
}
App.prototype = Object.create(Foam.App.prototype);
App.prototype.constructor = App;

App.prototype.setup  = function(resources){}
App.prototype.update = function(){};

window.addEventListener('load',function(){
    var app;
    Foam.Resource.load(
        { // Resource obj
            shaderA : {path:pathToShaderA},
            shaderB : {path:pathToShaderB}
        },
        function(resources){
            app = new App(null,resources);
        }
});

####Context node-webkit

• browserify app.js, gen index.html / package.son, zip it, run nodeWebkit, start remote debug session
• buildNodeWebkit.sh
• [more]

####Context node-webgl

• [more]

##Templates

(will change) Foam offers project templates to get you started quickly. It generates an index.html and src folder containing a program.glsl and app.js file depending on the template type you provide.

scripts/new -p newProjectPath -t [TEMPLATE] [-s] [-w]

| Arg | Value | Description | | ---- | -------- | ----------------------------------------------------------- | | -o | path | path of the new project | | -t | template | glsl & app.js template: basic2d, basic3d, basic3dTexture, basic3dLight |
| -s | | only creates app.js & program.glsl (optional) | | -w | | watchify app.js (optional) |

##Build

(will change)

browserify index.js -o pathOut -s foam-gl -d

##Dependencies

Opentype – A JavaScript parser for TrueType and OpenType fonts
Minimist - Argument parser
Watchify - Update any source file and your browserify bundle will be recompiled on the spot.

##License

MIT License

Copyright (c) 2013 - 2015 Henryk Wollik. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to, use copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.