## Friday, 21 November 2014

### Using Qt Library templates

The following video shows how to configure a Qt project to create a static library to use in your own projects, the main code for this can be found on github here

The main things you will need to do are in the .pro file as follows

TEMPLATE = lib
CONFIG+=staticlib


If you omit the staticlib it will create a dynamic library and the runtime linker will need to be told where to find your lib.

In the project you intend to use the library in you need to set the LIBS Qt variable passing in the -L[path to lib] and -l lib(s) to link

For more examples of this see this blog post

## Tuesday, 4 November 2014

### Drawing with Modern OpenGL

The following video demonstrate how modern OpenGL uses Vertex Array Objects to store buffers and generic vertex attributes together for faster drawing.

The first Video shows how the deprecated immediate mode OpenGL version would work as context for why we use Modern OpenGL.

The next videos show the basic framework code using ngl and a simple colour shader. The first demo will then use OpenGL calls to create and display a series of points. The second uses the ngl::VertexArrayObject class to do the same thing. The source code can be found here and suggested man pages are glGenVertexArrays glBindVertexArray glGenBuffers glBufferData glVertexAttribPointer glDrawArrays

## Introduction

I have been using the ngl:: library for many years as part of teaching various graphic programming courses. I decided recently it would be interesting to port the core library and many of the demos to work interactively on the web using WebGL so started investigating a number of ways to do this. The main library is written in C++ and uses either Qt or SDL to create the OpenGL context.
I had a number of choices as to which approach to take, I could learn Java Script and  three.js however this would mean porting all my codebase to Java Script which seemed like too much work.
In the end I came across the emscripten system which is a LLVM-to-JavaScript Compiler which can convert my C++ code into LLVM and then into JavaScript and then into asm.js the process was quite a steep learning curve, however I manage to get quite a lot of demos ported very quickly which can be seen here the rest of the blog will outline the process and how the webngl system was developed.

### Installing Emscripten

My main development environment is a mac, however I have also tested the files under linux and it also works well. To get started I followed the tutorial here and all worked first time. The next stage was to try a simple WebGL demo that is provided with the examples. There are several WebGL demos using different libraries for OpenGL context creation however as I'm most familiar with SDL I chose to use this as the basis of the framework.

### A Simple SDL demo program

The following code is a simple SDL program (very similar to a normal SDL program) the only difference is the call to emscripten_set_main_loop.

#include "SDL.h"
#include <GLES2/gl2.h>
#define GL_GLEXT_PROTOTYPES 1
#include <GLES2/gl2ext.h>
#include <emscripten.h>
#include <iostream>
#include <cstdlib>

void process()
{
// as we don't have a timer we need to do something here
// using a static to update at an interval
static int t=0;
if(++t > 100)
{
float r=(double)rand() / ((double)RAND_MAX + 1);
float g=(double)rand() / ((double)RAND_MAX + 1);
float b=(double)rand() / ((double)RAND_MAX + 1);

glClearColor(r,g,b,1);
t=0;
}
glClear(GL_COLOR_BUFFER_BIT);
// this is where we draw
SDL_GL_SwapBuffers();
}

int main(int argc, char *argv[])
{

SDL_Surface *screen;

// Init SDL
if ( SDL_Init(SDL_INIT_VIDEO) != 0 )
{
std::cerr<<"Unable to initialize SDL: "<<SDL_GetError();
return EXIT_FAILURE;
}

SDL_GL_SetAttribute( SDL_GL_DOUBLEBUFFER, 1 );

screen = SDL_SetVideoMode( 720, 576, 16, SDL_OPENGL  | SDL_RESIZABLE);
if ( !screen )
{
std::cerr<<"Unable to set video mode: "<<SDL_GetError();
return EXIT_FAILURE;
}

glEnable(GL_DEPTH_TEST);

// let emscripten process something then
// give control back to the browser
emscripten_set_main_loop (process, 0, true);

SDL_Quit();
return EXIT_SUCCESS;
}


