
Using the Cairo Graphics library on OS/2
========================================


About the package
-----------------

This package contains the binary distribution of the Cairo Graphics libary
for OS/2, and the header files needed to be able to use it.

It also has some test applications to show you how to use it, how to start.


IMPORTANT
---------

There is a bug in the OS/2 Presentation Manager, that some Win* API calls
change the FPU Control Word, and forget to restore it.
This usually results in crashes (exception code is 0097) in the application 
code which uses floating point numbers.

The solution is to restore the FPU Control Word after the problematic Win*
calls, and only then use the Cairo API (with floating point numbers)!

The example applications in this package use this workaround, search for
DisableFPUException() function!

See the following threads for more information about the problem:
https://bugzilla.mozilla.org/show_bug.cgi?id=224487
https://bugzilla.mozilla.org/show_bug.cgi?id=280813


The required compiler
---------------------

In theory, every kind of compiler can be used to compile the examples, however
the best is if you have OpenWatcom installed, because the makefiles here are 
for OpenWatcom.


Compiling the test applications
-------------------------------

To compile the test applications, do the followings:

1, Change into the 'TestApps' directory!
2, Run 'wmake' in there mutiple times, this way:

   wmake -f makefile.clock
   wmake -f makefile.font
   etc...

3, Now you should have the executables. Copy cairo*.dll next to them, also
   copy libc06.dll there if it's not on your libpath (libc06.dll is needed
   by the Cairo DLL because it was compiled with gcc) and run them!


About the test applications
---------------------------

Currently there are five test applications, and they do the following:

clock.exe:
  This application shows a clock in a window, showing the current time.
  If it's run without any parameters, then it works in 'jumping' mode.
  If it's started with more than one parameters (the content of the parameters
  are not important), then it works in 'analogue' mode.
  The difference is how the minute and hour markers move.

font.exe:
  This application shows some text in a window, while some lines are moving
  in front of them.
  It is mainly for testing FontConfig, which has to check your system for the
  first time it runs, and scan for the available fonts. It should show a
  dialog window about it, and should create some files in \PSFONTS, and in
  your home folder (or in %ETC% if you have no %HOME% defined).

operators.exe:
  Shows the effect of some of the operators.

patterns.exe:
  Shows some of the drawing patterns that can be used.

transforms.exe:
  Shows how to use transformations.


Cairo documentation
-------------------

The OS/2 specific functions and their documentation is in the cairo-os2.h
file, please check that for further details.

The Cairo API documentation is available with the Cairo source code package,
in the doc\public\html\index.html file!


Problems, suggestions, wishes
-----------------------------

If you have any problems/suggestions/wishes about Cairo, please contact the
original Cairo authors (http://www.cairographics.org).

However, if your problem/suggestion/wish is *strictly* about the OS/2 port,
you can contact me here:

Doodle <doodle@netlabs.org>
