Home

Quick tutorial on using Regal with Emscripten

Foreword: This is based on the very limited experience of myself as a user of this library. I'm not claiming anything below to be expert knowledge.

Why

Regal adds support for older OpenGL functions that aren't natively supported by Emscripten even with -s LEGACY_GL_EMULATION=1.

Include Regal header before OpenGL

First add to your source code something like:

#ifdef __EMSCRIPTEN__
#include <GL/Regal.h>     # Add this before OpenGL includes.
#include <GL/RegalGLU.h>  # Optional.
#include <emscripten.h>   # This you should already have.
#endif

#include <GL/glu.h>  # Your existing OpenGL include should come after Regal.

Compile your project

I'm assuming here that you're running a Linux shell with basic libraries.

Alternative 1: Using packaged release

Then after activating Emscripten, compile:

$ em++ src/*.cpp -lSDL -s USE_REGAL=1

Note here that we added -s USE_REGAL=1. That flag is incompatible with -s LEGACY_GL_EMULATION=1.

Alternative 2: Compile Regal manually

For Ubuntu the dependencies (including Emscripten dependencies) may be like:

$ apt update && apt install -y \
    build-essential \
    curl \
    libglu1-mesa-dev \
    libsdl1.2-dev \
    libxi-dev \
    libxmu-dev \
    python \
    nodejs \
    cmake \
    default-jre

Then compile Regal:

$ mkdir /opt/regal
$ cd $_
$ curl -L https://github.com/emscripten-ports/regal/tarball/master | tar xz --strip-components=1
$ make -f Makefile.regal
$ make -f Makefile.glu

Note: You may also try to compile using emmake make ... which might change some behaviors in Makefile.regal.

Then after activating Emscripten, compile:

$ em++ src/*.cpp -lSDL -I/opt/regal/include -L/opt/regal/lib/linux -lRegal -lRegalGLU -s ERROR_ON_UNDEFINED_SYMBOLS=0

Note here that we added -s ERROR_ON_UNDEFINED_SYMBOLS=0 to fix linking issues like https://github.com/p3/regal/issues/160.