App Game Interface Implementation Guide


NOTE:The App Game Interface (AGI) is no longer supported by the Intel® XDK.

For current HTML5 game support in the Intel XDK, see Getting Started with HTML5 Game Development with the Intel XDK.


The App Game Interface technology gives hybrid HTML5 applications the ability to accelerate their canvas tag commands using native device level technologies. It can be accessed from theIntel® XDK. The purpose of this documentation is to help users already familiar with the HTML5 canvas tag learn how to use that same technology to write accelerated graphical applications using App Game Interface (AGI). Furthermore, this guide aims to demonstrate some of the best known methods for writing rich graphical apps for Android* and iOS* using the HTML5 canvas tag commands and the App Game Interface.

Viewing the Sample App in the Intel® XDK

Included with this guide, you’ll find a sample application that demonstrates how the App Game Interface canvas tag acceleration is implemented for iOS and Android devices. The steps below will guide you through loading the sample into the Intel®XDK.

  • Open the Intel XDK.
  • Create a new HTML5 application by clicking the "Projects tab" and selecting "Start a New Project".
  • Import your project from a folder that includes code included in this guide.
  • Switch to the "Emulate" tab to start simulating the app.

Running the Sample on Your Device

To view how App Game Interface canvas acceleration performs on an actual device versus the Intel XDK emulation, you'll need to build the application into a binary. Perform an “adhoc” build for an iOS application, or a regular build on Android. Start by clicking on the "Build" tab within the Intel XDK. Select either an Apple* iOS "ad hoc" build or a Google* Android build. Follow the instructions on the screens presented. Once the app is built, load it on the device for testing. Further instruction materials for building “adhoc” apps on a device can be found at the following locations:

http://www.html5dev-software.intel.com/documentation/index.php?DOC=TUTORIAL_BUILD_BINARY_IOS

http://www.html5dev-software.intel.com/documentation/index.php?DOC=TUTORIAL_BUILD_BINARY_ANDROID

Once you have completed the build and installed the application on your device, you can then view and test the app on that device.

Some History

