UI for Allegro 5

I found a nice UI system called GWEN. It has lots of advanced features and is very easy to embed. It sits nicely on top of your application and can just be wired into its resources, to save competing systems, e.g. input or texture management.

Example of Gwen UI from the Gwen site.

I ported it to Allegro 5, which was quite easy as the renderer and input abstractions are well designed. I did it on the Mac, but it also works just fine on my old Windows XP laptop. Gwen also provides rendering backends for OpenGL, DirectX, SFML, and Windows GDI.

[Note] I have forked GWEN in order to fix various issues with Allegro 5, etc. There are notes in the readme and on the wiki. You may want to prefer this version if you are using Allegro 5. Please report any issues in the Github issue tracker for Gwork.

If you have used Delphi, or Windows Forms you'll probably find it quite easy to pick up. There are unit test examples from which to learn, but other than that you have to plough through the code at the moment. Hopefully more docs and comments will appear soon to ease the learning curve. There is a small tutorial on doing layout with docking.

One of the things that is really nice about Gwen is the skinning system. It is all laid out in one bitmap, along with the colour scheme at the bottom.

The default skin for Gwen.

Notes on using Allegro 5.1 on Mac

This is some notes I made whilst setting up Allegro for use on my Mac. I'm fairly new to Mac, having been a Windows programmer for a long time, so these notes may change as I learn more about the correct way to do things on the Mac.

Dependencies

Get all the libraries and tools that Allegro5 needs from Macport. This saves a lot of time. Very nice system. You can check what you have installed using:

port installed

You will need the following:

sudo port install zlib freetype jpeg libogg libvorbis libpng physfs +universal

If you have libraries installed that aren't 32 bit, and you get the "different system not i386" link error, they need to be recompiled with "+universal" (i.e. i386 and x86_64) . i386 is needed by the iPhone simulator. OSX desktop apps will use x86_64. You can force MacPorts to recompile any libraries using the following (and replace LIBNAME!):

sudo port upgrade --enforce-variants LIBNAME +universal

cmake should have been installed by MacPorts, but if not:

sudo port install cmake

Note: you will need at least version 2.8.8 of cmake if you are using Xcode 4.3 or newer.

Build 

make

Easiest way to build and install Allegro for OSX is use make. Get the Allegro source and in that directory:

• mkdir build
• cd build
• cmake ..
• make
• sudo make install

Add "-D WANT_FRAMEWORKS=1" to cmake if you want frameworks.

Add "-D CMAKE_OSX_ARCHITECTURES=i386" if you want 32 bit libs. - I had to do this initially, I think because some of the ports wouldn't compile 64 bit. No longer necessary.

I don't use frameworks. Default install directory is "/usr/local".

Xcode

You can generate Xcode project files for Allegro and build using Xcode. I do two builds of Allegro. One for OSX and for iOS.

• mkdir build_osx
• cd build_osx
• cmake -D SHARED=0 -G Xcode ..
• xcodebuild -project ALLEGRO.xcodeproj -target ALL_BUILD -arch x86_64 -sdk macosx10.7 -configuration Release
• cmake -D CMAKE_INSTALL_PREFIX=/my/install/path -P cmake_install.cmake 

I turn sharing off so I get static libs. You'll need to do this for iOS as dynamic libs aren't allowed.

Using

Don't use Xcode 4.0, it isn't ready. Use Xcode 4.1 or Xcode 3.2. Xcode 4.3 seems okay, still needs work. Stick with Xcode 3.2 if you like, I do on my laptop.

I create a Cocoa application and removed what I didn't want. If you followed make build instructions:

• Add "/usr/local/include" to header search paths.
• Drag in the Allegro libraries that you want to link to in "/usr/local/lib".
• Go into Interface Builder and delete the default Application and Window. Allegro supplies these.

Linking

The frameworks you need to for OSX are:

• AudioToolbox
• IOKit
• OpenAL
• OpenGL
• Cocoa

The frameworks you need to for iOS are:

