Posted on

Android + HXCPP – a Quickstart Guide

After having some success with making an Xcode template, I thought it would be relatively easy make something similar for eclipse and Android. However, there was nothing but pain for me when I tried, so instead I’ve decided to write this guide.

Prerequisites

There are quite a few prerequisites you need to organize before you can get things going. Android allows building from Windows, Mac and Linux. The procedures are quite similar, except that Windows requires some messing about with Cygwin binaries. The method described here avoids most of the Cygwin pain \- and the google make sytem pain \- by avoiding the google make sysem altogether.

  • Download and install the Android SDK. This is the Java tools and libraries required for building and debugging byte-code applications.
  • Download and install eclipse IDE. This is the IDE that runs the SDK – follow the instructions on the Android SDK page and install the Android plugins too.
  • Install the USB drivers for your device (if required). For my device (HTC Legend) I found the drivers on the phone itself by using it as a thumb drive.

You should now be in a position to build some sample (byte-code) applications for your device.

  • Download the Android Native Development Kit. This allows you to build binary code for your device. Now for HXCPP, it is very important to download the latest build provided at Crystax.net, which is a build done by a generous community member that corrects some of the glaring omissions of the official build, namely RTTI and exceptions. If it is all the same to you, extract it to c:/tools/android-ndk for Windows, and ~/tools/android-ndk for other systems, and this will make the remaining instructions easier.
  • Currenly on Windows, you need the svn version of HXCPP (slightly newer that 2.06.1) which has some include path fixes. See the instructions at http://code.google.com/p/hxcpp/ for getting the latest version.
  • Also on windows, you need the Cygwin dlls in your path. One way to do this is to install the whole Cygwin toolchain and put it in your path. The other way so to drop the two dlls from cygwin-extra.tgz into the ndk binary directory, ie c:/tools/android-ndk/build/prebuilt/windows/arm-eabi-4.4.0/bin.

Project structure

An android project consists several components that all work together.

  • Java Code. The Java code provided in the sample project comes from a couple of places. Because the project is graphics based, the copy NME Java code is included. If the version of NME increases, it may be desirable to update the NME code, either by copying the new code in, or instead linking to the NME code directly. Also, the HXCPP bootstrap Java code is included along with a small Activity wrapper file.
  • Native code. The shared object files provide native code for running on the device. These include the standard libraries, the NME library and the haxe code compiled with hxcpp.
  • AndroidManifest.xml. This controls how your application is deployed, and quite a few things can be done with this file. It is best to consult the Android documentation about what can be done here.
  • Resources & Assets. These can be useful if you want to add standard menus or other GUI elements to your application.

The basic workflow starts by making a change to your haxe source files. You then compile the haxe code to Android cpp, which is in turn is compiled to an android shared object. This .so file is then copied to the libs/armeabi directory in the project. Because eclipse does not recognize a change to the shared objects as a important update, it is then necessary to touch one of the Java files so that eclipse rebuilds the project. These steps are handled by the build_haxe batch/shell scripts provided with the project, so all you should have to do is change the code and run the script. Then, press the “play” button in eclipse(the first time you do this, you may need to specify Run-As Android Project) and your application should launch.

The haxe code included in the sample directory uses a fixed class name, AndroidMain, as the bootstrap point for building the haxe shared object, libAndroidMain.so. By fixing these names, the build script is simplified. I encourage you to put your main code for the application outside the provided project directory, and edit the AndroidMain.hx and build.hxml files to point to this external application code. This will help with cross-platform development, and keep the boiler-plate code separate from your precious source code.

Creating a New Project

I could not find a very nice way to make a project template, so this is what I’ve come up with. First, download and extract the example project, android-2.06.1.tgz. You may like to rename the parent directory from android-2.06 to something more meaningful at this stage.

At this point, you should be able to build the sample haxe code using the build-scripts provided. This requires your prerequisite installations to be good, so it is worth testing. If you have downloaded the android-ndk to a different location, you can edit the appropriate build script to reflect this. You will need the latest NME code from haxelib. Windows users may also need the svn version of HXCPP.

So that all worked? Congratulations, your system is set up for development.

Next, fire up eclipse, and create a “File – New Project..”, then select “Android Project”, then select “Create project from existing source”, and browse to your newly created directory. You will notice that down the bottom of the Dialog, the properties are filled out with names from the sample project – we will change these next. Once you select “Finish”, your project should be created, and ready to run on your device.

