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 |
Overview
An EAGLContext object manages the state information, commands, and resources needed to draw using OpenGL ES. All OpenGL ES commands are executed in relation to an EAGL context.
Drawing resources such as textures and renderbuffers are managed for the EAGLContext object by an EAGLSharegroup object associated with the context. When a new EAGLContext object is initialized, you can choose to have it create a new EAGLSharegroup object or use one obtained from a previously created EAGL context.
To draw to an EAGL context, a complete framebuffer object must first be bound to the context. For more information on configuring rendering contexts, see OpenGL ES Programming Guide for iOS.
Tasks
Creating EAGL Contexts
Setting the Current EAGL Context
Attaching Storage to a Renderbuffer
Displaying a Renderbuffer
Getting EAGL Context Information
-
APIproperty -
sharegroupproperty -
+ currentContext
Properties
API
Specifies the OpenGL ES rendering API version supported by the receiver. (read-only)
Availability
- Available in iOS 2.0 and later.
Declared In
EAGL.hsharegroup
The receiver’s sharegroup object. (read-only)
Discussion
You 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.
See Also
Declared In
EAGL.hClass Methods
currentContext
Returns the current rendering context for the calling thread.
Return Value
The current EAGL context for the calling thread.
Availability
- Available in iOS 2.0 and later.
Declared In
EAGL.hsetCurrentContext:
Makes the specified context the current rendering context for the calling thread.
Parameters
- context
The rendering context that you want to make current.
Return Value
YES if successful; otherwiseNO. If an error occurred, the rendering context for the current thread remains unchanged.
Discussion
All OpenGL ES calls are issued with respect to the current context and complete in the order they are called, unless otherwise specified.
EAGL retains the context when it is made current and 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.hInstance Methods
initWithAPI:
Initializes and returns a newly allocated rendering context with the specified version of the OpenGL ES rendering 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 it the current drawing context by calling setCurrentContext:.
Calling initWithAPI: creates a new EAGLSharegroup object and attaches it to this context.
Availability
- Available in iOS 2.0 and later.
Declared In
EAGL.hinitWithAPI:sharegroup:
Initializes and returns a newly allocated rendering context with the specified version of OpenGL ES rendering API and the specified 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
EAGLContextobject.
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. If nil is passed as the sharegroup parameter, a new EAGLSharegroup object is created and attached to the context.
Availability
- Available in iOS 2.0 and later.
Declared In
EAGL.hpresentRenderbuffer:
Displays a renderbuffer’s contents on screen.
Parameters
- target
The OpenGL ES binding point for a currently bound renderbuffer. For contexts that use the OpenGL ES 1.0 API, this must be
GL_RENDERBUFFER_OES. For contexts that use the OpenGL ES 2.0 API, the OES suffix should be removed.
Return Value
YES if successful; otherwise NO.
Discussion
The renderbuffer to be displayed must have 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.
See Also
Declared In
EAGLDrawable.hrenderbufferStorage:fromDrawable:
Binds a drawable object’s storage to an OpenGL ES renderbuffer object.
Parameters
- target
The OpenGL ES binding point for a currently bound renderbuffer. For contexts that use the OpenGL ES 1.0 API, this must be
GL_RENDERBUFFER_OES. For contexts that use the OpenGL ES 2.0 API, the OES suffix should be removed.- drawable
An object that conforms to the EAGLDrawable protocol whose storage will be bound to the renderbuffer. In iOS 3.0, this is always a
CAEAGLLayerobject.
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, you can call this method with drawable set to nil.
Special Considerations
In iOS 6.0 and later this method flushes for correctness reasons, making it unsuitable to call repeatedly in performance-critical code.
Availability
- Available in iOS 2.0 and later.
Declared In
EAGLDrawable.hConstants
OpenGL ES Versions
These constants are used to choose the version of OpenGL ES that a rendering context provides.
typedef NSUInteger EAGLRenderingAPI;
enum
{
kEAGLRenderingAPIOpenGLES1 = 1
kEAGLRenderingAPIOpenGLES2 = 2
};
Constants
© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)