The task at hand is to use the Boost GIL library to convert JPEG images to RGB if needed, as well as to resize them.

This resizing task is part of a larger set of tasks which is wrapped into a larger Qt project. It should be noted however, that at this point we’re only going to focus on the linking process, not the actual code.

This task, linking to a library, will be a very common task for most projects. It’s also interesting because we’ll be using something other than the Standard Library, which means we need to link and talk to other library and code files. This is the ‘glue’ I mention above, in that making these connections isn’t always obvious.

I chose the GIL library over using Qt’s QProcess class mainly for the purposes of learning more about linking. QProcess, for what it’s worth, could have made linking to something like ImageMagik quite simple, but again, in this case it was my wanting to learn which prompted me to chose the ‘tough’ path.

As it is, the first step for me was to research what would be needed to get this done. The first thing I found was that I would need the libjpeg library, as JPEG files are what i want to convert.

It’s a simple download, and can had from here.

To keep things clean, I uncompressed the folder into a directory called /libs in my /Documents directory. You may want to do the same, as we’ll also be putting the boost library there too.

This download contains a set of makefiles, source code, and instructions. As I’m on a Mac I didn’t have the luxury of using say, Ubuntu’s Software Center. If I was, getting this file and installing it is as simple as downloading its package. (the same goes for Boost)

No such luck though, so we need to build it. The good news is this package, at least on OSX 10.6, was very easy to use. All I needed to do was to open a command prompt and cd into the uncompressed folder in /libs/jpeg-8b, and then issue the standard set of build instructions:

./configure
make
make test
sudo make install

This does a few things. First, it runs the configure script to inspect our system and create a make file. We then issue make to compile the project. During this stage you’ll see all sorts of files being created in the jpeg directory. make test does a quick test to make sure the created files work, and sudo make install moves the compiled files to our system directories.

It’s important to note that this final install step moves two sets of files around:

The first set is a group of small application files to /usr/local/bin

We will actually ignore these, as for our project, they are not used.

The important part is the moving of the library files.

Here the install process will create and move two files and a symlink to /usr/local/lib/:

libjpeg.8.dylib

libjpeg.a

libjpeg.dynlib (the symlink)

These are the guys we care about, as this is what we link our application too. It’s important to point out though, that Qt and X-Code use two different methods to create this linkage. More on that in a bit.

For now we need to download and decompress the Boost library. I put mine in the same place as my jpeg library files in /Users/{user-name}/Documents/libs/

The full path would thus be:

/Users/{user-name}/Documents/libs/boost_1_44_0

Within the boost_1_44_0 folder we will have several files and folders. The important bit is /boost directory. This is where the code we include into a project resides, and what we point our IDE/Linker towards to build the program.

More on the Boost install Process.

We’re close now, but before we’re done we need to download and install one more file.

On that page we want to download a file called numeric.zip, the link should be near the bottom.

Extract the file and place it into:

/Users/{user-name}/Documents/libs/boost_1_44_0/boost/gil/extension/

Right, so now we have the needed files on our system, this means it’s time to get linking.

As mentioned above, this process differs for X-Code and Qt.

Adding Boost and libjpeg

The first thing we want to do is make sure Boost works. To do so we’ll grab a chunk of code from here:

#include <boost/lambda/lambda.hpp>
#include <iostream>
#include <iterator>
#include <algorithm>

int main()
{
    using namespace boost::lambda;
    typedef std::istream_iterator<int> in;

    std::for_each(
        in(std::cin), in(), std::cout << (_1 * 3) << " " );
}

X-Code

Create an X-Code Console C++ project and paste the above code into main.cpp.

Try to compile it: it should fail. This is because we need to tell X-Code where the Boost library files are.

Click on the project window (the one that shows all files)

Right Click on the top icon (the one with the projects name)

Select Get Info

This is a multi-tab window, click on the Build tab.

Scroll down until you find the Search Paths section, which is one of main headers in gray.

A sub area of this guy will be a setting called Header Search Paths

Double click the white space next to the setting name and a sheet will appear, click the plus button and add the path to the root of the boost directory.

When done you should have:

Notice how we didn’t use the full path to the code files, we stop at the boost root directory, that is:

/Users/grdinic/Documents/libs/boost_1_44_0

This is because when we:

#include <boost/lambda/lambda.hpp>

…we are saying: “go into the /boost directory starting from the Header Search Path base”.

In other words, we combine the Header Search Path and <boost.. (the last / is implicit). to make:

/Users/grdinic/Documents/libs/boost_1_44_0 <boost/lambda/lambda.hpp>

While we’re here, let’s also quick add the jpeg-8b path to the Header Search Path:

/Users/grdinic/Documents/libs/jpeg-8b

We could do this later, but getting it out of the way now seems prudent, as we know we’ll need it soon anyway.

Now when we recompile we should get no errors, as the Boost code files are being found.

Of course we can test this by running the program. Thing is, this program expects input, so we need to make sure to open the GDB console to supply it.

If you have not used this before (the console in X-Code), you can find it’s button after you’ve started the program(!) as seen below,  right in the middle of the screen next to the word __kill:

When the console window opens you can type in a number, and the program will multiply it by 3 and show the result. Boost Works!

Qt

To do the same in Qt we have a slightly easier task:

We define the include path to our code libraries by opening the .pro file for our project and adding:

INCLUDEPATH += \

    /Users/grdinic/Documents/libs/boost_1_44_0 \

    /Users/grdinic/Documents/libs/jpeg-8b \