• CoreGraphics
• Foundation
• OpenAL
• OpenGLES
• QuartzCore
• UIKit

The following error means you have the wrong "main" declaration:

dyld: Symbol not found: __al_mangled_main
Referenced from: /usr/local/lib/liballegro_main.5.1.dylib
Expected in: flat namespace
in /usr/local/lib/liballegro_main.5.1.dylib

It should be:

int main(int argc, char **argv) 

Other Info

There are other notes on the Allegro wiki on how to build Allegro from Git.


[16-Jul-11] Note about Xcode 4.0.
[27-Oct-11] Xcode 4.1 is fine. It doesn't crash and is faster than Xcode 3.2.
[Mar-12] Xcode 4.3. Compile 64-bit.
[29-Mar-12] Added +universal to "port install" so we get i386 and x86_64 libraries. I also updated the notes on the Allegro wiki.
[8-Jul-12] Added frameworks to link for Allegro 5.1.
[19-Dec-12] Notes on Xcode building.

Allegro 5.0 on Mac Snow Leopard

For more notes on Allegro 5 on Lion and Xcode 4 see this post.

I had been experimenting with Allegro 4.4, but now Allegro 5.0.0 has arrived. Apparently version 5.0 has had its API revamped and more functionality added, so I decided to give it a go. I believe it now expects hardware acceleration and has drivers for OpenGL and DirectX. Its appeal lies in its simplicity, good support, and is very cross platform, supporting Windows, Linux, OSX, iPhone, etc.

Build notes:

Dependencies

Previously I had been building libraries from their source and installing them in /usr/local using the usual UNIX build routine (i.e. download source and make). This is somewhat laborious and can be time consuming if something goes wrong (because not OSX compatible). This time round I decided to use MacPorts to do the lifting for me. This saves a lot of time. Just follow their standard installation instructions.

Then you need to install the libraries that you will need to compile Allegro 5. These are listed on this page, but aren't quite correct. I used:

sudo port install zlib freetype jpeg libogg libvorbis

Some of these need to be compiled in "universal" mode as they are compiled in 64 bit by default (which is the default of the compiler, new on OSX 10.6):

sudo port upgrade --enforce-variants libpng +universal

sudo port upgrade --enforce-variants physfs +universal

This will take a while if you are doing this from scratch (20+ mins). After this you should have a new /opt directory, which contains a load of new libraries. You can type "port installed" to see what you have. Some libraries will have "+universal" next to them.

Now download the Allegro 5 source, or get latest from svn. You can repeat the steps from here onwards when you get new versions of Allegro.

To build Allegro you can either build libraries or a framework, and you can either use makefiles or Xcode project files. I built libraries using Xcode 3, and now frameworks using makefiles. Frameworks are more in fitting with the Mac way of doing things, so probably best to use those.

Xcode 3 - Static library

To build using Xcode: Snow Leopard GCC compiles 64-bit code by default, but Allegro is not a 64-bit library, so we want to compile everything as i386. We first generate the Xcode files and then load them in Xcode 3 and change the settings for 32 bit (i386):

• cd to/allegro
• mkdir build
• cd build
• cmake -G Xcode ..

This will do a load of scanning for the dependencies it needs and then you'll end up with an Xcode project file: ALLEGRO.xcodeproj. This can be opened using Xcode 3 or 4. Although, at the current point (July 2011) I wouldn't recommend Xcode 4, it's just not ready.

For Xcode 3: open the the project file and (in the root project at the top):

• Change the Architectures to 32-bit Universal.
• I chose the RelWithDebInfo configuration. I haven't tried the others.
• Change the active architecture to i386. This is important as Allegro is 32-bit.
• Reading this article is useful if you don't know which SDK to use.

Build the ALL_BUILD target. You can run A5teroids and some of the example to check that it all works.

Sorry, I haven't built this using the project for Xcode 4. Use the frameworks below if you can't manage it. That's what I am using.

The install will fail because the script it is trying to run needs root access. So go back to the terminal and run the install command manually:

sudo cmake -DBUILD_TYPE=RelWithDbgInfo -P cmake_install.cmake

