Torque/Code/MSLU
From TDN
Contents |
Using the Microsoft Unicode Layer for Windows 98 and Windows ME
Introduction
Microsoft did not include Unicode support in Windows 95, Windows 98, and Windows ME. If you want your application to support Unicode on these platforms you need to compile it in a special way. This article walks you through the basic concepts of getting your version of the Torque Game Engine to compile with Unicode support for Windows 9X and Windows ME. Please note that as of TGE 1.4.2 this support is built-in right out of the box and you should only need to refer to this article if you are adding new libraries to your project. This article is also intended to help those who want to add Unicode support for these platforms for an older codebase.
What is the Microsoft Unicode Layer?
Microsoft Unicode Layer (MSLU) is a translation layer that provides a complete set of Unicode APIs on Windows Me/98/95. With this, an application can enjoy Unicode language support and eliminate the code page special-casing needed with ANSI applications. When an application calls a supported API, the Microsoft Layer for Unicode converts all strings to ANSI, calls the ANSI version of the API, and then converts all returned strings back into Unicode.
What this pratically boils down to is a library that you will link your application against and a dll that you must include in your executable directory. The library with an installation of Visual Studio 2003 or Visual Studio 2005 Professional. If you are using Visual C++ 2005 Express you will need to download and install the Platform SDK and configure Visual C++ to point to it in its Include and Library directories.
You can download the MSLU dll from here.
Learning more about MSLU from Microsoft
You can read more about the MSLU on Microsoft's website on the Official MSLU page.
The information on this page is decent but the best tutorial for understanding the MSLU can be found in this MSDN Magazine article.
I will be pulling excerpts from this article to use below because it does an excellent job of explaining how the MSLU works.
How the MSLU works
The MSLU takes advantage of how your linker works. The linker will attempt to resolve each function reference by working from left to right through the list of libraries you have in your linking list. The MSLU library provides a match to every function that uses Unicode in the other library files (such as kernel32.lib and gdi32.lib). By putting it first in the list of linked libraries you will force the linker to resolve those functions through the MSLU Library instead of using the references in the other libraries.
With these references being linked through the MSLU they will then call on their corresponding implementations in the unicows.dll. On an NT based Microsoft platform (Windows NT 4.0, Windows 2000, Window XP, Embedded XP, etc.) these implementations act as a straight pass through to the platform. On the non-NT based platforms (Windows 95, Windows 98, and Windows ME) it will instead convert all of the strings passed in into a non-Unicode form, call the non-Unicode implementations of the functions with these converted strings, and then convert back all of the returned strings into Unicode. This is a very thin layer and it performs quite well.
The key to all of this is making sure that the linker resolves all of the Unicode functions through the MSLU instead of through the other libraries.
How to link the MSLU in properly
The first step is to make sure that the platform libraries is not going to get resolved first. To do this go into your Project Properties and drill down into Linker->Input->Ignore Specific Library and add:
kernel32.lib;advapi32.lib;user32.lib;gdi32.lib;shell32.lib;comdlg32.lib;version.lib;mpr.lib;rasapi32.lib;winmm.lib;winspool.lib;vfw32.lib;secur32.lib;oleacc.lib;oledlg.lib;sensapi.lib;imm32.lib;wsock32.lib;LIBC;LIBCD;LIBCMT
This will ensure that these libraries aren't linked into your application before the libraries in the Additional Dependencies setting.
The next thing you need to do is to add Unicows.lib as the first library in the list in Additional Dependencies. This is what will allow the linker to resolve the Unicode functions through the MSLU. This list of ignored libraries should cover most of the Unicode functions that you could call from your application. However, if you do end up needing to add another library from the Platform SDK or from the system libraries that comes with Visual Studio it is a good idea to include them in this list in case they attempt to use another of the Unicode functions indirectly.
The last thing you need to do is to then add all of the ignored libraries above to the Additional Dependencies after Unicows.lib so that the linker can then resolve the non-Unicode functions
that the MSLU did not need to cover (such as the non-Unicode functionality in gdi32.lib). This means that for most Torque games your Additional Dependencies should look like:
unicows.lib kernel32.lib advapi32.lib user32.lib gdi32.lib shell32.lib comdlg32.lib version.lib mpr.lib rasapi32.lib winmm.lib winspool.lib vfw32.lib secur32.lib oleacc.lib oledlg.lib sensapi.lib wsock32.lib imm32.lib ljpeg_DEBUG.lib lpng_DEBUG.lib lungif_DEBUG.lib zlib_DEBUG.lib ogg_static.lib theora_static.lib vorbis_static.lib
Conclusion
Adding Unicode support for Windows 98 and Windows ME via the Microsoft Unicode Layer is a fairly straight-forward process.
The key things to look out for are:
- Make sure Unicows.lib is the first library in Additional Dependencies
- Make sure any system libraries you are using (and that they use) are listed under Ignore Specific Library
- Make sure that you include unicows.dll in the same folder as your executable. It will not find it in the system32 directory.
Categories: TGE | Code
