08 Dec

Inversion of Control in Software Engineering

What is Inversion of Control in Software Engineering?

Inversion of Control in Software Engineering (IoC) is essentially a strategy for decoupling software components. Basically, the purpose of IoC is to remove unnecessary dependencies (couplings) which might reduce flexibility and elegance of a system’s design. The term Inversion of Control in Software Engineering might sometimes appear applied to different design contexts. It is a term that comes from the 70s, when bottom-up parsing was considered an inversion of top-down parsing. It has roughly continued to be applied in multiple contexts. Some people think Inversion of Control in Software Engineering is a design strategy. For others, it’s a design pattern. After some articles dealing with OpenGL, in this post we will briefly discuss this topic of Software Engineering.

Read More
04 Dec

Render a Triangle with OpenGL

This post will discuss how to render a triangle with OpenGL. In the following, renderization of a triangle assumes modern OpenGL, i.e., the old, fixed-function pipeline is of no concern for us in this post, as we’ll be using OpenGL buffer objects and shaders.

A Simple Triangle

By following the tutorials in the previous posts (Setting up Eclipse CDT for OpenGL and the GLFW Example) we were able to create a minimal program displaying an empty window. Now we want to draw something with OpenGL on that window, specifically, a triangle. Why a triangle? Well, the geometric shape more frequently used to approximate surfaces is the triangle. Approximation of 3D surfaces in real-time graphics by means of simpler shapes is known as tessellation. For our tutorial purposes, a single triangle will suffice.

GPU Power

Modern GPUs are quite fast and can also have a considerable amount of dedicated memory. When rendering, we’d like for as much rendering data as possible to be read by the GPU directly from its local memory. In order to render a triangle with OpenGL we’ll need, obviously, to transfer the 3 vertices of the triangle to the GPU’s memory. However, we do NOT want our rendering to go like this:

  • read a vertex from our computer RAM
  • copy it to the GPU memory
  • let the GPU process that single vertex
  • and then repeat this whole process for the next vertex of the triangle.

Ideally, what we want is to transfer a batch of data to the GPU’s memory, copying all the triangle vertices, and then letting the GPU operate with this data directly from its local memory. In OpenGL we have the concept of Vertex Buffer Object (VBO) to represent these data placed on GPU’s memory.

The data to render the triangle in OpenGL

Normally, we think of a vertex as a point, which in 3D space leads to a representation with 3 coordinates, commonly designated by x, y and z. However, in this case I’d like to think of a vertex as a more abstract concept: a minimal data structure required to define a shape. Given a vertex, we can “link” attributes to it to further define our shape. Thereby, one of such attributes of a vertex can be its position (the “x, y, z values”.) Other attribute might be the vertex’s color. And so on. In this tutorial we will “link” two attributes to our vertices: position and color. For position we will have three coordinates, each a floating point value. If a float takes 4 bytes, then our position attribute would require 3 x 4 = 12 bytes. For the color attribute, we’d have 3 extra components, following the RGB model. Each color component would then take 4 bytes, and the color attribute would also require 12 bytes. In total, each vertex would take 24 bytes, 12 for its position attribute, and 12 for its color attribute.

Now we have to specify how to process these vertices.

Read More
03 Dec

GLFW Example

Here I’ll briefly discuss a tiny GLFW example. Previously, I explained how to setup Eclipse CDT to work with OpenGL, using GLFW and GLAD. However, I instructed to copy-paste the example code on GLFW Documentation page, without providing any details. In the following I’ll present some code that you can add to the little project of our setup post, and will include GLAD initialization too.

Read More
27 Nov

Setting up Eclipse CDT for OpenGL with GLFW and GLAD

What’s OpenGL?

OpenGL is an API to render 2D and 3D graphics. Remember that an API (Application Programming Interface) is an interface for interaction between components of a system. Typically, an API defines a set of functions, protocols and/or tools. I’ll skip the details about the client-server model, but OpenGL allows a client program to communicate with GPUs (Graphic Processing Units, e.g., your videocard) to achieve faster, hardware-accelerated rendering. That’s why OpenGL is a common topic in the game development scene.

OpenGL is focused on just rendering. It’s an API to write and read data from a framebuffer, and that’s it. It won’t handle user input, or sound playback, or loading a PNG image. It does not even have functions to create or close a window. We’ll need auxiliar libraries for all of that.

A minimal OpenGL window