The emscripten_set_main_loop function is explained very well here basically we create a function that is called asynchronously to allow the browser to regain control after every iteration of the function. It is important that this function does exit else the browser will hang up and I have had several times when I get a complete lockup of the system.

### Compiling the program

To compile the program we use the following command line (in this case I'm using c++ )
em++ -s FULL_ES2=1 SDL1.cpp -o SDL1.html

The flag -s FULL_ES2 tells emscripten to use full OpenGL ES 2 specification when compiling the code, the -o SDL1.html will generate an html file as well as the javascript file for the canvas to use. The html file can now be opened in the browser an in this case you will see a screen that changes colour every 100 cycles of the main loop. In the next post I will begin to discuss how I ported the rest of ngl to use emscripten.

## Thursday, 20 February 2014

### GamePlay 3D 101

Another Guest post on my Blog, this time from Callum James and Ramesh Balachandran from the BSc. Software Development for Animation, Games and Effects course at the NCCA

## What is Gameplay 3D?

Gameplay 3D is an open-source, code based engine that is aimed at being cross-platform compatible. We decided to use this engine over others as we would have the most control over the features and optimisations of the program / game we create. Whilst giving you the tools to produce a simple piece of high quality in relatively little time, other game engines such as the Unreal Development Kit , are restrictive to their scripting functionality and UI interaction. Therefore, by using an open-source engine that has an established rendering engine, we are able to extend upon and create a new version of the engine in our own desired way.

## Our Preferred Gameplay 3D Setup There are multiple ways you can use the Gameplay 3D engine on different platforms. By default, the engine comes with source and project files for Visual Studio on Windows and an XCode project for MacOSX.  It is then up to you to get an environment set up for a Linux build. However this makes it a little cumbersome to be easily platform independant for efficient development. We however have come up with a simple solution to make it as easy as possible to pass your project between all three major platforms and quickly get up and running for development. Whilst it would be ideal to have a single development project for all three platforms, due to our desire to support not only Windows 7 but also Windows 8, we have had to separate the Windows build to its own Visual Studio project. For Mac and Linux, we then have a single Qt Creator project (.pro file) that very easily compiles and runs on both of the Unix flavours. As the VS project file and the Qt project files all read from the same sources, cross platform development is still quick, easy and affects all platforms. To ensure this works however it is important to keep a strict directory hierarchy to your project so that no file gets lost and you keep independant local file paths to a minimum.  Following is a quick overview into how to set up Gameplay 3D on each of the three major platforms in the way we have discussed here.

### Setting up Gameplay 3D on Unix - Linux and MacOSX Setting up Gameplay 3D to work on a Unix platform (either Linux or MacOSX) using Qt Creator, there are a few things you need to make sure are set and linked correctly. Here we will discuss what you need to ensure is set correctly and included in the .pro file so that your project will build and run successfully. The first thing you need to look at is your include and library paths. You need to ensure that your include paths are at least set to ./include to pick up on your header files.  Other directories to include are:

INCLUDEPATH += $$GAMEPLAY_DIR/gameplay/src INCLUDEPATH +=$$GAMEPLAY_DIR/gameplay/src/lua
INCLUDEPATH += $$GAMEPLAY_DIR/external-deps/bullet/include INCLUDEPATH +=$$GAMEPLAY_DIR/external-deps/lua/include
INCLUDEPATH += $$GAMEPLAY_DIR/external-deps/oggvorbis/include INCLUDEPATH +=$$GAMEPLAY_DIR/external-deps/png/include

Libraries to link up to for your projects are as follows for Linux:
unix:!macx{
LIBS += -L$$GAMEPLAY_DIR/external-deps/lua/lib/linux/x64/ -llua LIBS += -L/usr/local/lib -lBulletCollision -lBulletDynamics -lLinearMath LIBS += -L$$GAMEPLAY_DIR/external-deps/glew/lib/linux/x64/ -lGLEW
QMAKE_CXXFLAGS += $$system(pkg-config --cflags gtk+-2.0) LIBS += -lgtk-x11-2.0 -lglib-2.0 -lgobject-2.0 LIBS += -L$$GAMEPLAY_DIR/external-deps/oggvorbis/lib/linux/x64/ -lvorbis -logg
LIBS+=  -lrt -ldl -lpng -lopenal -lz -pthread -lGL -lX11
}

And for MacOSX:
macx:{
INCLUDEPATH+=/usr/local/include/
LIBS+= -L/usr/local/lib -lBulletDynamics  -lBulletCollision -lLinearMath
LIBS+= -L/usr/local/lib -lpng
LIBS += -L/ext-deps/fmod/lib/macosx -lfmodex
LIBS += -framework Cocoa -framework GameKit -framework IOKit -framework QuartzCore -framework OpenGL -framework OpenAL
LIBS+= -llua -lvorbis -lvorbisfile -logg -lz  -ldl -lpthread
}

These are all the include paths and libraries you will need to get started. It is however important to note on Mac, you need to make sure you are linking against the right architecture for your build. The external dependency libraries supplied with the Gameplay 3D library are all 32 bit so if you want to build 64 bit projects you will need to recompile the external libraries as 64 bit and then link to these. You will the need to include in your .pro file the following:
macx:QMAKE_CXXFLAGS+= -arch x86_64
macx:CONFIG+=x86_64

Secondly, local path set-up is vital to ensuring your project will run on all platforms without having to go through and change all of the paths to files and assets. The paths differ due to the way that the game is built on different platforms. On Linux (and Windows) it is built as a simple executable. Gameplay 3D built on OSX however utilises the MacOSX app bundle feature. When compiling on Mac, the application will be built into the directory ./application_name.app/Contents/MacOS. This is also where it will be run from. However because the executable is run from here and not the root directory, any assets it requires are no longer visible to it. As such, all the required assets need to be copied into the correct directory for the application to find them. On Linux and Windows, this is simple as the executable will look from assets in a res/ folder from the root directory. So within your root directory as long as your assets are stored within a res folder, you will be fine. However on Mac, the files you require for the game need to be copied into the Resources folder into a folder called res. The gameplay engine will then pick up on these resources. The config files also go into the Resources folder (but not the res) folder. These can then be picked up and read by the application when run. In the .pro file, you just need to ensure all the files you require are passed to QMAKE_BUNDLE_DATA. So for example, to copy some splash screen images to the correct directory and use them with a local path, you need the following in your .pro file:
SPLASHIMAGES += res/splash/logo_powered_white.png

macx:{
APP_SPLASH_IMAGES.path = Contents/Resources/res/splash
APP_SPLASH_IMAGES.files += SPLASHIMAGES

QMAKE_BUNDLE_DATA +=  … \
APP_SPLASH_IMAGES \
… \
}


Any other files you need also need to be added to QMAKE_BUNDLE_DATA in this manner, so for example to also add audio files, use:
QMAKE_BUNDLE_DATA +=  APP_AUDIO_FILES \
APP_SPLASH_IMAGES \
… \

The Gameplay engine will automatically pick up on them when located in this directry, but anything you write yourself using paths needs to be prefixed. Adding ../Resources/ to the front of any local paths used in your code will ensure your game looks into the right folder on Mac. To automatically do this, we have developed a very simple function as below:
#ifdef DARWIN
#define PATH_PREFIX "../Resources/"
#else
#define PATH_PREFIX ""
#endif

std::string GeneralUtils::PLATFORM_FILE_PATH(std::string _path)
{
return (PATH_PREFIX+_path);
}

The DARWIN define is set within the .pro file if the macx platform is detected, as follows:
unix:!macx: DEFINES += LINUX
macx: DEFINES += DARWIN

If this is all set up correctly, then local paths will work on all platforms without any need to change them.

### Setting up Gameplay 3D on Windows

The setup for programming with Gameplay 3D on Windows differs slightly from the Unix build. Due to the current operating system used for development on Windows (Windows 8.1 64-bit), there were issues in setting up Qt Creator to enable complete cross-platform programming. The IDE of choice was shifted to Visual Studio 2010. In order to set up the project to work with Unix build, the Visual Studio project settings need to be set up to correctly link to the Gameplay3D libraries as well as the correct Windows external dependencies. To make sure this is done correctly, the engine needs to be built using the Visual Studio project file accompanying the engine. The Gameplay3D files are compiled for a 64-bit architecture of Windows to work alongside the 64-bit architecture setup of the OSX and Linux builds. Once this is compiled, the Visual Studio project needs to correctly link to the engine header files as well as the necessary external dependency files. This is done under Project -> Properties -> Configuration Properties -> C/C++ in the ‘Additional Include Directories’ section. In this section, the paths to all of the header files would be added:
../../external-deps/lua/lib/windows/x64
../../external-deps/bullet/lib/windows/x64
../../external-deps/openal/lib/windows/x64
../../external-deps/oggvorbis/lib/windows/x64
../../external-deps/glew/lib/windows/x64
../../external-deps/png/lib/windows/x64
../../external-deps/zlib/lib/windows/x64

### Compiling with xcode

Now we can open the xcode workspace (gameplay.xcworkspace) and configure and build the main gameplay static library.

To make development easier I'm going to setup the targets to build the library in the same root GamePlay directory. To do this we do the following first goto File->Workspace Settings in the xcode menu

Choose WorkSpace relative as shown below

Now we can build the library and the final lib should be placed in the directory GamePlay/DerivedData/gameplay/Build/Products/Debug. This actually builds a mac framework that we can copy into some other directory to use in our own projects. However for now we will leave it as it is.

### Creating a new project

Gameplay comes with a newproject script that will copy a template project to a new location. Again I have modified this to make it easier to create new projects in directories other than the main GamePlay one.

In an editor open up the GamePlay/newproject.sh script look for each instance of the cp command like this
cp "template/template.vcxproj" "$projPath/$projName.vcxproj"

Where it says "template/ we are going to pre-pend the path of the GamePlay install so in my example it's going to be $HOME/GamePlay/ cp "$HOME/GamePlay/template/template.vcxproj" "$projPath/$projName.vcxproj"
Do this for every cp command in the script.

Now this is done we can create a new directory to put our demos in. In my case I've created one called GamePlayDemos

mkdir GamePlayDemos
cd GamePlayDemos
~/GamePlay/newproject.sh

1. Enter a name for the new project.

This name will be given to the project
executable and a folder with this name
will be created to store all project files.

Project Name: Test

2. Enter a game title.

On some platforms, this title is used to
identify the game during installation and
on shortcuts/icons.

Title: Test

3. Enter a short game description.

Description:

4. Enter a unique identifier for your project.

This should be a human readable package name,
containing at least two words separated by a
period (eg. com.surname.gamename).

Unique ID: ncca

5. Enter author name.

On BlackBerry targets, this is used for
signing and must match the developer name

Author: jm

6. Enter your game's main class name.

will be given this name and a class with
this name will be created in these files.

Class name: Test

7. Enter the project path.

This can be a relative path, absolute path,
or empty for the current folder. Note that
a project folder named Test will also
be created inside this folder.

Path:./

Once the script has run you should see a folder like this
Now we can open the Test.xcodeproj file and get ready to build the demo. First we need to change the search paths for headers. By default they look like this
We need to add $(HOME)/GamePlay to each of these paths (or the directory you installed it into) This will now allow the project to compile, however we still need to set the linker paths and do the same path addition Add$(HOME)/GamePlay to the ../ paths as shown

Finally we need to add an additional path for the libgameplay.a location this can be done by selecting the build options and removing the original reference and locating the one we built earlier in the DerivedData directory as shown

The program should now run and give you the following screen.

I will do some more blog posts soon on using the game engine with maya.