With this done we have included the Boost and libjpeg code files.

Linking libjpeg

The next step is to make sure Boost+GIL works. As we already have Boost working you’d think this would be a given, but now we need to add our libjpeg library into the mix, which complicates things a bit.

First, we start with the docs page, where we find this bit of code*:

#include <boost/gil/image.hpp>
#include <boost/gil/typedefs.hpp>
#include <boost/gil/extension/io/jpeg_io.hpp>
#include <boost/gil/extension/numeric/sampler.hpp>
#include <boost/gil/extension/numeric/resample.hpp>

int main() {
    using namespace boost::gil;

    rgb8_image_t img;
    jpeg_read_image("test.jpg",img);

    // test resize_view
    // Scale the image to 100x100 pixels using bilinear resampling
    rgb8_image_t square100x100(100,100);
    resize_view(const_view(img), view(square100x100), bilinear_sampler());
    jpeg_write_view("out-resize.jpg",const_view(square100x100));

    return 0;
}

*Please note I have removed the header comments for the sake of clarity.

If we try to compile this code now we’ll get errors. We get these errors because we need to link the libjpeg.a file to our project.

It’s important to note that the Boost and libjpeg pieces are really just code files (well, not all, but for us in this project they are), so the inclusion process is just telling the linker where they are.

However, library files are different animals altogether, so they need to be linked to our project in similarly different manner.

As you might expect, the process of creating this library link differs between the two editors.

X-Code

X-Code expects library files to be selectable in the GUI under the Targets > Link Binary with Libraries > Add area:

This is a problem however, because the path the lib files were installed too above:

/usr/local/lib

…is not accessible through the X-Code GUI.

The fix is to simply open a terminal and cp the files to our project directory:

cp /usr/local/lib/libjpeg.a /Users/grdinic/Documents/X-Code/boost/

With that done, we can now use the GUI interface to select the library file, which should add the library to our project and makes it available for the linking step:

Now when we build, the project should do so without error**.

Qt

Qt, thankfully, is a bit more simple. To add a proper link to the library file we simple add this to the .pro file:

LIBS += -L/usr/local/lib -ljpeg

It is worth pointing out however, that their are some real subtleties going on here.

The LIBS+ part is all Qt, and should be strait forward. The trick is the -L switch, which is actually a GCC directive. The other tricky bit is the -ljpeg.

To be honest, this is one of those things that drives you batty if you don’t know what to look for. It’s great when you know sure, but man, during…

The -l means library, and the jpeg seems strait forward enough…until you look at the library files on your system and only see a libjpeg.a Where in the heck does jpeg come from?

Ah you see, the trick is that during the linking process the lib is removed for you, as is the .a. Thus, -ljpeg really means get libjpeg.a.

Again, it’s nice when you think about it for the simplicity it offers, but it’s a real bear if you didn’t know that going on!

**Other Issues

At this point I wish could say ‘all done’, but cannot. My OSX machine compiles this code as expected, but the situation is not so rosy on Ubuntu 10.4.

When we try to compile I get an error:

/home/matt/Qt Projects/boost/../../libs/boost_1_44_0/boost/gil/extension/numeric/sampler.hpp:104:
error: no matching function for call to ‘boost::gil::point2<int>::point2(boost::gil::point2<long int>)’

A quick look at the trunk shows that newer versions of GCC and gil don’t always play together so well. The good news is so long as we used the plain download of Boost 1_44_0 a simple change of:

point2<int> p0(ifloor(p)); // the closest integer coordinate top left from p

to:

point2<long> p0(ifloor(p)); // the closest integer coordinate top left from p

…should do the trick for this particular issue.

So as simple as that was, that’s the thing about library files. When something goes wrong, it can really, really go wrong. This is because the type of programming the GIL and Boost developers are using is called Template Metaprogramming, and is for all practical purposes the most advanced form of programming I’ve ever come across.

Some of this complexity in implementation is somewhat alleviated by the use of C++ Template Concepts, a feature that while not part of the C++ standard just yet, is implemented in spirit by the GIL developers. However, when things go wrong your error list could very well be undecipherable. It’s the price we pay for the power of templates.

The last interesting idea here is that if you want to actually run this program, you’ll need to specify the image file path to something real, else we’ll get a hard crash in our Qt app, or an error in the X-Code version.

Final Words

This post was all about linking two code libraries and one actual ‘library’ file to a small project so that we save ourselves the time and effort of writing image processing code ourselves. In the world of C++ application development this is an absolutely necessary skill.

The big takeaways are that most of what we did was actually quite simple, but also, in many places and ways, subtle.

Of course their is more to learn: We have yet to deal with portability, in that one of the primary goals of creating Qt apps is the effortless cross-platform distribution. As soon as we start adding external libraries we need to be aware of the extra time and effort getting these guys to play nice with our systems will be.

We also left out the idea of the two types of linking, static and shared. For OS X developers, we left out the concept of frameworks. In short, we’ll leave this as an exercise for you for now, though may revisit these topics and other at a later time.

My final point will be to play it safe. You can download a newer version of the gil library from Adobe’s website if you like, but my time with doing so was spent running down and fixing various template issues, and all to no avail. In short, stick with the version that comes in the official Boost package!

In this post we’ll look at the 3 main technical options Qt Designer employs to serve this function:

• Aggregation as a pointer member
• Aggregation
• Multiple Inheritance

