Jean-Marc Le Roux Web, RIAs and chocolate spaghettis…

Tutorial: Your first Minko application

In this tutorial we will see how to create your first scene with Minko. At the end of this tutorial, you will have nothing but a colored rectangle. Before you follow this tutorial it is recommended to read the "Getting started with Minko 2" article in order to learn how to setup your programming environment.

Creating the Viewport

Instanciating a new Viewport object

The first step before rendering anything is to have a rendering area. In Minko, this rendering area is called the "viewport" and is represented by a Viewport object. The viewport can be seen as the middle-man between the classic 2D rendering list and the hardware accelerated 3D rendering. Indeed, the Viewport class extends the Sprite class so it will behave like any other rendering element of the display list: it has a (x, y) position, a width, a height, etc...

Creating the viewport is really simple:

var viewport : Viewport = new Viewport();

The Viewport constructor accepts the following arguments:

• antiAliasing : uint, the anti-aliasing level to use when rendering in this viewport; this value can be 0, 2, 4 or 8 and the default value is 0
• width : uint, the width of the viewport; the default value is 0 to make the viewport fit its parent width automatically
• height : uint, the height of the viewport; the default value is 0 to make the viewport fit its parent height automatically

There a few things to remember about a viewport though:

• The viewport can only be behind or infront of all the other elements in the display list. This is because of a technical limitation of the Stage3D API. To make the viewport visible infront, you should set the Viewport.alwaysOnTop property to true.
• If the viewport is set to resized itself automatically according to its parent's size (ie. the Viewport constructor was built with width == height == 0), then you have to make sure its parent actually has a size different from 0

The following code snippet will create a 640x480 viewport with 4x anti-aliasing and move it in (100, 200):

var viewport : Viewport = new Viewport(4, 640, 480);

Adding the viewport to the display list

Just like any DisplayObject, the Viewport must be added to the stage to be visible. As it behaves like any other DisplayObject, you can simply use the addChild() method to add it to the display list:

var viewport : Viewport = new Viewport();
 
stage.addChild(viewport);

The viewport can be added to any DisplayObjectContainer, just make sure its parent has a proper width and height if you are working with an automatically resized Viewport.

Rendering into the viewport

As you can see, even with the viewport added to the Stage, there is no visual change. That's because the viewport is empty as long as we don't use it to render a scene. Now that we have a rendering area, we should render something in it! For now, we will just create an empty scene and render it in this viewport:

var scene : Scene = new Scene();
var viewport : Viewport = new Viewport();
 
stage.addChild(viewport);
scene.render(viewport);

This code snippet creates a new Viewport and a new Scene objects. Then, it adds the Viewport to the Stage and renders the Scene in that very Viewport. The immediate consequence is that our viewport will now be filled with black. Our viewport is completely black because we just rendered an empty scene and the default background color of the Viewport is black.

Manipulating the Viewport

Setting the background color

You can change the background color of the viewport by setting the Viewport.backgroundColor property. This property holds the background color of the viewport in the RGBA format:

// setting the background color to "blue"
viewport.backgroundColor = 0x0000ffff;

The alpha component of the background color is not used for now and is here only for forward compatibility.

Resizing the viewport

You can resize the viewport by setting the Viewport.width and Viewport.height properties:

// set the viewport width to 640
viewport.width = 640;

Everytime you set the Viewport.width or the Viewport.height property, the Viewport.resized signal is executed. Thus, in order to avoid executing unnecessary signals when you want to set both the width and the height of the viewport, it is recommended to use the Viewport.resize() method:

viewport.resize(640, 480);

This way, the Viewport.resized signal will be executed only once at the end of the Viewport.resize() method when the viewport has been successfully resized.

Moving the viewport

You can move the viewport using the Viewport.x and Viewport.y properties. It will behave just like any other DisplayObject element: the final position of the viewport is affected by the transformation applied by its parents. Thus, if you add the Viewport in a Sprite and if you move that Sprite, the viewport will move as well.

// move the viewport to the (100, 200) position
viewport.x = 100;
viewport.y = 200;

Conclusion

The following code sample describe the basic structure of a main class used to create a new Minko application:

public class MinkoApplication extends Sprite
{
  private var _viewport : Viewport;
  private var _scene : Scene;
 
  protected function get scene() : Scene
  {
    return _scene;
  }
 
  protected function get viewport() : Viewport
  {
    return _viewport;
  }
 
  public function MinkoApplication()
  {
    super();
 
    // make sure the stage is available
    if (stage)
      initialize();
    else
      addEventListener(Event.ADDED_TO_STAGE, initialize);
  }
 
  private function initialize(event : Event = null) : void
  {
    removeEventListener(Event.ADDED_TO_STAGE, initialize);
 
    // create the viewport
    _viewport = new Viewport();
    // add the viewport to the stage
    stage.addChild(_viewport);
 
    initializeScene();
 
    addEventListener(Event.ENTER_FRAME, enterFrameHandler);
  }
 
  protected function initializeScene() : void
  {
    // create an empty scene
    _scene = new Scene();    
  }
 
  protected function enterFrameHandler(event : Event) : void
  {
    // render a frame
    _scene.render(_viewport);
  }
}

You can re-use this class as you main class everytime you want to create a new 3D app!