This is a copy of the Java documentation for libGDX. It is not finished being ported.
What are (Open) GL and GL ES?
Whenever libGDX is talking about GL20 or GL30, it is in fact referring to OpenGL ES 2.0 and OpenGL ES 3.0. OpenGL ES is an API for rendering 2D and 3D computer graphics. Other popular graphics APIs are for example Direct3D, Metal or Vulcan. OpenGL ES exists in different versions (1.0, 1.1, 2.0, 3.0, 3.1, 3.2) which offer different functionality. It can be seen as a subset of OpenGL (which itself is a graphics API) and is designed for embedded systems (hence the name OpenGL ES), in particular smartphones.
By default, libGDX is relying on version 2.0 of OpenGL ES, but it can be configured to use 3.0 as well. The LWJGL 3 backend also supports GL ES 3.1 and 3.2. To use a specific OpenGL ES version, it has to be enabled in the application configuration. For the LWJGL 3 backend, this works as follows:
Lwjgl3ApplicationConfiguration cfg = new Lwjgl3ApplicationConfiguration();
// ...
cfg.setOpenGLEmulation(GLEmulation.GL30, 3, 2); // use GL 3.0 (emulated by OpenGL 3.2)
Platform specificities
Desktop (Windows, Mac, Linux)
On Desktop, libGDX is mapping all its graphics calls to OpenGL. In other words, while the GL20 object offers methods from the OpenGL ES 2.0 specification, on desktop those API calls are handed over to OpenGL. As OpenGL ES is inspired by and a subset of OpenGL, its versions are roughly equal to a version of the OpenGL API.
GL ES 2.0 is roughly based on Open GL 2.0, however, there are some incompatibilities that weren’t resolved until Open GL 4.1. To mimic GL ES 2.0, libGDX does not request any specific OpenGL version, so the driver will be more forgiving.
GL ES 3.0 is the successor of OpenGL ES 2.0. On desktop, OpenGL 4.3 provides full compatibility with OpenGL ES 3.0. For mimicking GL ES 3.0 on desktop, one can specify the exact OpenGL version, that should be used. Please note that macOS only has core profiles for OpenGL 3.2+ and the maximum supported version is 4.1.
GL ES 3.1 & 3.2 have done a lot of work to bring the API’s functionality significantly closer to it’s desktop counterpart. OpenGL 4.5 should be able to fully emulate GL ES 3.1.
Android
On Android Open GL ES 2.0 and 3.0 can be used. To prevent your application from being shown to unsupported devices in the Play Store, add one of the following lines to your Android Manifest:
- OpenGL ES 2:
<uses-feature android:glEsVersion="0x00020000" android:required="true" /> - OpenGL ES 3:
<uses-feature android:glEsVersion="0x00030000" android:required="true" />
iOS
Please note that support for OpenGL ES 3.0 is experimental on iOS.
Web
On Web, the graphic stuff is handled by WebGL. Since 1.12.0, libGDX supports WebGL 2, which is the equivalent of GL ES 3.0. It can be enabled via GwtApplicationConfiguration#useGL30.
And what about GLSL (ES)?
GLSL (or GLSL ES for mobile and web) is the language used for shaders. Its versioning has evolved alongside specific versions of the OpenGL API and is somewhat confusing:
GLSL - click to expand
| Open GL Version | GLSL Version |
|---|---|
| 2.0 | 110 |
| 2.1 | 120 |
| 3.0 | 130 |
| 3.1 | 140 |
| 3.2 | 150 |
| 3.3 | 330 |
| 4.0 | 400 |
| 4.1 | 410 |
| 4.2 | 420 |
| 4.3 | 430 |
| 4.4 | 440 |
| 4.5 | 450 |
| 4.6 | 460 |
For some advice on porting shaders from version 120 to 330+, see here.
GLSL ES - click to expand
| OpenGL ES Version | GLSL EL Version | Based on GLSL Version (OpenGL) |
|---|---|---|
| 2.0 | 100 | 120 (2.1) |
| 3.0 | 300 es | 330 (3.3) |
Precision modifiers
GLSL ES requires the specification of precision modifiers for attributes, uniforms and locals. GLSL (which is used on desktop) does not support this. You will have to guard against that in your fragment shader with something similar to this code snippet:
#ifdef GL_ES
#define LOW lowp
#define MED mediump
#define HIGH highp
precision mediump float;
#else
#define MED
#define LOW
#define HIGH
#endif
This will define the LOWP, MED, and HIGH macros to equivalent OpenGL ES precision modifiers and sets the default precision for float to medium. This will only happen on platforms actually running OpenGL ES, on the desktop, the macros are defined to be empty.
OpenGL ES 2.0 Documentation
- OpenGL ES 2.0 Reference Pages
- OpenGL ES 2.0 Reference Card
- OpenGL ES 2.0 Specification
- OpenGL ES Programming Guide for iOS: the core concepts are valid for other platforms as well
- OpenGL ES 2.0 Pipeline Structure