EAGLContext Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/OpenGLES.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
EAGL.h
EAGLDrawable.h
Related sample code

Overview

An EAGLContext object manages an OpenGL ES rendering context—the state information, commands, and resources needed to draw using OpenGL ES. To execute OpenGL ES commands, you need a current rendering context.

Drawing resources, such as textures and renderbuffers, are managed for the EAGLContext object by an EAGLSharegroup object associated with the context. When you initialize a new EAGLContext object, you can choose to have it create a new sharegroup, or you can use one obtained from a previously created context.

Before drawing to a context, you must bind a complete framebuffer object to the context. For more information on configuring rendering contexts, see OpenGL ES Programming Guide for iOS.

Tasks

Creating Contexts

Setting the Current Context

Attaching Storage to a Renderbuffer

Displaying a Renderbuffer

Getting Context Information

Enabling OpenGL ES Multithreading

Properties

API

The OpenGL ES rendering API version supported by the context. (read-only)

@property(readonly) EAGLRenderingAPI API
Availability
  • Available in iOS 2.0 and later.
Declared In
EAGL.h

debugLabel

A label describing the context for use in debugging.

@property(copy, nonatomic) NSString *debugLabel
Discussion

Use this property to provide a meaningful name for a context. This label, which appears in the Xcode OpenGL ES Frame Debugger interface, makes it easy for you to more easily keep track of different contexts when debugging a multicontext app.

Availability
  • Available in iOS 6.0 and later.
Declared In
EAGL.h

multiThreaded

A Boolean value that determines whether OpenGL ES defers work to another thread.

@property(getter=isMultiThreaded, nonatomic) BOOL multiThreaded
Discussion

Set the value of this property to YES to enable multithreading in OpenGL ES. A multithreaded OpenGL ES context automatically creates a worker thread and transfers some of its calculations to that thread. When you enable multithreading on a multicore device, internal OpenGL ES calculations performed on the CPU act in parallel with your app, improving performance.

When the value of this property is NO (the default), OpenGL ES performs any CPU-based calculations for a command on the thread it was called from.

If the current device does not support multithreaded OpenGL ES, the value of this property is always NO—attempting to set the value to YES has no effect.

Availability
  • Available in iOS 7.1 and later.
Declared In
EAGL.h

sharegroup

The context’s sharegroup object. (read-only)

@property(readonly) EAGLSharegroup *sharegroup
Discussion

Retrieve the sharegroup of a context when you want to create two or more contexts that share rendering resources. Call initWithAPI: to initialize the first context, retrieve its sharegroup, and then initialize additional contexts by calling initWithAPI:sharegroup:, passing this sharegroup as the parameter.

Availability
  • Available in iOS 2.0 and later.
Declared In
EAGL.h

Class Methods

currentContext

Returns the current rendering context for the calling thread.

+ (EAGLContext *)currentContext
Return Value

The current context for the calling thread.

Availability
  • Available in iOS 2.0 and later.
Declared In
EAGL.h

setCurrentContext:

Makes the specified context the current rendering context for the calling thread.

+ (BOOL)setCurrentContext:(EAGLContext *)context
Parameters
context

The rendering context that you want to make current.

Return Value

YES if successful; otherwise, NO. If an error occurred, the rendering context for the current thread remains unchanged.

Discussion

A context encapsulates all OpenGL ES state for a single thread in your app. When you call any OpenGL ES API function, OpenGL ES evaluates it with respect to the calling thread’s current context. Because OpenGL ES functions require a current context, you must use this method to select a context for the current thread before calling any OpenGL ES function. Unless otherwise specified, OpenGL ES commands calls made in the same context complete in the order they are called.

OpenGL ES retains the context when it is made current, and it releases the previous context. Calling this method with a nil parameter releases the current context and leaves OpenGL ES unbound to any drawing context.

You should avoid making the same context current on multiple threads. OpenGL ES provides no thread safety, so if you want to use the same context on multiple threads, you must employ some form of thread synchronization to prevent simultaneous access to the same context from multiple threads.

Availability
  • Available in iOS 2.0 and later.
Declared In
EAGL.h

Instance Methods

initWithAPI:

Initializes and returns a newly allocated rendering context with the specified version of the OpenGL ES rendering API.

- (id)initWithAPI:(EAGLRenderingAPI)api
Parameters
api

The desired version of the OpenGL ES rendering API. For legal values, see “OpenGL ES Versions.”

