In this post I want to show you a step by step guide on how you can start your Scala project with Spring Data for MongoDB.

You should have SBT 0.11 installed on your system since I am going to use it as the building tool through out this post.

1. Creating Project

Create the project like below:

$ mkdir springDataMongo
$ cd springDataMongo/
$ sbt
[info] Loading global plugins from /home/amir/.sbt/plugins
[info] Set current project to default-71a5a0 (in build file:/data/3-Projects/scala-projects/springDataMongo/)
> set name := "SpringMongo"
[info] Reapplying settings...
[info] Set current project to SpringMongo (in build file:/data/3-Projects/scala-projects/springDataMongo/)
> set version := "1.0"
[info] Reapplying settings...
[info] Set current project to SpringMongo (in build file:/data/3-Projects/scala-projects/springDataMongo/)
> set scalaVersion := "2.9.1"
[info] Reapplying settings...
[info] Set current project to SpringMongo (in build file:/data/3-Projects/scala-projects/springDataMongo/)
> session save
[info] Reapplying settings...
[info] Set current project to SpringMongo (in build file:/data/3-Projects/scala-projects/springDataMongo/)

Open file build.sbt and add the dependencies:

Save the file and run the following in SBT console:

> reload
[info] Loading global plugins from /home/amir/.sbt/plugins
[info] Set current project to SpringMongo (in build file:/data/3-Projects/scala-projects/springDataMongo/)
> update
[info] Updating {file:/data/3-Projects/scala-projects/springDataMongo/}default-71a5a0...
[info] Done updating.

And generate the IDE related files. I am using IntelliJ:

> gen-idea

or if you use Eclipse:

> eclipse create-src

Now you have configured your project and you can start coding!

2. Configuring Spring

There are two ways to configure Spring Data for MongoDB: Annotations and XML. I explain annotations here. You have to extend AbstractMongoConfiguration class as follows to define your database settings:

As you see there are two methods to implement. mongo method should return an instance of Mongo class. If you are using a mongo instance in a network, you should then specify the address and possibly port (if not the default).

3. Data Model

Consider we have the following class for keeping accounts in a system. This class will be mapped to a mongo document by Spring:

4. Interacting with MongoDB

Now let's write a simple program to interact with MongoDB:

mongoTemplate is an implementation of MongoOperation interface. With MongoOperation you can do all CRUD operations. E.g. inserting/saving a document:

"accounts" is the name of collection. Or if you want to query:

Note that JavaConversions is required here since the result of find is a java.util.List[Account] and we need to convert it to Scala list.

Please refer to documentation of Spring Data for MongoDB for more info about what you can do more

You will need to download and install a couple of things.

Eclipse

I usually go with the Eclipse Classic version. It is available from eclipse.org. Installing Eclipse is simply just unpacking the downloaded file.

Android SDK

The SDK is located at developer.android.com There is a really good installation guide at developer.android.com

Android NDK

The NDK is located at developer.android.com with an installation guide.

Eclipse C/C++ Development Tools

To make it a bit easier we also install the C/C++ Development Tools to get C/C++ support in Eclipse. From the 'Help' menu choose 'Install New Software...'

From the drop down select the update site for your eclipse version, in my case Indigo.

Under 'Programming Languages' you will find 'C/C++ Development Tools'. Select it and click 'next' and follow the install instructions.

Getting started

I will show you how to get started by making a small application called NDKSetup.

Create a new android project for this example I will call it NDKSetup.

First thing we need to do is to create a new folder called 'jni'

The next thing we need to do is to setup Eclipse so we can build the JNI code. Click on the small down arrow on the external tool button and choose the 'External Tools Configuration...'.

Mark the 'Program' and click on the 'new'-icon.

Select a proper name.

Location is the location of the external tool you want to run, in our case the ndk-build file. Click on 'Browse file system...' and locate the ndk-build file located under your NDK folder.

The working directory is the jni folder we created in our project. Click on 'Browse Workspace...' ...

... and choose the jni folder.

You should now have something looking like this:

Press run and you will get this error:

/Users/uncle/ndk-setup/android-ndk-r6b/build/core/add-application.mk:118: *** Android NDK: Aborting...    .  Stop.
Android NDK: Your APP_BUILD_SCRIPT points to an unknown file: /Users/uncle/Workspaces/ndk-setup/NDKSetup/jni/Android.mk

This means two things. Your setup to the ndk-build works and you are missing the Android.mk file.

Create a new file called Android.mk in the jni folder.

In the Android.mk file write this:

LOCAL_PATH := $(call my-dir)
 
include $(CLEAR_VARS)
 
LOCAL_LDLIBS := -llog
 
LOCAL_MODULE    := ndksetup
LOCAL_SRC_FILES := native.c
 
include $(BUILD_SHARED_LIBRARY)

LOCAL_PATH := $(call my-dir)
An Android.mk file must begin defining the LOCAL_PATH variable, this is where the source files are. The macro 'my-dir' is the path where the Android.mk file is located.

include $(CLEAR_VARS)
Since all the building and parsing is done in the same context the variables called LOCAL_XXX is globals and need to be cleared.

LOCAL_MODULE := ndksetup
This is where you set the name used as the identifier for each module. Later used in java when loading the module. The system will add 'lib' before the module name when compiling into the .so file. So ndksetup will become libndksetup.so. The only exception is if you add 'lib' first in your module name then the system will not add it.

LOCAL_SRC_FILES := native.c
Here you add a list of the files you need to compile your module. You do not need to add headers or include files the system will take care of that for you.

include $(BUILD_SHARED_LIBRARY)
The NDK provides you with two make files that parse and build everything accordingly to your Android.mk file. The two once are BUILD_STATIC_LIBRARY for building static library and BUILD_SHARED_LIBRARY for building shared library.

For the example project here we use the BUILD_SHARED_LIBRARY.

If you run the external tool "NDK Build" we get a new error:

make: *** No rule to make target `/Users/uncle/Workspaces/ndk-setup/NDKSetup/jni/native.c', needed by `/Users/uncle/Workspaces/ndk-setup/NDKSetup/obj/local/armeabi/objs/ndksetup/native.o'.  Stop.

So lets att the missing native.c file into the jni folder.

Before we start adding code to the native.c file I think it is easier to write the API starting from java. We start by adding the loading of the library.

static {
    System.loadLibrary("ndksetup"); // ndksetup is the LOCAL_MODULE string.
}

We also need to define the function we are going to implement. By adding the keyword 'native' the system will know it is a function located in the native code.

private native void printLog(String logThis);

Putting in all together give us this:

package com.jayway.ndksetup;

import android.app.Activity;
import android.os.Bundle;

public class NDKSetupActivity extends Activity {

    static {
        System.loadLibrary("ndksetup");
    }

    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        printLog("Hello!!!");
    }

    private native void printLog(String logThis);
}

Back to the native.c file.

The name structure of the function is important. It is build from the java starting with a java identifier followed by the package name, followed by the class name, followed by the function name. This is one way of converting our java function into the native function. I usually do it by right clicking on the function name ( printLog ) and select 'Copy Qualified Name' paste it in the native.c file:

com.jayway.ndksetup.NDKSetupActivity.printLog(String)

Start by changing all dots (.) to underscores (_).

com_jayway_ndksetup_NDKSetupActivity_printLog(String)

Add the return value and a Java_ identifier to the function:

void Java_com_jayway_ndksetup_NDKSetupActivity_printLog(String)

The input variable is a String in java so lets make it a java string in native as well.

void Java_com_jayway_ndksetup_NDKSetupActivity_printLog(jstring logString)

The last thing we need to add is a reference to the JNI enviroment and a reference to java object that this function belongs to.

void Java_com_jayway_ndksetup_NDKSetupActivity_printLog(JNIEnv * env, jobject this, jstring logString)

Finally our first native function will look like this:

#include <jni.h>
#include <string.h>
#include <android/log.h>
 
#define DEBUG_TAG "NDKSetupActivity"
 
void Java_com_jayway_ndksetup_NDKSetupActivity_printLog(JNIEnv * env, jobject this, jstring logString)
{
    jboolean isCopy;
    const char * szLogString = (*env)->GetStringUTFChars(env, logString, &isCopy);
 
    __android_log_print(ANDROID_LOG_DEBUG, DEBUG_TAG, "NDK: %s", szLogString);
 
    (*env)->ReleaseStringUTFChars(env, logString, szLogString);
}

Just for fun we add another function, a fibonacci function.

private native int fibonacci(int value);

jint Java_com_jayway_ndksetup_NDKSetupActivity_fibonacci(JNIEnv * env, jobject this, jint value)
{
	if (value <= 1) return value;
	return Java_com_jayway_ndksetup_NDKSetupActivity_fibonacci(env, this, value-1)
            + Java_com_jayway_ndksetup_NDKSetupActivity_fibonacci(env, this, value-2);
}

Now you are up and running with your NDK development for Android.

This category has served me well, and even got traction in the iOS developer community, so I never bothered to stop and think if there exist an even better solution.

Especially now that GDC exists, and doing an inline block to invoke on the main thread or a background queue is easier than ever before.

Until Today

Traveling home by bus as usual I got a flash of genius; Why not use proxy objects? Calling a method on the main thread should be no harder then this;

[[self.slider mainThreadProxy] setValue:0.5f animated:YES];

The old NSInvocation solutions have a few drawbacks. First of all there is no code completion for the arguments, secondly there is not even basic type checking, and lastly the implementation is quite ABI specific.

The NSObject class already has support for method forwarding, and wrapping method calls up into NSInvocation instances. Why not use seriously battle proven code that Apple provides.

The Skeleton

The implementation for -[NSObject mainThreadProxy] will be childishly simple:

-(id)mainThreadProxy;
{
    // Return self directly if already on main thread.
    if ([NSThread isMainThread]) {
        return self;
    } else {
        return [CWMainProxy proxyWithTarget:self];
    }
}

The CWMainProxy class is a simple private helper, that will perform all of the heavy lifting. The interface and life time code is very small:

@interface CWMainProxy : NSObject {
    id _target;
}
+(id)proxyWithTarget:(id)target;
@end

@implementation CWMainProxy

+(id)proxyWithTarget:(id)target;
{
    CWMainProxy* proxy = [[[self alloc] init] autorelease];
    proxy->_target = [target retain];
    return proxy;
}

-(void)dealloc;
{
    [_target release];
    [super dealloc];
}
@end

The Meaty Parts

Now comes the tricky parts; actually act like a proxy. The proxy is a simple NSObject subclass, first it needs to be able to fake to any caller that it can respond to everything that the proxies target responds to.

-(BOOL)respondsToSelector:(SEL)sel;
{
    return [super respondsToSelector:sel] ||
           [_target respondsToSelector:sel];
}

Next up if the object claims it responds to a selector but do not have an actual implementation, then we must provide a NSMethodSignature so the run-time can create a proper NSInvocation for us.

