Sunday, May 25, 2008

Eclipse CDT + MinGW + FreeGLUT

Eclipse CDT + MinGW + FreeGLUT

[Note: if this document seems out-of-date to you, you might want to see the updated and related documents in the bottom.]

(May 24, 2008)
Today, I tried to use Eclipse CDT + MinGW + FreeGLUT to study OpenGL to build my skill for current research and future career development.  This note is created to show how I could get everything done and perhaps, it can be useful for other people.

I started with installing MinGW version 3.4.5 on Windows XP service pack 2.  During installation, we need to install only g++ to get C/C++ compiler.  We should not include the MinGW make tool if we want to make things easier when we work with source base derived from the Unix world.  In such a case, we should use MSYS (Minimal SYStem), instead [1].  However, if you want to use Eclipse CDT's make system, you have no need to worry about this.  It is interesting to note that MinGW already contains GL header files right from its package.  This makes thing very simple for those who want to quickly set things up.

Side Note: MSYS is a part of MinGW project and can be downloaded from the same download area of MinGW at Sourceforge.  

Next, I installed Eclipse CDT.  It is worth noting that we can have multiple Eclipse copies in a single machine.  We can even have each copy of Eclipse associated with one task (project or solution).  If we do not have any specific reason to share this Eclipse CDT copy with other tasks, we can just download a new copy to get only Eclipse CDT.  This can reduce complexity and confusion in the tool as well.  The figure below shows Eclipse features I used.  You can see that it is very lean because it contains only relevant features for C/C++ development.


Figure 1: Eclipse CDT features

Now, we are close to the last step: getting FreeGLUT up and running with Eclipse CDT and MinGW.  I suggest you obtain a compiled DLL from 'Temp Variable's Blog' [2].  The compiled package also comes with necessary header files, so we don't need to go else where, including the official FreeGLUT web site.  If you need to build Free Glut from scratch or need another version, please see the 'update' note at the bottom of this page.  Next, we are ready to create an Eclipse project with a very simple OpenGL program.  This is just for testing the software configuration.  To avoid confusion, I break the process down to steps:

1. Create an Eclipse project with MinGW compiler

Figure 2: When we choose to create a C or C++ project, we need to choose a compiler / toolchain we want to use.

2. Once the project is created, we probably see the default list of included files related to MinGW in the Eclipse project view.  Check if its main include folder has GL header files.  If not, we probably did something wrong.

Figure 3: Default MinGW include paths, including GL header files

3. We have to place FreeGLUT header files in an appropriate place.  We may choose to put them in the GL folder shown above, in an Eclipse project folder, or in a shared folder (so that you can have only one FreeGLUT header copy in your system).  If we choose the last choice (I chose this one too), we have to add an include directory containing FreeGLUT header files.  To do this, right click on the project item in Eclipse and select Properties.  Then, add an include directory as shown in Figure 4.

Figure 4: 'Adding include directories' can be done in C/C++ Build -> Settings -> GCC C++ Compiler -> Directories

4. Now, we need to refer to the OpenGL layer in Windows, opengl32.  This OpenGL layer will connect to a video driver in a machine.  We don't need to worry if we change a video card.  Things will be the same as long as the new video card driver supports OpenGL commands we employ.  This OpenGL layer is, in fact, a library used by a linker.  Hence, we need to set up the GCC C++ linker.  It can be done from almost the same spot shown in Figure 4.  Just scroll down from the 'GCC C++ Compiler' option to 'MinGW C++ Linker'.  Then, add two libraries: opengl32 and freeglut.  Of course, if your OpenGL project is more complicated, you probably need to add more libraries. We don't need to specify any library search path for opengl32 since they are in a system folder.  For freeglut, however, we need to specify library search path for it if it is not in a system folder.  Note that Eclipse CDT will not search for any library in its project folder.  We need to explicitly specify it for any non-system library search path.

By the way, it is interesting to note that, even if we are working on Windows 64-bit version, we still use opengl32, NOT opengl64.  This may sound odd, but it makes things easier since programs from a 32-bit world can be run seamlessly on Windows 64-bit version without any recompilation.  And for programmers, they don't need to change OpenGL configuration much; Windows will handle it by connecting to an appropriate video driver.

Figure 5: Adding more libraries to MinGW C++ Linker

5. Create the main file with a very simple usage of OpenGL.  Once again, I suggest you use the same example as in 'Temp Variable's Blog'.  The file seems to be in a book by E. Angel, Interactive Computer Graphics, A Top-Down Approach with OpenGL, Third Edition, Addison-Wesley Longman, 2003 [3].  The direct link to the file is http://www.box.net/shared/u2o7k31ogc

6. Build a project (press Ctrl + B or click the hammer button).

