GLKBaseEffect Class Reference

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

Overview

The GLKBaseEffect class provides shaders that mimic many of the behaviors provided by the OpenGL ES 1.1 lighting and shading model, including materials, lighting and texturing. The base effect allows up to three lights and two textures to be applied to a scene.

At initialization time, your application first creates a compatible OpenGL or OpenGL ES context and makes it current. Then, it allocates and initializes a new effect object, configures its properties, and calls its prepareToDraw method. Binding an effect causes a shader to be compiled and bound to the current context. The base effect also requires vertex data to be supplied by your application. To supply vertex data, create one or more vertex array objects. For each attribute required by the shader, the vertex array object should enable the attribute and point to data stored in a vertex buffer object.

At rendering time, your application calls the effect’s prepareToDraw method to prepare the effect. Then, it binds a vertex array object and submits one or more drawing commands.

Lighting calculations for the base effect are done in eye-space coordinates.  The light0, light1 and light2 properties hold the position and spot direction of the base effect’s lights. The transform property contains the model view matrix assigned to the scene. When a light is assigned a new position or spot direction, those values are immediately modified by the current model view matrix. Thus, it is important to sequence changes to the model view matrix and changes to the lights to achieve the desired light positioning.  Light positions that need to be transformed in a manner similar to scene geometry should be set after the model view matrix is updated.

Subclassing Notes

Although this class can be subclassed, there are no methods your subclass can use to directly override the underlying shader generation. Instead, your subclass should implement its functionality by changing the values of existing properties declared by the base class.

Tasks

Naming the Effect

Configuring the Modelview Transform

Configuring Lights

Configuring Textures

Configuring Fog

Configuring Color Information

Preparing the Effect for Drawing

Properties

colorMaterialEnabled

A Boolean value that indicates whether or not to use the color vertex attribute when calculating the light’s interaction with the material.

@property(nonatomic, assign) GLboolean colorMaterialEnabled
Discussion

If the value is set to GL_TRUE, then the color attribute provided in the vertex data is used as the material’s color when performing any lighting calculations. If the value is set to GL_FALSE then the colors stored in the material property are used to light the primitive. The default value is GL_FALSE.

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

constantColor

A constant color, used when per-vertex color data is not provided.

@property(nonatomic, assign) GLKVector4 constantColor
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

fog

The fog properties to apply to the scene. (read-only)

@property(nonatomic, readonly) GLKEffectPropertyFog *fog
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

label

A string used to name your effect.

@property(nonatomic, retain) NSString *label
Discussion

The name of the effect isn’t used directly by GLKit, but is printed when, for example, you log the object to the console via the NSLog function.

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

light0

The lighting properties for the first light in the scene. (read-only)

@property(nonatomic, readonly) GLKEffectPropertyLight *light0
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

light1

The lighting properties for the second light in the scene. (read-only)

@property(nonatomic, readonly) GLKEffectPropertyLight *light1
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

light2

The lighting properties for the third light in the scene. (read-only)

@property(nonatomic, readonly) GLKEffectPropertyLight *light2
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

lightingType

The strategy the effect uses to calculate light values at each fragment. See Determining How Lighting is Calculated.

@property(nonatomic, assign) GLKLightingType lightingType
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

lightModelAmbientColor

The ambient color applied to all primitives rendered by the effect.

@property(nonatomic, assign) GLKVector4 lightModelAmbientColor
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

lightModelTwoSided

A Boolean value that indicates whether lighting is calculated for both sides of a primitive.

@property(nonatomic, assign) GLboolean lightModelTwoSided
Discussion

If the value is GL_TRUE and the back face of a primitive is being rendered, the lighting values are calculated by negating the surface normals for the primitive. If the value is GL_FALSE, then the facing of the primitive is ignored when performing the lighting calculation. The default value is GL_FALSE.

Setting the value of this property to GL_TRUE may impact performance. Only use two-sided lighting when either side of a primitive could theoretically be visible to the camera.

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

material

The material properties used when calculating the light values for a rendered primitive. (read-only)

@property(nonatomic, readonly) GLKEffectPropertyMaterial *material
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

texture2d0

The properties for the first texture. (read-only)

@property(nonatomic, readonly) GLKEffectPropertyTexture *texture2d0
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

texture2d1

The properties for the second texture. (read-only)

@property(nonatomic, readonly) GLKEffectPropertyTexture *texture2d1
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

textureOrder

The order in which textures are applied to rendered primitives.

@property(nonatomic, retain) NSArray *textureOrder
Discussion

The value of this property should be an array whose contents are all GLKEffectPropertyTexture objects provided by the effect. The order of these objects in the array determines the order in which the textures are applied in the shader. For example, to reverse the order that the textures are applied to a scene, your application would use the following code:

baseEffect.textureOrder = [NSArray arrayWithObjects: baseEffect.texture2d1, baseEffect.texture2d0, nil];

The default value is an array that executes the texture stages in increasing order, skipping any texture stages that are not enabled.

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

transform

The modelview, projection and texture transformations applied to the vertex data when the effect is bound. (read-only)

@property(nonatomic, readonly) GLKEffectPropertyTransform *transform
Availability
  • Available in iOS 5.0 and later.
Declared In
GLKBaseEffect.h

useConstantColor

A Boolean value that indicates whether or not to use the constant color.

@property(nonatomic, assign) GLboolean useConstantColor
Discussion

If the value is set to GL_TRUE, then the value stored in the constantColor property is used as the color value for each vertex. If the value is set to GL_FALSE, then your application is expected to enable the GLKVertexAttribColor attribute and provide per-vertex color data. The default value is GL_FALSE.

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

Instance Methods

prepareToDraw

Prepares an effect for rendering.

- (void)prepareToDraw
Discussion

An effect must be prepared after it is configured and again when your application wants to use the effect to render any primitives. When your application prepares an effect, some OpenGL state is altered to allow the effect to operate:

  • The GL_CURRENT_PROGRAM state is always changed to point to the shader provided by the effect object.

  • When texturing is enabled, the GL_TEXTURE_BINDING_2D state may also change.

If your application requires the previous state to be saved before the effect alters them, it must explicitly save and restore the values.

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


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-17)

Did this document help you? Yes It's good, but... Not helpful...