Return Value

An initialized context object, or nil if the object couldn't be created.

Discussion

To issue OpenGL ES commands to this context, you must first make the context current by calling setCurrentContext:.

Calling initWithAPI: creates a new EAGLSharegroup object and attaches it to this context.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
EAGL.h

initWithAPI:sharegroup:

Initializes and returns a newly allocated rendering context with the specified version of OpenGL ES rendering API and the specified sharegroup.

- (id)initWithAPI:(EAGLRenderingAPI)api sharegroup:(EAGLSharegroup *)sharegroup
Parameters
api

The desired version of the OpenGL ES rendering API. For legal values, see “OpenGL ES Versions.”

sharegroup

A sharegroup obtained from another EAGLContext object.

Return Value

An initialized context object, or nil if the object couldn't be created.

Discussion

To issue OpenGL ES commands to this context, you must first make it the current drawing context by calling setCurrentContext:.

OpenGL ES objects such as textures, renderbuffers, framebuffers and vertex buffers are shared across all contexts that are created with the same sharegroup. To specify that a new context should be initialized in an existing sharegroup, retrieve the sharegroup property from a previously initialized context and pass it as a parameter to this initialization method. Pass nil as the sharegroup parameter to create a new EAGLSharegroup object attached to the context.

Availability
  • Available in iOS 2.0 and later.
Declared In
EAGL.h

presentRenderbuffer:

Displays a renderbuffer’s contents on screen.

- (BOOL)presentRenderbuffer:(NSUInteger)target
Parameters
target

The OpenGL ES binding point for a currently bound renderbuffer. The value of this parameter must be GL_RENDERBUFFER (or GL_RENDERBUFFER_OES in an OpenGL ES 1.1 context).

Return Value

YES if successful; otherwise, NO.

Discussion

The renderbuffer to be displayed must have been allocated storage using the renderbufferStorage:fromDrawable: method. The exact semantics for how and when the renderbuffer contents are displayed is controlled by the drawable object.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
EAGLDrawable.h

renderbufferStorage:fromDrawable:

Binds a drawable object’s storage to an OpenGL ES renderbuffer object.

- (BOOL)renderbufferStorage:(NSUInteger)target fromDrawable:(id<EAGLDrawable>)drawable
Parameters
target

The OpenGL ES binding point for a currently bound renderbuffer. The value of this parameter must be GL_RENDERBUFFER (or GL_RENDERBUFFER_OES in an OpenGL ES 1.1 context).

drawable

An object managing the data store for the renderbuffer. In iOS, the value of this parameter must be a CAEAGLLayer object.

Return Value

YES if successful; otherwise, NO.

Discussion

To create a renderbuffer that can be presented to the screen, you bind the renderbuffer and then allocate shared storage for it by calling this method. This method call replaces the call normally made to glRenderbufferStorage. A renderbuffer whose storage has been allocated with this method can later be displayed with a call to presentRenderbuffer:.

The width, height, and internal color buffer format are derived from the characteristics of the drawable object. You may override the internal color buffer format by adding an kEAGLDrawablePropertyColorFormat key to the drawableProperties dictionary of the drawable object before calling this method.

To specify that the OpenGL ES renderbuffer should be detached from the drawable object, call this method with the drawable parameter set to nil.

Special Considerations

In iOS 6.0 and later, this method automatically flushes the OpenGL ES command buffer, making it unsuitable to call repeatedly in performance-critical code.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
  • GLES2Sample
Declared In
EAGLDrawable.h

Constants

OpenGL ES Versions

Versions of OpenGL ES that a rendering context provides.

typedef NSUInteger EAGLRenderingAPI;
enum
{
   kEAGLRenderingAPIOpenGLES1         = 1,
   kEAGLRenderingAPIOpenGLES2         = 2,
   kEAGLRenderingAPIOpenGLES3         = 3,
};
Constants
kEAGLRenderingAPIOpenGLES1

Context supports OpenGL ES 1.x rendering API.

Available in iOS 2.0 and later.

Declared in EAGL.h.

kEAGLRenderingAPIOpenGLES2

Context supports OpenGL ES 2.x rendering API.

Available in iOS 3.0 and later.

Declared in EAGL.h.

kEAGLRenderingAPIOpenGLES3

Context supports OpenGL ES 3.x rendering API.

Available in iOS 7.0 and later.

Declared in EAGL.h.