GLKView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GLKit.framework
Availability
Available in iOS 5.0 and later.
Declared in
GLKView.h
Related sample code

Overview

The GLKView class simplifies the effort required to create an OpenGL ES application by providing a default implementation of an OpenGL ES-aware view. A GLKView directly manages a framebuffer object on your application’s behalf; your application simply needs to draw into the framebuffer when the contents need to be updated.

To use a GLKView in your application, allocate and initialize a new GLKView object and provide it an OpenGL ES context. Then, modify the view’s drawableColorFormat, drawableDepthFormat, drawableStencilFormat, and drawableMultisample properties to configure the format of the drawable’s framebuffer object. After this, the view automatically creates or updates the framebuffer object whenever the view must be redrawn. A GLKView object uses the regular view drawing cycle for a UIView object, calling its drawRect: method whenever the contents of the view need to be updated. Before calling its drawRect: method, the view makes its EAGLContext object the current OpenGL ES context and binds its framebuffer object to the OpenGL ES context as the target for rendering commands. Your application’s implementation of the drawRect: method should call one or more OpenGL ES functions to render an image into the framebuffer object. Then, the view resolves any multisampling that you may have enabled and delivers the finished results.

The GLKView class can be used in conjunction with a GLKViewController object to create an animation rendering loop that redraws the contents of the view at a specified frame rate.

Subclassing Notes

Typically, there is no need to subclass the GLKView class. Instead, provide a delegate object to draw the view’s contents. See GLKViewDelegate Protocol Reference.

Tasks

Initializing the View

Delegate

Configuring the Framebuffer Object

Read-only Framebuffer Properties

Drawing Your View’s Contents

Deleting the View’s Underlying Framebuffer Object

Properties

context

The OpenGL ES context used when drawing the view’s contents.

@property(nonatomic, retain) EAGLContext *context
Discussion

The view uses this context as the place to create its underlying framebuffer object and it also sets the context before calling your drawing method. Never change the context from inside your drawing method.

Availability
  • Available in iOS 5.0 and later.
Related Sample Code
Declared In
GLKView.h

delegate

The view’s delegate.

@property(nonatomic, assign) id<GLKViewDelegate> delegate
Discussion

A delegate is optional. If a delegate is provided, it is called instead of calling a drawRect: method whenever the view’s contents need to be drawn. You should either subclass the view to override the drawRect: method, or provide a delegate, but not both.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

drawableColorFormat

The format of the color renderbuffer.

@property(nonatomic) GLKViewDrawableColorFormat drawableColorFormat
Discussion

The default value is GLKViewDrawableColorFormatRGBA8888.

After your application changes the value of this property, the view recreates its framebuffer object the next time the view is drawn.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

drawableDepthFormat

The format of the depth renderbuffer

@property(nonatomic) GLKViewDrawableDepthFormat drawableDepthFormat
Discussion

The default value is GLKViewDrawableDepthFormatNone.

After your application changes the value of this property, the view recreates its framebuffer object the next time the view is drawn.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

drawableHeight

The height, in pixels, of the underlying framebuffer object. (read-only)

@property(nonatomic, readonly) NSInteger drawableHeight
Discussion

The height and width of the underlying framebuffer object is calculated automatically by the view object based on its bounds and contentScaleFactor properties and change whenever either of those properties change. Your application never directly adjusts the size of the framebuffer object. Instead, your application should read the drawableHeight and drawableWidth properties and use those to configure its OpenGL ES rendering code. For example, you might use the drawableHeight and drawableWidth properties to set the OpenGL ES viewport, determining the size and complexity of the art assets to load, and so on.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

drawableMultisample

The format of the multisampling buffer.

@property(nonatomic) GLKViewDrawableMultisample drawableMultisample
Discussion

The default value is GLKViewDrawableMultisampleNone.

After your application changes the value of this property, the view recreates its framebuffer object the next time the view is drawn.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

drawableStencilFormat

The format of the stencil renderbuffer.

@property(nonatomic) GLKViewDrawableStencilFormat drawableStencilFormat
Discussion

The default value is GLKViewDrawableStencilFormatNone.

After your application changes the value of this property, the view recreates its framebuffer object the next time the view is drawn.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

drawableWidth

The width, in pixels, of the underlying framebuffer object. (read-only)

@property(nonatomic, readonly) NSInteger drawableWidth
Discussion

The height and width of the underlying framebuffer object is calculated automatically by the view object based on its bounds and contentScaleFactor properties and change whenever either of those properties change. Your application never directly adjusts the size of the framebuffer object. Instead, your application should read the drawableHeight and drawableWidth properties and use those to configure its OpenGL ES rendering code. For example, you might use the drawableHeight and drawableWidth properties to set the OpenGL ES viewport, determining the size and complexity of the art assets to load, and so on.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

enableSetNeedsDisplay

A Boolean value that indicates whether the view responds to messages that invalidate the view’s contents.

@property(nonatomic) BOOL enableSetNeedsDisplay
Discussion

By default, a GLKView object respects the standard view drawing cycle for a UIView object, as described in UIView Class Reference. However, many OpenGL ES applications need to update their contents explicitly in an animation rendering loop. When updating your contents in a rendering loop, the normal on-demand mechanism for view updates can be disabled by setting the value of this property to NO. If your application uses a GLKViewController object to drive the rendering loop, the view controller automatically sets this property to NO.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
GLKView.h