The project and package names are tied into Java and Android naming conventions, as well as the Android manifest, and can be difficult to budge. It is easiest to use the eclipse Refactor-Rename menu option to change the name from “MyActivity” to something more appropriate for you, say “CircleDisplay”. Then in the source tree under “src”, there is a file in com.company called “MyActivity.Java”. Select this, and use the menu option to change its name to “CircleDisplay” too. Similarly, select the “com.company” and change this to something else, in my case “com.gamehaxe” (select preview and agree to everything). There is one final change required – the refactor option misses a reference in the AndroidManifest.xml because it starts with a period. Double click this and in the “AndroidManifest.xml” tab, change the “.MyActivity” to “.CircleDisplay”.

It is important to rename these items because it effects how your application is ultimately stored in the device.

So now you should be good to go – press the play button and select “Android Project”.

There are quite a few things that can go wrong with so many things to install, so I’ve got my fingers crossed for you.

Posted on

New Releases!

Finally, I’ve managed to make a few more releases. Namely, HXCPP 2.06 and NME 2.0.
HXCPP can be downloaded via “haxelib”, and works with the new 2.06 version of haxe. This release contains many bug fixes and optimizations. Also, when you compile with the -debug flag, you can get additional null checks and stack dumps.
NME 2 is a complete rewrite from the ground up. Most of the logic has been moved from neash to the c++ code for optimization reasons.
For NME developers this only means a couple of things:

  • You use –remap flash=nme instead of –remap flash=neash
  • The “boot” code has changed, so you will need to follow the main line from one of the samples.
  • Improved performance!

I updated my Xcode SDK, which caused a bunch of link errors linking for the simulator with the NME library. It seems Apple have changed the “ABI” for objc (basically, broke binary compatibility). So I must choose pre 4.0, post 4.0 or both. I think I am going to require NME iphone simulator users to have the latest SDK – unless there are any objections?

iPhone Xcode Template

I finally got around to making an Xcode template for haxe compiling. Try it out and let me know if it works. It’s my first one, so I’m open to ideas for improving it.

To use the template, first extract it to your developer template area, eg: /Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Project Templates/Application.
Then when you create an new Xcode project, this template should show up. You should be able to build for the simulator.

To build for a real device, you will need to go though the official Apple developer program, and get yourself signed up. Then you need to get your certificates in order, and finally edit the “plist” file in the Resources folder and change the company URL to match the one you used in your certificates.

You can edit Main.hx code in the “haxe/src” directory, but you will probably want to locate your haxe source tree outside your project area, since we are multi-platform developers an do not want to tie ourselves to Xcode. To do this, you can edit the class path in the Build.xml file, and change the boot code in IPhoneMain.hx. It is done this way so the haxe-generated library always has the same name. If all else fails, you can have a look in the makefile, which is set up to allow building debug and release versions for iphoneos and simulator without having to change other project settings.

Let me know if you have any luck.

Posted on

3 Years On

Wow, has it really been 3 years? 2009 was an interesting year – I guess the big ticket items were haxe for the iPhone and getting hxcpp into the standard distribution for haxe. I am very satisfied with these achievements, however there is still quite a bit of polish to add – especially in terms of ease-of-use.
I also started some other projects – fastcgi for haxe, and “waxe“, the wx/haxe interface, as well as continuing with neash and nme development. One of the big changes for hxcpp, although not visible, was using an internal garbage collector which has improved performance and reduced the compile dependence on a library that is hard to debug on other peoples machines.

Currenly, I’m working on an NME rewrite to remove GPL code from the iPhone target, and to help integration. Now that hxcpp has reached a certain level of quality, the diverse projects are starting to coalesce and I’m pushing ahead with a complete hxcpp/nme/iphone solution which should be very useful.

Looks like 2010 may be the year it all comes together (hopefully!).

Posted on

Quick Update

Just a quick update to let you know things are still moving forwards. I have not done very much iPhone specific stuff recently, but I have been working on the graphics code base in general. The idea is to separate the graphics code from SDL (although still use SDL most of the time) to avoid GPL issues and also allow the library to be used in a wider set of applications rather than just games. For example, inside a window in a larger desktop application, or inside Google’s Native Client plugin. Another goal is to improve rendering speed by minimising the amount of data moved between haxe and the graphics code – this involves moving code logic from haxe into c++. I have also been looking at a few minor tweaks such as setting object widths/alphas like flash does.

Once this is done and moved into Neash/NME, I will fix a few of the remaining issues on the C++ backend – maybe even get to add dynamic properties to the runtime. I would also like to spend a bit of time finishing off the internal garbage collection to make it thread-safe and run automatically – this could solve some of the problems compiling boehm-gc on various systems.

And, of course, I would like to write more tutorials…

Posted on

