Notes on OpenGL with Mercury Grades

Although Saffron does not require a specific grade beyond one of the C grades, some consideration should be given to which grades to use.

Low-level Parallel Grades

For obscure reasons, Mercury's low-level parallelism grades (any grade with .par that is not hlc or hl) will not function with OpenGL. This problem occurs regardless of your OpenGL driver and client library, and regardless of your platform. If your compiler builds using one of these grades as a default (you can test with mmc --output-grade-string to see the default grade), you must set the grade to build with using the GRADE make variable, as so: make GRADE=asm_fast.gc.stseg, or make GRADE=hlc.gc.spf.par, etc

Single-precision Float Grades

Graphics performance will usually be slightly faster if you use a .spf grade for your programs. This allows Saffron to send less data (half as many bytes per float value), and on 32-bit platforms (especially Windows) we can use the unboxed Mercury float arrays for OpenGL buffers. Saffron should still work with or without .spf grades, and care has been taken to use the OpenGL functions that correspond to the native Mercury float size, in an effort to reduce single/double conversions regardless of the grade.

Preparing for a build

Regardless of the platform, you will need:

• OpenGL development libraries and headers, at least gl.h (glext.h required on some platforms)
• Mercury, at least version 20.1 (most ROTDs from 2019 onwards should work)

To prepare to build tests and demos (not necessary for the base library, but a good idea), run: git submodule init && git submodule update Saffron also requires make to build, the exact type of make depends on the platform. Usually GNU or BSD make will work, however the situation is slightly more complicated on Windows (including Cygwin). Note that you can only build using the Cygwin instructions if Mercury has been configured to use a Cygwin C compiler, and you can only build using the Windows instructions if Mercury has been configured to use the MSVC compiler.

Unix (Linux, BSD, etc)

On Unix, the requirements for building are:

• GNU or BSD make
• Mercury, at least verison 20.1 (most ROTDs from 2019 onwards should work)
• OpenGL development libraries and at least gl.h and glext.h headers
• X11 and GLX development libraries and headers

To build the base library, just use make. You can control parallelism, as so: make PARALLEL=8 -j2, where the PARALLEL flag indicates the Mercury parallel jobs and the -j flag indicates the Make parallel jobs. Since most of the Mercury libraries can't be parallelized due to dependencies, it's recommended to set PARALLEL equal to your number of cores and do -j of 2 or 4. To build and run the base demo, do: make demos && sh demo/saffron_cube_demo.sh

Cygwin

For Cygwin, the requirements for building are:

• GNU make
• Mercury, at least verison 20.1 (most ROTDs from 2019 onwards should work), configured to use the Cygwin C compiler
• OpenGL development libraries, and at least the gl.h header
• Win32 API development libraries and headers

To build the base library, use make -f makefile.cyg. On Windows, the Mercury parallelism flag (PARALLEL=) will not do anything, although it should still be safe to use the make -j flag. To build and run the base demo, do: make -f makefile.cyg demos && sh demo/saffron_cube_demo.sh These instruction should also work with MSYS, but have not been tested with it.

Windows

NOTE THAT THESE INSTRUCTIONS ARE STILL CONSIDERED EXPERIMENTAL!

For Windows (using MSVC), the requirements for building are:

• Microsoft NMake (Sometimes included in the Visual Studio installation, available in the Windows SDK)
• MSVC C++ 2015 or later (same requirement as needed to build the Mercury compiler)
• Mercury, at least verison 20.1 (most ROTDs from 2019 onwards should work), configured to use the MSVC compiler and not compiled with --with-msvcrt

To build the base library, use nmake /fnmakefile from a Visual Studio build command prompt. If you really want build parallelism, Qt's JOM make program should also work, however a relatively new version is required (older versions had broken MAKEDIR variables). To build and run the base demo, do: nmake /fnmakefile demos && demo\saffron_cube_demo.exe