Tutorial

Basics

IvanK Lib is JavaScript 2D graphics library for GPU-accelerated <canvas> element. You can create a display object tree, which is rasterized by WebGL using colored or textured triangles. Graphic elements and events in IvanK have nothing to do with Display Object Model (DOM) or Cascading Style Sheets (CSS). You don't have to know DOM or CSS to use IvanK.

Each IvanK application always has a full size of HTML page. If you want it to be bigger or smaller, insert it into another webpage using <iframe> tag.

The center of coordinate system is the top left corner. X axis goes right, Y goes down. Metric units are pixels. Background of IvanK is transparent, so you can see the web page and other HTML elements behind the IFRAME.

The root of display tree is always a Stage object. It's created using var s = new Stage("canvas_id"), where "canvas_id" is an ID of target Canvas.

IvanK is almost a subset of standard Flash classes. When you don't know how to get something done, you can search the internet for Flash / AS3 tutorials.

Class hierarchy

Event model

A class, which can dispatch or listen to events, should be a descendant of EventDispatcher. It has methods dispatchEvent, addEventListener and removeEventListener.

Some events are dispatched automatically by IvanK, such as ADDED_TO_STAGE or mouse events. You can listen to them in your code.

Mouse Events

As you move the mouse cursor over your IvanK.js application, the system is registering a Path, which is a list of InteractiveObjects located under cursor. The Path goes from Stage to the End - the last, "deepest" object on the path. It may look like this:

stage:Stage -> form:Sprite -> button:Sprite -> label:TextField

All mouse events are dispatched on the End of Path and they are "bubbling up" to the Stage. Bubbling means, that event is dispatched on the End - in label, and it "bubbles up" from child to parent, up to the stage being dispatched on every object in that Path.

MouseEvent.target is the End of Path of that event. MouseEvent.currentTarget is an object, which currently dispatches that event.

InteractiveObject.mouseEnabled says, whether that object can be at the End of the Path.

DisplayObjectContainer.mouseChildren says, whether its children can occur in the Path (it still "owns" their area).

Stage.focus is the latest End, which was clicked. KeyboardEvents are dispatched on Stage.focus.

With IvanK, you can disable the standard context menu (usually shown on right mouse click). It is disabled, when stage has MouseEvent.RIGHT_CLICK listener.

3D graphics

IvanK.js is high-level library and it does not offer an access to GPU buffers, shaders or any WebGL commands. The main 3D function is Graphics.drawTriangles3D, which allows to draw colored or textured triangles.

Every DisplayObject has it's 3D transformation properties: x/y/z, scaleX/scaleY/scaleZ and rotationX/rotationY/rotationZ. The whole transformation can be accessed as matrix through DisplayObject.transform.matrix3D. It can be used to connect the graphics with physical engines etc.

Best practice

When you are working on a large project (larger than any of demos), it is very useful to inherit your classes from IvanK classes and put some logic into them. Other good practice is, that each "node" in display tree accesses only the direct children and dispatches events to parent. It does it's work and does not care about sub-children or objects above it.

Here is an example of how to "extend classes" of IvanK: Custom classes demo.

BitmapData

There is a difference between BitmapData in IvanK and Flash. In IvanK, it is used both to load and access an image. You can not access pixels (or image width, height), until BitmapData image is loaded. BitmapData has "loader" property, which dispatches Event.COMPLETE event, when an image is loaded.

You can load or create textures using any other method (Image element, XMLHttpRequest, from different Canvas, from Video element, from webcam ...) and get your raw pixel data into BitmapData using BitmapData.empty(...), BitmapData.setPixels(...). This way you can build your own custom preloaders etc.

Textures in WebGL

When you are testing your app locally, you may see some errors when loading textures. For security reasons, JavaScript is allowed to access only resources from the same domain. So, if you want to use images in your app, you must upload your app to a web server, or install some local HTTP server (LightTPD) or turn off the security mode (e.g. "--disable-web-security" parameter for Chrome).