We’ll also see examples of each method in practice. By the end of this post we should have a good grasp on the various ways we can use Qt Designer to create and integrate designer forms into a larger application.

When considering which method to use it’s important to understand why multiple methods exist in the first place.

The first part of our answer is to understand that when we design an application, our user interface will at some point need to interact with our underlying program logic and/or data structures. Thus, while we can create a new form for our application using the visual editor, it’s up to us to make a programmatic connection so these elements actually do something meaning ful in the context if the larger application.

In short then, how do we get say, a dialog box to write values to a main window? That is, how does one window (designer form) talk to another?

The three methods mentioned above are an abstract answer to this question.

So let’s open Qt Creator and create a basic, empty Qt GUI Application. For our purposes we’ll leave the default names the same, which means we should have a few basic files in our project:

main.cpp

mainwindow.cpp

mainwindow.h

mainwindow.ui

formsdemo.pro

At least in Qt Creator 2.0, the first window that should be open when we leave the create project wizard is the integrated Qt Designer tool. We can close that for now, as our focus is the code files Qt Creator has created for us.

Specifically, mainwindow.cpp and its definition file, mainwindow.h.

The contents of these files will differ based on a setting you may not have seen before:

Qt Preferences > Designer > Embedding of the UI Class

Notice the three options:

• Aggregation as a pointer member
• Aggregation
• Multiple Inheritance

The default on a fresh install should the first: Aggregation as a pointer member. If it’s not, then set it as such and recreate the project (delete the one you just created and start over).

The reason why is with this setting Qt Creator designates the mainwindow.cpp and mainwindow.h files to utilize a private pointer to our Ui::MainWindow object, which is in turn defined in mainwindow.h, which itself part of the Ui:: namespace, of which Ui_MainWindow is a subclass of MainWindow, our main window widget.

It’s a mouthful, and may not the easiest to understand strait away. The end result is that in mainwindow.cpp, so long as we include:

…our Ui objects defined in ui_mainwindow.h should all be accessible (exposed) via our private ui-> pointer in mainwindow.cpp.

Sure enough, our MainWindow constructor contains a call to setupUi() using this pointer:

Again, this is somewhat of a mouthful and is not always the easiest to understand. This technique gets at the heart of some of C++’s more advanced Object Oriented features, many of which could be completely foreign to you. Complexities aside, the end result is with this logic any time we need to access a Ui element in our MainWindow class, we simply use the ui-> pointer.

This is an incredibly important point, as it sets us up for understanding how to add and integrate our own designer forms. In other words, when faced with the task of linking a Ui_ definition file (ui_mainwindow.h) to the mainwindow.h and .cpp files, this is what the designers of Qt have decided to do…it’s a pretty good idea to follow this lead!

Creating A New Designer Form

To see why, right click on your projects name in the Protect Panel (the listing with all the project files, left and side), and from the context menu, click Add New…

Depending on your platform and version, you need to locate the Qt Designer From Class template.

Choose Dialog without Buttons and click continue.

Now set the Class name MyDialog.

This will update the other fields in the wizard such that your header and source files will be mydialog.cpp and mydialog.h respectively.

Again, the first window that will open is the Qt Designer editor. Go ahead and add a single lineEdit item to the dialog and save and close the Qt Designer editor.

Let’s assume this dialog box needs to communicate with the MainWindow form. How do we do that?

We have two main options: Signals and Slots, and Direct Exposure.

Signals and Slots

This is perhaps the most ‘pure’ method, as is means we do not have to force direct connections between widgets. We simply set up a signal from MyDialog and create a slot in MainWindow to process any signals it receives. The only down-side to this method is it creates more coding work, and can be harder to maintain. The upshot is as we’re using signals and slots, we have a greater ability to compose multiple objects together and only listen to the elements we choose. In short, the dialog and caller remain disconnected for the most part.

Direct Exposure

Direct Exposure means we manipulate the mydialog.h file to gain direct access to its ui members from the calling class, in this case MainWindow. The manipulation is a bit of a force though, as our change is making the ui-> member pointer public instead of the default private.

I addition to the privilege change, we must also include both mydialog.h and ui_mydialog.h in the mainwindow.cpp file.

The upshot to this manipulation and inclusion is our MyDialog ui members are now visible to MainWindow, and can be accessed in a manner similar to:

Again, it’s important to note that in order to get to this point we needed to make a private member public, as well as include two header files in our mainwindow.cpp file. This could be considered a bit of heavy-handed coding, and may not always be what you want. That said, it’s a totally legitimate solution, and is certainly less code-heavy and maintenance prone than the Signals and Slots approach.

What About The Others?

Up until this point we’ve only looked at the first of Qt Creators three options for creating code, Aggregation as a pointer member. The other two are just as important, and in some ways, perhaps a bit more convenient.

Aggregation

First we have aggregation. This is very similar in usage terms to the first, in that we aggregate the ui object into our definition file. However, as it’s not a pointer the syntax is a bit cleaner, and in terms of includes, is a bit easier to keep track of as the ui_.h file (the one created by moc), is included in the .h file of the form implementation, meaning we do not need to include it in the mainwindow.cpp class. However, we still need to make the Ui:: member public instead of private, which means we need to edit the moc generated code.This is fine, but is something you should be aware of when faced with creating many widgets.

The end result however, is that we can now access the ui members from MainWindow:

Notice that as our Ui member was created on the stack as opposed to the heap like the first method, we access the ui elements using the member operator (.)

Multiple Inheritance