Then the Allegro files will be installed in /usr/local and you can include and link then from the usual places.

Frameworks

OSX 10.6 switched from 32 bit to 64 bit. Allegro needs to be compiled as 32 bit (i386). So we do the following in the unpacked allegro directory:

• mkdir build
• cd build
• cmake -DWANT_FRAMEWORKS=1 -DCMAKE_OSX_ARCHITECTURES=i386 ..
• make
• make install

And Bob is your Auntie.

Hopefully at some point some kind person will add Allegro 5 to MacPorts to save having to do this.

New Project

The easiest way to set a new project up is to create a command-line application in Xcode. However, if we want to package all the assets, like normal Mac applications, you need to create a Cocoa application ("New Project..." > "Cocoa Application").

In the project settings, add "/usr/local/include" as a user header path. This will include the Allegro file that we just installed above. In targets, right click on your application and choose "Add..." and add existing files "/usr/local/lib/liballegro.dylib" and "/usr/local/lib/liballegro_main.dylib". Now, you should be able to build and run your application. However, two windows will appear! This is because the liballegro_main stub will create a window as well as your default application having one (in the .xib).

To remove the default app window (because we want the Allegro one) look in the "resources" folder and open "MainMenu.xib". This brings up the interface designer. In the list of objects, delete the NSWindow object, this will stop two windows being created when the application starts. We also don't need the auto-generated stub code for the application either, so you delete the "main.m" and "app delegate.m" files. You can also delete items from the menu you don't want by dragging them onto the desktop (and they disappear in a puff of smoke). If you build and run you should have one window now.

There is a tutorial on Allegro 5 on the wiki. The API looks a bit more tidy and better namespaced now.


[6-Mar-11] - Updated for Allegro 5.0.0. Notes were previously for the release candidates.
[25-Mar-11] - Added missing libvorbis to port install.
[26-Apr-11] - Using Xcode 3 for building. Xcode 4 wasn't available when this was written.
[7-Jul-11] - Notes for building with frameworks and Macports 32-bit builds.

Using Allegro 4.4 on Mac

Building

I have Macbook with Snow Leopard 10.6.2 installed and Allegro 4.4.1.1. I did have some hiccups with Allegro 4.4.0.1. Not sure if this was my fault or the distro as I'm still newish to the Mac and the Allegro Mac instructions are a bit dated.

I first tried building Allegro as a framework, but this doesn't work as I think it should. If you include a framework using: #include "Allegro/allegro.h", the internal Allegro files don't prefix with the framework name "Allegro". So, you end up adding the framework path, which is pointless, so you may as well just compile Allegro in /usr/local and link it from there.

Get Allegro (I used 4.4.1.1). Unzip. I have cmake 2.8. In the Allegro directory :-

• mkdir build
• cd build
• cmake ..
• sudo make install
• make clean

Dependencies:

• OpenGL - included in OS.
• libpng, zlib and vorbis - These can be downloaded and installed as standard libs in /usr/local. I don't bother with fink or Macports as I don't want the clutter. I want everything to work "natively". There are some details under the pygame build instructions.

So you should now have a working copy of Allego in /usr/local/include and /usr/local/lib, with some executable utilities in /usr/local/bin.

From the mailing list it appears that you can only compile Allegro as a 32 bit library, there is no 64 bit support so any libraries or frameworks and the dependent libraries will have to be 32 bit. Leopard default is 32 bit. Snow Leopard default is 64 bit.

Creating project in Xcode

• Create a new command-line C++ tool project.
• Paste in the GL example.
• Add /usr/local/include to the header search paths in project settings.
• Add the following frameworks to "Link with Binary Libraries" :
• Cocoa.
• OpenGL.
• Carbon. (Ideally you shouldn't need this, but there is some reference to ShowMenuBar and HideMenuBar, which doesn't appear when you build Allegro as a framework.)
• Add the following libraries from /usr/local/lib :
• liballeg.4.4.dylib
• liballeggl.a
• liballeg-main.a  (This is a stub for "main" that glues Cocoa to Allegro.)
• Build the target and it should compile and link.
• You are now good to go at writing OpenGL games using Allegro.

