'\"macro stdmacro
.if n .pH g3w.olPixConver @(#)olPixConver	40.3 of 1/8/90
.tr ~
.ds oS METRICS
.nr oN 0
.nr X
.if \nX=0 .ds x} ""PIXEL CONVERSION ROUTINES" 3W "\&"
.if \nX=1 .ds x} ""PIXEL CONVERSION ROUTINES" 3W
.if \nX=2 .ds x} ""PIXEL CONVERSION "" "\&"
.if \nX=3 .ds x} ""PIXEL "" "" "\&"
.TH \*(x}
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Xlib.h>
#include <OpenLook.h>
.P
\s-1\f4Screen *OlDefaultScreen;
Display *OlDefaultDisplay;
.P
\s-1\f4Axis axis;
Screen screen;
.P
\s-1\f4OlMMToPixel(axis, millimeters);
Ol_MMToPixel(axis, millimeters);
.P
\s-1\f4OlPointToPixel(axis, points);
Ol_PointToPixel(axis, points);
.P
\s-1\f4OlScreenMMToPixel(axis, millimeters, screen);
Ol_ScreenMMToPixel(axis, millimeters, screen);
.P
\s-1\f4OlScreenPointToPixel(axis, points, screen);
Ol_ScreenPointToPixel(axis, points, screen);
.P
\s-1\f4OlPixelToMM(axis, pixels);
Ol_PixelToMM(axis, pixels);
.P
\s-1\f4OlPixelToPoint(axis, pixels);
Ol_PixelToPoint(axis, pixels);
.P
\s-1\f4OlScreenPixelToPoint(axis, pixels, screen);
Ol_ScreenPixelToPoint(axis, pixels, screen);
.P
\s-1\f4OlScreenPixelToMM(axis, pixels, screen);
Ol_ScreenPixelToMM(axis, pixels, screen);\f1\s+1
.fi
.SH "DESCRIPTION"
All the X-based OPEN LOOK widgets refer to pixels in
coordinates and dimensions
for compatibility with other X~Window System widgets.
However,
this puts the burden on the application programmer to convert
between externally useful measures,
such as points or millimeters,
and pixels as applied to the screen at hand.
These routines examine the data structures that describe the
physical dimensions and the
pixel resolution of a screen and convert among millimeters,
points, and pixels for that screen.
.sp
\f3Which Screen?\f1
.P
The shorter forms of these routines
(the ones without the word
\f4Screen\f1
in their names)
work for the default screen.
This is the screen that is active when the X~Toolkit
Intrinsics are started.
The longer forms of these routines take a
\f4Screen *\f1
type argument that refers to a particular screen.
.P
The macros
\f4OlDefaultScreen\f1
and
\f4OlDefaultDisplay\f1
identify the current screen and display being used by the
Intrinsics.
Although the SYNOPSIS above implies these are variables of type
\f4Screen *\f1
and
\f4Display *\f1,
respectively,
they are really macros that produce values of these types.
.sp
\f3Note:  Use After Toolkit Initialization\f1
.br
These routines make use of data structures that are initialized
when the Toolkit is initialized (see \f3OlInitialize\f1 in
"Mandatory Routines" earlier in this document).  Therefore,
using them before Toolkit initilization (for example, as an
initial value to a statically defined variable) will result
in a \f2run time\f1 error.
.sp
\f3Axis Argument\f1
.P
The first argument of all the routines is the direction in
which the measurement is made.
This is necessary because not all screens have equivalent
resolution in the horizontal and vertical axes.
The
\f4axis\f1
argument can take one of the two values:  \f4OL_HORIZONTAL\f1
or \f4OL_VERTICAL\f1.
These routines are not directly usable in computing a
diagonal measure.  (Find the diagonal with the Pythagorean 
Theorem:  \s-2a\u2\d + b\u2\d = c\u2\d\s+2)
.sp
\f3Implemented as Macros\f1
.P
All these routines are implemented as macros,
so they can take any reasonable type value for the
\f4millimeters\f1,
\f4points\f1,
and
\f4pixels\f1.
The macros cast the values into the proper type needed for the
conversion.
However,
only a single type value can be "returned".
The routines without an underscore in their names produce values of type
\f4int\f1
(the values are rounded to the nearest integer).
The routines with an underscore in their names produce values of type
\f4double\f1 (these values have not been rounded,
leaving it up to the application to round up, round down, or
truncate as needed).
Given the small size of the units involved,
the integer returning routines should be sufficient for many
applications.
.P
Because these routines are implemented as macros,
there are no function addresses available.