This is an interesting approach, as from a pedagogical standpoint many of the Qt learning tools use this method in their examples. In other words, knowing about this method helps us learn Qt.

As the name suggests, in this method we subclass both the Base Class of our Widget as well as the namespaced class, which designates the Ui_ class as a subclass.

This dependency chain thus provides our base class with direct access to our forms Ui elements. As can be seen, this makes for the cleanest, most easy-to-understand code:

However, it should be said this benefit comes with a price. Classes defined in this way or almost certainly less flexible for more complex projects, as now we’ve created a tight bond between ui definition and implementation.

Overall though it’s not a surprise why Qt chooses this method in many example code blocks, it’s the easiest to understand and totally sufficient, at least for smaller projects.

Conclusion

This post is rather heavy on theory, so to aid in its consumption I’ve created a test project which shows off each method. The project is purposely light on comments, as the goal here is to just open it up and stalk through the code, letting your own explorations decipher it.

Please keep in mind that their are no doubt other techniques and strategies/design patterns for adding and integrating Qt Designer forms.

Code Download

Contains a simple project showing the methods discussed in this post.

uimembers

This is handy for many operations, and while simplistic in that we’re not synchronizing data, still has many uses, from processing large blocks of images to streaming chunks of data.

In this post we’ll check out some sample code for implementing QFuture.

Let’s start with the following code which implements QFuture in the most basic manner possible:

This code will consume a thread for the computation method call, returning the result via future.result(). When compared to our raw POSIX thread example it becomes clear just how much more simple the Qt version is.

Simple enough, but this code has one potential problem: as the comment shows, waitForFinished() blocks, which means our GUI stalls.

To fix this we’ll implement a signal/slot solution to let the long-running process chug away in the background, leaving the GUI thread free for updates. Of course the only trick to this is we need signals and slots, which means we must break our application apart into traditional header and implementation files.

main.cpp

mainwindow.cpp

mainwindow.h

thread.cpp

thread.h

Between this and the official documentation it should be pretty clear what’s going on.

However. the one thing to point out is that time and again we’ll be confronted with the question of how do we ‘get’ values back from a signal/slot architecture. Of course in this example we’re using threads, but this question applies equally well to non-threaded scenarios.

In many instances the answer to this question is we needn’t do anything. We’re processing a batch of images and only need to know when the batch operation is complete. This can be in the form of a dialog box, and is where QFutureWatcher comes in–we only care about being notified as to when we’re done processing.

But that’s not always good enough, and is for me at least, where much of the learning pains of signal/slots has come from.

In this example I wanted to return the value of our threaded computation to the main thread via qDebug(). The problem was that while QFuture returns a value via future.result(), we cannot get this value asynchronously without blocking the GUI, as was the case in the first example. Why? Because when we implement QFutureWatcher to notify us the result of a QFuture has finished, we now only have signals, and these signals do not contain the results of our method call.

So how do we get our results?

In the end my solution was simple: bypass QFutureWatcher and emit a signal directly from the threaded computation method. This has the exact same effect as emitting a signal when the thread is done, only now we get a value back as well.

In the end my original failure was because I was trying to force functionality where it didn’t belong. QFuture is a very simple wrapper (though powerful), which makes spawning threads a snap. But it is in the end just that, a simplified wrapper for a more complex process.

Of course the downside to this is I had to implement my own signal/slot connections to retrieve the value, and in doing so, made my function a touch less portable. No matter, it’s a small price to pay as I now get my values back to the main thread as desired.

The last thing I would like to point out is the syntax of the call:

Although this is covered in the official documentation I ended up stuck for a bit because I didn’t realize one very important subtlety:

When passing members functions the first parameter must be a pointer to an instance of the class. It says as much in the docs–the trick is that the second parameter must then be the address of the member function being called.

If you leave this part out you’ll get compiler errors, so make sure to double check what you’re passing.

Of course this is the most simplistic thread concept in Qt, but it’s a a darn powerful one. Study the code above, try it yourself, and get multi-threading!

In the next two posts we’ll take a look at the Fibonacci algorithm used in a few other posts and see just how fast we can make it by looking at loop implementation, data type usage, and assembly code optimizations. In this first post we’ll take a look at some basic timing code, what gcc will do for us using the -O2 flag, then in the second post, see what we can do (if anything) to improve upon the generated code.

The Algorithm
The traditional use of the Fibonacci sequence is to show off the use of recursive function calls. The only problem with this is for every recursive call we dump the result of the previous call back on the functions call stack. For a few recursions this isn’t that bad, but in the case of a Fibonacci sequence it can lead to millions of calls and loads of memory–the most common end result then is too many calls will simply stall or crash the application.

The solution then is to use an iterative approach to solving the sequence.

Recall that the fib sequence is simply the sum of the previous two numbers in the sequence:

1+1=2, 1+2=3, 2+3=5, 3+5=8, 5+8=13, 8+13=21 [...]

For the sake of my implementation, we need to tell the loop how many times to run, and to shift the variables values down by 1 for each loop.

So on the first turn we set x and y to be 1 and 1 respectively. We then add them together, placing the value into a third variable.

We then swap the values of x and y down “1″, with x getting y’s old value and y getting z.

So how can we make this run as fast as possible? The first step is to figure out how fast it currently is. With modern CPU’s being as fast as they are seconds and milliseconds simply won’t do. Thus, we need to look at the finest grain counter an x86 CPU offers: CPU clocks.