So we want to build a minimal OpenGL application on Windows. We’ll create an empty window with an OpenGL context, using the GLFW and GLAD libraries. In the following, I assume we’re using a 64 bits version of Windows. I’ll also be relying on mingw-w64. In summary, these are our assumptions:

  • Windows operating system (64 bits.) Things will be a tad different for macOS and Linux users.
  • Eclipse CDT.
  • mingw-w64 to build GLFW from sources. Besides, our Eclipse CDT project will be compiled with the gcc version of mingw-w64.
  • GLFW and GLAD libraries.

What’s GLFW?

As told, OpenGL does not provide any facility to create a window, retrieve user input, create the OpenGL context, etc. These functionalities depend on the operating system. GLFW is a C library which provides a neat abstraction layer to handle all of this on several platforms. Notice that GLFW is focused on management of windows, OpenGL contexts, user input and time. It will not play sounds, or load images, etc.

Read More
25 Sep

UTF-8 with BOM

When localizing DragonScales 3 we experienced a baffling issue with an internal tool whose purpose is simply to replace text in a group of files. Those UTF-8 encoded files contain messages loaded by the game from the very beginning. However, after running the tool, the game started crashing when reading such files. By using an old buddy, fc /B, we found out that our tool was “injecting” a few extra bytes at the start of the file: EF BB BF. In short, the tool was altering the encoding of files from UTF-8 to UTF-8 with BOM. That was the cause for the crashing, as our game expects the files to be UTF-8 encoded without BOM.

What’s this BOM, anyway? Simply put, it’s just a sequence of bytes (EF BB BF) used to signal readers about the file being UTF-8 encoded. It seems such mark might be useful in some specific contexts, with some specific programs. Not our case, so we had to remove the BOM with a little batch script like this:

for /r ".\DE\scenes" %%i in (*.*) do (
  copy %%i .\tmp.txt /Y
  sed -i '1s/^\xEF\xBB\xBF//' .\tmp.txt
  attrib -R .\tmp.txt
  move /Y .\tmp.txt %%i
)

In this snippet we remove the BOM via sed. Files are those under a fictitious directory, .\DE\scenes. Those copies and attribs help to circumvent some problems with permissions of files created by our sed version on Windows.

31 Aug

Extracting text from PSD files

Typically, we need to translate hundreds of strings when localizing our games. Most strings are text messages which the game loads from some database or simple text file. However, we often have to handle localization of several PNG images, such as the one below.

AWESOME! message in DragonScales

Such PNG images are exported from PSD files which must obviously contain at least one Text Layer. To speed up the localization process we have a little Photoshop script which opens the PSD files and extracts all the text we have to translate. PSD files are grouped in directories corresponding to the tileset they belong to. For instance, this would be a typical directory structure for the DragonScales games:

images/
    board/
        awesome.psd, great.psd, ...
    cards
        youwin.psd, sorry.psd, ...
    ending
        congratulations.psd, ...
    levelselect
        clickhere.psd, ...
    mainmenu
        welcome.psd, ...
    etc

A simplified but functional version of the script we use is this:

#target photoshop

var target = "/C/projects/ds/images";
var toLocalize = new Array();
var totalProcessed = 0;
var warningsFiles = new Array();

function log(msg) {
	$.writeln(msg);
}

function processPSDFolder(dir) {
	var files = dir.getFiles("*.psd");
    log("===============================================");
    log(dir + " -> "+ files.length);
    log("===============================================");
	for (var i = 0; i < files.length; i++) {
    	var doc = app.open(files[i]);
    	log("  file: " + files[i]);
        totalProcessed++;
        if ( doc.artLayers.length == 0 ) {
            log("   -> WARNING: ZERO TEXT LAYERS? THEY SHOULD NOT BE IN GROUPS.");
            warningsFiles.push(files[i]);
        }
    	for (var j = 0; j < doc.artLayers.length; j++) {
        	var lyr = doc.artLayers[j];
        	if (lyr.kind == LayerKind.TEXT) {
            	var lyr = doc.artLayers[j];
            	log("   ->" + lyr.textItem.contents);
            	toLocalize.push(lyr.textItem.contents);
        	}
     	}
    	doc.close(SaveOptions.DONOTSAVECHANGES);
	}
}

function saveStrings() {
	var out = new File(target + "/strings.txt");
	out.open("w");
	for (var i = 0; i < toLocalize.length; i++) {
		var str = toLocalize[i];
		out.writeln(str);
	}
 	out.close();
}