Haxe3D C++ Demo.

Nicolas Cannasse has written a 3D engine for flash 10. I have ported this code to neko and c++ using the neash library.

h3d

To test the code, first extract the contents of the zip and then look in the bin directory. Double click the h3d.exe or h3d_ogl.bat files to run the c++ version (the h3d\_ogl.bat uses opengl, the other version uses the software renderer). You can see the flash version from the .html file (note: you will need flash player 10). You can run the neko if you have the haxelib version of nme installed by running “neko h3d.n”. All the source files are there in case you want to do some mods.

I have changed the mouse-look scheme from the original code to keep things a bit more centred. Move the mouse left/right to spin the objects, move it up/down to raise or lower the camera. You can use ‘w’ key for wireframe and the ‘p’ key for shading effects.

On my faster computer, I get about 100fps for the opengl renderer, 80fps for the software renderer, 40fps for the flash10 renderer, and 1fps for the neko/software renderer. There are some optimisations that could be done for the neash API, but really significant improvements could be gained by moving some of the engine into c++ code.

Currently, it is windows only. You can get it here.

Update:

There were reports of preformance loss in opengl, and I think I may have traced it to excessive texture transactions due to the text in the status panel. To work around this, I have cached the text as glyph bitmaps (doing this was on my todo list) which seems to have helped. (This update is in the svn version of neash). I have also added a command-line switch to use a simple fps counter instead of the status panel. You can try this out with the h3d\_ogl\_simple.bat command, In the new download.

Posted on

WordPress markdown.php Unknown modifier '|'

So all of a sudden, all the posts started showing preg\_replace\_callback() [function.preg-replace-callback]: Unknown modifier ‘|’ in …/wp-content/plugins/text-control/markdown.php. I presume this was because my provider changed php versions. There are 2 possible fixes:

  1. Disable your markdown plugin
  2. Fix the markdown.php file, if you can edit it. This problem was a couple of lines above the one reported, one of the opening braces (“{“) had a back-slash quote where it should not have. ie, it was …(?:[ ]\{$md_tab_width}… but shold just be …(?:[ ]{$md_tab_width}…
Posted on

GM2D.com – New Sister Site

I’ve just launched a new site, GM2D.com, about making games in 2D. The new site is more about tutorials and documentation for haxe, flash, NME and Neash libraries, as well as general documentation, while this site will remain more about technology and experimentation. I hope the new site will help motivate me to bring out some more documentation and promote some of the great things that are being done in haxe.

Posted on

2 Years Old!

Another year has gone, and I’ve updated the blog look for a bit of a change. 2008 was pretty productive – three main technologies (NME, for low level rendering, Neash for flash interfacing and HXCPP for generating C++ code) have progressed to the “very useful” stage. I have one more technology to go, “gm2d” – a reasonably light weight API to abstract the platform quirks required for super fast rendering on flash, software NME or OpenGL. This will also contain some stuff for making games more easily. And of course, I hope to get the first three technologies to production quality.

Posted on

HXCPP 0.3 Released

I have put together a new version of hxcpp, the c++ backend for haxe. New features include improved coverage of language features. All the unit tests except remoting pass now. I have also cleaned up the ocaml code a bit and improved the output consistency. Still a bit to do here, but not that much.

The code now contains a dependency system that allows for incremental compiling, greatly improving the speed.

Dlls are now all in one directory – by adding this to the exe path no dll copying should be required. This still needs a little thought :- I tried to delay load the dll, thereby giving greater control over locating it, but it seems the rtti system brings the dll in before I can change the load path. Apart from this, most of the 0.1 TODO list is finished. There are still a few little language features required – such as “break” from within a return block but it’s 99% there, and the external libraries are pretty much untested.

I have also hijacked the neko code to provide OS libraries. This means that I had to allow “neko” class paths in the cpp target – this seems a little odd – I will have to think about a solution here.

Strings are implemented with wchar_t, rather than utf8 bytes, so some neko functions that took “string” actually take “byte array” in cpp. On the plus side, multi-byte characters are “native” in the c++ target.

The source and demos are in hxcpp-03.zip.

Posted on

HXCPP 0.2 – Huge performance increase.

I have switched hxcpp over from using ref-counting to using Boehm garbage collection. I have also added some additional perfromance improvements, such as integer-index field names to make interaction with neko more efficient.

The overall result is that for the Physaxe demo, the frame rate went from 24 fps to 82 fps (in opengl mode). The swf file runs at about 35 fps, and neko at about 8 fps. This is about what I was hoping for from the first round, but I got there in the end.

You can download the updated files here.