To count clocks we’ll implement a CPU clock counting benchmark routine valid on gcc and x86-64 hardware:

The basic idea is we define a number for how many tests to perform, then loop over the code this many times. On each iteration we call our inline rdtsc() routine which is written in assembly. It’s important to note that with modern processors we need to serialize the instruction stream (via CPUID), as well as issue clobbers for the effected registers from the CPUID call. We’ll also measure the overhead of calling CPUID and subtract this from the final result. In the end this routine allow us to get a good feel for how many CPU clocks our code consumed.

Finally, as a general point of interest, context switches present in all modern operating systems can and will effect the clock count of very large functions. Thus, in our case we make sure to only benchmark small sections of code.

With our counting routine ready for action the first thing I wanted to look at was the base performance. Running through the first 8 iterations shows:

Overhead:440 Clocks: 363
Overhead:440 Clocks: 286
Overhead:440 Clocks: 407
Overhead:440 Clocks: 308
Overhead:440 Clocks: 286
Overhead:440 Clocks: 286
Overhead:440 Clocks: 286
Overhead:440 Clocks: 286

In other words, after a cache warm up period we stabilize at 286 cycles.

We’ll then add the -O2 optimization flag to the compiler directives (in NetBeans, open your projects options page and select the C++ Compiler options > Additional Options) and see what we get:

Overhead:429 Clocks: 121
Overhead:429 Clocks: 99
Overhead:429 Clocks: 66
Overhead:429 Clocks: 55
Overhead:429 Clocks: 66
Overhead:429 Clocks: 55
Overhead:429 Clocks: 66
Overhead:429 Clocks: 66

To make sense of this we’ll check out the assembly for each:

First, the unoptimized version:

And the -O2 optimized version:

The first thing that jumps out is the loop counting–whereas in the unoptimized version we count using the 16-bit registers against main memory, the optimized version adds ‘logic’ to the process, using cmpq to check an immediate value from a register (%rax).

This explains some of the speedup, but not all. The get to bottom of why the optimized code is so much smaller (faster) we can take a huge hint from the number of raw instructions, of which the optimized code of course has far fewer.

Part of this is a side-effect of the 64-bit architecture we’re compiling too, as %rdx and %rbx are leaq’d to %rcx to produce code which stores loop values in registers at all times, as opposed to the unoptimized code which continually pushes values to the call stack. This eliminates almost all of the movq’s which certainly helps, but far more importantly, we no longer access main memory.

All that said, it still doesn’t explain everything in terms of raw performance.

The big hint comes from recompiling the application to use only 4 Fibonacci loops. It’s a bit hard to see, so I’ve added an intermediate asm(“nop”) in the loop so it becomes clear:

gcc has unrolled the loop for us. Of course we only have so many registers, so one more loop to make 5 means we lose the unroll, and we’re back to standard loop code.

This is related to another important rule -O2 brings to the mix, which is if we remove the call to save our values in values[n], -O2 literally removes our code from the final assembly file:

Generates:

If however, we add a: cout << y; call after our loop, we generate:

In other words, the secret to the speed-up is in -O2 mode gcc adds just enough code to get the correct result, but nothing more. We’ll see this time and again when using optimizations, gcc stripping away the fat and making intelligent decisions based on your actual code, as opposed to blindly creating assembly that fits the most general scenario.

That said, nothings stopping us from rewriting the code using hand-crafted assembly to match the -O2 version, though with -O2 being 3 characters away, one could ask why bother…though we will anyway in the next post.

In the previous post we wrote a short C++ program that loaded two numbers. Despite its simplicity in C++, we saw how the assembly version was comprised of several dozen individual instructions in a rather cryptic format. Much of this complexity stems from the fact that in our sample program we called a function to perform our addition. Calling functions means dealing with a stack, base pointers, and the setup and maintenance of that stack. It means dealing with memory offsets, relative positions, and several other factors. The good news is that at this point we can safely ignore these details. In fact, we will do well to ignore them and focus on just the core competencies of function implementation code. In other words, we’ll let gcc create the function shells, calls, and stack management, we’ll focus on the core logic.

The general idea is that we want to write assembly that adds two numbers together. There is a direct assembly instruction for doing so, add, and in this post we’ll implement it.

One of the key things to remember about writing assembly is that we’re dealing with very few abstractions. In C++:

Has a very specific meaning, but its true meaning to the machine it runs on is hidden. It’s only after gcc compiles the code that int, t, and 10 mean anything to the processor. In assembly we free ourselves from these abstractions and deal with the very direct process of moving bits around.

Thus, our first step in writing assembly to add two numbers is to realize that the add instruction we’ll be using expects two parameters, neither of which can be memory locations. They can however, be registers. Thus, our first steps in code must be to load two registers with the values we want to add.

To load a value into a register we use the mov instruction, which for us in AT&T syntax takes the form of:

This moves the immediate value (2) into the %rax register. Please keep in mind %rax is a 64-bit register, it would be %eax on 32-bit systems.

We then push our second number:

And finally, call the add instruction, passing in our two registers:

The whole function in extended assembly looks like:

Should we run this in our IDE, we would watch the rax and rcx register’s end up with 0×1 and 0×3, respectively.

Thing is, this is not a very useful construct, as immediate values means we’ve hard coded the return in by default. It’s much more realistic to accept parameters.

To do so, we take advantage of gcc extended syntax like so:

Will output:

While we now have plenty of control over implementation, it’s still a bit heavy on syntax. Thus, we can further optimize by letting gcc have full control over register assignment:

Here we let gcc decide which registers to use, which leads to slightly faster code generation, but we may lose the exacting control we need.

At this point we now have a functioning addition routine. Of course we already know it’s not the most efficient, as we could/should be using lea. This is because while our actual hand-written assembly is shorter, we still need to place values in registers and use the two-step addition instruction.

Doing so allows us to exploit potential performance gains, learn more about our machines, and is in all cases, a fascinating exercise in the lowest level of computer programming.

In this post I want to share a few tips and tricks I’ve learned when using AT&T style syntax on Linux/gcc, and also explain how basic assembly coding works. We’ll start by creating a simple function and checking out the gcc created assembly code. We’ll then take this apart and step through the code to understand how it works.

To start then, the first thing to do is look at what a basic function call looks like to gcc in assembly. The function we’ll use is as simple as it gets:

In Netbeans or your favorite IDE, set a breakpoint @ add(1,2). Now run the code in debugging mode and open the : Window > Debugging > Disassembly mode.

We should see something similar too:

+33 and +38 push our parameters to the esi and edi registers. +43 calls the callq function which will jump us to the function (and also preps the stack). When we single step a few places, the disassembly window will change to that functions code and show:

The code reads as follows: we set up the base pointer and stack in +0 and +1. In +4 and +7 we take the two values placed into the esi and edi registers in the main() function and push them onto the stack relative to the base pointer (rbp). As these are ints, they are 4 bytes ‘apart’.

This is where things get a bit interesting. As we are dealing with x86-64 we have to remember that rax and eax are related, in that eax holds the lower 32 bits of rax’s full value (in x86-64 it’s helpful to note that any register with a Rxx is 64-bit, Exx denotes 32-bit). Thus, you’ll notice that in +16 we’re using two 64-bit registers to perform the addition via lea using rdx (the so-called ‘third’ argument register), and rax.

How did values get into rax and rdx? This is a valid question, as in +10 and +13 we spend cycles pushing our variables into eax and edx (edx is a general purpose register), Why do this when we do not use them anyway?

To understand this, it helps to know that a) this is non-optimized code, and b) there is a very specific method to how parameters should be passed, and reading this helps explain why things work the way they do! (see p. 17). We go into greater detail on this topic in the next post.

At this point we’re ready to perform our addition. However, we do so using lightly optimized assembly code via the lea instruction (Load Effective Address). The assembly we’ll write in the next post will be different, but it’s helpful to understand how this lea call works.

Just as in C++ we can use the address of operator to grab the address of a variable, we use the lea instruction to do the same in assembly.

This bit of code demonstrates:

The output from this program is:

In other words, lea loads the address of m and stores it in g. A quick check of &m shows the values match, as we would expect.

So how does this relate to adding? The purpose of lea is to load memory addresses, and as part of that duty it can calculate offsets. Thus, we exploit this adding behavior by, instead of passing memory values, passing raw values (though still via registers). It will then sum these registers and place the result into a destination register. As this completes in one instruction, we effectively get the addition and move in one cycle–a savings over the mov + add instruction combination. In short, it’s a simple and elegant optimization gcc performs for us.

The following code shows this technique deliberately used:

We could have also exchanged the second parameter “r” with a direct value (2), instead of the mx constraint, which would add 5+2, for example.

Further, as you may suspect, the C++ address of operator (&) makes direct use of lea. Consider:

Which in assembly appears as:

Here we see lea in a more ‘natural’ state, loading the effective address of our variable and stashing it into %rax. It’s important to note that in +112, the -0×28 is an offset, and the parenthesis indicate a memory location.

** It should be said at this point that while we instinctively know that C++ and raw assembly are intertwined, it’s fun and instructive to see how concepts we’ve learned in C++ manifest themselves in assembly. **

With that done we assign the value of the addition to our variable in +19, then call leave and ret to clean up the stacks and return to the calling function (main).

That’s it for now. In the next post we’ll implement our own add function, and instead of throwing assembly code out rapid style, actually explain it in greater detail.

Thing is though, if your a non-techie all this talk of HTML 5 probably makes you say “Wah?” — While  those of us in the development community are left wondering when we’ll get to implement this cool stuff as the giant elephant in the room sits docilely in the corner.

It’s a confusing release really, filled with more promise and hope than tangible benefit–or is it?

As a guy who runs a web software company I thought I’d share my quick thoughts on Safari 5 and provide some links to learn more.

HTML 5

HTML5 AJAX History

This is an interesting one in that it’s a feature in need of a web infrastructure to support it–or at least if I understand the feature correctly. I assume this is a system for storing application state, but I haven’t had much luck finding out for sure. Regardless, it’s interesting to me as someone who wrote a full AJAX based web site that utilizes AJAX history state saving. It was done using a script called Real Simple History, and was as you would expect, a direct answer to the annoyances of losing your save state if the user hit the back, reload, or forward button. It works well enough, but just as with HTML Draggables, would be nice to have built in.

HTML5 forms validation

Sorry, not too informative, but I did find this link which describes more on this topic.

WebSocket

I like to think of this as a extension of the HTTP Request object introduced in IE 5 way back in ‘99. The basic idea is that we can open a direct link to a server on what’s called a Full Duplex channel (e.g. your telephone), which allows simultaneous two-way communication.

http://code.google.com/p/phpwebsocket/

What is this good for? Chat logs I suppose, but it may lead to more advanced types of form validation…

Web workers