var root = Folder(target).getFiles();
for ( var i = 0; i < root.length; i++ ) {
	var fileFoldObj = root[i];
	if ( fileFoldObj instanceof File ) {         
        // Discard files at this level
	} else {
         processPSDFolder( Folder(fileFoldObj) );
	}
}
saveStrings();
log("Total PSDs processed: " + totalProcessed);
log("Warnings: " + warningsFiles.length);
for ( var i = 0; i < warningsFiles.length; i++ ) {
	log(" " + warningsFiles[i]);
}

Observations:

  • target is the path to your directory structure holding the PSD files.
  • The strings to be translated will we written to file strings.txt under your target directory.
  • This script looks for text layers on the top level of the PSD. It can be easily extended to inspect layers in groups, though.
  • We use warnings to be notified about files not containing Text Layers. These might be files requiring special exporting and extra formatting, and therefore we’ll have to handle such files exceptionally.
24 Feb

Comments about warning “Deprecated Carbon Component Manager” on OS X El Capitan

Last November, after updating to OS X “El Capitan”, we started seeing a strange warning message when running DragonScales 2:

“WARNING: 140: This application, or a library it uses, is using the deprecated Carbon Component Manager for hosting Audio Units. Support for this will be removed in a future release. Also, this makes the host incompatible with version 3 audio units. Please transition to the API’s in AudioComponent.h.”

DragonScales 2 was built with LibGDX, and before updating to “El Capitan” it did run with no problems, warnings, etc. After some research, we were informed that this was caused by an OpenAL-Soft issue (which has already been fixed.) Specifically, Apple is deprecating some libraries, e.g., the Carbon Component Manager, and the OpenAL-Soft library was referencing such deprecated Carbon Component. When a game referencing these deprecated libraries is executed, newer OS X (e.g., El Capitan) shows the above warning. However, as told, this OpenAL-Soft issue was already solved on last November: the library is updated and ready for prime time.

A build of OpenAL-Soft is part of the LWJGL natives bundled with LibGDX. If you don’t use an updated build of OpenAL-Soft you’ll keep receiving the deprecation warning. As we commented on this thread, a quick fix is downloading the latest LWJGL3 build, grab the native libopenal.dylib and drop it over the OpenAL native bundled with LibGDX.

A caveat, though, about using the OpenAL-Soft included in LWJGL3 (at time of writing.) Some testers of DragonScales 2 for OS X reported a nasty crash. Here’s part of the crash report:

