Home

Some proposals for kami v 1.0.0.

key features

• modularity - follow the unix philosophy and only do "one thing"
• unit tests - kami doesn't currently have any. all modules should have their own unit testing. for now the tests will simply run in a WebGL browser (i.e. no testling-ci 😦 )
• composability - composes (somewhat) well with non-kami modules, like modules-gl and ndarray.
• documentation - improved docs on running and building

API changes

• hide constructor; the new keyword is optional
• for constructors: use an object for options instead of flat arguments
• the first argument to most classes can be a kami-context or a regular WebGLRenderingContext. If the former is passed, the object will be managed and re-created on context restore.
• sprite batching will use ortho matrices instead of a 2d projection vector. this will break shader code
• TextureRegion may break to become more agnostic of kami, and usable with modules-gl

--

modules

Kami is split into many modules in order to achieve different tasks. Each module tries to focus on a single task, and attempts to find a balance between flexible low-level needs and convenient high-level APIs.

Although many of these modules are prefixed with kami-, they are not necessarily specific to it. They all take generic WebGLRenderingContext in the constructors, so you can just as easily use any WebGL framework you please.

Primary modules:

• kami-context - sets up a GL context; passing this to Textures and Shaders will have them managed during context loss events
• kami-texture - a wrapper around glTexImage2D
• kami-shader - a minimal shader utility
• kami-batch - a 2D sprite batcher, can render images from gl-module or kami
• kami-fbo - 2D framebuffer (render-to-texture) utilities for kami

Internal modules: (may not be useful to the average layperson)

• kami-mesh-buffer - a vertex/index buffer wrapper
• kami-util - misc utilities that are shared across many kami modules
• webgl-compile-shader - kami-shader uses this to compile the shader with sane error logging

Generic modules: (not specific to kami, but often used alongside it)

• webgl-context - gets a GL context; will not handle context loss
• texture-region - a texture region in UV coordinates, ideal for sprite batching

Various utils:

• kami-white-texture - creates a 1x1 white texture, ideal for tinted lines and rectangles

composability example

Here is an example of using a kami renderer alongside unrelated gl-texture2d. Typically this wouldn't be encouraged, but it's nice to have it as an option and also shows that all the modules in play are indeed just focusing on "one thing."

//setup an empty GL canvas
var gl = require('webgl-context')({
    width: 512,
    height: 512
});

//grab a ndarray texture
var pixels = require('baboon');

//load the image with modules-gl
var tex = require('gl-texture2d')(gl, pixels);

//create a sprite batcher
var batch = require('kami-batch')(gl);

//draw the image with kami
batch.begin();

//draw at 85% opacity
batch.setColor(1,1,1,0.85);
batch.draw(tex, 0, 0, 512, 512);

//draw it smaller at full color
batch.setColor(1);
batch.draw(tex, 25, 25, 15, 50);

batch.end();

//add canvas to DOM
document.body.appendChild( gl.canvas );