I’ve actually covered these guys in another post on this blog, but the basic idea is that web can run concurrent JavaScript code to speed up execution. Now Safari 4 already supported Web Workers, though with a reduced feature-set as compared to FireFox. So the real question is, have they been enhanced in any appreciable way? I’ll have to test the feature set in a future post, but for now, here’s a quick look at performance between FireFox 3.6.3 and Safari 5:

Firefox 3.6.3:

Fibonacci Set 1 Time Taken: 1.16

Safari 5 (initial release)

Fibonacci Set 1 Time Taken: 0.2

Of course this is the horrible inefficient stack smashing way, the optimised iterative version favors FireFox slightly:

Firefox 3.6.3:

Fibonacci Set 1 Time Taken: 1.08

Safari 5:

Fibonacci Set 1 Time Taken: 1.52

HTML5 draggable attribute

This is an interesting one, if for no other reason than here we have another Microsoft originated API from IE 5!

http://html5doctor.com/native-drag-and-drop/

As far as it’s integration into web applications–I think the greatest benefit of a native API to handle drag and drop will be from a performance perspective. Right now in FormBoss, for example, dragging multiple items isn’t as precise as I would like it to be. This is not necessarily a performance problem, but a native method should mean we can sample more efficiently during the drag operation, which should help smooth things out and improve precision.

Their is more to it of course, to which I simply defer to: http://html5doctor.com

Developer Tools and Closing Comments

The last thing I want to look at is the all-important subject of Safari 5 as a developer friendly release.

FireBug simply rules them all–this has been, and most likely will continue to be, the clarion call for all serious web developers. Yet in the recent years it seems as if inline JavaScript debugging is becoming the norm, not the exception. IE8 has a debugger, Chrome, and of course Safari.

Problem is, they’ve always fallen well short of Firebug for one simple reason: FireBug is about more than just debugging, it’s about the DOM too. Without a good way of viewing the DOM a debugger is nearly useless for complex work. To be clear, by DOM I mean the entire DOM starting from the window element, not just the visible page bits from the HTML element on down. FormBoss, like most web applications, makes extensive use of the root DOM object to store objects and arrays.

The strange thing is Safari will gladly show you the window element if you open the Console and type:

…but not from the comfort of the main debugger, or even from a separate DOM tab.

Unfortunately, while the developer tools in Safari 5 seem very slick, they do not address the DOM viewing issue, and they also seem to be a touch unstable. While viewing the property of a paused debugging session the entire browser crashed. I’ve had FireFox get twitchy, but not outright crash.

That said, the tools are slick, as I said. Syntax coloring is very nice to see, as is the clean and intuitive user interface. Now if they could only add a proper DOM inspector!

The Original ‘Command Line’ Code

We perform a couple of distinct steps in this code. First, we open our directory for iteration with:

And then write the contents of the file into a buffer with:

Not too complicated: We use getline() to only get the raw text of a line, to which we then add a \r\n. We do this because part of our task is to recreate proper tags, and it just so happens that so long as we know where our line breaks are, we can do so reliably. Adding our own line break tags means cross-platform differences will be eliminated, plus our p tag code will run exactly as intended.

The remainder of the code removes extra formatting from headline elements, as well as adds p tags in proper order and sequence. Most of this logic, as it turns out, was the same in Qt, though we did have some significant differences in key locations.

The New Code

The new code segment is the result of a fair bit of experimentation. The command line version was in fact easier to create, though only because of the higher availability of resources for performing file opening, string manipulation, and file writing in plain old C++.

Some key points are as follows:

The method used to iterate through a directory:

…feels a bit strange to me, almost as if I’m missing something. Specifically, the while() statement checks for an empty string if no further files are found. This just seems…wrong to me, but I could be mistaken. For the record, examples given in Qt help documentation had a flaw of never returning the last element of a directory. For example, if we had four items, only three would be iterated through. The do { } while() was the only way I found to hit all files.

As similar as the core logic is, here’s where things take a pretty radical departure from the command line version.

In this code we’re using the handy QTextStream on an address of a QFile object to read each line of text, to which we add the \r\n to, just like the command line version.

We also save a chunk of time here by using REGEX enabled replace method to remove unwanted tags from the headline text:

As you may recall in the old code we used a more complex:

The last part, the section where we add our properly closed p tags, is largely untouched, save for using indexOf() instead of find(), as well as using mid() to build our temporary string for editing.

The last step was to write the fixed file back to the file system. In the first version we used the rather succinct ofstream to do the job, The new version used a more complex series of command as:

Of course we may have a more simplistic way of doing this, but I didn’t find one.

Closing Thoughts

The end result of our project is a slick little Qt desktop app that removed the burden of command line operation for its use. However, as nice as this may be for the end-user, as a developer what I was most curious to see was if Qt would stand up to the challenge of being user friendly, powerful, and at the same time, a joy to work with.

Simple answer: It was. Qt is simply brilliant–I’m sold, hooked, and thoroughly excited to learn and do more with this library. It’s all the power and functionality of C++, but wrapped into a cross platform, easy to use deployment platform with powerful tools and solid documentation.

Though of course this is somewhat relative when it comes to porting command line app to a GUI. Our command line app weighed in at 223 lines, Qt: 368. While it was very easy to find examples of file operation for vanilla C++ on the web, it was markedly more difficult for Qt. In fact, as hinted at in the text I’m still quite unsure of the “properness” of this code. It works well enough, but am I missing something?

