Adopting OpenGL ES 3.0
OpenGL ES 3.0 is a superset of the OpenGL ES 2.0 specification, so adopting it in your app is easy. You can continue to use your OpenGL ES 2.0 code while taking advantage of the higher resource limits available to OpenGL ES 3.0 contexts on compatible devices, and add support for OpenGL ES 3.0–specific features where it makes sense for your app’s design.
Checklist for Adopting OpenGL ES 3.0
To use OpenGL ES 3.0 in your app:
Create an OpenGL ES context (as described in Configuring OpenGL ES Contexts), and specify the API version constant for OpenGL ES 3.0:
EAGLContext *context = [[EAGLContext alloc] initWithAPI:kEAGLRenderingAPIOpenGLES3];
If you plan to make your app available for devices that do not support OpenGL ES 3.0, follow the procedure in Listing 2-1 to fall back to OpenGL ES 2.0 when necessary.
Include or import the OpenGL ES 3.0 API headers in source files that use OpenGL ES 3.0 API:
Update code that uses OpenGL ES 2.0 extensions incorporated into or changed by the OpenGL ES 3.0 specifications, as described in Updating Extension Code below.
(Optional.) You can use the same shader programs in both OpenGL ES 2.0 and 3.0. However, if you choose to port shaders to GLSL ES 3.0 to use new features, see the caveats in Adopting OpenGL ES Shading Language version 3.0.
Test your app on an OpenGL ES 3.0–compatible device to verify that it behaves correctly.
Updating Extension Code
OpenGL ES 3.0 is a superset of the OpenGL ES 2.0 specification, so apps that use only core OpenGL ES 2.0 features can be used in an OpenGL ES 3.0 context without changes. However, some apps also use OpenGL ES 2.0 extensions. The features provided by these extensions are also available in OpenGL ES 3.0, but using them in an OpenGL ES 3.0 context may require at least minor code changes.
Remove Extension Suffixes
The OpenGL ES 2.0 extensions listed below define APIs that are incorporated into the core OpenGL ES 3.0 specification. To use these features in an OpenGL ES 3.0 context, simply remove the extension suffixes from function and constant names. For example, the name of the
glMapBufferRangeEXT function becomes
glMapBufferRange, and the
DEPTH_COMPONENT24_OES constant (used in the
internalformat parameter of the
glRenderbufferStorage function) becomes
Modify Use of Extension APIs
Some features defined by OpenGL ES 2.0 extensions are in the core OpenGL ES 3.0 specification, but with changes to their API definitions. To use these features in an OpenGL ES 3.0 context, make the changes described below.
Working with Texture Formats
extensions define constants for use in the
type parameters of the
glTexImage family of functions. The functionality defined by these extensions is available in the OpenGL ES 3.0 core API, but with some caveats:
glTexImagefunctions do not support
internalformatconstants without explicit sizes. Use explicitly sized constants instead:
// Replace this OpenGL ES 2.0 code:
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, width, height, 0, GL_RGBA, GL_HALF_FLOAT_OES, data);
// With this OpenGL ES 3.0 code:
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA16F, width, height, 0, GL_RGBA, GL_HALF_FLOAT, data);
OpenGL ES 3.0 does not define float or half-float formats for
LUMINANCE_ALPHAdata. Use the corresponding
The vector returned by depth and depth/stencil texture samplers no longer repeats the depth value in its first three components in OpenGL ES 3.0. Use only the first (
.r) component in shader code that samples such textures.
The sRGB format is only valid when used for the
internalformatparameter in OpenGL ES 3.0. Use GL_RGB or GL_RGBA for the format parameter for sRGB textures.
Alternatively, replace calls to
glTexImage functions with calls to the corresponding
glTexStorage functions. Texture storage functions are available in as core API in OpenGL ES 3.0, and through the
extension in OpenGL ES 1.1 and 2.0. These functions offer an additional benefit: using a
glTexStorage function completely specifies an immutable texture object in one call; it performs all consistency checks and memory allocations immediately, guaranteeing that the texture object can never be incomplete due to missing mipmap levels or inconsistent cube map faces.
Mapping Buffer Objects into Client Memory
extension defines the
glMapBuffer function for mapping the entire data storage of a buffer object into client memory. OpenGL ES 3.0 instead defines the
glMapBufferRange function, which provides additional functionality: it allows mapping a subset of a buffer object’s data storage and includes options for asynchronous mapping. The
glMapBufferRange function is also available in OpenGL ES 1.1 and 2.0 contexts through the EXT_map_buffer_range extension.
glInvalidateFramebuffer function in OpenGL ES 3.0 replaces the
glDiscardFramebufferEXT function provided by the
extension. The parameters and behavior of both functions are identical.
OpenGL ES 3.0 incorporates all features of the
extension, except for the
glResolveMultisampleFramebufferAPPLE function. Instead the
glBlitFramebuffer function provides this and other other framebuffer copying options. To resolve a multisampling buffer, set the read and draw framebuffers (as in Using Multisampling to Improve Image Quality) and then use
glBlitFramebuffer to copy the entire read framebuffer into the entire draw framebuffer:
glBlitFramebuffer(0,0,w,h, 0,0,w,h, GL_COLOR_BUFFER_BIT, GL_NEAREST);
Continue Using Most Other Extensions in OpenGL ES 3.0
Several key features of iOS device graphics hardware are not part of the core OpenGL ES 3.0 specification, but remain available as OpenGL ES 3.0 extensions. To use these features, continue to check for extension support using the procedures described in Verifying OpenGL ES Capabilities. (See also the iOS Device Compatibility Reference to determine which features are available on which devices.)
Most code written for OpenGL ES 2.0 extensions that are also present as OpenGL ES 3.0 extensions will work in an OpenGL ES 3.0 context without changes. However, additional caveats apply to extensions which modify the vertex and fragment shader language—for details, see the next section.
Adopting OpenGL ES Shading Language version 3.0
OpenGL ES 3.0 includes a new version of the OpenGL ES Shading Language (GLSL ES). OpenGL ES 3.0 contexts can use shader programs written in either version 1.0 or version 3.0 of GLSL ES, but version 3.0 shaders (marked with a
#version 300 es directive in shader source code) are required to access certain new features, such as uniform blocks, 32-bit integers and additional integer operations.
Some language conventions have changed between GLSL ES version 1.0 and 3.0. These changes make shader source code more portable between OpenGL ES 3.0 and desktop OpenGL ES 3.3 or later, but they also require minor changes to existing shader source code when porting to GLSL ES 3.0:
varyingqualifiers are replaced in GLSL ES 3.0 by by the keywords
out. In a vertex shader, use the
inqualifier for vertex attributes and the
outqualifier for varying outputs. In a fragment shader, use the
inqualifier for varying inputs.
GLSL ES 3.0 removes the
gl_FragColorbuiltin fragment output variables. Instead, you declare your own fragment output variables with the
Texture sampling functions have been renamed in GLSL ES 3.0—all sampler types use the same texture function name. For example, you can use the new
texturefunction with either a
samplerCubeparameter (replacing the texture2D and textureCube functions from GLSL ES 1.0).
The features added to GLSL ES 1.0 by the
extensions are part of the core GLSL ES specification. When porting shaders that use these features to GLSL ES 3.0, use the corresponding GLSL ES 3.0 functions.
extension works differently. GLSL ES 3.0 removes the
gl_FragColorbuiltin fragment output variables in favor of requiring fragment outputs to be declared in the shader. Correspondingly, the
gl_LastFragDatabuiltin variable is not present in GLSL ES 3.0 fragment shaders. Instead, any fragment output variables you declare with the
inoutqualifier contain previous fragment data when the shader runs. For more details, see Fetch Framebuffer Data for Programmable Blending.
For a complete overview of GLSL ES 3.0, see the OpenGL ES Shading Language 3.0 Specification, available from the OpenGL ES API Registry.