7. Try running your application.  You may find that there is nothing happens.  Your program just terminated.  When you try to debug it, you will see only an error message that "there is an error occurred", but no other clue.  This problem arises from a missing DLL.  It is important to know that the executable file we get will not try to search for libraries specified in the Eclipse settings.  Thus, we need to put the DLL in the executable folder  (or in a system one if you prefer).  Make sure that you have DLL copies in both Debug and Release folders.  Anyway, if you encounter 'silent errors' like this in Eclipse CDT, I recommend you run an executable file from the Windows command prompt; Windows may give you more information than Eclipse CDT.

Note: if you are new to Eclipse CDT, you may wonder how to run a program in a Debug or Release mode as you wish.  From the beginning, it will run solely in a Debug mode, even when you set the active configuration to Release.  To change the default running mode, you have to do it in the 'Run Dialog'.  It can be found from the menu bar on the top of Eclipse as shown in Figure 6.  When you go there, you may find two configurations you can choose, but still have no idea which one is Release (I had this problem before).  You can differentiate it by its location.  From the main tab, you can see a project name and 'C/C++ Application'.  The latter will tell you about an application location as shown in Figure 7.  Notice the release folder name before an executable file name.


Figure 6: 'Run Dialog' can be accessed from the menu bar.  Note: click on the arrow beside the green Run button, not the Run button itself.
Figure 7: Main tap in the 'Run Dialog' can show us the location of an executable.  We can use the location to figure out what mode it is in

References:

1. Eclipse CDT: Before You Begin, http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.cdt.doc.user/concepts/cdt_c_before_you_begin.htm
2. Temp Variable's Blog: Installing freeglut on Visual Studio 2008, http://tempvariable.blogspot.com/2008/02/installing-freeglut-on-visual-studio.html
3. E. Angel, Interactive Computer Graphics, A Top-Down Approach with OpenGL, Third Edition, Addison-Wesley Longman, 2003. (a portion of source code in the book is obtained from http://www.box.net/shared/u2o7k31ogc)


Pinyo Taeprasartsit
(May 2008, May 2010, Oct 2011)

This document can be viewed at my blog and my Google docs.  Questions, comments, and suggestions are welcomed.  Please leave a message in my blog if you have any.  Thank you.

=======

Update: [May 2010] I now have a few other documents that closely related to this one.  They discuss how to compile FreeGlut for both 32 and 64-bit applications and using more recent versions of MinGW, including the 64-bit version.  Check them out if you are interested:
  1. Eclipse CDT with MinGW x64.  If you want to use MinGW 64-bit with Eclipse, this is a document for you.
  2. Build FreeGlut 2.6.0 with MinGW in both 32 and 64 bit.  Pre-compiled binary packages are also available.  This package is newer than the one discussed in this document and come with both static and dynamic library.  Very handy if you need one.  
  3. Eclipse CDT + MinGW + FreeGlut (2).  This adds information about 64-bit version of MinGW and FreeGlut.  It shows you how to use both static and dynamic library versions of FreeGlut.  Also, if you need to easily download MinGW 4.5.0 32-bit without bothering with wget and bash as mentioned in MinGW web site.  The package provided in this document will help you with that.  This should be helpful until MinGW comes with a more polished installer.

This document can be viewed at my blog and my Google docs.  Questions, comments, and suggestions are welcomed.  Please leave a message in my blog if you have any.  Thank you.

Sunday, May 18, 2008

Enable mouse scrolling in Ubuntu 8.04 on VMWare 6.0.3

(May 18, 2008)

Last night, I installed Ubuntu 8.04 on VMWare 6.0.3 and mouse scroll did not work, even after VMWare tools were installed. My friend, P' Moo+, told me to update Ubuntu, install VMWare and do some X config. I am, however, too lazy to revert my VM to previous snapshot, so I searched Internet for a solution.

I found a topic "How To Enable Mouse Wheel Scrolling in Ubuntu 8.04 on VMware" on http://www.windowsvistaplace.com/how-to-enable-mouse-wheel-scrolling-in-ubuntu-804-on-vmware/othersoftware
This solution does help (my host machine is Windows XP, the author's is Mac OS X). In short, I have to replace

Section "InputDevice"
Identifier "Configured Mouse"
Driver "vmmouse"
[.. blah blah blah ..]
EndSection

with

Section "InputDevice"
Identifier "Configured Mouse"
Driver "vmmouse"
Option "CorePointer"
Option "Device" "/dev/input/mice"
Option "Protocol" "ImPS/2"
Option "Buttons" "5"
Option "ZAxisMapping" "4 5"
EndSection

Many thanks to 'computerboom' (the author of the article I found).