Do I really need to used a QTextStream to write data, or should I have used the more low-level write() function inherited from QIODevice? This question reminds me of the difference in PHP between using:

verses using:

In short, one simple step vs. a few more obtuse ones. It’s by no means wrong, but I can’t help but wonder…

Of course it should also be said that this program could use more error and sanity checks if it was to ever be released an a commercial app, but in this case, it’s just for pedagogical purposes.

Complete Application Source Download

Being a Qt app you should be able to run this code (build) on any platform Qt supports.
Download cleaner.zip

The goal during this step is to make exclusive use of the Qt frameworks built-in functions and methods for handling these tasks, as the end result must be a cross-platform compatible app.

We’re already getting a valid directory entry from part 2, so the first step in this part is to figure out how we iterate and query files from our base folder.

As setup for this task, in the first app (the command line one) we defined a few globals:

We’ll keep that basic structure, but of course implement them as member private variables. It should be noted that in the new version the ‘base’ directory value comes from our Worker constructor with:

In the worker constructor we then:

Same thing as the original version really, though one thing I had to check on is if using / will be a problem for Windows. *Turns out the answer is no.*

With the setup tasks done notice that in the GUI we have two buttons: The first allows us to select the base folder, the second kicks off the Process Images task. Notice how we do this: in cleaner.enc__cppqt our clicked() SIGNAL of the processButton button is assigned to the processAction slot, which in turn, after creating our Worker instance object, calls cleanImages(). And so we’re getting an images directory via the GUI–so far so good!

This brings us to the next big question question: how do we open and iterate over directories?

Iterator Over Directories

As you may recall the first task of our program is to remove all files with a _bw_ in the name from the /images sub-folder. It looks like we have: QDirIterator and QDir to help us perform this duty, with the possibly of others as well. The former seems to be for general access, the latter for iterating–we want to iterate.

Basic QDirIterator Implementation

Pretty strait forward really. Iterator over the directory, making sure to skip the path items.

This takes care of the iteration, now we need to find and remove files that have the _bw_.

In the old code we used:

I should step back to mention the first step was to get the file name. In the first attempt we relied on a struct returned by dirent to store file info for checking, now we have a nice simple fileName() method to call. I’m not going to lie, the Qt way feels much cleaner than the command line version. dirent was tricky to work with at first without having a debugger, this is no longer an issue in Qt. With that out of the way, what of finding the text “_bw_”?

I suspected, and was proven right, that QString would have some type of find function. Sure enough:

Beautiful! I can’t help but show my gratitude over such an elegant and natural thing. Without any documentation look up I was able to basically guess and implement my search function in one line. Yes std::string had the same thing with .find(), but this was a nice treat regardless.

Right, so now how do we delete files?

In the first version we had to use a separate variable (location) and a member function .c_str() to pass to the delete(char*) call. This is fine, but a touch verbose. It would be nice to encapsulate this a bit more.

Delete File Implementation

It turns out that we can use the same remove() call, though it wants a char*, we’ve got a QString. As was the goal anyway, we want to use native solutions for cross-platform consistency. I did some digging and found QFile. QFile has a member function for removing files: .remove(). Even better though, QDirIterator has a member function filePath() to return the full path to the file (not just file name). Of course I may have missed similar functionality in the first go (such as using QDir), but now we save ourselves the hassle of rebuilding the file path from scratch. The final code is:

Sure it’s about the same length as the original command line code, if not a bit longer, but it feels more intuitive–almost like OO PHP coding. I do not however, like the idea of creating a new QFile for each item to remove, but I’m learning–I’m sure we’ll find a better way in the next few posts.

Final Method Implementation

For the sake of completeness, here’s the final cleanImages() function:

Up next, rewriting the cleanXMLStoryFiles() function.

At the end of this post we’ll have a shell ready for the actual porting process to being. In other words, a GUI that loads, reacts to button presses, and updates status text.

So here’s the code:

main.enc__cppqt

cleaner.enc__cppqt

cleaner.h

worker.enc__cppqt

worker.h

The biggest thing to note about this code is that we’re not using the Qt Designer program to create the UI. It’s all hand coded, done for the sake of learning the core UI model. If you’re learning Qt I suggest you try this as well. Yes the Qt Designer tool is fantastic and yes I’ll use it for most tasks moving forward, but for this project we’ll keep it low-level.

Core Implementation

On the implementation level it’s important to note that we’re using a totally object oriented approach to the UI and logic. Speaking of UI and Logic, note how we’ve split the app in two logical components: cleaner.enc__cppqt which holds the presentation logic, worker.enc__cppqt for the ‘model’.

On a releated note, as the XML logic will almost certainly get parallelized we’ll take special note of how we add and handle additional classes and data structures. From what I can see Qt may want all parallel code in separate classes, so we’ll see. We may end up editing the core functionality of worker.enc__cppqt, or possibly add a workerXML.ccp to the mix.

Also note how our call to: QFileDialog::getExistingDirectory() via: void Cleaner::loadAction() in cleaner.enc__cppqt is how we get the file path to process. In short, we’ve already replaced the command line apps argument with a GUI based equivalent!

To that end notice that as of right now we still have implementation bugs. So for example we create pointer to an instance of Worker on the heap in processAction() but do not call delete() on it. Of course this is wrong, and we’ll fix that in time–for now though the main idea is this code creates the UI which reacts to member functions of the worker class.

Next Steps

That’s it for the core UI code, in part 2 we’ll start porting our base application.

Go To Part 3 –>
Link