[8-Apr-10] Changed because building as framework just doesn't work properly.

Clanlib vs Allegro vs SDL on Mac OSX

I want to write a little game in C++. Previously, on Windows, I've used Clanlib. This is nicely designed and has pretty much all you need for a game. However, I now have a Macbook (OSX 10.6.2) and Clanlib has fallen behind the times Mac-wise as it still uses Carbon. There don't seem to be any plans to port it and I don't have the experience or time to this work. So I had a look round at the alternatives (again!).

Clanlib 2.1

• Pretty mature, modern library with some nice features (e.g. slots and GUI support).
• Hardware acceleration through OpenGL or DirectX depending on platform.
• Windows and Linux are well supported but Mac has fallen behind, no Cocoa support.
• Version 2.0 was the previous 0.9 version; and 1.0 is the old 0.8 version, renamed. Version 1.0 compiles for the Mac but uses the 32-bit Carbon API. In Xcode 3.2.1 you can no longer create a Carbon project, it must be Cocoa; and if you want to do iPhone, this must definitely be the case.
• Xcode project files provided for Mac. Version 2 needs work.
• Licence: BSD.

SDL 1.2 / 1.3

• SDL is a well thought out low level library, but SDL libraries a bit scattered and some look unmaintained.
• Very portable and core well supported.
• OpenGL compatible.
• Uses Cocoa on Mac.
• Can be built as a framework. 
• Basic sprites don't support rotation.
• Licence for version 1.2:  LGPL.
• Licence for version 1.3: Dual licence, LGPL and commercial (closed source). On embedded platforms (e.g. iPhone) you have no choice but to buy a commercial licence or you are forced to go open source.

Allegro 4.4

• This is quite an old game library but seems to be well supported. Some of it is quite archaic, with palette support and support for old DOS compilers.
• Mac port uses Cocoa.
• API being reworked in Allegro 5.
• Can be built as a framework.
• Uses cmake to generate project files.
• Polling API.
• Minimal external dependencies (e.g. includes JPEG decoder).
• Licence: Giftware.

Allegro 5.1

• Allegro 5 been a long time in development, but worth the wait. Allegro had a lot of cruft from DOS and pre-graphic cards. The latest version is 5.1.
• The API is a lot more organised than 4.x. It is simple and elegant.
• The live version, straight from git (with build instructions) is available. Please note that whilst this contains new features and fixes, it also sometimes contains bugs (which happens during development). If you aren't comfortable with this use the latest stable release.
• OpenGL and DirectX renderers (hardware accelerated) by default.
• Event based API (i.e. not polling).
• Notes on building for Mac OSX.
• Licence: Giftware.
• (This was version 4.9 in the original comparison, which was a work-in-progress version of Allegro 5.0.)

Conclusion

I like the extra features that Clanlib and Allegro supply in their default libraries. Clanlib unfortunately uses Carbon on the Mac and Mac version not supported for long time. This is a real shame because Clanlib includes everything you need (including a GUI).

SDL provides extra features in libraries which I find a little scattered and iPhone development requires a commercial licence if you don't want to release your source code.

So as a result I decided on switching to Allegro 4.4, because unsure how mature 4.9 is, and generally Mac lags behind the main development platforms (Linux and Windows). I'll build my own API, hiding some of the the archaic nature of Allegro. I also decided on Allegro because I found the retro games site, which uses AllegroGL. :-)

I've now switched to Allegro 5. It is still a nice simple API, much improved and tidied up, and libraries updated for modern hardware. Works fine for OSX 10.6.  This is the best, simple cross platform (Windows, Linux, OSX) solution I have found.

[24-Jul-10] Updated because SDL 1.3 has now move to dual licence.
[25-Mar-11] Updated for Allegro 5.0. Removed notes on 4.9 as not useful.
[16-Jan-13] Updated notes on Allegro 5.1.