-(NSMethodSignature*)methodSignatureForSelector:(SEL)sel;
{
    if ([_target respondsToSelector:self) {
        return [_target methodSignatureForSelector:sel];
    } else {
        return [super methodSignatureForSelector:sel];
    }
}

And finally we need to actually forward the NSInvocation call to the main thread, as per the callers request:

-(void)forwardInvocation:(NSInvocation*)invocation;
{
    [invocation performSelectorOnMainThread:@selector(invokeWithTarget:)
                                 withObject:_target
                              waitUntilDone:YES];
}

Conclusions

Given some thought I regard this solution to be much more elegant than my old solution. And it even yields less and more readable code than using GCD on iOS 4 and later:

[[self.slider mainThreadProxy] setValue:0.5f animated:YES];
    // vs
dispatch_async(dispatch_get_main_queue(),
               ^{
                   [self.slider setValue:0.5f animated:YES];
               });

• The implementation is much smaller, and relies on the Foundation framework functionality, not my own Objective-C ABI hacks.
• It is less code to write to use the functionality.
• Xcode can do proper code completion and basic type checking.
• It is compatible all the way back to iPhone OS 2, or Mac OS X 10.0, if you should care.

The CWFoundation project on Github has a more complete implementation. With more support for optional blocking, delays, and more proxies not only for the main thread but also for background threads and operations queue.

You are seldom alone with great ideas, so a nod to Joachim Bengtsson who has written about an invocation grabber before.

Incrementing the version number of your project for every small update is often not feasible, if it involves manual labor it just does not get done. Would it not be nice if Xcode just autoincremented a build number for you every time you build?

This can be done

There are dozens of solution to the problem available by Google. Unfortunately most do not work in both Xcode 3.2 and Xcode 4, and many more require a lot of hacking, even running external Perl or Python scripts. Using avgtool seems to be a major overkill for most use-cases. There must be an easier way, and there is.

What we want to do is to have the build number available in our Info.plist file, so that it can be read and displayed at run-time. And we also want Xcode to automatically increment this number for every build.

Add a key named CWBuildNumber to your Info.plist file, and set it to a sane start value, maybe "0". You can load it at run-time with a short statement like:

NSString* buildNumber = [[NSBundle mainBundle] objectForInfoDictionaryKey:@"CWBuildNumber"];

Both Xcode 3.2 and Xcode 4 allows to add a Run Script phase to any target. Unfortunately Xcode 3.2 and 4 run these scripts with different paths. PROJECT_DIR environment variable to the rescue! Secondly we want to rewrite the target's source Info.plist file, not the file bundled with the application, so make sure to order the script phase before the Copy Resources phase. Then just add this tiny script phase to your target build:

buildNumber=$(/usr/libexec/PlistBuddy -c "Print CWBuildNumber" ${PROJECT_DIR}/MyApp-Info.plist)
buildNumber=$(($buildNumber + 1))
/usr/libexec/PlistBuddy -c "Set :CWBuildNumber $buildNumber" ${PROJECT_DIR}/MyApp-Info.plist 

Conclusions

Happy developers, and happy tester. Maybe even happy users, if you choose to show the full version number including build number in the final product.

All the libraries built for Node use non-blocking I/O. This is a really cool feature, which allows the single thread in Node to serve thousands of request per second. It even lets you run multiple servers in the same thread. Check out the performance characteristics of Nginx and Apache that utilize the same technique.

The graph for memory usage is even better.

Read more about it at the Web Faction Blog

OK, so what's the catch? The catch is that all code that does I/O, or
anything slow at all, has to be called in an asynchronous style.

// Synchronous
var result = db.query("select * from T");
// Use result 

// Asynchronous
db.query("select * from T", function (result) {
    // Use result
});

So, all libraries that deal with IO has to be re-implemented with this
style of programming. The good news is that even though Node has only
been around for a couple of years, there are more than 1800 libraries
available. The libraries are of varying quality but the popularity of
Node shows good promise to deliver high-quality libraries for anything
that you can imagine.

History

Node is definitely not the first of its kind. The non-blocking
select() loop, that is at the heart of Node, dates back to 1983.

Twisted appeared in Python (2002) and EventMachine in Ruby (2003).

This year a couple of newcomers appeared.

Goliath, which builds on EventMachine, and uses fibers to allow us to program in an synchronous style even though it is asynchronous under the hood.

And, the Async Framework in
.Net, which enhances the compiler with the keywords async and await to allow for very elegant asynchronous programming.

Get Started

This example uses OSX as an example platform, if you use something else
you will have to google for instructions.

# Install Node using Homebrew
$ brew install node
==> Downloading http://nodejs.org/dist/node-v0.4.7.tar.gz
######################################################################## 100.0%
==> ./configure --prefix=/usr/local/Cellar/node/0.4.7
==> make install
==> Caveats
Please add /usr/local/lib/node to your NODE_PATH environment variable to have node libraries picked up.
==> Summary
/usr/local/Cellar/node/0.4.7: 72 files, 7.5M, built in 1.2 minutes

When installed you have access to the node command-line command. When
invoked without arguments, it start a REPL.

$ node
> function hello(name) {
... return 'hello ' + name;
... }
> hello('tapir')
'hello tapir'
>

When invoked with a script it runs the script.

// hello.js
setTimeout(function() {
    console.log('Tapir');
}, 2000);
console.log('Hello'); 

$ node hello.js
Hello
...
Tapir

Networking

As I mentioned above, Node is focused on networking. That means it
should be easy to write networking code. Here is a simple echo server.

// Echo Server
var net = require('net'); 

var server = net.createServer(function(socket) {
    socket.on('data', function(data) {
        console.log(data.toString());
        socket.write(data);
    });
});
server.listen(4000); 

And here is a simple HTTP server.

// HTTP Server
var http = require('http');
var web = http.createServer(function(request, response) {
  response.writeHead(200, {
    'Content-Type': 'text/plain'
  });
  response.end('Tapirs are beautiful!\n');
});
web.listen(4001); 

Quite similar. A cool thing is that the servers can be started from the
same file and node will, happily, serve both HTTP and echo requests from
the same thread without any problems. Let's try them out!

# curl the http service
$ curl localhost:4001
Tapirs are beautiful! 

# use netcat to send the string to the echo server
$ echo 'Hello beautiful tapir' | nc localhost 4000
Hello beautiful tapir

Modules

Node comes with a selection of built in modules. Ryan Dahl says that
they try to keep the core small, but even so the built-in modules cover
a lot of useful functionality.

• net - contains tcp/ip related networking functionality.
• http - contains functionality for dealing with the HTTP protocol.
• util - holds common utility functions, such as log, inherits, pump,
  ...
• fs - contains filesystem related functionality, remember that
  everything should be asynchronous.
• events - contains the EventEmitter that is used for dealing with
  events in a consistent way. It is used internally but it can be used
  externally too.

An example

Here is an example of a simple module.

// module tapir.js 

// require another module
var util = require('util'); 

function eat(food) {
  util.log('eating '+ food);
} 

// export a function
exports.eat = eat; 

As you can see it looks like a normal Javascript file and it even looks
like it has global variables. It doesn't. When a module is loaded it is
wrapped in code, similar to this.

var module = { exports: {}};
(function(module, exports){
  // module code from file
  ...
})(module, module.exports); 

As you can see the code is wrapped in a function and an empty object
with an export property is sent into it. This is used by the file to
export only the functions that it want to publish.

The require function works in symphony with the module and it returns
the exported functions to the caller.

Node Package Manager, npm

To allow simple handling of third-party packages, Node uses npm. It
can be installed like this:

$ curl http://npmjs.org/install.sh | sh
... 

And used like this:

$ npm install -g express
mime@1.2.1 /usr/local/lib/node_modules/express/node_modules/mime
connect@1.4.0 /usr/local/lib/node_modules/express/node_modules/connect
qs@0.1.0 /usr/local/lib/node_modules/express/node_modules/qs
/usr/local/bin/express -> /usr/local/lib/node_modules/express/bin/express
express@2.3.2 /usr/local/lib/node_modules/express

As you can see, installing a module also installs its dependencies. This
works because a module can be package with meta-data, like so:

// express/package.json
{
  "name": "express",
  "description": "Sinatra inspired web development framework",
  "version": "2.3.2",
  "author": "TJ Holowaychuk <tj@vision-media.ca>",
  "contributors": [
    { "name": "TJ Holowaychuk", "email": "tj@vision-media.ca" },
    { "name": "Guillermo Rauch", "email": "rauchg@gmail.com" }
  ],
  "dependencies": {
    "connect": ">= 1.4.0 < 2.0.0",
    "mime": ">= 0.0.1",
    "qs": ">= 0.0.6"
  },
  "keywords": ["framework", "sinatra", "web", "rest", "restful"],
  "repository": "git://github.com/visionmedia/express",
  "main": "index",
  "bin": { "express": "./bin/express" },
  "engines": { "node": ">= 0.4.1 < 0.5.0" }
} 

The package.json contains information about who made the module, its
dependencies, along with some additional information to enable better
searching facilities.

Npm installs the modules from a common
respository, which contains more than 1800
modules.

Noteworthy Modules

Express is probably the most used of all third-party modules. It is
a Sinatra clone and it is very good, just like Sinatra.

// Create a server
var app = express.createServer();
app.listen(4000); 

// Mount the root (/) and redirect to index
app.get('/', function(req, res) {
  res.redirect('/index.html');
}); 

// Handle a post to /quiz
app.post('/quiz', function(req, res) {
  res.send(quiz.create().id.toString());
});

Express uses Connect to handle middleware. Middleware is like Rack
but for Node (No wonder that Node is nice to work with when it borrows
its ideas from Ruby

connect(
      // Add a logger
      connect.logger()
      // Serve static file from the current directory
    , connect.static(__dirname)
      // Compile Sass and Coffescript files, on the fly
    , connect.compiler({enable: ['sass', 'coffeescript']})
      // Profile all requests
    , connect.profiler()
  ).listen(3000);

Another popular library is Socket.IO. It handles the usual socket
variants, such as WebSocket, Comet, Flash Sockets, etc...

var http = require('http');
var io = require('socket.io'); 

server = http.createServer(function(req, res){...});
server.listen(80); 

// socket.io attaches to an existing server
var socket = io.listen(server);
socket.on('connection', function(client){
  // new client is here!
  client.on('message', function(){ ... })
  client.on('disconnect', function(){ ... })
});

MySql has a library for Node.

client.query(
  'SELECT * FROM ' + TEST_TABLE,
  // Note the callback style
  function(err, results, fields) {
    if (err) { throw err; } 

    console.log(results);
    console.log(fields);
    client.end();
  }
);

And Mongoose can be used for accessing MongoDB.

// Declare the schema
var Schema = mongoose.Schema
  , ObjectId = Schema.ObjectId; 

var BlogPost = new Schema({
    author    : ObjectId
  , title     : String
  , body      : String
  , date      : Date
}); 

// Use it
var BlogPost = mongoose.model('BlogPost'); 

// Save
var post = new BlogPost();
post.author = 'Stravinsky';
instance.save(function (err) {
  //
}); 

// Find
BlogPost.find({}, function (err, docs) {
  // docs.forEach
});

Templating Engines

Everytime a new platform makes its presence, it brings along a couple of
new templating languages and Node is no different. Along with the
popular ones from the Ruby world, like Haml and Erb (EJS in Node),
comes some new ones like Jade and some browser templating languages like
Mustache and jQuery templates. I'll show examples of Jade and Mu
(Mustache for Node).

I like Jade, because it is a Javascript dialect of Haml and it seems
appropriate to use if I'm using Javascript on the server side.

!!! 5
html(lang="en")
  head
    title= pageTitle
    script(type='text/javascript')
      if (foo) {
        bar()
      }
  body
    h1 Jade - node template engine
    #container
      - if (youAreUsingJade)
        p You are amazing
      - else
        p Get on it!

I'm not really sure if I like Mustache or not, but I can surely see the
value of having a templating language which works both on the server side
and in the browser.

<h1>{{header}}</h1>
{{#bug}}
{{/bug}}

{{#items}}
  {{#first}}
    <li><strong>{{name}}</strong></li>
  {{/first}}
  {{#link}}
    <li><a href="{{url}}">{{name}}</a></li>
  {{/link}}
{{/items}}

{{#empty}}
  <p>The list is empty.</p>
{{/empty}}

Testing

Node comes with assertions built in, and all testing frameworks build on
the Assert module, so it is good to know.

assert.ok(value, [message]);
assert.equal(actual, expected, [message])
assert.notEqual(actual, expected, [message])
assert.deepEqual(actual, expected, [message])
assert.strictEqual(actual, expected, [message])
assert.throws(block, [error], [message])
assert.doesNotThrow(block, [error], [message])
assert.ifError(value)
assert.fail(actual, expected, message, operator) 

// Example
// assert.throws(function, regexp)
assert.throws(
  function() { throw new Error("Wrong value"); },
  /value/
);

Apart from that there are at least 30 different testing frameworks to
use. I have chosen to use NodeUnit since I find that it handles
asynchronous testing well, and it has a nice UTF-8 output that looks
good in the terminal,

// ./test/test-doubled.js
var doubled = require('../lib/doubled'); 

// Exported functions are run by the test runner
exports['calculate'] = function (test) {
    test.equal(doubled.calculate(2), 4);
    test.done();
}; 

// An asynchronous test
exports['read a number'] = function (test) {
    test.expect(1); // Make sure the assertion is run 

    var ev = new events.EventEmitter();
    process.openStdin = function () { return ev; };
    process.exit = test.done; 

    console.log = function (str) {
        test.equal(str, 'Doubled: 24');
    }; 

    doubled.read();
    ev.emit('data', '12');
}; 

Deployment

There are already a lot of platforms providing Node as a service (PaaS
, Platform as a Service). Most of them are using
Heroku style deployment by pushing to a Git remote.
I'll show three alternatives that all provide free Node hosting.

Joyent (no.de)

Joyent, the employers of Ryan Dahl, give you ssh access so that you
can install the modules you need. Deployment is done by pushing to
a Git remote.

$ ssh node@my-machine.no.de
$ nmp install express
$ git remote add node node@andersjanmyr.no.de:repo
$ git push node master
Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 321 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: Starting node v0.4.7...
remote: Successful
To node@andersjanmyr.no.de:repo
  8f59169..c1177b0  master -> master

Nodester

Nodester, gives you a command line tool, nodester, that you use to
install modules. Deployment by pushing to a Git remote.

$ nodester npm install express
$ git push nodester master
Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 341 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: Syncing repo with chroot
remote: From /node/hosted_apps/andersjanmyr/1346-7856c14e6a5d92a6b5374ec4772a6da0.git/.
remote:    38f4e6e..8f59169  master     -> origin/master
remote: Updating 38f4e6e..8f59169
remote: Fast-forward
remote:  Gemfile.lock |   10 ++++------
remote:  1 files changed, 4 insertions(+), 6 deletions(-)
remote: Checking ./.git/hooks/post-receive
remote: Attempting to restart your app: 1346-7856c14e6a5d92a6b5374ec4772a6da0
remote: App restarted..
remote:
remote:
remote:     \m/ Nodester out \m/
remote:
remote:
To ec2-user@nodester.com:/node/hosted_apps/andersjanmyr/1346-7856c14e6a5d92a6b5374ec4772a6da0.git
   38f4e6e..8f59169  master -> master

Cloud Foundry

Cloud Foundry is one of the most interesting platforms in the cloud. It
was genius by VM Ware to open source the platform, allowing anyone to
set up their own cloud if they wish. If you don't want to setup your own
Cloud Foundry Cloud, you can use the service hosted at
cloundfoundry.com.

With Cloud Foundry, you install the modules locally and then they are
automatically deployed as part of the vmc push. Push in this case does
not mean git push, but instead, copy all the files from my local machine
to the server.

$ npm install express  # Install locally
mime@1.2.1 ./node_modules/express/node_modules/mime
connect@1.4.0 ./node_modules/express/node_modules/connect
qs@0.1.0 ./node_modules/express/node_modules/qs
express@2.3.0 ./node_modules/express

$ vmc push
Would you like to deploy from the current directory? [Yn]: Y
Application Name: snake
Application Deployed URL: 'snake.cloudfoundry.com'?
Detected a Node.js Application, is this correct? [Yn]:
Memory Reservation [Default:64M] (64M, 128M, 256M, 512M, 1G or 2G)
Creating Application: OK
Would you like to bind any services to 'snake'? [yN]:
Uploading Application:
  Checking for available resources: OK
  Packing application: OK
  Uploading (1K): OK
Push Status: OK
Staging Application: OK
Starting Application: ........OK

Tools

There are of course a bunch of tools that come with a new platform,
Jake, is a Javascript version of Rake, but I am happy with Rake and
I don't see the need to switch. But, there are some tools that I cannot
live without when using Node.

Reloaders

If you use the vanilla node command then you have to restart it
every time you make a change to a file. That is awfully annoying and
there are already a number of solutions to the problem.

# Nodemon watches the files in your directory and reloads them if necessary
$ npm install nodemon
nodemon@0.3.2 ../node_modules/nodemon

$ nodemon server.js
30 Apr 08:21:23 - [nodemon] running server.js
...
# Saving the file
30 Apr 08:22:01 - [nodemon] restarting due to changes... 

# Alternative
$ npm install supervisor
$ supervisor server.js
DEBUG: Watching directory '/evented-programming-with-nodejs/. 

Debuggers

Another tool that it is hard to live without is a debugger. Node comes
with one built in. It has a gdb flavor to it and it is kind of rough.

$ node debug server.js
debug> run
debugger listening on port 5858
connecting...ok
break in #<Socket> ./server.js:9
    debugger; 

debug> p data.toString();
tapir

// Javascript
var echo = net.createServer(function(socket) {
  socket.on('data', function(data) {
      debugger; // <= break into debugger
      socket.write(data);
  });
});

If you want a GUI debugger, it is possible to use the one that comes with
Chrome by installing the node-inspector. It is started similarly to
the built in debugger, but the --debug is an option instead of
a subcommand.

$ node-inspector &
visit http://0.0.0.0:8080/debug?port=5858 to start debugging

$ node --debug server.js debugger listening on port 5858

After that you can just fire up Chrome on the URL,
http://0.0.0.0:8080/debug?port=5858 and you can debug the node process
just as if it was running in the browser.

Idioms

Idioms, patterns, techniques, call it what you like. Javascript code is
littered with callbacks, and event more so with Node. Here are some tips
on how to write good asynchronous code with Node.

Return on Callbacks

It is easy to forget to escape from the function after a callback has
been called. An easy way to remedy this problem is to call return before
every call to a callback. Even though the value is never used by the
caller, it is an easy pattern to recognize and it prevents bugs.

function doSomething(response, callback) {
  doAsyncCall('tapir', function(err, result) {
    if (err) {
      // return on the callback
      return callback(err);
    }
    // return on the callback
    return callback(null, result);
  });
}

Exceptions in Callbacks

Exceptions that occur in callbacks cannot be handled the way we are used
to, since the context is different. The solution to this is to pass
along the exception as a parameter to the callback. In Node the
convetion is to pass the error as the first parameter into the callback.

function insertIntoTable(row, function(err, data) {
  if (err) return callback(err);
  ... 

  // Everything is OK
  return callback(null, 'row inserted');
}

Parallel Execution

If you have multiple tasks that need to be finished before you take some
new action, this can be handled with a simple counter. Here is an
example of a simple function that starts up a bunch of functions in
parallel and waits for all of them to finish before calling the
callback.

// Do all in parallel
function doAll(collection, callback) {
  var left = collection.length;
  collection.forEach(function(fun) {
    fun(function() {
      if (--left == 0) callback();
    });
  });
}; 

// Use it
var result = [];
doAll([
  function(callback) {
    setTimeout(function() {result.push(1); callback();}, 2000 )},
  function(callback) {
    setTimeout(function() {result.push(2); callback();}, 3000 )},
  function(callback) {
    setTimeout(function() {result.push(3); callback();}, 1000 )}
  ], function() { return result; } 

// returns [3, 1, 2]

Sequential Execution

Sometimes the ordering is important. Here is a simple function that
makes sure that the calls are executed in sequence. It uses recursion to
to make sure that the calls are handled in the correct order. It also
uses the Node function process.nextTick() to prevent the stack from
getting to large for large collections. Similar results can be obtained
with setTimeout() in browser Javascript. It can be seen as a simple
trick to achieve tail recursion.

function doInSequence(collection, callback) {
    var queue = collection.slice(0); // Duplicate 

    function iterate() {
      if (queue.length === 0) return callback();
      // Take the first element
      var fun = queue.splice(0, 1)[0];
      fun(function(err) {
        if (err) throw err;
        // Call it without building up the stack
        process.nextTick(iterate);
      });
    }
    iterate();
} 

var result = [];
doInSequence([
  function(callback) {
    setTimeout(function() {result.push(1); callback();}, 2000 )},
  function(callback) {
    setTimeout(function() {result.push(2); callback();}, 3000 )},
  function(callback) {
    setTimeout(function() {result.push(3); callback();}, 1000 )}
  ], function() { return result; }); 

// Returns [1, 2, 3]

Library Support for Asynchronous Programming

If you don't want to write these functions yourself, there are a few
libraries that can help you out. I'll show two version that I like.

Fibers

Fibers are also called co-routines. Fibers provide two functions,
suspend and resume, which allows us to write code in a synchronous
looking style. In the Node version of fibers,
node-fibers, suspend and
resume are called yield() and run() instead.

require('fibers');
var print = require('util').print; 

function sleep(ms) {
    var fiber = Fiber.current;
    setTimeout(function() { fiber.run(); }, ms);
    yield();
} 

Fiber(function() {
    print('wait... ' + new Date + '\n');
    sleep(1000);
    print('ok... ' + new Date + '\n');
}).run();
print('back in main\n');

Fibers are a very nice way of writing asynchronous code but, in Node,
they have one drawback. They are not supported without patching the V8
virtual machine. The patching is done when you install node-fibers and
you have to run the command node-fibers instead of node to use it.

The async Library

If you don't want to use the patched version of V8, I can recommend the
async library. Async provides
around 20 functions that include the usual 'functional' suspects (map,
reduce, filter, forEach...) as well as some common patterns for
asynchronous flow control (parallel, series, waterfall...). All these
functions assume you follow the Node convention of providing a single
callback as the last argument of your async function.

async.map(['file1','file2','file3'], fs.stat, function(err, results){
    // results is now an array of stats for each file
}); 

async.filter(['file1','file2','file3'], path.exists, function(results){
    // results now equals an array of the existing files
}); 

async.parallel([
    function(){ ... },
    function(){ ... }
], callback); 

async.series([
    function(){ ... },
    function(){ ... }
], callback);

Conclusion

Node is definitely an interesting platform. The possibility to have
Javascript running through the whole stack, from the browser all the way
down into the database (if you use something like CouchDB or MongoDB)
really appeals to me. The easy way to deploy code to multiple, different
cloud providers is also a good argument for Node.

Loading bitmaps

First step would be to get a bitmap to generate a texture from. You can get hold of a bitmap in many different ways from downloading, generating or simply just load one from the resources. I'm going with the simplest one for this example witch is loading from the resources.

Bitmap bitmap = BitmapFactory.decodeResource(contect.getResources(),
                                             R.drawable.icon);

One other thing about textures is that some hardware requires that the height and width are in the power of 2 (1, 2, 4, 8, 16, 32, 64...). If you run a texture with a size of 30x30pixels on a hardware that don’t support it you will just get a white square (unless you change the default color).

Generating a texture

After we have loaded the bitmap we need to tell OpenGL to actually create the texture.

First thing we need to do is to let OpenGL generate some texture id's that we will use as handles to the textures later on. In this example we will only have one texture.

// Create an int array with the number of textures we want,
// in this case 1.
int[] textures = new int[1];
// Tell OpenGL to generate textures.
gl.glGenTextures(1, textures, 0);

With the same parameters you can delete the textures:

// Delete a texture.
gl.glDeleteTextures(1, textures, 0)

Now when the texture id's are generated we need to just like everything else tell OpenGL what to work with. With textures we use the command glBindTexture:

gl.glBindTexture(GL10.GL_TEXTURE_2D, textures[0]);

From this point all commands we call on regarding textures will be applied on to your texture with the generated id.

glTexParameter

There is a couple of parameters we need to set on the texture, the first one is to tell OpenGL what to do if the texture need to be shrunk or magnified to match the rendered image.
If the texture is smaller it needs to be magnified that is done with the magnification function:

// Scale up if the texture if smaller.
gl.glTexParameterf(GL10.GL_TEXTURE_2D,
                   GL10.GL_TEXTURE_MAG_FILTER,
                   GL10.GL_LINEAR);

And how to scale if the texture needs to be scaled down using the minification function.

// scale linearly when image smalled than texture
gl.glTexParameterf(GL10.GL_TEXTURE_2D,
                   GL10.GL_TEXTURE_MIN_FILTER,
                   GL10.GL_LINEAR);

You need to pass an argument to these functions. I'm only going to show you two of them the rest you can investigate your self

If you want a crisp and clean rendering like this image you need to use the GL10.GL_NEAREST parameter.

If you rather want a blurred image you should use the GL10.GL_LINEAR parameter.

UV Mapping

We will also need to tell OpenGL how to map this image onto the mesh this is done in two steps, fist we need to assign UV coordinates

UV mapping is the way we map the pixels on the bitmap to the vertices in our mesh. The UV coordinates are 0,0 in the upper left and 1,1 is the bottom right, like the left image below. The right image below illustrates how our plane is built. To get the texture mapped correctly we need to map the lower left part of the texture (0,1) to the lower left vertex (0) in our plane and we need to map the the bottom right (1,1) in the texture to the bottom right (1) to the bottom right in our plane and... you get the idea.

We put this mapping into a float array like this:

float textureCoordinates[] = {0.0f, 1.0f,
                              1.0f, 1.0f,
                              0.0f, 0.0f,
                              1.0f, 0.0f };

If we instead used 0.5 instead of 1.0 like this:

float textureCoordinates[] = {0.0f, 0.5f,
                              0.5f, 0.5f,
                              0.0f, 0.0f,
                              0.5f, 0.0f };

Back to the glTexParameterf, if we go the other way and uses values higher then 1.0 like this:

float textureCoordinates[] = {0.0f, 2.0f,
                              2.0f, 2.0f,
                              0.0f, 0.0f,
                              2.0f, 0.0f };

We actually tell OpenGL to use part of the texture that does not exist so we need to tell OpenGL what to do with the part that does not exist.

We use the glTexParameterf function to tell OpenGL what to do with the texture. By default OpenGL uses something called GL_REPEAT.

GL_REPEAT means that OpenGL should repeat the texture beyond 1.0.
GL_CLAMP_TO_EDGE means that OpenGL only will draw the image once and after that just repeat the last pixel line the rest of the image.

Since we are working with a 2D texture so we need to tell OpenGL what to do in two directions: GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T.

Below you see a chart with the 4 combinations of GL_REPEAT and GL_CLAMP_TO_EDGE.

WRAP_S: GL_REPEAT WRAP_T: GL_REPEAT	WRAP_S: GL_REPEAT WRAP_T: GL_CLAMP_TO_EDGE
WRAP_S: GL_REPEAT WRAP_T: GL_CLAMP_TO_EDGE	WRAP_S: GL_CLAMP_TO_EDGE WRAP_T: GL_CLAMP_TO_EDGE

This is how we use the glTexParameterf function:

gl.glTexParameterf(GL10.GL_TEXTURE_2D,
                   GL10.GL_TEXTURE_WRAP_S,
                   GL10.GL_REPEAT);
gl.glTexParameterf(GL10.GL_TEXTURE_2D,
                   GL10.GL_TEXTURE_WRAP_T,
                   GL10.GL_REPEAT);

The last thing we need to do is to bind the bitmap we loaded to the texture id we created.

GLUtils.texImage2D(GL10.GL_TEXTURE_2D, 0, bitmap, 0);

Using the texture

To be able to use the texture we need just like with everything else create a byte buffer with the UV coordinates:

FloatBuffer byteBuf = ByteBuffer.allocateDirect(texture.length * 4);
byteBuf.order(ByteOrder.nativeOrder());
textureBuffer = byteBuf.asFloatBuffer();
textureBuffer.put(textureCoordinates);
textureBuffer.position(0);

Rendering

// Telling OpenGL to enable textures.
gl.glEnable(GL10.GL_TEXTURE_2D);
// Tell OpenGL where our texture is located.
gl.glBindTexture(GL10.GL_TEXTURE_2D, textures[0]);
// Tell OpenGL to enable the use of UV coordinates.
gl.glEnableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
// Telling OpenGL where our UV coordinates are.
gl.glTexCoordPointer(2, GL10.GL_FLOAT, 0, textureBuffer);
 
// ... here goes the rendering of the mesh ...
 
// Disable the use of UV coordinates.
gl.glDisableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
// Disable the use of textures.
gl.glDisable(GL10.GL_TEXTURE_2D);

Putting it all together

I'm using a modified version of the code from the previous tutorial. The different is mostly that I renamed some variables and functions and added more comments and all code is now under Apache License. To make the code easier to understand I removed the previous plane and added a new easier one called SimplePlane.

Updating the Mesh class

The first thing we need to do is to update the Mesh class (se.jayway.opengl.tutorial.mesh.Mesh). We need to add the functionality to load and render a texture.

We need to be able to set and store the UV coordinates.

// Our UV texture buffer.
private FloatBuffer mTextureBuffer;
 
/**
 * Set the texture coordinates.
 *
 * @param textureCoords
 */
protected void setTextureCoordinates(float[] textureCoords) {
	// float is 4 bytes, therefore we multiply the number if
        // vertices with 4.
	ByteBuffer byteBuf = ByteBuffer.allocateDirect(
                                           textureCoords.length * 4);
	byteBuf.order(ByteOrder.nativeOrder());
	mTextureBuffer = byteBuf.asFloatBuffer();
	mTextureBuffer.put(textureCoords);
	mTextureBuffer.position(0);
}
 

We also need to add functions to set the bitmap and create the texture.

// Our texture id.
private int mTextureId = -1;
 
// The bitmap we want to load as a texture.
private Bitmap mBitmap;
 
/**
 * Set the bitmap to load into a texture.
 *
 * @param bitmap
 */
public void loadBitmap(Bitmap bitmap) {
	this.mBitmap = bitmap;
	mShouldLoadTexture = true;
}
 
/**
 * Loads the texture.
 *
 * @param gl
 */
private void loadGLTexture(GL10 gl) {
	// Generate one texture pointer...
	int[] textures = new int[1];
	gl.glGenTextures(1, textures, 0);
	mTextureId = textures[0];
 
	// ...and bind it to our array
	gl.glBindTexture(GL10.GL_TEXTURE_2D, mTextureId);
 
	// Create Nearest Filtered Texture
	gl.glTexParameterf(GL10.GL_TEXTURE_2D, GL10.GL_TEXTURE_MIN_FILTER,
			GL10.GL_LINEAR);
	gl.glTexParameterf(GL10.GL_TEXTURE_2D, GL10.GL_TEXTURE_MAG_FILTER,
			GL10.GL_LINEAR);
 
	// Different possible texture parameters, e.g. GL10.GL_CLAMP_TO_EDGE
	gl.glTexParameterf(GL10.GL_TEXTURE_2D, GL10.GL_TEXTURE_WRAP_S,
			GL10.GL_CLAMP_TO_EDGE);
	gl.glTexParameterf(GL10.GL_TEXTURE_2D, GL10.GL_TEXTURE_WRAP_T,
			GL10.GL_REPEAT);
 
	// Use the Android GLUtils to specify a two-dimensional texture image
	// from our bitmap
	GLUtils.texImage2D(GL10.GL_TEXTURE_2D, 0, mBitmap, 0);
}
 

And finally we need to add the call to the texture loading and to actually tell OpenGL to render with this texture. I removed some code so the page would not be so long but you will find the code complete in the attached zip file.

// Indicates if we need to load the texture.
private boolean mShouldLoadTexture = false;
 
/**
 * Render the mesh.
 *
 * @param gl
 *            the OpenGL context to render to.
 */
public void draw(GL10 gl) {
	...
 
	// Smooth color
	if (mColorBuffer != null) {
		// Enable the color array buffer to be used during rendering.
		gl.glEnableClientState(GL10.GL_COLOR_ARRAY);
		gl.glColorPointer(4, GL10.GL_FLOAT, 0, mColorBuffer);
	}
 
	if (mShouldLoadTexture) {
		loadGLTexture(gl);
		mShouldLoadTexture = false;
	}
	if (mTextureId != -1 && mTextureBuffer != null) {
		gl.glEnable(GL10.GL_TEXTURE_2D);
		// Enable the texture state
		gl.glEnableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
 
		// Point to our buffers
		gl.glTexCoordPointer(2, GL10.GL_FLOAT, 0, mTextureBuffer);
		gl.glBindTexture(GL10.GL_TEXTURE_2D, mTextureId);
	}
 
	gl.glTranslatef(x, y, z);
 
	...
 
	// Point out the where the color buffer is.
	gl.glDrawElements(GL10.GL_TRIANGLES, mNumOfIndices,
			GL10.GL_UNSIGNED_SHORT, mIndicesBuffer);
 
	...
 
	if (mTextureId != -1 && mTextureBuffer != null) {
		gl.glDisableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
	}
 
	...
 
}

Creating the SimplePlane class

We also need to create the SimplePlane.java. The code is pretty simple and self-explaining if you have read my previous tutorials. The new element is the textureCoordinates variable.

 
package se.jayway.opengl.tutorial.mesh;
 
/**
 * SimplePlane is a setup class for Mesh that creates a plane mesh.
 *
 * @author Per-Erik Bergman (per-erik.bergman@jayway.com)
 *
 */
public class SimplePlane extends Mesh {
	/**
	 * Create a plane with a default with and height of 1 unit.
	 */
	public SimplePlane() {
		this(1, 1);
	}
 
	/**
	 * Create a plane.
	 *
	 * @param width
	 *            the width of the plane.
	 * @param height
	 *            the height of the plane.
	 */
	public SimplePlane(float width, float height) {
		// Mapping coordinates for the vertices
		float textureCoordinates[] = { 0.0f, 2.0f, //
				2.0f, 2.0f, //
				0.0f, 0.0f, //
				2.0f, 0.0f, //
		};
 
		short[] indices = new short[] { 0, 1, 2, 1, 3, 2 };
 
                float[] vertices = new float[] { -0.5f, -0.5f, 0.0f,
                                                  0.5f, -0.5f, 0.0f,
                                                 -0.5f,  0.5f, 0.0f,
                                                  0.5f, 0.5f, 0.0f };
 
		setIndices(indices);
		setVertices(vertices);
		setTextureCoordinates(textureCoordinates);
	}
}
 

References

The info used in this tutorial is collected from:
Android Developers
OpenGL ES 1.1 Reference Pages

You can download the source for this tutorial here: Tutorial_Part_VI
You can also checkout the code from: code.google.com

Previous tutorial: OpenGL ES Tutorial for Android – Part V – More on Meshes

Programmer vs. User

Exceptions are intended for signaling programming errors and fatal errors that the application can never recover from. One such error is index out of bounds when accessing an array. There is little reason to catch any exception; if you for example could not calculate a legal array index the first time around your app is in an illegal state. Exceptions are for your own use as a developer, to catch all programming errors in testing before shipping to the end user. Only secondary to inform the user of fatal errors when possible.

Errors are intended for signaling user errors, and conditions that can not be predicted until the end user runs your application. One such error is network timeout. There are many reasons to catch these errors; e.g. the user could be asked to check the network connectivity, and try again. Errors should always be handled, and be properly presented to the user. A user is much more forgiving if your application fails with a clear reason, than if it simply crashes or refuses to work.

Signal and Handle Exceptions

Exceptions are thown in Objective-C, just as in most other programming languages. You can construct your NSException object manually, and throw it using the @throw compiler directive if you like. But the preferred way is to use the NSException convenience class methods.

[NSException raise:NSInvalidArgumentException
            format:@"Foo must not be nil"];

Here we see the first divergence from how for example Java and C# handles exceptions. In Objective-C different exceptions are not normally signaled by different subclasses, but instead the exception is given a name, in the form of a constant string. Exceptions are however handled quite traditionally.

@try {
    // Normal code flow, with potential exceptions
}
@catch (NSException* e) {
    // Handle exception or re-throw
}
@finally {
    // Mandatory cleanup
}

Signal and Handle Errors

Errors do not use any special feature of the Objective-C run-time or programming language. Errors are instead treated as normal method arguments.

For synchronous tasks the error is returned as the last out argument of the method. A typical synchronous method signature with error handling looks like this:

- (id)initWithContentsOfURL:(NSURL *)url
                      error:(NSError **)outError

The client of such a task can always pass NULL to explicitly ignore the details of the error, the method must therefor also signal the error by the return value. This is typically done by returning nil, or NO if no other return value should exist. Ignoring the error is never recommended.

For asynchronous tasks the error is returned as the last argument of a delegate method. A typical asynchronous method signature with error handling looks like this:

- (void)connection:(NSURLConnection *)connection
  didFailWithError:(NSError *)error

The client of such a task can never opt out of receiving the error. It is still never recommended to ignore the error.

The information in an NSError is always localized and phrased in end-user friendly words. This is something you can trust of errors from system frameworks, and a hard requirement on you when you create your own errors. Therefor handling the error is never a burden, in the simplest case you can simply display the localized error message to the end user and call it a day.

- (void)connection:(NSURLConnection *)connection
  didFailWithError:(NSError *)error
{
	[[[[UIAlertView alloc] initWithTitle:[error localizedDescription]
                                 message:[error localizedFailureReason]
                                delegate:nil
                       cancelButtonTitle:NSLocalizedString(@"OK", nil)
                       otherButtonTitles:nil] autorelease] show];
}

There is more to NSError

Cocoa and Cocoa Touch have much in common. Classes not brought straight over from Mac OS X to iOS often have a sibling anyway. One such class is NSAlert from Mac OS X and it's sibling UIAlertView on iOS. They serve the same purpose of displaying an alert message to the end user, optionally with a few choices in the form of buttons.

One convenience method for handling errors on Mac OS X is -[NSAlert alertWithError:], it did not survive the transformation to UIAlertView on iOS. It is a pity, since it is a convenient way to quickly setup an alert with all the localized and human readable information. Basically turning the example code for handling an asynchronous error above from five lines of code, into a single line of code.

But that is not all. NSAlert and NSError on Mac OS X also have standardize facilities for handling recovery options. For example adding a "Retry" button to the alert, and calling the correct methods in response to this user selection.

On iOS NSError still have all the facilities to handle error recoveries, it is only UIAlertView that is lacking the final user facing bits. Fortunately this is easy to add. NSError manages error recovery with information held in it's userInfo dictionary. The following keys are used:

• NSLocalizedRecoverySuggestionErrorKey - A localized text with a general suggestion for how to recover from the error, for example "Check the network connection".
• NSLocalizedRecoveryOptionsErrorKey - An array of localized button titles such as "Retry".
• NSRecoveryAttempterErrorKey - An object conforming to the informal protocol NSErrorRecoveryAttempting.

The informal protocol NSErrorRecoveryAttempting declares one method that is significant for iOS:

- (BOOL)attemptRecoveryFromError:(NSError *)error
                     optionIndex:(NSUInteger)recoveryOptionIndex

The recoveryOptionIndex is the index into the array of button titles, and is the actual choice the user made for recovering from the error.

Adding a -[UIAlertView alertWithError:] convenience method to UIAlertView is made really easy since Objective-C has categories, and classes themselves are object instances so we can use the UIAlertView class as alert delegate for error recovery alerts.

@implementation UIAlertView (CWErrorHandler)

static NSMutableDictionary* cw_recoveryErrors = nil;

+(void)alertViewCancel:(UIAlertView *)alertView;
{
    NSValue* key = [NSValue valueWithPointer:(const void *)alertView];
    [cw_recoveryErrors removeObjectForKey:key];
}

+ (void)alertView:(UIAlertView *)alertView
clickedButtonAtIndex:(NSInteger)buttonIndex;
{
    NSValue* key = [NSValue valueWithPointer:(const void *)alertView];
    NSError* error = [cw_recoveryErrors objectForKey:key];
	NSString* buttonTitle = [alertView buttonTitleAtIndex:buttonIndex];
    NSInteger recoveryIndex = [[error localizedRecoveryOptions]
                                   indexOfObject:buttonTitle];
    if (recoveryIndex != NSNotFound) {
	    [[error recoveryAttempter]
             attemptRecoveryFromError:error
                          optionIndex:recoveryIndex];
    }
    [cw_recoveryErrors removeObjectForKey:key];
}

+(UIAlertView*)alertViewWithError:(NSError*)error;
{
    UIAlertView* alert = [UIAlertView alloc];
    [[alert initWithTitle:[error localizedDescription]
                  message:[error localizedFailureReason]
                 delegate:nil
        cancelButtonTitle:NSLocalizedString(@"Cancel", nil)
        otherButtonTitles:nil] autorelease];
    if ([error recoveryAttempter]) {
    	if (cw_recoveryErrors == nil) {
			cw_recoveryErrors = [[NSMutableDictionary alloc]
                                     initWithCapacity:4];
        }
        NSValue* key = [NSValue valueWithPointer:(const void *)alertView];

        [cw_recoveryErrors setObject:error
                              forKey:key];
        for (id recoveryOption in [error localizedRecoveryOptions]) {
        	[alert addButtonWithTitle:recoveryOption];
        }
        alert.delegate = (id)self;
    }
    return alert;
}

@end

Conclusion

The clean separation of exceptions and errors help you as a developer to catch programming errors during development and with unit tests, and also handle errors of interest to the end users in a standardized and uniform way. The very nature of NSError encourages developers to write descriptive error messages that end users can understand and make informed discussions about. Errors are unavoidable in any application of non-neglectable complexity, gracefully handling these errors gives an aura of quality and ensures happy users. Happy users means better sales.

Full source code to the examples in this post, including some more convenience methods can be downloaded here, and are released under the Apache 2 open source license.

We start with creating a new eclipse plugin project and create our wizard class. The NewElementWizard we want to extend resides in the org.eclipse.jdt.ui bundle. So we add both org.eclipse.jdt.ui and org.eclipse.jdt.core to our plugin manifest:

Then we create a new class "NewActivityWizard":

package newwizard;

import org.eclipse.jdt.internal.ui.wizards.NewElementWizard;

public class NewActivityWizard extends NewElementWizard {

}

First thing we get is a warning
"Discouraged access: The type NewElementWizard is not accessible due to restriction on required library /Applications/eclipse/plugins/org.eclipse.jdt.ui_3.5.1.r351_v20090821-0800.jar".

The NewElementWizard belongs to an internal package and is only exported (using the 'xfriends' directive) to some chosen bundles. So we have the choice to have a look at the code of NewElementWizard and implement our wizard by extending org.eclipse.jface.wizard.Wizard instead, or we could make our plugin a fragment. Fragments are part of the OSGi R4 release and according to the specification a fragment is “a bundle that is attached to a host bundle”, adding content to the target bundle. For now we choose the later alternative, just because it requires less work.

Next thing we have to do is to override some methods of the superclass and of course we want to add our own wizard page. Our wizardpage will extend the org.eclipse.jdt.ui.wizards.NewTypeWizardPage. The following code is pretty much the same as in the wizards used internally in JDT as for example org.eclipse.jdt.internal.ui.wizards.NewClassCreationWizard.

public class NewActivityWizard extends NewElementWizard {

	private NewActivityWizardPage newActivityPage = null;

	public NewActivityWizard() {
        setWindowTitle("My new Android Activity");
        newActivityPage = new NewActivityWizardPage();
    }

	@Override
	public void addPages() {
        addPage(newActivityPage);
    }

    @Override
	 public void init(IWorkbench workbench, IStructuredSelection selection) {
    	newActivityPage.init(selection);
    }

    @Override
	public boolean canFinish() {
       return super.canFinish() &&
                   getContainer().getCurrentPage() == newActivityPage;
    }

	@Override
	protected void finishPage(IProgressMonitor monitor)	throws InterruptedException, CoreException {
		newActivityPage.createType(monitor);
	}

	@Override
	public IJavaElement getCreatedElement() {
		return newActivityPage.getCreatedType();
	}
}

Next we have to define the extension in the fragment.xml:

The most interesting part of the wizard page is the code generation part. We want to generate a onCreate method that takes a android.os.Bundle as argument:

private void generateOnCreate(IType type, ImportsManager imports) throws CoreException, JavaModelException {
	StringBuilder buf = new StringBuilder();
	final String delim = "\n";
	buf.append("@Override");
	buf.append(lineDelim);
	buf.append("public void onCreate(");
	buf.append(imports.addImport("android.os.Bundle"));
	buf.append(" savedInstanceState) {");
	buf.append(lineDelim);
	buf.append("super.onCreate(savedInstanceState);");
	buf.append(lineDelim);
	final String content =
            CodeGeneration.getMethodBodyContent(type.getCompilationUnit(),
               type.getTypeQualifiedName('.'), "onCreate", false, "", delim);
	if (content != null && content.length() != 0)
		buf.append(content);
	buf.append(lineDelim);
	buf.append("}"); //$NON-NLS-1$
	type.createMethod(buf.toString(), null, false, null);
}

This is just the basic version of the new wizard, we also want to add intent actions and categories and update the Android manifest file. The complete source is available at http://github.com/kobmic/adt-extensions.

So how do we update the android manifest? As a Java programmer dom4j and XStream are some of my favourite XML frameworks - but I'm quite enthusiastic about Scala and Scala provides XML support baked into the language. The XML generation code for a new Android activtiy with a given list of intent actions and categories in Scala looks like this:

def createXML(activityName: String, intentActions: List[String], intentCategories: List[String]) : Node = {
  val xml =
    
         {for(action <- intentActions)
             yield {}}
	 {for(category <- intentCategories)
             yield {}}
      
    
   xml
}

Putting it all together

I chose to do the XML manipulation (written in Scala) and the Wizard (written in Java) in different OSGi bundles. If you don't have the eclipse Scala IDE installed you even need the Scala library 2.7.7 as OSGi bundle. You can download the wizard with or without Scala dependencies from http://github.com/kobmic/adt-extensions/downloads.

The complete wizard looks like this:

At time of writing there's a new version of MOTODEV studio available, now even as a set of plugins to eclipse:
http://developer.motorola.com/docstools/library/Installing_MOTODEV_Studio_for_Android/#installingStudioPlugins

[someTextField performSelectorOnMainThread:@selector(setText:)
                              	withObject:@"A new text"
                             waitUntilDone:YES];

But not everything is an object

Since Objective-C is a superset of C, there are still all the types from C available. Such as all the primitives, including enums, and more complex struct types. Cocoa Touch is pragmatic and will use the most proper type for the use-case, not forcing everything into a square OOP hole.

This makes it quite hard to call for example -[UIView setHidden:], that takes a single BOOL argument. Same for -[UIView setFrame:], that takes a single CGRect struct argument, that in turn consists of one CGPoint and one CGSize struct.

Every type imaginable in C can be bundled in an NSValue instance. So we could bundle up the BOOL primitive, or the CGRect struct in a NSValue object. Then pass that object to the main thread, where it is unbundled and passed to the desired method. Quite cumbersome as it requires us to bundle, and unbundle types manually, and implement at least one extra method.

There must be an easier way

It turns out that NSInvocation can also handle any imaginable C type, or else it would not be able to invoke any imaginable Objective-C method. Making a NSInvocation invoke its method on the main thread is easy enough. Just add a category to the NSInvocation class, with a new method like this:

-(void)invokeOnMainThreadWaitUntilDone:(BOOL)wait;
{
  [self performSelectorOnMainThread:@selector(invoke)
                         withObject:nil
                      waitUntilDone:wait];
}

So now all you need to do is to create a NSInvocation object, fill it in with the primitive or struct types, and invoke it on the main thread. But creating and setting up a NSInvocation object is also a bit on the boring side...

There must be an even easier way!

We could use variable argument lists from plain old C. Too bad that they are untyped?
No despair, we know the target object for our invocation, and we know what method to call. So we have what we need to fetch the NSMethodSignature object for the call, that contains all the type information we need to safely process the va_list.

Our target machine is a Mac running 32- or 64-bit Intel CPU, or an iPhone OS device with a 32 bit ARM CPU. Turns out that on both platforms va_list is simply a void* pointer, to the stack frame. Even better va_start() will always flush any argument passed into the register on the stack frame. So we can skip most of the boring argument handling, by treating the arguments like a byte buffer, only advancing and aligning the buffer according to the information in the NSMethodSignature object.

A convenience method for creating a NSInvocation object for a particular target, selector, and list of variable arguments, would turn out like this:

+(NSInvocation*)invocationWithTarget:(id)target
                            selector:(SEL)aSelector
                     retainArguments:(BOOL)retainArguments, ...;
{
  va_list ap;
  va_start(ap, retainArguments);
  char* args = (char*)ap;
  NSMethodSignature* signature = [target methodSignatureForSelector:aSelector];
  NSInvocation* invocation = [NSInvocation invocationWithMethodSignature:signature];
  if (retainArguments) {
    [invocation retainArguments];
  }
  [invocation setTarget:target];
  [invocation setSelector:aSelector];
  for (int index = 2; index < [signature numberOfArguments]; index++) {
    const char *type = [signature getArgumentTypeAtIndex:index];
    NSUInteger size, align;
    NSGetSizeAndAlignment(type, &size, &align);
    NSUInteger mod = (NSUInteger)args % align;
    if (mod != 0) {
      args += (align - mod);
    }
    [invocation setArgument:args atIndex:index];
    args += size;
  }
  va_end(ap);
  return invocation;
}

Conclusion

And now we can easily call any method on the main UI thread.

An example where a CGRect struct is used to update the UI components frame;

// Set new frame of a label.
[[NSInvocation invocationWithTarget:someLabel
                           selector:@selector(setFrame:)
                    retainArguments:NO, CGRectMake(40, 40, 200, 100)]
 invokeOnMainThreadWaitUntilDone:NO];

A slightly more complex example, where we send a primitive int, and also waits for and fetches the result from the main thread:

// Query a UITableView for the number of rows in section 2.
NSInvocation* i = [NSInvocation invocationWithTarget:tableView
                                            selector:@selector(numberOfRowsInSection:)
                                     retainArguments:NO, (NSUInteger)2];
// Block this thread until method has been invoked and result is available.
[i invokeOnMainThreadWaitUntilDone:YES];
NSInteger numberOfRows;
[i getReturnValue:&numberOfRows];

Download full source code here: NSInvocation+CWVariableArguments.zip

Update: Example 2 was not 64-bit compatible as David Remahl pointed out to me. Added type cast to fix the error.

Update 2: A new version with some more features and small bug-fixes to BOOL, float and uint16_t types, plus proper unit tests can be downloaded here: CWFoundationAsyncAdditions.zip

When I started I had problems with finding out how to programmatic make different meshes like cubes, cones and so on. I needed this so I easy easy could put my scenes together. So this tutorial will show how to make some of the basic primitives. They might not be the most effective way of creating them but it is a way of doing them.

Starting point will be from the source of the second tutorial. I will show you plane and cube and then give you a couple of hint for additional primitives.

Design

A good place to start when designing an OpenGL framework is to use the composite pattern. This is a start of how I would proceed:

Let's start making out pattern.

Mesh

It's a good idea to have a common base for your meshes. So let us start by creating a class called Mesh.

package se.jayway.opengl.tutorial.mesh;
public class Mesh {
 
}

We add the draw function from previous example, since I when over this function in a previous tutorial I just show it here:

    // Our vertex buffer.
    private FloatBuffer verticesBuffer = null;
 
    // Our index buffer.
    private ShortBuffer indicesBuffer = null;
 
    // The number of indices.
    private int numOfIndices = -1;
 
    // Flat Color
    private float[] rgba = new float[]{1.0f, 1.0f, 1.0f, 1.0f};
 
    // Smooth Colors
    private FloatBuffer colorBuffer = null;
 
    public void draw(GL10 gl) {
        // Counter-clockwise winding.
	gl.glFrontFace(GL10.GL_CCW);
	// Enable face culling.
	gl.glEnable(GL10.GL_CULL_FACE);
	// What faces to remove with the face culling.
	gl.glCullFace(GL10.GL_BACK);
	// Enabled the vertices buffer for writing and to be used during
	// rendering.
	gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);
	// Specifies the location and data format of an array of vertex
	// coordinates to use when rendering.
	gl.glVertexPointer(3, GL10.GL_FLOAT, 0, verticesBuffer);
        // Set flat color
        gl.glColor4f(rgba[0], rgba[1], rgba[2], rgba[3]);
        // Smooth color
        if ( colorBuffer != null ) {
            // Enable the color array buffer to be used during rendering.
            gl.glEnableClientState(GL10.GL_COLOR_ARRAY);
            // Point out the where the color buffer is.
            gl.glColorPointer(4, GL10.GL_FLOAT, 0, colorBuffer);
        }
	gl.glDrawElements(GL10.GL_TRIANGLES, numOfIndices,
		GL10.GL_UNSIGNED_SHORT, indicesBuffer);
	// Disable the vertices buffer.
	gl.glDisableClientState(GL10.GL_VERTEX_ARRAY);
	// Disable face culling.
	gl.glDisable(GL10.GL_CULL_FACE);
    }

We need functions where the subclasses can set the vertices and the indices. These function contains nothing new and are pretty much the same as you seen in earlier tutorials.

    protected void setVertices(float[] vertices) {
	// a float is 4 bytes, therefore we multiply the number if
	// vertices with 4.
	ByteBuffer vbb = ByteBuffer.allocateDirect(vertices.length * 4);
	vbb.order(ByteOrder.nativeOrder());
	verticesBuffer = vbb.asFloatBuffer();
	verticesBuffer.put(vertices);
	verticesBuffer.position(0);
    }
 
    protected void setIndices(short[] indices) {
	// short is 2 bytes, therefore we multiply the number if
	// vertices with 2.
	ByteBuffer ibb = ByteBuffer.allocateDirect(indices.length * 2);
	ibb.order(ByteOrder.nativeOrder());
	indicesBuffer = ibb.asShortBuffer();
	indicesBuffer.put(indices);
	indicesBuffer.position(0);
	numOfIndices = indices.length;
    }
 
    protected void setColor(float red, float green, float blue, float alpha) {
        // Setting the flat color.
        rgba[0] = red;
        rgba[1] = green;
        rgba[2] = blue;
        rgba[3] = alpha;
    }
 
    protected void setColors(float[] colors) {
	// float has 4 bytes.
	ByteBuffer cbb = ByteBuffer.allocateDirect(colors.length * 4);
	cbb.order(ByteOrder.nativeOrder());
	colorBuffer = cbb.asFloatBuffer();
	colorBuffer.put(colors);
	colorBuffer.position(0);
    }

We need to add a couple of things. When we start working with multiple meshes we need to be able to move and rotate them individual so let us add translation and rotation parameters:

    // Translate params.
    public float x = 0;
    public float y = 0;
    public float z = 0;
 
    // Rotate params.
    public float rx = 0;
    public float ry = 0;
    public float rz = 0;

And use them in the draw function add this lines just before the gl.glDrawElements call.

    gl.glTranslatef(x, y, z);
    gl.glRotatef(rx, 1, 0, 0);
    gl.glRotatef(ry, 0, 1, 0);
    gl.glRotatef(rz, 0, 0, 1);

Plane

Let us start making a plane an quite easy task you might think and it kinda is. But to make it more interesting and more useful we need to be able to create it with some different settings like: width, depth, how many width segments and how many depth segments.

Just so we have the same terminology, width is the length over the x-axis, depth is over the z-axis and height is over the y-axis. Look at the image below as a visual input.

Width, height and depth.

Segments is how many parts the length should be divided by. This is useful if you need to make a surface that is not total even. If you create a plane over x, y and make z not all be 0 say you give z a random span from -0.1 to 0.1 you will get something you could use as a ground plane in a game just put a nice texture on it.

Segments.

Looking at the image above you see that the different segments gives you squares. Since we like it to be triangles so just split them up into 2 triangles.

I hate frameworks and classes that don't have a default setup and easy class constructors I try to always have more then one constructor. The constructors I will put in this plane is:

For an easy and quick setup:

// Gives you a plane that is 1 unit wide and 1 unit high with just one segment over width and height.
public Plane()

An easy one just to change the size:

 // Let you decide the size of the plane but still only one segment.
public Plane(float width, float height)

And finally one for setting up the plane with different segments:

// For alla your settings.
public Plane(float width, float height, int widthSegments, int heightSegments)

If I in theory would construct a plane that is 1 unit wide and 1 units high with 4 segments in both width and height direction it would look like this images:

The one to the left shows the segments and the one to the right show us the faces we need to create.

package se.jayway.opengl.tutorial.mesh;
 
public class Plane extends Mesh {
 
    public Plane() {
	this(1, 1, 1, 1);
    }
 
    public Plane(float width, float height) {
	this(width, height, 1, 1);
    }
 
    public Plane(float width, float height, int widthSegments,
		int heightSegments) {
	float[] vertices = new float[(widthSegments + 1) * (heightSegments + 1)
			* 3];
	short[] indices = new short[(widthSegments + 1) * (heightSegments + 1)
			* 6];
 
	float xOffset = width / -2;
	float yOffset = height / -2;
	float xWidth = width / (widthSegments);
	float yHeight = height / (heightSegments);
	int currentVertex = 0;
	int currentIndex = 0;
	short w = (short) (widthSegments + 1);
	for (int y = 0; y < heightSegments + 1; y++) {
            for (int x = 0; x < widthSegments + 1; x++) {
	        vertices[currentVertex] = xOffset + x * xWidth;
		vertices[currentVertex + 1] = yOffset + y * yHeight;
		vertices[currentVertex + 2] = 0;
		currentVertex += 3;
 
		int n = y * (widthSegments + 1) + x;
 
		if (y < heightSegments && x < widthSegments) {
		    // Face one
		    indices[currentIndex] = (short) n;
		    indices[currentIndex + 1] = (short) (n + 1);
		    indices[currentIndex + 2] = (short) (n + w);
		    // Face two
		    indices[currentIndex + 3] = (short) (n + 1);
		    indices[currentIndex + 4] = (short) (n + 1 + w);
		    indices[currentIndex + 5] = (short) (n + 1 + w - 1);
 
		    currentIndex += 6;
		}
	    }
	}
 
	setIndices(indices);
	setVertices(vertices);
    }
}

Cube

The next step I think a cube will be nice. I will only make a cube that you can set: height, width and depth on but I suggest you as a practice make it with segments just as we did with the plane.

The constructor will look like this:

public Cube(float width, float height, float depth)

And since I'm not doing this with any segments the constructor will be quite easy.

package se.jayway.opengl.tutorial.mesh;
 
public class Cube extends Mesh {
    public Cube(float width, float height, float depth) {
        width  /= 2;
        height /= 2;
        depth  /= 2;
 
        float vertices[] = { -width, -height, -depth, // 0
                              width, -height, -depth, // 1
                              width,  height, -depth, // 2
                             -width,  height, -depth, // 3
                             -width, -height,  depth, // 4
                              width, -height,  depth, // 5
                              width,  height,  depth, // 6
                             -width,  height,  depth, // 7
        };
 
        short indices[] = { 0, 4, 5,
                            0, 5, 1,
                            1, 5, 6,
                            1, 6, 2,
                            2, 6, 7,
                            2, 7, 3,
                            3, 7, 4,
                            3, 4, 0,
                            4, 7, 6,
                            4, 6, 5,
                            3, 0, 1,
                            3, 1, 2, };
 
        setIndices(indices);
        setVertices(vertices);
    }
}

If you like to make it with segments the constructor could look like this:

public Cube(float width, float height, float depth,
                 int widthSegments, int heightSegments, int depthSegments)

Since we now have a plane that replaces the Square class ( in the code from tutorial II ) I will just remove it and in OpenGLRenderer change the square to a cube...

public OpenGLRenderer() {
    // Initialize our cube.
    cube = new Cube(1, 1, 1);
    cube.rx = 45;
    cube.ry = 45;
}

... and render it.

public void onDrawFrame(GL10 gl) {
    ...
    // Draw our cube.
    cube.draw(gl);
}

Group

A group is really good to have when setting up and controlling your 3D scene. What a group really do is to distribute all commands sent to the group to all it's children. You can see the implementation of a simple group here:

package se.jayway.opengl.tutorial.mesh;
 
import java.util.Vector;
 
import javax.microedition.khronos.opengles.GL10;
 
public class Group extends Mesh {
    private Vector<Mesh> children = new Vector<Mesh>();
 
    @Override
    public void draw(GL10 gl) {
        int size = children.size();
        for( int i = 0; i < size; i++)
            children.get(i).draw(gl);
    }
 
    public void add(int location, Mesh object) {
        children.add(location, object);
    }
 
    public boolean add(Mesh object) {
        return children.add(object);
    }
 
    public void clear() {
        children.clear();
    }
 
    public Mesh get(int location) {
        return children.get(location);
    }
 
    public Mesh remove(int location) {
        return children.remove(location);
    }
 
    public boolean remove(Object object) {
        return children.remove(object);
    }
 
    public int size() {
        return children.size();
    }
}

Make the renderer work with a group as a root node and add your cube to it.

Group group = new Group();
Cube cube = new Cube(1, 1, 1);
cube.rx = 45;
cube.ry = 45;
group.add(cube);
root = group;

And draw our scene:

public void onDrawFrame(GL10 gl) {
    ...
    // Draw our scene.
    root.draw(gl);
}

Suggestions

It's always a good idea to have different primitives ready to use when you starting up a new project. My experience tell me that in 9 times of 10 you won't have any meshes from the graphic people when you start coding so it's really good to have some meshes to work with as place holders. I'll give you a hint of the way to start with your own meshes library by giving you an idea of how I would do it.

Creating your own meshes is a really good way of getting to know vertices and indices really close up.

Cone

After you have gotten your cube up and ready to go my suggestion is that you move onto a cone. A cone with the right settings could be more then just a cone. if you give is 3-4 sides it will be a pyramid. If you give it the same base and top radius it becomes a cylinder. So you can see why it is so useful. Take a look at this image and see what the this cone can do.

public Cone(float baseRadius, float topRadius, float height, int numberOfSides)

Pyramid

public class Pyramid extends Cone {
    public Pyramid(float baseRadius, float height)  {
        super(baseRadius, 0, height, 4);
    }
}

Cylinder

public class Cylinder extends Cone {
    public Cylinder(float radius, float height)  {
        super(radius, radius, height, 16);
    }
}

One more thing

Dividing up surfaces is a good thing to know about and by now you know how to divide up a regular square. To divide up a triangle look at the images below. It is a bit different and it might be a bit harder to implement.

References

The info used in this tutorial is collected from:
Android Developers
OpenGL ES 1.1 Reference Pages

You can download the source for this tutorial here: Tutorial_Part_V
You can also checkout the code from: code.google.com

Previous tutorial: OpenGL ES Tutorial for Android – Part IV – Adding colors
Next tutorial: OpenGL ES Tutorial for Android – Part VI – Textures

This is the second part of the blog post I wrote about TDD in XCode. Make sure you've followed that tutorial before continuing here, or at least have a project of your own with OCUnit tests ready.

The server which we'll use is called Hudson and is very popular in the Java community. It does not readily support XCode projects but it does allow shell commands, so we'll use that to make our Calculator project compatible. We also want to fetch new versions of the source code as soon as it's checked in. We'll be a bit fancy and use Git as source control software. Here's a summary of what we want to do:

1. Download and install the Hudson continuos integration server
2. Download, install and setup the Git source control software as well as the Git plugin for Hudson
3. Download and install a script that converts OCUnit test results to JUnit format
4. Setup a new job in Hudson that checks out our XCode project and builds and tests it
5. Set up a notification and try it out

Downloading and Installing Hudson

In order to keep the instructions in this tutorial simple, we will have the source code repository and the build server itself on localhost. In real life you'll probably want to setup a dedicated machine.

Head over to the Hudson web site and download your copy of the server. Follow their included installation instructions, it's quite simple. Once you have Hudson up and running you can visit http://localhost:8080 to see the welcome screen. By the way, when you're ready to install Hudson on a real remote server I recommend running it as a Servlet inside Apache Tomcat instead.

Downloading and Setting Up Git

Next we want to install Git. There are several ways to install it. The simplest might be to use the OS X installer, but I personally prefer MacPorts. Either way, go ahead and install it and make sure that you can use the "git" command from Terminal.app when you're done.

In the Terminal, change directory to your XCode project folder and type:

		git init
	

You now have a working source code repository in your project folder. Neat. Before you continue create a text file called .gitignore and let it contain:

		build/*
		*.pbxuser
		*.mode1v3
		.DS_Store
		test-reports/*
	

That's a listing of the files and folders that should not be version controlled, since they are temporary or just used for XCode. Feel free to add any other files that you think only should be present locally. Now add all files (that aren't ignored) using:

		git add *
	

and finally commit them to a first version using:

		git commit -m "Initial import"
	

Fetching the Script

We need to fetch one more thing, ocunit2junit.rb, which is a little Ruby script that I wrote. Since you now have git, you can also download it using git (or clone the repo, which is the correct term). Change directory to /tmp and then type like this:

git clone git://github.com/ciryon/OCUnit2JUnit.git

Copy the script from /tmp/OCUnit2JUnit/ anywhere, like to /usr/local/bin/. Make sure it's executable by typing chmod +x ocunit2junit.rb.

The script will parse output from xcodebuild (the console command for building your XCode project) and look for output from OCUnit. The test results (success, failure, time passed etc) will be saved in the "test-reports" folder in the same XML format that JUnit uses. This also happens to be a format that Hudson understands.

Setting Up Hudson

Now head back to your Hudson welcome screen. Select Manage Hudson, Manage plugins and check "Hudson GIT plugin" under Available. Hudson will automatically download and install the plugin. Afterwards just restart Hudson.

We're ready to create a job in Hudson for our project. From the main screen select "New job", Build a free-style software project and call it "Calculator". There are some settings which you should fill in:

• Select to use git as source code management tool. The URL should be the file path to your project, like:

  /Users/youruser/XCodeProjects/Calculator/

• Select to poll SCM with Schedule:

  * * * * *

  That means it'll check every minute if there are changes. If you want to check less often, do that.

• Add new build step and select to execute shell. Use this command (make sure to point to the version of the iPhone SDK you want to use):

  xcodebuild -target "UnitTests" -sdk /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator3.1.2.sdk/ -configuration "Debug" | /usr/local/bin/ocunit2junit.rb

• Select to also publish a JUnit test result report and the Test report XMLs reside at

  test-reports/*.xml

Trying it out

This is the moment of truth. Try to change your CalculatorTest.m so that one of the test cases fail. Type:

	git -a commit CalculatorTest.m "Broke the test, on purpose"

and see what happens. If all goes well, and you have entered everything correctly, Hudson should automatically notice there's a new version available, build it and try to run the test suite. Check the results and how it reports the test failure. Nice, eh? Fix the error and commit the test class again to see how Hudson reacts.

There are many settings, plugins and cool things to try out in Hudson. Go into Manage Hudson-> Configure system and setup your email settings, to allow Hudson to send mail. Then go back to configure your Calculator job and at the bottom select E-mail Notification. Enter your own email address and see how it works after you commits a file that breaks the build. If you don't want a mail, you can get an instant message, or perhaps have the server play a loud annoying sound? Everyone in your team should be aware of when a build fails, so it can be fixed right away. This is one of the great advantages of having a continuos integration server.

There's a few reasons when to use JNI in a Java program

• Wrap lower level functionality - Classes in the Android Application Framework uses JNI to interface with the underlying platform and hardware like Camera, Sensors and GPS.
• Interface native legacy code - You might have some old legacy code written in C/C++ and you don't want to waste your time porting the code to Java. With JNI you can create an interface class in Java that exposes the functionality of your legacy code.
• Bypass performance bottlenecks - Execute heavy number crunching in native code and get rid of the overhead that the instruction interpretation in the JVM introduces.

On Android, in order to prevent fragmentation, we are only allowed to use the following libraries in our native code.

• libc (C library) headers
• libm (math library) headers
• JNI interface headers
• libz (Zlib compression) headers
• liblog (Android logging) header
• OpenGL ES 1.1 (3D graphics library) headers (since 1.6)
• A Minimal set of headers for C++ support

In this blog I will demonstrate how to transform a time consuming Java method with a lot of number crunching into a native declared method where the real work is performed in native code. Here's the time consuming Java method

public double compare(int[] sourceData,int[] targetData, double targetError) {
  double error = 0.0D;
  for (int index = 0; index < targetData.length; index++) {
    int c1 = sourceData[index];
    int c2 = targetData[index];
    int b = (c1 >> 16 & 255) - (c2 >> 16 & 255);
    int g = (c1 >> 8 & 255) - (c2 >> 8 & 255);
    int r = (c1 & 255) - (c2 & 255);
    error += r * r + g * g + b * b;
    if (error > targetError)
      return error;
  }
  return error;
}

The sourceData and targetData arguments represents the pixels of two Bitmaps. In short the method calculates the sum of the square distance in color between two images, pixel by pixel. If we compare two 200x200 pixels images the for-loop will run 40000 times! This is a typical candidate for when to use JNI.

What to do in Native

You can use the boilerplate.c file as boilerplate code for all your native c functions.

Implement the native function

This is what the function will look like when written in C.

static jdouble compareNative(JNIEnv *env, jobject thiz, jintArray sourceArr,
                                                jintArray targetArr, jdouble targetError){
  jdouble error = 0.0;
  int index, c1, c2, b, g, r  = 0;
  jint *sarr, *tarr;

  sarr = (*env)->GetIntArrayElements(env, sourceArr, NULL);
  tarr = (*env)->GetIntArrayElements(env, targetArr, NULL);

  if (sarr == NULL || tarr == NULL) {
         return targetError; /* exception occurred */
  }

  int size = (*env)->GetArrayLength(env, sourceArr);

  for (index = 0; index < size; index++) {
    c1 = sarr[index];
    c2 = tarr[index];
    b = (c1 >> 16 & 255) - (c2 >> 16 & 255);
    g = (c1 >> 8 & 255) - (c2 >> 8 & 255);
    r = (c1 & 255) - (c2 & 255);
    error += r * r + g * g + b * b;
    if (error > targetError){
      (*env)->ReleaseIntArrayElements(env, sourceArr, sarr, 0);
      (*env)->ReleaseIntArrayElements(env, targetArr, tarr, 0);
      return error;
    }
  }
 (*env)->ReleaseIntArrayElements(env, sourceArr, sarr, 0);
 (*env)->ReleaseIntArrayElements(env, targetArr, tarr, 0);
 return error;
}

All native functions must have the JNIEnv (a reference to the virtual machine itself) and the jobject (a reference to the "this pointer" of the Java object where the native method call comes from) as the first two arguments. Then we can add our own arguments. For more information on how to write native code for JNI see the JNI Reference Documentation.

Register your native functions

We need a way to make the virtual machine direct the calls to the native declared Java method to our native C function. This is done using the registerNatives function of the JNIEnv. If you use the boilerplate C code from above you only have to do two things.

1. Set the classpath variable to the full class name of your Java class (including package name). Replace the dots with slashes.
2. For each native declared method in Java, insert a JNINativeMethod struct into the methods[] array.

For our example it will look like this

static const char *classPathName = "com/jayway/MyComparator";

static JNINativeMethod methods[] = {
  // nameOfNativeMethod, methodSignature, methodPointer
  {"compare", "([I[ID)D", (void*)compareNative },
};

The first parameter is the name of the native declared Java method, the second is the signature of the native declared Java method and the last parameter is the function pointer to the C function to execute when the native declared Java function is executed.

The signature of a Java method can be determined using the javap tool from SUN's Java SDK or you can create it yourself using the following table, Java VM Type Signatures.

Build using Android NDK

To make things really simple when developing JNI code Google has released the Android Native Development Kit (NDK). It's easy to setup and use. Just setup a new project according to the NDK documentation and build your project. In short, you create a folder named jni in your Android Eclipse project. Here you put all the c-files together with an Android.mk file. In the Android.mk you specify which c-files to compile. In the Android NDK/apps folder you create a directory named after your project (perhaps my-app). In this directory you add an Application.mk file. In the Application.mk, set the APP_PROJECT_PATH to the path of your Eclipse project. To create the lib simply type make APP=my-app from the console in your Android NDK folder. If everything goes well you will see a libs folder in your Eclipse project.

What to do in Java

In order to transform our Java method into a native declared method simply add the word native in the method signature and remove the implementation of the method.

 
public native double compare(int[] sourceData, int[] targetData,
			double targetError);
 

To make sure that the virtual machine loads our library into memory and register our native functions we have to add the following code.

static{
  System.loadLibrary("comparejni");
}

This tells the virtual machine to load the library libcomparejni.so from the underlying operating system. The OnLoad function is executed on the library and our native functions gets registered with the virtual machine.

The Result

After some simple benchmarking I found that the native declared method executed about 2-3 times faster than the original method executing within Dalvik. For larger images the improvement might be even bigger since a call to a native declared method takes more time than calling a normal Java method. Eventually, when Dalvik supports JIT compilation, we would probably get the above performance boost for free without calling native functions. But bear in mind, most devices on the market today will never get an upgraded Dalvik with JIT.

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

That means that test cases are written before any production code. Not all tests are written up front, it's rather that a small test is written, then a small piece of production code is written that only allows that test to pass. This is repeated in many small iterations: test, fail, code, pass, test, fail, code, pass...

Many people consider TDD to encourage clean code, simple architectures and a stable system that's actually testable. Plus, it's also fun! We've previously written about various aspects of TDD, but in this tutorial we'll focus on how it works for XCode projects, where you write apps for Mac and iPhone. We will create a simple XCode project, do some special configuration steps and then demonstrate how TDD can be used to write your app. We're going to use OCUnit and its framework SenTestingKit, which nowadays is included with Apple's XCode tools.

Creating the Calculator project

Let's start by creating a new project in XCode. You can pick any template, since we aren't going to touch the generated code. I picked a Window-based iPhone project. Name the project Calculator. Select New Target from the Project menu. Under Cocoa select Unit test Bundle. Call it UnitTests (I've had problems with space in the target name so avoid that) and add it to the project. We now need to change some small settings for this target. Select the UnitTests target and hit Command-I for Info. Select the Build tab and locate Other Linker Flags. Replace Cocoa with Foundation. Also remove the entry for GCC_PREFIX_HEADER.

Now it's time to create your test suite. Create a new group in your project and call it "Test Classes". Add a new File to this group and make sure it's a Cocoa->Objective-C test case class. Name it CalculatorTest.m. Uncheck "Also create CalculatorTest.h" since we don't need a header file. Don't add it to the Calculator target, but check it to be included in UnitTests. Open CalculatorTest.m file and above the @implementation declaration add:

#import <SenTestingKit/SenTestingKit.h>
#import "Calculator.h"
@interface CalculatorTest : SenTestCase
{

}
@end

This is just because we don't want a rather empty header file. All your test classes will look like this.

Following TDD, we should build right away. First make sure that the active target is "UnitTets" and then press the "Build" button. This will not only do a normal build, but also perform some shell script magic and actually execute the unit tests. Now the build fails of course, since Calculator.h can't be found.

So let's add a file which represents production code. Create a new empty Cocoa Touch Objective-C class called Calculator.m (also create the .h file), this is the class that we want to test. Don't forget to check that they should be included in both your targets. Notice that we mix Cocoa and Cocoa Touch, that's is fine - all code is executed on your Mac. Build again, and this time you'll see in the build log that everything built and the test suite was executed, but contained 0 test cases. Let's remedy that.

Writing test cases

Next we want to write our first test case. Open up CalculatorTest.m and add the following method:

-(void)testAdd
{
        Calculator* calculator = [[Calculator alloc] init];
        int result = [calculator add:5 to:6];
}

All methods that start with "test" will be recognized as being a test case, and automatically run when building the target. Try and build and you'll unsurprisingly get the erro "unrecognized selector sent to instance...". That's all good. Let's add the add method to our Calculator class. In Calculator.h add:

-(int)add:(int)a to:(int)b;

Then in Calculator.m add:

-(int)add:(int)a to:(int)b
{
        return 0;
}

That should be enough to let it compile and run, right? Try it out! You'll see that it indeed build and executes the tests.

Now we change the test so that it actually checks that we get the expected value back. We want to "assert" that the returned value is what we expected. Change the test case to look like this:

-(void)testAdd
{
        Calculator* calculator = [[Calculator alloc] init];
        int expected = 11;
        int result = [calculator add:5 to:6];
        STAssertEquals(expected, result,
                @"We expected %d, but it was %d",expected,result);
}

Build and you see that the test runs and fails since our calculator always returns 0 regardless of the input. Change the production code so that it returns a+b and rerun the test. Nice, we have a successful build and our test works! Notice the fast cycle of test, code, fix, rerun. The point of TDD is to write tests and production code in small iterations so that you always have something stable (= the tests pass). If you follow the rules of TDD you'll have a growing amount of test cases and you'll right away know when something breaks.

Let's write one more test. Now we want to add the functionality to allow one number to be divided by another. Start up like before with a new test case like this:

-(void)testDivide
{
        Calculator* calculator = [[Calculator alloc] init];
        float expected = 2.5;
        int result = [calculator divide:5 by:2];
        STAssertEquals(expected, result,
                @"We expected %d, but it was %d",expected,result);
}

You see, this time we expect to get back a float. Add the corresponding divide method to Calculator.h and Calculator.m. If you need help see the full code listing at the end of this article. You might notice that just returning a/b gives you 2.0. Type cast the return value to (float)a/b and you'll be fine. Go ahead when you got it working.

What happens if you try to divide something with zero? Well, why not add a test case for this scenario? If you're into maths you know that the result of this operation is undefined. How do you expect something to be undefined? This is tricky. Start off by just expecting any number and see what you get back. As you see, the float value "inf" is returned. It seems like Objective-C treats the zero as "a value approaching zero" and that will indeed result in infinity in a division. But, hey, that might not be what we want our calculator to do. Let's change the test case to expect an exception to be raised instead:

-(void)testDivideByZero
{
        Calculator* calculator = [[Calculator alloc] init];
        STAssertThrows([calculator divide:5 by:0],
                @"We expected an exception to be raised when dividing by 0");
}

Build and notice the error message when no exception was raised. Now change the production code to something like this:

-(float)divide:(int)a by:(int)b
{
        float result =  (float)a/b;
        if (result==INFINITY) {
                [NSException raise:@"Cannot divide by zero!"
                            format:@"Not possible to divide %d with %d", a,b];
        }
        return result;
}

Rerun and smile as the test passes! There are many different variants of asserts you can do with SenTestingKit. Compare objects with STAssertEqualObjects. STAssertTrue to check that a returned boolean is true. Open up SentTestCase_Macros.h if you want to see what you can play around with. By the way. You might have tried using NSLog in your test cases (just to experiment). This is nothing you would do in real life, as you want all necessary information in the fail message and output nothing if the test passes. Anyway, since the tests are actually run using a separate shell script for the UnitTest target you won't see the log in your console as usual. Instead check the build log and click the "text" icon to the right for the "Run test suite" step.

Wrapping up

Finally, if you look at your test class you might notice that we're allocating a new Calculator for every test case, and we never release them. That's no good. Luckily there are setUp and tearDown methods that will be launched automatically before and after each test case. Change your implementation to look like this (this is the final listing):

#import <SenTestingKit/SenTestingKit.h>
#import "Calculator.h"
@interface CalculatorTest : SenTestCase
{
        Calculator* calculator;
}
@end

@implementation CalculatorTest

- (void) setUp
{
        calculator = [[Calculator alloc] init];
}

-(void)tearDown
{
        [calculator release];
}

-(void)testAdd
{
        int expected = 11;
        int result = [calculator add:5 to:6];
        STAssertEquals(expected, result,
                @"We expected %d, but it was %d",expected,result);
}

-(void)testDivide
{
        float expected = 2.5;
        float result = [calculator divide:5 by:2];
        STAssertEquals(expected, result,
                @"We expected %f, but it was %f",expected,result);
}

-(void)testDivideByZero
{
        STAssertThrows([calculator divide:5 by:0],
                @"We expected an exception to be raised when dividing by 0");
}
@end

For completeness, here's the listing for Calculator.h:

#import 

@interface Calculator : NSObject {

}

-(int)add:(int)a to:(int)b;
-(float)divide:(int)a by:(int)b;

@end

and for Calculator.m:

#import "Calculator.h"

@implementation Calculator

-(int)add:(int)a to:(int)b
{
        return a+b;
}

-(float)divide:(int)a by:(int)b
{
        float result =  (float)a/b;
        if (result==INFINITY) {
                [NSException raise:@"Cannot divide by zero!"
                            format:@"Not possible to divide %d with %d", a,b];
        }
        return result;
}

@end

Next blog post we'll see how to automate the running of test cases on a build server called Hudson!

Adding color

3D models with no colors are pretty boring so let's add some color to it. In general colors need no explanation. OpenGL ES uses a color model called RGBA ( Red, Green, Blue and Alpha ). The first three are self explained. The fourth is transparency, how solid the color should be. If you like to read more about colors go to: RGB color model - Wikipedia, the free encyclopedia

You might be familiar with defining colors with hex (#FF00FF) or with decimals (255, 0, 255) we will use 0..1 where 0 map to 0 (#00) and 1 map against 255 (#FF).

The easiest way of coloring meshes is called vertex coloring and I am going to show you two different ways of doing that. Flat coloring that gives one solid color and smooth coloring that will blend colors specified for each vertex. Texturing is also a way of giving your mesh colors but it is not vertex coloring so I will show you how to do that in a later tutorial.

Flat coloring

Flat coloring is really easy just tell OpenGL ES what color to use when it is going to render. One thing to remember is that when you set the color OpenGL ES uses this color until you change the color. This means that if you have two different squares and you tell OpenGL ES to change the color right before the second square the first frame the two squares will have different color but the next rendered frame both squares will have the same color.

To tell OpenGL ES what color to work with you use this command:

public abstract void glColor4f(float red, float green, float blue, float alpha)

The default values are: red = 1, green = 1, blue = 1 and alpha = 1. Those values are white, and that's why all the squares we previous made has a white color.

Create a new class called FlatColoredSquare it should be identical to the Square class. Then in the FlatColoredSquare function draw, add this line:

gl.glColor4f(0.5f, 0.5f, 1.0f, 1.0f); // 0x8080FFFF

I usually add a comment like the one above ( // 0x8080FFFF ) because I am used to read that. It makes it easier for me when reviewing the code.

It should now look like this:

public void draw(GL10 gl) {
        gl.glColor4f(0.5f, 0.5f, 1.0f, 1.0f);
        ...

Then change in the renderer so it uses the FlatColoredSquare instead of the Square.

public class OpenGLRenderer implements Renderer {
	private FlatColoredSquare flatSquare; // CHANGED

	public OpenGLRenderer() {
		// Initialize our square.
		flatSquare = new FlatColoredSquare(); // CHANGED
	}

        public void onDrawFrame(GL10 gl) {
                ...
		flatSquare.draw(gl); // Don't forget to change this one.
                ...
	}

Remember that anything rendered after you set a color uses the same color and that this spans over frames and will not be reset in-between.

If you compile and run the application you will see one big flat colored blue square.

Just to give place to the smooth colored square coming up we move the flat square up.

public void onDrawFrame(GL10 gl) {
	gl.glLoadIdentity();
	// Translates 7 units into the screen and 1.5 units up.
	gl.glTranslatef(0, 1.5f, -7);
        // Draw our flat square.
	flatSquare.draw(gl);
}

Notice that with flat coloring you don't need to tell OpenGL ES to turn it on or off. OpenGL ES uses flat coloring as a default way of coloring the meshes.

Smooth coloring

Smooth coloring is gained when you give each vertex its own color. OpenGL ES will interpolate the colors between the vertices and you will gain a smooth coloring effect. Just as with the flat coloring you tell OpenGL ES what to work with and it will be used as long as you don't say anything else.

Create a new class called SmoothColoredSquare it should be identical to the Square class just as you did with the FlatColoredSquare. Modify the new class with this:

Define the colors you like your vertices to have.

public class SmoothColoredSquare {
        ...
        // The colors mapped to the vertices.
        float[] colors = {
                1f, 0f, 0f, 1f, // vertex 0 red
                0f, 1f, 0f, 1f, // vertex 1 green
                0f, 0f, 1f, 1f, // vertex 2 blue
                1f, 0f, 1f, 1f, // vertex 3 magenta
        };
        ...

The order of defining the colors are important since they map against the vertices so in this example above the first color (1f, 0f, 0f, 1f ) map against the top left vertex ( -1.0f, 1.0f, 0.0f ) the green against the bottom left vertex and the rest you can figure out. Hint: Look at the image above.

And put them in a buffer just as we did with the vertices and indices.

public SmoothColoredSquare() {
	...

	// float has 4 bytes, colors (RGBA) * 4 bytes
	ByteBuffer cbb = ByteBuffer.allocateDirect(colors.length * 4);
	cbb.order(ByteOrder.nativeOrder());
	colorBuffer = cbb.asFloatBuffer();
	colorBuffer.put(colors);
	colorBuffer.position(0);
	}

Don't forget to add colorBuffer as a variable to the class as well.

        // Our color buffer.
	private FloatBuffer colorBuffer;

We also need to enable the color buffer and tell openGL where it is.

public void draw(GL10 gl) {
        ...
	gl.glVertexPointer(3, GL10.GL_FLOAT, 0, vertexBuffer);

	// Enable the color array buffer to be used during rendering.
	gl.glEnableClientState(GL10.GL_COLOR_ARRAY); // NEW LINE ADDED.
	// Point out the where the color buffer is.
	gl.glColorPointer(4, GL10.GL_FLOAT, 0, colorBuffer); // NEW LINE ADDED.

	gl.glDrawElements(GL10.GL_TRIANGLES, indices.length,
				GL10.GL_UNSIGNED_SHORT, indexBuffer);
	...
        // Disable the color buffer.
	gl.glDisableClientState(GL10.GL_COLOR_ARRAY);
        ...
	}

Don't forget to disable the use of the color array. If you don't disable the color array both squares will be smooth colored. Try it.

Let's use this new smooth square as well. Start by adding it to your renderer.

public class OpenGLRenderer implements Renderer {
	private FlatColoredSquare flatSquare;
	private SmoothColoredSquare smoothSquare; // NEW LINE ADDED.

	public OpenGLRenderer() {
		// Initialize our squares.
		flatSquare = new FlatColoredSquare();
		smoothSquare = new SmoothColoredSquare(); // NEW LINE ADDED.
	}

We need to move the square down a bit so they don't collide.

public void onDrawFrame(GL10 gl) {
	...
        // Translate to end up under the flat square.
	gl.glTranslatef(0, -3f, 0);
	// Draw our smooth square.
	smoothSquare.draw(gl);
}

Now if you compile and run the application you will see two squares, one solid blue and one smooth with different colors.

References

The info used in this tutorial is collected from:
Android Developers
OpenGL ES 1.1 Reference Pages

You can download the source for this tutorial here: Tutorial_Part_IV
You can also checkout the code from: code.google.com

Previous tutorial: OpenGL ES Tutorial for Android – Part III – Transformations
Next tutorial: OpenGL ES Tutorial for Android – Part V – More on Meshes

I am not going to bore you with a lot of mathematics but I believe it is important to know that when OpenGL render a mesh it multiplies all vertices with a matrix. All the transformations you do are about manipulating the vertices in different ways by modifying this matrix. You can think of the matrix as a paper and that you never move the pen before you start to draw. You always draw in the center. But by doing a translation on the matrix you are moving the paper and also the center. A rotation is like rotating the paper around the center. And a scale is a bit harder to visualize with the paper view but it is like changing the unit size regarding to how you translate your meshes. Usually you talk about transformations according to the mesh not the world, but it is still important to know about.

Coordinate System

OpenGL uses a so called right-handed coordinate system. A system is called right-handed if you look from the positive end towards the origin of the axis the counter-clockwise rotation is considered to be a positive rotation. When you have started up your view and haven't applied any transformations the axis are aligned like this: The x-axis goes from left to right, the y-axis comes from the bottom and goes up and the z-axis is moving from the back of the screen towards the front of the screen.

Translate

public abstract void glTranslatef (float x, float y, float z) //OpenGL docs.

A translations added to the matrix makes the mesh appear as it has been moved. Translations are made along the axis and with no rotation added the axis are in there default state. Translation affects all the vertices in a polygon the same amount over the same axis. Translations are simply additions and subtractions to a current value. The image to the right shows a translation in 2 dimensions.
The start point is {x:-2, y:1} we like to go to {x:1, y:3} so we add {x:3, y:2}.

A simple addition: {x:-2, y:1} + {x:3, y:2} = {x:-2 + 3, y:1 + 2} = {x:1, y:3}.

In 3 dimensions we do the same, if we are located at position: {x:1, y:1, z:0} and we like to move 3 units into the screen we add {x:0, y:0, z:-3} and end up at: {x:1, y:1, z:-3}.

In the last tutorial we moved the square 4 units into the screen just to be able to see the square. What we did was that we added {x:0, y:0, z:-4} to the current position. This is the code we used for the translation:

// Translates 4 units into the screen.
gl.glTranslatef(0, 0, -4); OpenGL docs.

If you do several translations after each other the order of the movement is along the X, Y and Z axis, in that order. On translate the order isn't so important but when we do a rotation it's really important.

It can be quite tricky to remember how the axis are aligned. Fortunate there is a good trick to remember the direction of the axis. Hold your left hand like the photo below. The point on each finger represents the positive direction on one axis. Your thumb is y-axis, index finger is x-axis and your middle finger would represent the z-axis. When I first started with 3D programming I actually wrote the letters, x, y and z on my fingers

Rotate

public abstract void glRotatef(float angle, float x, float y, float z)//OpenGL docs.

Rotating is what it sounds like. You add a rotation to the matrix making it appears like the mesh are rotated. With no translation before the rotation is around the origo. The x, y and z values defines the vector to rotate around. The angle value is the number of degrees to rotate.

If you remember these three things you will manage rotation quite easy.

1. The rotation value are in degrees.
Most frameworks and math functions on computers use radians but OpenGL use degrees.

2. When doing several rotations the order are important.
If you like to restore a rotation you negate the angle or all the axis like this: glRotatef(angle, x, y, z) is restored with glRotatef(angle, -x, -y, -z) or glRotatef(-angle, x, y, z).

But if you do several rotations after each other like this:

gl.glRotatef(90f, 1.0f, 0.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, 1.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, 0.0f, 1.0f); // OpenGL docs.

And want to restore the mesh to it's original position you can't just negate the angle like this:

gl.glRotatef(90f, -1.0f, 0.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, -1.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, 0.0f, -1.0f); // OpenGL docs.

You have to revert the order of the rotations as well like this:

gl.glRotatef(90f, 0.0f, 0.0f, -1.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, -1.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, -1.0f, 0.0f, 0.0f); // OpenGL docs.

The order of several rotations is important.

3. If you look from the positive end towards the origin of the axis the positive rotation is counter-clockwise.
If you take a pencil in your hand, let the point be in the same direction as your thumb, as in the picture below, then aligns the pencil with the x-axis. Let the pencil's point be aligned with the positive direction of the axis. Your other fingers will now point in the positive direction of the rotation over that axis.

Translate & Rotate

Since both rotation and translations are made within each mesh own coordinate system it is important to remember that the order you do the translation and rotation are very important.

If you do a translation on the mesh first and then rotate it, the translation is made on the current state of the mesh coordinate system and then rotated at the new location.

Scale

public abstract void glScalef (float x, float y, float z) // OpenGL docs.

Scaling is just as it sounds and it is possible to scale over each axis separately. Scaling is the same as multiplying all vertexes with the same scalar. In the image below we scale with: gl.glScalef(2f, 2f, 2f). That means that we multiply all vertixes with 2.

Translate & Scale

The order of scaling and translating does matter. If you translate before scaling the transformation is intact. Like this example, first a translation of 2 units and then scale it by 0.5.

gl.glTranslatef(2, 0, 0); // OpenGL docs.
gl.glScalef(0.5f, 0.5f, 0.5f); // OpenGL docs.

gl.glScalef(0.5f, 0.5f, 0.5f); // OpenGL docs.
gl.glTranslatef(2, 0, 0); // OpenGL docs.

Load Identity, push and pop matrix

When you translate, rotate or scaling you are not applying the transformation from the same preconditions, you are applying them to the previous transition. You need to be able to reset the position.

glLoadIdentity

public abstract void glLoadIdentity() // OpenGL docs.

glLoadIdentity replaces the current matrix with the identity matrix. It is the same as calling glLoadMatrix with the identity matrix:

1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1

There are situations where you don't want to reset the model matrix, you rather want to go back to how it was just before your latest transformation.

glPushMatrix

public abstract void glPushMatrix() // OpenGL docs.

glPushMatrix makes a copy of the current matrix and put it on the stack. This means that when you do any kind of translations after glPushMatrix you are doing them on a copy.

glPopMatrix

public abstract void glPopMatrix() // OpenGL docs.

To get back to the previous matrix you use the glPushMatrix command.

A good practice can be to have one glLoadIdentity in the begining of each frame and after that use glPushMatrix and glPopMatrix.

Putting it all togetter

So to make something with this new knowlege let us do 3 squares call them A, B and C. Scale them so that B is 50% smaller then A and C is 50% smaller then B. Then let A rotate counter-clockwise in the center of the screen. B should rotate clockwise around A and finaly C rotating clockwise around B and counter-clockwise in a high speed around it's own center.

public void onDrawFrame(GL10 gl) {
	// Clears the screen and depth buffer.
	gl.glClear(GL10.GL_COLOR_BUFFER_BIT | GL10.GL_DEPTH_BUFFER_BIT);
	// Replace the current matrix with the identity matrix
	gl.glLoadIdentity();
	// Translates 10 units into the screen.
	gl.glTranslatef(0, 0, -10); 

	// SQUARE A
	// Save the current matrix.
	gl.glPushMatrix();
	// Rotate square A counter-clockwise.
	gl.glRotatef(angle, 0, 0, 1);
	// Draw square A.
	square.draw(gl);
	// Restore the last matrix.
	gl.glPopMatrix();

	// SQUARE B
	// Save the current matrix
	gl.glPushMatrix();
	// Rotate square B before moving it, making it rotate around A.
	gl.glRotatef(-angle, 0, 0, 1);
	// Move square B.
	gl.glTranslatef(2, 0, 0);
	// Scale it to 50% of square A
	gl.glScalef(.5f, .5f, .5f);
	// Draw square B.
	square.draw(gl);			

	// SQUARE C
	// Save the current matrix
	gl.glPushMatrix();
	// Make the rotation around B
	gl.glRotatef(-angle, 0, 0, 1);
	gl.glTranslatef(2, 0, 0);
	// Scale it to 50% of square B
	gl.glScalef(.5f, .5f, .5f);
	// Rotate around it's own center.
	gl.glRotatef(angle*10, 0, 0, 1);
	// Draw square C.
	square.draw(gl);

	// Restore to the matrix as it was before C.
	gl.glPopMatrix();
	// Restore to the matrix as it was before B.
	gl.glPopMatrix();

	// Increse the angle.
	angle++;
}

And don't forget to add angel as a variable as well. Thanks Tim!

public class OpenGLRenderer implements Renderer {
	private Square square;
	private float angle; // Don't forget to add this.
        ...

References

The info used in this tutorial is collected from:
Android Developers
OpenGL ES 1.1 Reference Pages

You can download the source for this tutorial here: Tutorial_Part_III
You can also checkout the code from: code.google.com

Previous tutorial: OpenGL ES Tutorial for Android – Part II – Building a polygon
Next tutorial: OpenGL ES Tutorial for Android – Part IV – Adding colors

Building a polygon

In this tutorial we will render our first polygon.

3D models are built up with smaller elements (vertices, edges, faces, and polygons) which can be manipulated individually.

Vertex

A vertex (vertices in plural) is the smallest building block of 3D model. A vertex is a point where two or more edges meet. In a 3D model a vertex can be shared between all connected edges, paces and polygons. A vertex can also be a represent for the position of a camera or a light source. You can see a vertex in the image below marked in yellow.

To define the vertices on android we define them as a float array that we put into a byte buffer to gain better performance. Look at the image to the right and the code below to match the vertices marked on the image to the code.

private float vertices[] = {
      -1.0f,  1.0f, 0.0f,  // 0, Top Left
      -1.0f, -1.0f, 0.0f,  // 1, Bottom Left
       1.0f, -1.0f, 0.0f,  // 2, Bottom Right
       1.0f,  1.0f, 0.0f,  // 3, Top Right
};

// a float is 4 bytes, therefore we multiply the number if vertices with 4.
ByteBuffer vbb = ByteBuffer.allocateDirect(vertices.length * 4);
vbb.order(ByteOrder.nativeOrder());
FloatBuffer vertexBuffer = vbb.asFloatBuffer();
vertexBuffer.put(vertices);
vertexBuffer.position(0);

Don't forget that a float is 4 bytes and to multiply it with the number of vertices to get the right size on the allocated buffer.

OpenGL ES have a pipeline with functions to apply when you tell it to render. Most of these functions are not enabled by default so you have to remember to turn the ones you like to use on. You might also need to tell these functions what to work with. So in the case of our vertices we need to tell OpenGL ES that it’s okay to work with the vertex buffer we created we also need to tell where it is.

// Enabled the vertex buffer for writing and to be used during rendering.
gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);// OpenGL docs.
// Specifies the location and data format of an array of vertex
// coordinates to use when rendering.
gl.glVertexPointer(3, GL10.GL_FLOAT, 0, vertexBuffer); // OpenGL docs.

When you are done with the buffer don't forget to disable it.

// Disable the vertices buffer.
gl.glDisableClientState(GL10.GL_VERTEX_ARRAY);// OpenGL docs.

Edge

Edge is a line between two vertices. They are border lines of faces and polygons. In a 3D model an edge can be shared between two adjacent faces or polygons. Transforming an edge affects all connected vertices, faces and polygons. In OpenGL ES you don't define the edges, you rather define the face by giving them the vertices that would build up the three edges. If you would like modify an edge you change the two vertices that makes the edge. You can see an edge in the image below marked in yellow.

Face

Face is a triangle. Face is a surface between three corner vertices and three surrounding edges. Transforming a face affects all connected vertices, edges and polygons.

The order does matter.

When winding up the faces it's important to do it in the right direction because the direction defines what side will be the front face and what side will be the back face. Why this is important is because to gain performance we don't want to draw both sides so we turn off the back face. So it's a good idea to use the same winding all over your project. It is possible to change what direction that defines the front face with glFrontFace.

 gl.glFrontFace(GL10.GL_CCW); // OpenGL docs

To make OpenGL skip the faces that are turned into the screen you can use something called back-face culling. What is does is determines whether a polygon of a graphical object is visible by checking if the face is wind up in the right order.

 gl.glEnable(GL10.GL_CULL_FACE); // OpenGL docs

It's ofcource possible to change what face side should be drawn or not.

 gl.glCullFace(GL10.GL_BACK); // OpenGL docs

Polygon

Time to wind the faces, remember we have decided to go with the default winding meaning counter-clockwise. Look at the image to the right and the code below to see how to wind up this square.

private short[] indices = { 0, 1, 2, 0, 2, 3 };

To gain some performance we also put this ones in a byte buffer.

// short is 2 bytes, therefore we multiply the number if vertices with 2.
ByteBuffer ibb = ByteBuffer.allocateDirect(indices.length * 2);
ibb.order(ByteOrder.nativeOrder());
ShortBuffer indexBuffer = ibb.asShortBuffer();
indexBuffer.put(indices);
indexBuffer.position(0);

Don't forget that a short is 2 bytes and to multiply it with the number of indices to get the right size on the allocated buffer.

Render

Time to get something on the screen, there is two functions used to draw and we have to decide which one to use.

The two functions are:

public abstract void glDrawArrays(int mode, int first, int count) // OpenGL docs

glDrawArrays draws the vertices in that order they are specified in the construction of our verticesBuffer.

public abstract void glDrawElements(int mode, int count, int type, // OpenGL docs
                                    Buffer indices) 

glDrawElements need a little bit more to be able to draw. It needs to know the order which to draw the vertices, it needs the indicesBuffer.

Since we already created the indicesBuffer I'm guessing that you figured out that's the way we are going.

What is common for this functions is that they both need to know what it is they should draw, what primitives to render. Since there is some various ways to render this indices and some of them are good to know about for debugging reasons. I'll go through them all.

What primitives to render

GL_POINTS

Draws individual points on the screen.

GL_LINE_STRIP

Series of connected line segments.

GL_LINE_LOOP

Same as above, with a segment added between last and first vertices.

GL_LINES

Pairs of vertices interpreted as individual line segments.

GL_TRIANGLES

Triples of vertices interpreted as triangles.

GL_TRIANGLE_STRIP

Draws a series of triangles (three-sided polygons) using vertices v0, v1, v2, then v2, v1, v3 (note the order), then v2, v3, v4, and so on. The ordering is to ensure that the triangles are all drawn with the same orientation so that the strip can correctly form part of a surface.

GL_TRIANGLE_FAN

Same as GL_TRIANGLE_STRIP, except that the vertices are drawn v0, v1, v2, then v0, v2, v3, then v0, v3, v4, and so on.

I think the GL_TRIANGLES is the easiest to use so we go with that one for now.

Putting it all togetter

So let's putting our square together in a class.

package se.jayway.opengl.tutorial;

import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.FloatBuffer;
import java.nio.ShortBuffer;

import javax.microedition.khronos.opengles.GL10;

public class Square {
	// Our vertices.
	private float vertices[] = {
		      -1.0f,  1.0f, 0.0f,  // 0, Top Left
		      -1.0f, -1.0f, 0.0f,  // 1, Bottom Left
		       1.0f, -1.0f, 0.0f,  // 2, Bottom Right
		       1.0f,  1.0f, 0.0f,  // 3, Top Right
		};

	// The order we like to connect them.
	private short[] indices = { 0, 1, 2, 0, 2, 3 };

	// Our vertex buffer.
	private FloatBuffer vertexBuffer;

	// Our index buffer.
	private ShortBuffer indexBuffer;

	public Square() {
		// a float is 4 bytes, therefore we multiply the number if
		// vertices with 4.
		ByteBuffer vbb = ByteBuffer.allocateDirect(vertices.length * 4);
		vbb.order(ByteOrder.nativeOrder());
		vertexBuffer = vbb.asFloatBuffer();
		vertexBuffer.put(vertices);
		vertexBuffer.position(0);

		// short is 2 bytes, therefore we multiply the number if
		// vertices with 2.
		ByteBuffer ibb = ByteBuffer.allocateDirect(indices.length * 2);
		ibb.order(ByteOrder.nativeOrder());
		indexBuffer = ibb.asShortBuffer();
		indexBuffer.put(indices);
		indexBuffer.position(0);
	}

	/**
	 * This function draws our square on screen.
	 * @param gl
	 */
	public void draw(GL10 gl) {
		// Counter-clockwise winding.
		gl.glFrontFace(GL10.GL_CCW); // OpenGL docs
		// Enable face culling.
		gl.glEnable(GL10.GL_CULL_FACE); // OpenGL docs
		// What faces to remove with the face culling.
		gl.glCullFace(GL10.GL_BACK); // OpenGL docs

		// Enabled the vertices buffer for writing and to be used during
		// rendering.
		gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);// OpenGL docs.
		// Specifies the location and data format of an array of vertex
		// coordinates to use when rendering.
		gl.glVertexPointer(3, GL10.GL_FLOAT, 0, // OpenGL docs
                                 vertexBuffer);

		gl.glDrawElements(GL10.GL_TRIANGLES, indices.length,// OpenGL docs
				  GL10.GL_UNSIGNED_SHORT, indexBuffer);

		// Disable the vertices buffer.
		gl.glDisableClientState(GL10.GL_VERTEX_ARRAY); // OpenGL docs
		// Disable face culling.
		gl.glDisable(GL10.GL_CULL_FACE); // OpenGL docs
	}

}

We have to initialize our square in the OpenGLRenderer class.

// Initialize our square.
Square square = new Square();

And in the draw function call on the square to draw.

public void onDrawFrame(GL10 gl) {
		// Clears the screen and depth buffer.
		gl.glClear(GL10.GL_COLOR_BUFFER_BIT | // OpenGL docs.
                           GL10.GL_DEPTH_BUFFER_BIT);

		// Draw our square.
		square.draw(gl); // ( NEW )
}

If you run the application now the screen is still black. Why? Because OpenGL ES render from where the current position is, that by default is at point: 0, 0, 0 the same position that the view port is located. And OpenGL ES don’t render the things that are too close to the view port. The solution to this is to move the draw position a few steps into the screen before rendering the square:

// Translates 4 units into the screen.
gl.glTranslatef(0, 0, -4); // OpenGL docs

I will talk about the different transformations in the next tutorial.

Run the application again and you will see that the square is drawn but quickly moves further and further into the screen. OpenGL ES doesn’t reset the drawing point between the frames that you will have to do yourself:

// Replace the current matrix with the identity matrix
gl.glLoadIdentity(); // OpenGL docs

Now if you run the application you will see the square on a fixed position.

References

The info used in this tutorial is collected from:
Android Developers
OpenGL ES 1.1 Reference Pages

You can download the source for this tutorial here: Tutorial_Part_II
You can also checkout the code from: code.google.com

Previous tutorial: OpenGL ES Tutorial for Android – Part I – Setting up the view
Next tutorial: OpenGL ES Tutorial for Android – Part III – Transformations

I can't always remember where I found particular info so I might not always be able to give you the right reference. If you feel that I have borrowed stuff from you but have forgotten to add you as a reference, please e-mail me.

In the code examples I will have two different links for each function. The actual function will be linked to the android documentation and after that I will also link the OpenGL documentations. Like this:

gl.glClearColor(0.0f, 0.0f, 0.0f, 0.5f);  // OpenGL docs.

So, let's start.

In this tutorial I will show you how to set up your OpenGL ES view that’s always a good place to start.

Setting up an OpenGL ES View

Setting up a OpenGL view has never been hard and on Android it is still easy. There really are only two things you need to get started.

GLSurfaceView

GLSurfaceView is a API class in Android 1.5 that helps you write OpenGL ES applications.

• Providing the glue code to connect OpenGL ES to the View system.
• Providing the glue code to make OpenGL ES work with the Activity life-cycle.
• Making it easy to choose an appropriate frame buffer pixel format.
• Creating and managing a separate rendering thread to enable smooth animation.
• Providing easy-to-use debugging tools for tracing OpenGL ES API calls and checking for errors.

If you want to get going fast with your OpenGL ES application this is where you should start.

The only function you need to call on is:

public void  setRenderer(GLSurfaceView.Renderer renderer)

Read more at: GLSurfaceView

GLSurfaceView.Renderer

GLSurfaceView.Renderer is a generic render interface. In your implementation of this renderer you should put all your calls to render a frame.
There are three functions to implement:

// Called when the surface is created or recreated.
public void onSurfaceCreated(GL10 gl, EGLConfig config) 

// Called to draw the current frame.
public void onDrawFrame(GL10 gl)

// Called when the surface changed size.
public void onSurfaceChanged(GL10 gl, int width, int height)

onSurfaceCreated

Here it's a good thing to setup things that you don't change so often in the rendering cycle. Stuff like what color to clear the screen with, enabling z-buffer and so on.

onDrawFrame

Here is where the actual drawing take place.

onSurfaceChanged

If your device supports flipping between landscape and portrait you will get a call to this function when it happens. What you do here is setting upp the new ratio.
Read more at: GLSurfaceView.Renderer

Putting it together

First we create our activity, we keep it clean and simple.

package se.jayway.opengl.tutorial;

import android.app.Activity;
import android.opengl.GLSurfaceView;
import android.os.Bundle;

public class TutorialPartI extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
    	super.onCreate(savedInstanceState);
 		GLSurfaceView view = new GLSurfaceView(this);
   		view.setRenderer(new OpenGLRenderer());
   		setContentView(view);
    }
}

Our renderer takes little bit more work to setup, look at it and I will explain the code a bit more.

package se.jayway.opengl.tutorial;

import javax.microedition.khronos.egl.EGLConfig;
import javax.microedition.khronos.opengles.GL10;

import android.opengl.GLU;
import android.opengl.GLSurfaceView.Renderer;

public class OpenGLRenderer implements Renderer {
	/*
	 * (non-Javadoc)
	 *
	 * @see
	 * android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.
         * microedition.khronos.opengles.GL10, javax.microedition.khronos.
         * egl.EGLConfig)
	 */
	public void onSurfaceCreated(GL10 gl, EGLConfig config) {
		// Set the background color to black ( rgba ).
		gl.glClearColor(0.0f, 0.0f, 0.0f, 0.5f);  // OpenGL docs.
		// Enable Smooth Shading, default not really needed.
		gl.glShadeModel(GL10.GL_SMOOTH);// OpenGL docs.
		// Depth buffer setup.
		gl.glClearDepthf(1.0f);// OpenGL docs.
		// Enables depth testing.
		gl.glEnable(GL10.GL_DEPTH_TEST);// OpenGL docs.
		// The type of depth testing to do.
		gl.glDepthFunc(GL10.GL_LEQUAL);// OpenGL docs.
		// Really nice perspective calculations.
		gl.glHint(GL10.GL_PERSPECTIVE_CORRECTION_HINT, // OpenGL docs.
                          GL10.GL_NICEST);
	}

	/*
	 * (non-Javadoc)
	 *
	 * @see
	 * android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.
         * microedition.khronos.opengles.GL10)
	 */
	public void onDrawFrame(GL10 gl) {
		// Clears the screen and depth buffer.
		gl.glClear(GL10.GL_COLOR_BUFFER_BIT | // OpenGL docs.
                           GL10.GL_DEPTH_BUFFER_BIT);
	}

	/*
	 * (non-Javadoc)
	 *
	 * @see
	 * android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.
         * microedition.khronos.opengles.GL10, int, int)
	 */
	public void onSurfaceChanged(GL10 gl, int width, int height) {
		// Sets the current view port to the new size.
		gl.glViewport(0, 0, width, height);// OpenGL docs.
		// Select the projection matrix
		gl.glMatrixMode(GL10.GL_PROJECTION);// OpenGL docs.
		// Reset the projection matrix
		gl.glLoadIdentity();// OpenGL docs.
		// Calculate the aspect ratio of the window
		GLU.gluPerspective(gl, 45.0f,
                                   (float) width / (float) height,
                                   0.1f, 100.0f);
		// Select the modelview matrix
		gl.glMatrixMode(GL10.GL_MODELVIEW);// OpenGL docs.
		// Reset the modelview matrix
		gl.glLoadIdentity();// OpenGL docs.
	}
}

Fullscreen

Just add this lines in the OpenGLDemo class and you will get fullscreen.

    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        this.requestWindowFeature(Window.FEATURE_NO_TITLE); // (NEW)
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
            WindowManager.LayoutParams.FLAG_FULLSCREEN); // (NEW)
        ... // Previous code.
    }

This is pretty much all you need to get your view up and running. If you compile and run it you will see a nice black screen.

References

The info used in this tutorial is collected from:
Android Developers
OpenGL ES 1.1 Reference Pages

You can download the source for this tutorial here: Tutorial_Part_I.zip
You can also checkout the code from: code.google.com

Next tutorial: OpenGL ES Tutorial for Android – Part II – Building a polygon

The Problem

The most intuitive way to create and use a UIToolbar is to add it manually for each of your view controllers. If your application is very simple this could be the right thing to do, but if our application uses a UINavigationController then it is the wrong way to do it.

If you look at the Mail application you will notice how the toolbar stays in place, and the items on the toolbar cross fades when you navigate the application hierarchy. You might also have noticed that the toolbar do not cross fade, but rather is pushed, if you add a toolbar to each of the view trees of your own view controllers. This is because your toolbar is then part of the wrong three hierarchy, as shown in this image.

Screen estate as owned by different view controllers.

You will find a few solutions if you Goole on the topic, all of them that I have found are dead wrong. They tend to use self.view.superview on the view controller instance to slide the toolbar up one level in the hierarchy. It works, most of the time, but is an ugly hack that is not future proof.

A Better Solution

The reason the toolbar is pushed off screen is that the toolbar is owned by the navigation controller,as we saw in the image above, and a navigation controller pushes it's content. The view hierarchy we would like to have is instead something like this.

Screen estate as owned by different view controllers.

In this setup the navigation controller can push the content, as it is intended to do, and the custom toolbar controller can manage a static UIToolbar with cross fades. Only problem is; this custom toolbar controller do not exist, and we must implement it on our own. Luckily not many lines of code is needed.

Custom Toolbar Conroller Requirement

The custom toolbar controller should be a subclass of UIViewController, that way it's fits nicely into the Cocoa Touch framework, and can nicely be fitted into any well written application.

The custom toolbar controller should manage a view consisting of a UIToolbar instance, and a view that is fetched from another view controller. This is modelled after how a UINavigationController manages a view that consists of a UINavigationBar and the view fetched from other view controllers. This way any well written view controller can be used with our custom toolbar controller.

Lastly our custom toolbar controller should implement the UINavigationControllerDelegate protocol, so that we can listen to events as view controllers are pushed and poped from the navigation stack, and update the toolbar with contextual toolbar items. Just as the navigation controller updates it's title by fetching the title property of the managed view controllers, so will our custom toolbar controller update the toolbar items by fetching the toolbarItems property if available.

Toolbar Controller Interface

The interface will be sparse, all we need is an initializer for creating a toolbar controller with another view controller providing the main content, and for sports two properties to access the content view controller, and the toolbar itself.

#import <UIKit/UIKit.h>
 
@interface CWToolbarController : UIViewController <UINavigationControllerDelegate> {
@private
    UIViewController* _contentViewController;
    UIToolbar* _toolbar;
}
 
@property(nonatomic, retain, readonly) UIViewController* contentViewController;
@property(nonatomic, retain, readonly) UIToolbar* toolbar;
 
-(id)initWithContentViewController:(UIViewController*)contentViewController;
 
@end

Toolbar Controller Implementation

The grunt work for implementing the toolbar controller do not need any further explanation.

#import "CWToolbarController.h"
 
@implementation CWToolbarController
 
@synthesize contentViewController = _contentViewController;
@synthesize toolbar = _toolbar;
 
- (id)initWithContentViewController:(UIViewController*)contentViewController;
{
    self = [super init];
    if (self) {
        _contentViewController = [contentViewController retain];
        if ([_contentViewController isKindOfClass:[UINavigationController class]]) {
            ((UINavigationController*)_contentViewController).delegate = self;
        }
    }
	return self;
}
 
// More code here...
 
- (void)dealloc;
{
    [_contentViewController release];
    [super dealloc];
}
 
@end

The first interesting code is to setup the view that is managed by our toolbar controller. This view have two subviews, a UIToolbar, and a view that we fetch from the content view controller we where given. We do this setup in the loadView method.

- (void)loadView;
{
    UIView* contentView = _contentViewController.view;
    CGRect frame = contentView.frame;
    UIView* view = [[UIView alloc] initWithFrame:frame];
 
    frame = CGRectMake(0, 0, frame.size.width, frame.size.height - 44.0f);
    contentView.frame = frame;
    [view addSubview:contentView];
 
    frame = CGRectMake(0.0f, frame.size.height, frame.size.width, 44.0f);
    _toolbar = [[UIToolbar alloc] initWithFrame:frame];
    [view addSubview:_toolbar];
 
    self.view = view;
    [view release];
    [_toolbar release];
}

This code reuses the screen setup already done by the content view controller, and re-layouts our subviews. It is a simple solution, and you will need a custom class for the root view with an overloaded layoutSubviews if you want to properly handle orientation changes. But I have left this out, as it is not within the scope of this post.

Next up we need to update the toolbar with contextual toolbar items, when our content changes. This is only supported if the content view controller is a UINavigationController, as can be seen in the initializer above. This could be made more flexible, but is also outside the scope of this post. We have set our toolbar controller to be the delegate for the content navigation view controller, so all we need to do is to respond to navigation events as they occur.

- (void)navigationController:(UINavigationController *)navigationController
        willShowViewController:(UIViewController *)viewController
        animated:(BOOL)animated;
{
    NSArray* items = nil;
    if ([viewController respondsToSelector:@selector(toolbarItems)]) {
        items = [viewController performSelector:@selector(toolbarItems)];
    }
    [_toolbar setItems:items animated:animated];
}

Conclusion

As shown with this code, doing the correct way with Cocoa Touch almost always means doing it in the easiest way as well. The hard part is knowing what the correct way is. My hope is that this post can guide you in the right direction. Rule of thumb is to always try to follow the same pattern as similiar things in Cocoa, it might feel like it is harder to do, but at the end of the day you will end up with less code, with more features.

The code above for implementing the custom toolbar controller, is much less code than what is needed to write a small application to demonstrate it being used. I have therefor made a small demonstration application with this complete code. It is a tree of table views, where each item opens up a new table view tree with one less toolbar item.

The source code is released under BSD license, and you can download it here.

Simple LDAP Authentication

One of the most requested pieces of functionality in Spring LDAP has been a means to perform simple authentication. We have previously hesitated to include this, not finding any logical place to put it. In this release however we got a couple of suggestions on suitable API additions that enabled us to attack this from a different angle, in the end resulting in explicit methods in LdapTemplate for this purpose.

Background

The problem with authentication in LDAP is that it normally requires two separate steps: First you need to find the principal to authenticate in the LDAP tree, typically performing an LDAP search based on e.g. a user name. A new LDAP connection will then be acquired, authenticating it using the Distinguished Name of the found entry (normally referred to as an 'LDAP Bind').

Example

Consider the LDAP tree below:

Let us say a user identifying himself as 'John Doe' is trying to log into our system. We would execute a search from the top of the LDAP tree using a search filter like (&(objectclass=person)(cn=John Doe)). The search would return one single entry, from which we would extract the absolute DN; cn=John Doe, ou=company1, c=Sweden, dc=jayway, dc=se. This DN would then be used for authenticating a new LDAP connection to the server, thus validating the password supplied by the user.

New Spring LDAP Authentication API

While the above has indeed been possible to do using previous versions of Spring LDAP, it has required quite a lot of work and resulted in rather messy code. Spring LDAP 1.3.0 adds a couple of methods to LdapTemplate, making the authentication procedure very straightforward:

public boolean authenticate(Name base, String filter, String password)
public boolean authenticate(Name base, String filter, String password, AuthenticatedLdapEntryContextCallback callback)

The first method performs exactly the procedure described above, returning true or false depending on the outcome. The second method goes one step further, allowing us to perform any operation on the authenticated LDAP connection. Focusing on the simplest case, a standard authentication method using Spring LDAP would look something like the following:

public boolean login(String username, String password){
  AndFilter filter = new AndFilter();
  filter.and(new EqualsFilter("objectclass", "person")).and(new EqualsFilter("cn", username));
  return ldapTemplate.authenticate(DistinguishedName.EMPTY_PATH, filter.toString(), password);
}

Simple, clean and to the point, especially compared to the mess that used to be required (won't linger on those nasty details here). Obviously however, using a Spring library we will be required to write a few lines of XML as well:

<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://url.to.ldap.server:389" />
<property name="userDn" value="uid=admin,ou=system" />
<property name="password" value="adminpassword" />
</bean>
<bean id="ldapTemplate" class="org.springframework.ldap.core.LdapTemplate">
  <constructor-arg ref="contextSource" />
</bean>
<bean id="myAuthenticator" class="com.example.MyAuthenticatingClass">
  <!-- Assuming constructor injection of LdapTemplate instance in your authentication class -->
  <constructor-arg ref="ldapTemplate" />
</bean>
 

A couple of comments on the suggested solution:

• The search needs to return exactly one result entry. In the example above, if there would be more than one person entry in the tree with cn 'John Doe' (which would be perfectly legal according to schema regulations), the call to authenticate would fail.
• In actual implementations the attribute to use for identification will likely be e.g. uid or sAMAccountname (in Active Directory). Both of these attributes have uniqueness enforced throughout the entire tree by the LDAP server.
• The method only returns true or false; thus the actual reason for failing will not be visible to the caller. The reason will however be logged, which might be useful useful when tracking down problems with search filters and such.
• A common reason for confusion in LDAP searches is the base parameter, which is used for pointing out where in the LDAP tree to start searching. Referring again to the potential problem where several users might have the same cn; in that case these entries would have to be located in different subtrees. The search could then be narrowed by specifying a different base DN to the authenticate method, e.g. c=Sweden, dc=jayway, dc=com

Note: While the provided methods will handle the simple task of authentication for you it is likely that your actual security requirements go way past plain authentication (e.g. authorization, web integration, etc.). The realm of security is a very complex one, which is the reason you should carefully consider your actual requirements - if they appear to go beyond simple authentication you should definitely consider using Spring Security instead. (Obviously, under the covers Spring LDAP would be used for the actual authentication anyway).

That said, for many systems the API provided with Spring LDAP will be quite sufficient.

Other improvements in Spring LDAP 1.3.0

As compared to the 1.2.1 version of Spring LDAP, 1.3.0 includes more than 50 fixes, varying from internal modifications and minor improvements to important bug fixes and significant functionality additions. The full list of modifications can be viewed in the the changelog.

About Spring LDAP

Spring LDAP is a Java library for simplifying LDAP operations, based on the pattern of Spring's JdbcTemplate. The framework relieves the user of common chores, such as looking up and closing contexts, looping through results, encoding/decoding values and filters, and more. The library is free, open source, and distributed under the Apache Licence version 2.

For more information on the Spring LDAP project, including downloads, maven usage, as well as project reference and API documentation, refer to its project home page on springsource.org. Support and enhancement requests will be answered in the Spring LDAP Forum at Spring Community Forums.

So I took out my laptop during the next 60 minutes of Panel Debate, and wrote an iPhone app, and as I expected the code landed on 46 lines of code for the actual application logic, physics, grits and all. Or 112 lines of code if headers and boiler-plate should be counted as well.

This blog post will describe what I did, in a quite nice model-view-controller fashion (Model and Controller is implemented in the same class).

• First of all I needed a view to display my bouncing ball on, I choose to subclass UIViewController to handle this view.
• A standard UIView instance with a UIImageView sub-view for the ball is all I need for my view, this I setup using Interface Builder.
• And the model/logic is handled by one CGPoint for the current location, and one CGPoint with the current delta movement of the ball.

First the custom view controller sets up itself as the accelerometer delegate when awakening from it's nib-file.

-(void)awakeFromNib;
{
  self.location = CGPointMake(160, 230);
  UIAccelerometer* accelerometer = [UIAccelerometer sharedAccelerometer];
  accelerometer.updateInterval = 0.02;
  accelerometer.delegate = self;
}

Then comes a private function for the quite faked physics, it is responsible for detecting if a value with a given delta movement has hit a min or max edge. If it do hits an edge, it flips it's delta movement with some deceleration, and corrects it's value.

static inline BOOL bounce(float* val, float* delta, float min, float max) {
#define FLIP(val, c) (c - (val - c))
  if (*val < min || *val > max) {
    *delta = -(*delta * 0.75);
    float loc = *val < min ? min : max;
    *val = FLIP(*val, loc);
    return YES;
  }
  return NO;
}

And lastly the delegate method that is called by the accelerometer. Here we update the delta movement, and use the bounce-function to detect and compensate location+delta when the ball hits any edges. If an edge it hit, a vibration is also triggered.

-(void)accelerometer:(UIAccelerometer*)accelerometer
       didAccelerate:(UIAcceleration*)acceleration;
{
#define CAP(val, max) (val < -max ? -max : (val > max ? max : val))
  CGPoint delta = CGPointMake(CAP(self.delta.x + acceleration.x, 32),
                              CAP(self.delta.y - acceleration.y, 32));
  CGPoint location = CGPointMake(self.location.x + delta.x,
                                 self.location.y + delta.y);
  if (bounce(&location.x, &delta.x, 8, self.view.bounds.size.width - 8 ) ||
      bounce(&location.y, &delta.y, 8, self.view.bounds.size.height - 8))
  {
      AudioServicesPlayAlertSound(kSystemSoundID_Vibrate);
  }
  self.delta = delta;
  self.location = location;
  self.ballView.center = self.location;
}

In conclusion Cocoa Touch requires surprisingly little code for accessing and using the accelerometer and trigger a vibration. Triggering a vibration is literary done with a single line of code. The lines of code needed to setup and listen to the accelerometer can literary be counted on the fingers of one hand.

On the downside there is no finer control of the vibration, and if you like to have the rotation angles of the device instead of simple gravity forces of the x, y and z axis, then you must do the math for yourself. Simple enough, but it would had been nice to have to current rotations around each axis as well.

The full source code can be downloaded here.

ps. I dare Mike Jennings to best this . ds.