Dyld Error Message:
Symbol not found: ___sincosf_stret
Referenced from: /var/folders/*/openal.dylib
Expected in: /usr/lib/libSystem.B.dylib

Clearly, our OpenAL library was referencing a function not provided by OS X. It turns out that our testers were using an older OS X version (10.7, I think) whereas the libopenal.dylib bundled with LWJGL3 was targeting OS X 10.9. In fact, output of otool -l libopenal.1.17.0.dylib includes these lines:

cmd LC_VERSION_MIN_MACOSX
cmdsize 16
version 10.9
sdk 10.9

As our publishers require support for OS X >= 10.7, we had to compile our own libopenal.dylib. We set OS X 10.6 as deployment target and 10.11 (El Capitan) as the root SDK, by using these CMake variables:

-DCMAKE_OSX_DEPLOYMENT_TARGET=10.6 -DCMAKE_OSX_SYSROOT=macosx10.11.

By the way, here you can find OS X SDKs if you need them.

Checking our build with otool, yields:

Load command 8
cmd LC_VERSION_MIN_MACOSX
cmdsize 16
version 10.6
sdk 10.11

This version of the library passed all our tests successfully.

27 Aug

Resizing multiple image files with ImageMagick

For the first DragonScales post I had several PNGs with a 1920×1200 resolution. Nevertheless, the ideal width for images in this blog is about 600 pixels:

DragonScales Logo (Black background)

DragonScales Logo (Black background)

This is a frequent issue when publishing images here. Thereby I recur to ImageMagick in order to resize sets of images. ImageMagick’s command line tools are excellent and indispensable tools for our work. For instance, on Windows command prompt, it’s enough to type:

forfiles /M *.png /C “cmd /c convert -resize 31% @file resized_@file”

That way all of the images will have resized versions, at 31% their original size, yielding a 600-pixels width approximately. Very useful. And ImageMagick is a great piece of software.

19 Aug

A weekend boxed inside a dylib

I’ve dedicated the entire weekend to heterogeneous yet related tasks. First, I started off by trying to build NagiQ, our first published game, on OS X Mavericks. By “build” I mean to produce a binary complying with the requirements of the Mac App Store. You know what I mean: well-formed directory hierarchies inside the .app, proper icons and .plists, code signing, etc. For the record, NagiQ is a word game created with Ren’Py, a visual novel engine which is, in turn, built with Python. At the time of release a lot of folks shared their thought regarding our election of Ren’Py to create our word game: it was, to say the least, an unorthodox choice. However, almost 3 years after its initial release, NagiQ is still running fairly well on Windows, Mac and Linux, thanks to the wonderful capabilities of Ren’Py for multi-platform deployment.

Building NagiQ on Mavericks is easy, it amounts to just a single click on a Ren’Py option[1]. However, turning the generated .app into a binary suitable for the Mac App Store has proven to be a daunting task. You have to organize the directory structure of the Python Framework distributed with the game. You have to circumvent the writing of Python .o files in the .app directory, a big no-no for sandboxed apps. You have to retrieve the proper directory to save user and game data (~/Library/Application Support/NagiQ is not allowed). Etcetera. Right on the middle of such etcetera lies the requirement of communication with a few dynamic libraries needed by NagiQ to satisfy several functional demands.

As you surely know, dynamic libraries = dylibs on Mac. Taking into account that Ren’Py is a citizen of the Python world, we use the ctypes library to communicate with our dylibs from inside the game. An important lesson I learned during this weekend is that you have to be very careful when dealing with dylibs and ctypes. First, you have to verify that your dylib and the Python version you’re running are compatible. Is your dylib a 32 or a 64-bits binary? Your Python instance must be apt to properly load and call functions of your dylib, or you will spend a lot of time trying to sort out segmentation faults.

Typing python on a terminal of my Mac launches the 64-bit version of the interpreter by default. If you want to execute the 32-bit version, run this in your shell before launching python:

export VERSIONER_PYTHON_PREFER_32_BIT=Yes

After you have launched the proper version of Python, you can import ctypes to load and communicate with your dylib. However, don’t take this communication lightly. Pay special attention to the type of the arguments and return values of your functions. For instance, if you’re invoking a function of your dylib which requires a char* value, then you have to wrap your argument in the type c_char_p. Let’s see another example. Suppose you want to get the proper location to save the data of your game. Of course, as a good programmer, you don’t want to hardcode such path. Instead, you’ll be asking the operating system for it, the right way. Let’s create a tiny, demonstrative Objective-C library (demolib.m) for this:

#import <Foundation/Foundation.h>
const char* findAppDir()
{
    NSArray *paths = NSSearchPathForDirectoriesInDomains(
        NSApplicationSupportDirectory,
        NSUserDomainMask, YES);
    NSString *basePath = [paths objectAtIndex:0];
    const char *convertedPath = [basePath UTF8String];

    return convertedPath;
}

Compile with:

clang -dynamiclib -framework Foundation demolib.m -o demolib.dylib

Then you can call your function from Python:

Python 2.7.5 (default, Mar  9 2014, 22:15:05)
[GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.0.68)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import ctypes
>>> lib = ctypes.cdll.LoadLibrary("demolib.dylib")
>>> findAppDir = lib.findAppDir
>>> findAppDir.restype = ctypes.c_char_p
>>> findAppDir()
'/Users/yourusername/Library/Application Support'
>>>

This little function will prove useful later, when I resume the building of NagiQ. However, the weekend is already over and I have yet to implement several adjustments for DragonScales, our next game soon to be released. The delight of working with dylibs, sandboxes, etc., will surely be the subject of future happy weekends.

  1. [1]This single-step build has grown to be the Ren’Py feature I love the most.
29 Apr

Lampson’s Hints for Computer System Design

Although it’s a bit dated in parts (mostly the examples), the article Hints for Computer System Design by Butler W. Lampson is still a valuable resource for today’s designers and engineers. It’s a nice reading, with plenty of timeless advice. For instance, regarding the issue of how to handle all the cases, the article says:

Handle normal and worst cases separately as a rule, because the requirements for the two are quite different:

  • The normal case must be fast.
  • The worst case must make some progress.

In most systems it is all right to schedule unfairly and give no service to some of the processes, or even to deadlock the entire system, as long as this event is detected automatically and doesn’t happen too often. The usual recovery is by crashing some processes, or even the entire system. At first this sounds terrible, but one crash a week is usually a cheap price to pay for 20% better performance. Of course the system must have decent error recovery (an application of the end-to-end principle…), but that is required in any case, since there are so many other possible causes of a crash.

The full article can be found at Microsoft Research.