Instance Methods

bindDrawable

Binds the underlying framebuffer object to OpenGL ES.

- (void)bindDrawable
Discussion

Before calling your drawing method, the view binds the underlying framebuffer object to the context so that rendering commands are automatically drawn into it. However, some rendering strategies require you to change the target of your rendering commands to another framebuffer object, such as when you need to render to a texture first. If your application changed the framebuffer object bound to OpenGL ES, it calls this method to rebind the view’s framebuffer object to OpenGL ES.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

deleteDrawable

Deletes the drawable object associated with the view.

- (void)deleteDrawable
Discussion

The drawable object consumes a significant amount of memory, so whenever the view is not going to be used to display content for a significant period of time, your application should call this method to dispose of the underlying memory. For example, your application might call this method after hiding a view or before transitioning to another screen of content.

If you use a GLKViewController object to manage the view, the view controller automatically calls this method whenever your application moves into the background.

After calling this method, do not invalidate the view’s contents or call the view’s display method until you are ready to display the content again to the user; drawing the view’s contents automatically reallocates the drawable object.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

display

Redraws the view’s contents immediately.

- (void)display
Discussion

This method causes your drawing method to be called immediately and then presents the rendered image to the screen. Your application typically calls this method inside of a rendering loop, such as the one provided by the GLKViewController class, in order to provide a continuous smooth animation.

Never call this method inside your drawing function.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

initWithFrame:context:

Initializes a new view.

- (id)initWithFrame:(CGRect)frame context:(EAGLContext *)context
Parameters
frame

The frame rectangle for the view, measured in points. The origin of the frame is relative to the superview in which you plan to add it. This method uses the frame rectangle to set the center and bounds properties accordingly.

context

An OpenGL ES context used to store the framebuffer object.

Return Value

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

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

snapshot

Draws the contents of the view and returns them as a new image object.

- (UIImage *)snapshot
Return Value

An image object.

Discussion

When this method is called, the view sets up a drawing environment and calls your drawing method. However, instead of presenting the view’s contents on screen, they are returned to your application as an image instead. This method should be called whenever your application explicitly needs the contents of the view; never attempt to directly read the contents of the underlying framebuffer using OpenGL ES functions.

Never call this method inside your drawing function.

Availability
  • Available in iOS 5.0 and later.
Declared In
GLKView.h

Constants

GLKViewDrawableColorFormat

The format of the color renderbuffer.

typedef enum
{
   GLKViewDrawableColorFormatRGBA8888 = 0,
   GLKViewDrawableColorFormatRGB565,
   GLKViewDrawableColorFormatSRGBA8888
} GLKViewDrawableColorFormat;
Constants
GLKViewDrawableColorFormatRGBA8888

An RGBA8888 format.

Available in iOS 5.0 and later.

Declared in GLKView.h.

GLKViewDrawableColorFormatRGB565

An RGB565 format.

Available in iOS 5.0 and later.

Declared in GLKView.h.

GLKViewDrawableColorFormatSRGBA8888

An sRGBA8888 format.

Available in iOS 7.0 and later.

Declared in GLKView.h.

GLKViewDrawableDepthFormat

The format of the depth renderbuffer.

typedef enum
{
   GLKViewDrawableDepthFormatNone = 0,
   GLKViewDrawableDepthFormat16,
   GLKViewDrawableDepthFormat24,
} GLKViewDrawableDepthFormat;
Constants
GLKViewDrawableDepthFormatNone

The underlying framebuffer object has no depth buffer.

Available in iOS 5.0 and later.

Declared in GLKView.h.

GLKViewDrawableDepthFormat16

A 16-bit depth entry for each pixel.

Available in iOS 5.0 and later.

Declared in GLKView.h.

GLKViewDrawableDepthFormat24

A 24-bit depth entry for each pixel.

Available in iOS 5.0 and later.

Declared in GLKView.h.

GLKViewDrawableStencilFormat

The format of the stencil renderbuffer.

typedef enum
{
   GLKViewDrawableStencilFormatNone = 0,
   GLKViewDrawableStencilFormat8,
} GLKViewDrawableStencilFormat;
Constants
GLKViewDrawableStencilFormatNone

The underlying framebuffer object has no stencil buffer.

Available in iOS 5.0 and later.

Declared in GLKView.h.

GLKViewDrawableStencilFormat8

An 8-bit stencil entry for each pixel.

Available in iOS 5.0 and later.

Declared in GLKView.h.

GLKViewDrawableMultisample

The format of the multisampling buffer.

typedef enum
{
   GLKViewDrawableMultisampleNone = 0,
   GLKViewDrawableMultisample4X,
} GLKViewDrawableMultisample;
Constants
GLKViewDrawableMultisampleNone

Multisampling is not enabled.

Available in iOS 5.0 and later.

Declared in GLKView.h.

GLKViewDrawableMultisample4X

Multisampling is enabled.

Available in iOS 5.0 and later.

Declared in GLKView.h.

Discussion

Multisampling improves the quality of the output image, but may require more memory and image processing to do so. As such, you should profile your application with and without multisampling enabled, and choose a setting that provides both the image quality and performance you require.