This note collects a bunch of portability issues that I've found in
ensuring that GLUT example source code is truly portable. I encourage
contributors to the GLUT source code distribution to review these
guidelines:

o Avoid variables, routines, or structure elements named "new" or
"delete" to avoid these C++ keywords.

o Avoid the "near" and "far" keywords introduced by Intel. Instead
try using "nnear" and "ffar" since these are common names in
graphics programming.

o Do not assume the defines M_PI. Instead, after including
, say the following:

-----------------------------------------------------------------------
/* Some files do not define M_PI... */
#ifndef M_PI
#define M_PI 3.14159265358979323846
#endif
-----------------------------------------------------------------------

o If you use the GLU tessellator, when you define or declare
callback functions, use the "CALLBACK" calling convention
identifier. This is required for the callbacks to work correctly
under Win32. After including , say the following:

-----------------------------------------------------------------------
/* Win32 calling conventions. */
#ifndef CALLBACK
#define CALLBACK
#endif
-----------------------------------------------------------------------

Then using a GLU tessellator begin callback as an example say:

-----------------------------------------------------------------------
static void CALLBACK
begin(GLenum type, void *polyData)
{
glBegin(type);
}
-----------------------------------------------------------------------

When registering the callback, say:

gluTessCallback(tess, GLU_TESS_BEGIN_DATA, (void (CALLBACK*)()) &begin);

o Avoid the floating point trig and exponential functions such as
"sinf", "cosf", "expf", etc. These functions are reserved by ANSI
C but not mandated. Instead use the double precision mandated
functions "sin", "cos", "exp", etc. Some systems also support
"fcos", "fsin", etc; definitely avoid these.

o Do not use the EXIT_FAILURE and EXIT_SUCCESS constants defined by
ANSI C. Some old systems do not define these in stdlib.h but are
otherwise ANSI C compliant. Instead use "exit(1);" for failure
and "exit(0);" for success.

o Use "rand" to generate random number. Do not use "random" or "drand48"
since they are not supported under Win32.

o Avoid using "gettimeofday" or other system dependent routines to
determine a timestamp. Instead use

timestamp = glutGet(GLUT_ELAPSED_TIME);

o If you need to read a directory, check out the "win32_direct.h"
file used in progs/demos/walker/walker.c

o Try to avoid including since it is not in Win32.

o If your program runs in single buffered mode, be sure to call
glFlush() at the end of your display callback. Some OpenGL
implementations need a glFlush for pending graphics commands
to fully execute. Note that glutSwapBuffers performs an
implicit glFlush operation.

o Avoid using strdup because strdup is not an actual ANSI C or
POSIX required routine. Indeed, OpenVMS does not support it.
And standard Linux libc only advertises strdup in string.h
if BSD or SVID routines are requested. Instead, directly include
the routine below:

-----------------------------------------------------------------------
static char *
stralloc(const char *string)
{
char *copy;

copy = malloc(strlen(string) + 1);
if (copy == NULL)
return NULL;
strcpy(copy, string);
return copy;
}
-----------------------------------------------------------------------

o Do not #include ; some platforms like IBM's AIX do not
have a getopt.h header file. Instead, you can portabily rely on
getopt() to be declared in on Unix machines. Still,
Win32 does not have a builtin getopt.

o IBM's AIX defines "quad" to be a 64-bit type in .
Avoid using quad as a variable name.

o HP's HP-UX 10.20 may have a type or otherwise define "time".
Avoid using time as a variable name. XXX GLUT doesn't do this
well currently.

o GLU 1.2 introduced the types GLUquadric, GLUnurbs, and
GLUtesselator as aliases for the older GLUquadricObj, GLUnurbsObj,
and GLUtesselatorObj type names. Avoid the newer type names; use
the older names with the "Obj" suffix since all versions of GLU
support the Obj-suffixed types. (Note: yes, the GLU API has
GLUtesselatorObj is spelled incorrectly - tessellator should have
two l's.)

o Do not include to get the standard C malloc/free
routines. Instead, include . FreeBSD and probably
other systems lack a .

o Linux systems prototype a function called "idle" in .
This can result in an error in GLUT programs that name their
idle callback "idle" and include . Do no use a function
named idle if you include .

o The SunOS 5.6 version of requires that also
be included because the assert() macro uses stderr. Be sure to
include along with everywhere to avoid
build errors on SunOS 5.6.

- Mark Kilgard
October 17, 1998