Introduction

Heaps is a cross platform graphics engine designed for high performance games.

Heaps has been designed to leverage modern GPU that are now commonly available on both desktop and mobile devices.

Heaps currently supports HTML5 WebGL, Flash Stage3D, native Mobile (iOS and Android) and Desktop with OpenGL.

Heaps consists in several top level packages, which are:

Getting Started

In order to get started with Heaps, you need first to:

You should then be ready to run your first example: 

class Main extends hxd.App {
	var bmp : h2d.Bitmap;
	override function initialize() {
		var tile = h2d.Tile.fromColor(0xFF0000, 100, 100);
		bmp = new h2d.Bitmap(tile, s2d);
		bmp.x = s2d.width * 0.5;
		bmp.y = s2d.height * 0.5;
	}
	override function update(dt:Float) {
		bmp.rotation += 0.1;
	}
	static function main() {
		new Main();
	}
}

In order to compile, make sure you have included the Heaps library or have added -lib heaps to your compilation parameters.

You should now be able to compile and display the example. It will show you a rotating red square.

Several examples for both 2D and 3D are available in the heaps samples directory.

----- Part 1 : H2D -----

H2D Concepts

Before entering into the details of h2d, let's introduce a few concepts that we will use in the documentation:

In-Memory Bitmap
A Bitmap (represented by hxd.Bitmap type) is a picture stored in local memory which you can modify and access its individual pixels. In Heaps, before being displayed, a Bitmap need to be turned into a Texture
Texture
a Texture (represented by h3d.mat.Texture type) is a picture that is allocated into the GPU memory. You can no longer access its pixels or modify it in an efficient way. But it can be used to display 3D models or 2D pictures.
Tile
a Tile (represented by h2d.Tile) is a sub part of a Texture. For instance a 256x256 Texture might contain several graphics, such as different the frames of an animated sprite. A Tile will be a part of this texture, it has a (x,y) position and a (width,height) size in pixels. It can also have a pivot position (dx,dy).
Tile Pivot
by default a Tile pivot is to the upper left corner of the part of the texture it represents. The pivot can be moved by modifying the (dx,dy) values of the Tile. For instance by setting the pivot to (-tile.width,-tile.height), it will now be at the bottom right of the Tile. Changing the pivot affects the way Bitmap Sprites are displayed and the way local transformations (such as rotations) are performed.
Sprite
a Sprite (represented by h2d.Sprite) is the base class of all of H2D displayable objects. A Sprite has a position (x,y), a scale (scaleX,scaleY), a rotation. It can contain other Sprites which will inherit its transformations, creating a scene tree
Scene
the Scene (represented by h2d.Scene) is a special Sprite which is at the root of the scene tree. In hxd.App is it accessible with the s2d variable. You will need to add your Sprites to the scene before they can be displayed. The Scene also handles events such as clicks, touch, and keyboard keys.
Bitmap sprite
a Bitmap sprite (represented by h2d.Bitmap) is a Sprite that allows you to display an unique Tile at the sprite position, such as in the previous example.

Now that the basic concepts have been introduced, let's get back to our previous example, this time with comments: 

class Main extends hxd.App {
	var bmp : h2d.Bitmap;
	override function initialize() {
		// allocate a Texture with red color and creates a 100x100 Tile from it
		var tile = h2d.Tile.fromColor(0xFF0000, 100, 100);
		// create a Bitmap sprite, which will display the tile
		// and will be added to our 2D scene (s2d)
		bmp = new h2d.Bitmap(tile, s2d);
		// modify the display position of the Bitmap sprite
		bmp.x = s2d.width * 0.5;
		bmp.y = s2d.height * 0.5;
	}
	// on each frame
	override function update(dt:Float) {
		// increment the display bitmap rotation by 0.1 radians
		bmp.rotation += 0.1;
	}
	static function main() {
		new Main();
	}
}

We can easily make the Bitmap rotate around its center by changing the tile pivot, by adding the following lines: 

	bmp.tile.dx = -50;
	bmp.tile.dy = -50;

Sprite Properties

The following properties and methods can be accessed on any Sprite:

Sprite have other properties and methods which can be discovered by visiting the h2d.Sprite API section.

H2D Drawable

H2D classes that can display something on screen usually extends the h2d.Drawable class.

Each Drawable (including h2d.Bitmap) has then several properties that can be manipulated:

Drawable have other properties which can be discovered by visiting the h2d.Drawable API section.

H2D Animation

Creating an animated sprite in H2D is quite easy.

Instead of using h2d.Bitmap to display a single Tile, you can use h2d.Anim to display a list of tiles that will automatically be played: 

	// creates three tiles with different color
	var t1 = h2d.Tile.fromColor(0xFF0000, 30, 30);
	var t2 = h2d.Tile.fromColor(0x00FF00, 30, 40);
	var t3 = h2d.Tile.fromColor(0x0000FF, 30, 50);
	// creates an animation for these tiles
	var anim = new h2d.Anim([t1,t2,t3],s2d);

The following properties and methods can be accessed on h2d.Anim:

Anim have other properties which can be discovered by visiting the h2d.Anim API section.

Displaying Text

H2D Font

Before start with text manipulation, we must know the h2d.Font class:

  1. h2d.Font is a manager who links each character with his h2d.Tile: it is used to display each letter of a text;
  2. The ressource manager can easily instantiate an h2d.Font;
  3. To instancied a h2d.Font we must have:

Do not forget to add to your compilation parameters the location of your resource files -D resourcesPath=yourPath

Copy the two font files in your resources directory:

You can use h2d.Font like this: 

	// compilation parameter: -D resourcesPath=res
	// location of the files: res/customFont.fnt and res/customFont.png

	// load a bitmap font Resource:
	var font = hxd.Res.customFont.toFont();

H2D Text

h2d.Text extends h2d.Drawable to display text with H2D.

h2d.Text is a text field whose you can easily change the textual content with its property text.

To manipulate easily h2d.Text you can use the following properties:

You should then be ready to display your first text: 

	// load a bitmap font Resource
	var font = hxd.Res.customFont.toFont();
	// adds a red shadow
	tf.dropShadow = { dx : 3, dy : 3, color : 0xFF0000, alpha : 0.8 };
	// creates a text field with this font
	var tf = new h2d.Text(font, s2d);
	tf.text = "Hello h2d!";

Optimizing many Bitmaps

With TileGroup

With SpriteBatch

H2D Events and Interactives

H2D Layers

Filters

Scene size and zoom

Resource Management

----- Part 2 : H3D -----

Scene and Camera

Loading FBX Models

Using HMD Models

Animation system

Mesh Material

Lights

Shadows

Multipass explained

Custom Renderer

----- Part 3 : Shaders -----

HXSL Introduction

Comparison with GLSL

Writing your own Shaders

Runtime Shader linking

----- Part 4 : Sound -----

----- Part 5 : Tools -----

Model Viewer

Particles Editor

Castle DB

----- Part 6 : Misc -----

Gamepad support

2D and 3D collision library

Additional 3D effects

Fog

FXAA

Scalable Ambient Occlusion