iOS Developer Library — Prerelease

Developer

OpenGL ES Framework Reference EAGLContext Class Reference

Options
Deployment Target:

On This Page
Language:

EAGLContext

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.

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

    Declaration

    Swift

    convenience init!(API api: EAGLRenderingAPI)

    Objective-C

    - (instancetype)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.

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

    Declaration

    Swift

    init!(API api: EAGLRenderingAPI, sharegroup sharegroup: EAGLSharegroup!)

    Objective-C

    - (instancetype)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.

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

    Declaration

    Swift

    class func setCurrentContext(_ context: EAGLContext!) -> Bool

    Objective-C

    + (BOOL)setCurrentContext:(EAGLContext *)context

    Parameters

    context

    The rendering context that you want to make current.

    Return Value

    YEStrue if successful; otherwise, NOfalse. 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. To prevent a non-current context from being deallocated, your app should keep a strong reference to the context (or retain it, if using manual reference counting). 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.

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

    Declaration

    Swift

    func renderbufferStorage(_ target: Int, fromDrawable drawable: EAGLDrawable!) -> Bool

    Objective-C

    - (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

    YEStrue if successful; otherwise, NOfalse.

    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.

  • Displays a renderbuffer’s contents on screen.

    Declaration

    Swift

    func presentRenderbuffer(_ target: Int) -> Bool

    Objective-C

    - (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

    YEStrue if successful; otherwise, NOfalse.

    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.

  • API API Property

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

    Declaration

    Swift

    var API: EAGLRenderingAPI { get }

    Objective-C

    @property(readonly) EAGLRenderingAPI API

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var sharegroup: EAGLSharegroup! { get }

    Objective-C

    @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.

  • A label describing the context for use in debugging.

    Declaration

    Swift

    var debugLabel: String!

    Objective-C

    @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.

  • Returns the current rendering context for the calling thread.

    Declaration

    Swift

    class func currentContext() -> EAGLContext!

    Objective-C

    + (EAGLContext *)currentContext

    Return Value

    The current context for the calling thread.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var multiThreaded: Bool

    Objective-C

    @property(getter=isMultiThreaded, nonatomic) BOOL multiThreaded

    Discussion

    Set the value of this property to YEStrue 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 NOfalse (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 NOfalse—attempting to set the value to YEStrue has no effect.

    Availability

    Available in iOS 7.1 and later.

  • Versions of OpenGL ES that a rendering context provides.

    Declaration

    Swift

    enum EAGLRenderingAPI : UInt { case OpenGLES1 case OpenGLES2 case OpenGLES3 }

    Objective-C

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

    Constants

    • OpenGLES1

      kEAGLRenderingAPIOpenGLES1

      Context supports OpenGL ES 1.x rendering API.

      Available in iOS 2.0 and later.

    • OpenGLES2

      kEAGLRenderingAPIOpenGLES2

      Context supports OpenGL ES 2.x rendering API.

      Available in iOS 3.0 and later.

    • OpenGLES3

      kEAGLRenderingAPIOpenGLES3

      Context supports OpenGL ES 3.x rendering API.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import OpenGLES;

    Swift

    import OpenGLES

    Availability

    Available in iOS 2.0 and later.