Retired Document
Important: OpenGL ES was deprecated in iOS 12. To create high-performance code on GPUs, use the Metal framework instead. See Metal.
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:
#import <OpenGLES/ES3/gl.h>
#import <OpenGLES/ES3/glext.h>
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 DEPTH_COMPONENT24
.
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
The
, OES_depth_texture
, OES_packed_depth_stencil
, OES_texture_float
, OES_texture_half_float
, and EXT_texture_rg
extensions define constants for use in the EXT_sRGB
internalformat
and 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:
The
glTexImage
functions do not supportinternalformat
constants 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
orLUMINANCE_ALPHA
data. Use the correspondingRED
orRG
formats instead.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
internalformat
parameter 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 EXT_texture_storage
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
The
extension defines the OES_mapbuffer
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.
Discarding Framebuffers
The glInvalidateFramebuffer
function in OpenGL ES 3.0 replaces the glDiscardFramebufferEXT
function provided by the
extension. The parameters and behavior of both functions are identical.EXT_discard_framebuffer
Using Multisampling
OpenGL ES 3.0 incorporates all features of the
extension, except for the APPLE_framebuffer_multisample
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:
The
attribute
andvarying
qualifiers are replaced in GLSL ES 3.0 by by the keywordsin
andout
. In a vertex shader, use thein
qualifier for vertex attributes and theout
qualifier for varying outputs. In a fragment shader, use thein
qualifier for varying inputs.GLSL ES 3.0 removes the
gl_FragData
andgl_FragColor
builtin fragment output variables. Instead, you declare your own fragment output variables with theout
qualifier.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
texture
function with either asampler2D
orsamplerCube
parameter (replacing the texture2D and textureCube functions from GLSL ES 1.0).The features added to GLSL ES 1.0 by the
,EXT_shader_texture_lod
, andEXT_shadow_samplers
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.OES_standard_derivatives
The
extension works differently. GLSL ES 3.0 removes theEXT_shader_framebuffer_fetch
gl_FragData
andgl_FragColor
builtin fragment output variables in favor of requiring fragment outputs to be declared in the shader. Correspondingly, thegl_LastFragData
builtin variable is not present in GLSL ES 3.0 fragment shaders. Instead, any fragment output variables you declare with theinout
qualifier 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.
Copyright © 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-06-04