The Engine & Contexts

The engine

Every Famo.us application begins with the engine. The engine is a singleton object that is responsible for orchestrating all of the components in your application. There should only be one engine per Famo.us application. Most of the time, you will use the engine only to create a context, but we’ll cover some other important uses here too.

Creating a context

Contexts are the home for visible elements. We create one using the engine’s .createContext() method. When this method runs, a DOM element is created. That context element is given a single child, <div class="famous-container"></div>, whose children are renderable elements. Contexts themselves are not displayed; they are merely containers for renderables.

var Engine = famous.core.Engine;
var context = Engine.createContext();

When creating a context this way, the document’s <body> will be used as the context for the application.

Creating a context within a specific element

We don’t have to create a context using the <body>. If desired, we can create a context out of another specific DOM element. Simply pass that element to the .createContext() method:

var Engine = famous.core.Engine;
var element = document.getElementById('mycontext');
var context = Engine.createContext(element);

Heads up! If you want to initialize a Famo.us context in a specific context, you may want to disable app mode.

Disabling appMode

App mode is a special setting in Famo.us that has two main effects:

Browser scrolling is disabled, giving control of scroll events to Famo.us
The document, body, and window are assigned styles for presenting a full-viewport application

We can use the engine to disable app mode. You may want to do this when initializing Famo.us inside a specific element:

var Engine = famous.core.Engine;
Engine.setOptions({
  appMode: false
});
var context = Engine.createContext();
// etc.

Note that you need to disable app mode before creating the context for the setting to work properly.

Specifying a framerate

You can also set the maximum framerate at which the engine will operate. The engine will throttle the render loop to prevent it from going over the limit you set:

Engine.setOptions({
  fpsCap: 30
});

The value passed is the desired maximum frames to display per second.

Scheduling functions

The engine provides two functions for scheduling. The first, .nextTick(), will execute the passed function on the very next tick of the engine:

Engine.nextTick(function() {
  // This function will run only once,
  // invoked on the very next tick of
  // the engine.
});

The other function, .defer(), will execute the given function at a time that is unlikely to affect the engine’s framerate. This method is useful when you want your application to do asynchronous work.

Engine.defer(function() {
  // This function will run only once,
  // as soon as it can be run without
  // affecting framerate.
});

Using engine events

The engine emits a handful of events useful to hook into when creating complex application logic. The first of them, 'prerender', runs every frame, before any contexts are updated (i.e., before any render tree elements are rendered).

Engine.on('prerender', function() {
  // Be careful what you do here! This function
  // will be run on every single engine tick.
});

There’s also a 'postrender' event that runs after all context have been updated:

Engine.on('postrender', function() {
  // Be careful what you do here! This function
  // will be run on every single engine tick.
});

A 'resize' event is triggered whenever the window is resized.

Engine.on('resize', function() {
  // This function runs any time the window is
  // resized. You may want to debounce this
  // function, for performance.
});

Contexts

When you invoke Engine.createContext(), a context object is returned. The context object represents a top-level container for renderable elements. It keeps a reference to the DOM element used to contain renderables (such as surfaces), and forms the root of the render tree. In practice, you’ll rarely use contexts directly, but it’s worth covering a few key uses. Although your Famo.us application may have multiple contexts, it’s most common to use just one.

Setting context perspective

Each context object has a .setPerspective() method. This method takes an integer as its first argument, an optional transition object as its second argument, and an optional callback function as the third. Setting the perspective changes the apparent distance between the screen and 3D objects, changing the way renderables look when transformed in space. This operation’s effects are most apparent when rotating elements along the Y- or X- axis; the vanishing point changes.

// @famous-block
// @famous-block-option preset famous-0.3.0-globals
// @famous-block-group perspective
// @famous-block-option textPanelActive true
var Engine = famous.core.Engine;
var Surface = famous.core.Surface;
var Modifier = famous.core.Modifier;
var Transform = famous.core.Transform;

var context = Engine.createContext();
context.setPerspective(1000);

var modifier = new Modifier({
  transform: Transform.rotateY(0.5)
});

var surface = new Surface({
  size: [200, 200],
  content: 'Hello world',
  properties: {
    backgroundColor: '#fa5c4f'
  }
});

context.add(modifier).add(surface);

// @famous-block
// @famous-block-option preset famous-0.3.0-globals
// @famous-block-group perspective
// @famous-block-filename en.md
# Keeping things in perspective

Changes in perspective aren't readily apparent until we rotate an element in space.

Here, we've rotated the surface around the Y-axis using a transform, so you can see the effect.

Try changing the value passed to `.setPerspective()`. You'll quickly see how changes affect the distortion of the surface (line 7).

Setting context size

You can explicitly set the viewport size of a context, too, using the context object’s .setSize() method. The first and only argument is an array of two elements representing an X and a Y pixel value for size:

var Engine = famous.core.Engine;
var context = Engine.createContext();
context.setSize([100, 100]);

Next: The Famo.us stylesheet »