The App Game Interface technology was originally developed by the HTML5 services company appMobi* (http://www.appmobi.com) under the name of “directCanvas”. Consequently, much of the underlying JavaScript* objects provided by AGI still carry the object name AppMobi. The object was not renamed in an effort to preserve the functionality of previous apps written using this same technology.

App Game Interface Architecture

To use the App Game Interface, you must first understand how it is constructed. The accelerated canvas commands for App Game Interface need to be loaded into its own “view” not unlike an HTML frame, where these commands are interpreted at a lower level and executed at a faster rate. However, this separate view does not include access to the full document object model (DOM) and must rely on a bridging command to communicate between the standard Web “view” and the accelerated “view”.

The code for the accelerated “view” is actually drawn below the HTML5 Web view, which means that any graphical elements included in an AGI application’s HTML file or files will always be rendered above any accelerated graphics.

Best Practices

The following points are “best known practices” for creating a rich graphical app for iOS or Android using App Game Interface. Where it is appropriate, code from the included sample application are provided as an example.

Use a single HTML file

Each time a new HTML page is loaded, the user will see a flash as the new page is drawn on the screen. Developers can prevent this interruption by building their application using a single HTML file. Since the very first HTML file opened is index.html that should be the one worth keeping.

Include the intel.xdk JavaScript bridge library

To get access to the App Game Interfaces JavaScript objects, your application will need to include the intel.xdk JavaScript bridge library in the index.html file. The library is actually served from the application itself whether it is coming from the Intel XDK or from the application. For more information on the intel.xdk JavaScript bridge library check out its documentation here

CSS style concerns

You can’t use a CSS background image or background color on the HTML file because it will cover the underlying graphical AGI layer. Be sure to set the background-color CSS attribute to “transparent”. Additionally, Android selection highlight, iOS select, and WP8* click feedback should all be disabled in CSS.

Creating the AGI view

The AGI view layer is created when the AppMobi.canvas.load() command is called to load a JavaScript library. This JavaScript library should include all the canvas tag calls that are required to draw to the AGI accelerated canvas. Please note that the App Game Interface accelerated canvas layer is always at full screen. Multiple AGI layers may be created by calling several AppMobi.canvas.load() commands, but be aware that more layers tax the resources of the mobile device which could degrade performance.

Add all canvas code to the AGI view

All the JavaScript code used to drive the canvas tag should be loaded into the AGI view using the AppMobi.canvas.load() command or included from within the AGI view using the

In the example application, the AGI view is created and the index.js file is loaded into that view within index.html like this:

//load the AGI view layer AppMobi.canvas.load("index.js");

Once index.js is loaded into the AGI view, a host of other JavaScript libraries are included in the view from that library using the AppMobi.context.include() command.

//use the context.include method to load external JavaScript libraries into the AGI view layer AppMobi.context.include( 'agiDebug.js' ); AppMobi.context.include( 'eventListeners.js' ); AppMobi.context.include( 'screenSizing.js' ); AppMobi.context.include( 'starBackground.js' ); AppMobi.context.include( 'rocketSprite.js' ); AppMobi.context.include( 'spaceRockSprites.js' ); AppMobi.context.include( 'sounds.js' ); AppMobi.context.include( 'animationLoop.js' );

Presenting the canvas commands to the AGI context

Unlike normal calls to the HTML5 canvas tag, the AGI canvas calls are not actually executed until the present() method is called from a reference to AppMobi.canvas.getContext(‘2d’). This method will trigger the App Game Interfaces canvas view to render all canvas operations to the screen. Without it, AGI will not draw a thing.

The sample app calls the present() method at the end of the game loop just before calculating its speed in frames per second. You can find it in the animate() function of the animationLoop.js file.

//the canvas context variable var ctx; if (ctx == null) { var ctx = AppMobi.canvas.getContext("2d"); } … //this function is the animation loop itself function animate() { //clear the screen ctx.fillRect(0,0,w,h); //alternately, this method may be used to clear the screen //fillRect was chosen for this demo instead because it can use opacity to "smear" the starfield and add the illusion of velocity //ctx.clearRect(0, 0, w, h); //draw the background drawStarBackground(); //draw the space rocks drawRockSprites(); //draw the rocket ship drawRocketSprite(); //Tell AGI to present the new frame ctx.present(); //calculate FPS and queue up the next animation frame throttle(); }

Communicating between the AGI layer and the HTML5 layer

With two separate views layered one on top of the other, it will become necessary for one to communicate with the other. For example, events triggered by users touching the HTML5 webview will need to instruct graphic elements running on the AGI view below.

In the HTML5 webview, use the AppMobi.canvas.execute() method to call JavaScript code running in the AGI view. An example of this in the sample application can be found in the index.html file.

//this webview function handles the button touch events and passes information to the AGI view layer to make things happen function laser_fire() { //call the AGI view layer to make something happen AppMobi.canvas.execute("handle_fire_laser();"); //return false to the event handler to keep the event from "bubbling" return false; }

Oftentimes, the opposite is required as well. JavaScript code running in the AGI view layer can call back to the HTML5 webview using a similar command named AppMobi.webview.execute(). The sample application uses just such a call to write debug information to the webview in the agiDebug.js library.

//Use this function to help debug the AGI view portion of the application since the regular console.log method is not available on device var maxDebugLevel = 0; function dbg(txt,debugLevel) { if (debugLevel <= maxDebugLevel) { AppMobi.webview.execute("document.getElementById('debugMessage').innerText = '" + txt + "';"); try { console.log(txt); } catch(e) {} } }

Enabling multiple touch events for Android

App Game Interfaces for the Google Android platform gives developers the ability to interpret multiple screen touches at a time. It is designed to allow game developers to create user interfaces with multiple buttons that can be used simultaneously by players. However, it is not intended for use with gestures where multiple touches could be used on the same HTML element. The Apple iOS platform version does not require this added feature as it already supports multiple touches simultaneously.

The sample application enabled multiple touches immediately within the index.html file.

//enable multi-touch for AGI on Android devices try { AppMobi.multitouch.enable(); } catch(e) {} 

The AppMobi.multitouch.enable method is used to engage multi touch for the Android platform to start listening for multiple touch events from different HTML elements.

Using the AGI sound features

App Game Interfaces has solved many HTML5 sound shortcomings with multi sound enhancements. HTML5 was not designed to play multiple asynchronous sounds with low latency, yet that's exactly what games and other applications need to do. The AGI multi sound technology allows each entity in a game to play sound when it needs to, without regard to any other concurrent sounds. The only limitations are those classic issues - memory and storage.

There are two sets of audio APIs available in App Game Interfaces. The first is the regular HTML5 audio tag. It is available as usual in the HTML5 Webview as well as in the AGI layer. An example of regular HTML5 audio playing from the AGI view is available in the sample. Take a peek in the sounds.js library to find the following code.

// developers can load sounds just as they would in the HTML5 webview by creating a virtual Audio tag. engineSound = new Audio(); //AGI audio tag engineSound.src = "sounds/engines.wav"; engineSound.load();

The second set of APIs are all available via the AppMobi.context object and are meant to provide improved performance and increased ease of use. Complete documentation for the APIs discussed in this section can be found at this URL.

http://www.html5dev-software.intel.com/documentation/gamingAPI/directCanvas/AppMobi/context/index.html

There are three methods available that can be used to control a single (optionally looping) background sound; startBackgroundSound, toggleBackgroundSound and stopBackgroundSound .

Other sounds can be preloaded via loadSound or loadPolySound and then played via playSound. loadPolySound enables multiple copies of a particular sound to be loaded and overlap on playback. That is, for a 3 second sound loaded via loadPolySound('sound.mp3', 3), if playSound('sound.mp3') is called 3 times at 1 second intervals, 3 copies of the sound will play simultaneously. Calls to playSound that exceed the polyCount value or play sounds that were not loaded via loadPolySound will either be ignored or cause the sound to seek to the beginning (depending on several factors intended to prevent performance issues caused by very frequent calls to playSound for a particular sound).

You can then unload individual sounds via unloadSound or use unloadAllSounds to unload all sounds currently loaded.An example of loading a polyphonic sound is available in the sample application in the sounds.js library as well.

//To play a sound in a Accelerated Canvas App Game Interface application repeatedly in a manner that it may overlap itself, //use this method to load the sound for playing later using the playSound method AppMobi.context.loadPolySound("sounds/laser.wav",5);

All app assets must be local

Any assets located on the Internet may not necessarily be available to a natively run app. Files such as images and videos should be referenced using relative path names. They should be located in the same directory that contains index.html, or in a subdirectory underneath that one. Furthermore, since iOS and Android operating systems are case-sensitive, make sure your file references are spelled out using the appropriate case.

Limitations of App Game Interface

There are a few limitations to AGI that an HTML5 developer should be aware of. First, AGI does not have access to the DOM. Be aware that calls that would normally work, such as console.log or alert() can crash an AGI-enabled app without warning despite the fact that these are available in the Intel XDK simulator of AGI. Don’t be surprised when an application taking advantage of AGI works in the Intel XDK but not on device.

Consider creating a debug helper function to use in development such as the one included in the sample application.

//Use this function to help debug the AGI view portion of the application since the regular console.log method is not available on device var maxDebugLevel = 0; function dbg(txt,debugLevel) { if (debugLevel <= maxDebugLevel) { AppMobi.webview.execute("document.getElementById('debugMessage').innerText = '" + txt + "';"); try { console.log(txt); } catch(e) {} } }

AGI is not a complete implementation of the HTML5 canvas tag specification. Several commands are missing and a few are added for developers’ convenience. For a matrix detailing the current command differences, take a look at the online documentation here:

http://www.html5dev-software.intel.com/documentation/resources/pregenPages/AGIFeaturesMatrix.html

Make sure to test on device early and often, and your App Game Interface accelerated canvas application should help you develop an attractive and responsive application.

Download Code

有关编译器优化的更完整信息,请参阅优化通知