GLKEffectPropertyLight Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GLKit.framework
Availability
Available in OS X v10.8 and later.
Declared in
GLKEffectPropertyLight.h

Overview

The GLKEffectPropertyLight class defines properties for a single light applied to an effect. The lighting model implemented by GLKEffectPropertyLight is identical to the lighting model implemented in OpenGL ES 1.1; each light interacts with any material properties on the effect to determine the intensity and color that particular light contributes to the scene at a fragment.

There are three basic kinds of lights: directional, point and spotlights.

Lighting calculations are performed in eye-space coordinates.  The eye-space coordinates for the position and the spot direction are calculated at the precise moment that new position values are specified and may be affected by other properties of the effect. For more information, see GLKBaseEffect Class Reference.

Tasks

Configuring Common Lighting Properties

Configuring Light Colors

Configuring Lighting Attenuation

Configuring Spotlight Properties

Properties

ambientColor

The ambient portion of the light.

@property(nonatomic, assign) GLKVector4 ambientColor
Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

constantAttenuation

A constant factor applied to the attenuation of a point light or spotlight.

@property(nonatomic, assign) GLfloat constantAttenuation
Discussion

The distance attenuation factor is calculated as 1.0 / (k0 + k1 * d + k2 * d * d), where d represents the distance from the light to the point being lit. The constantAttenuation property is represented in this calculation as k0. The default value is 1.0.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

diffuseColor

The diffuse portion of the light.

@property(nonatomic, assign) GLKVector4 diffuseColor
Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

enabled

A Boolean value that indicates whether calculations should be performed on this light.

@property(nonatomic, assign) GLboolean enabled
Discussion

If the value of enabled is GL_TRUE, then lighting calculations are performed for this light. If the value is GL_FALSE, this light is skipped when computing the fragment color.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

linearAttenuation

A linear factor applied to the attenuation of a point light or spotlight.

@property(nonatomic, assign) GLfloat linearAttenuation
Discussion

The distance attenuation factor is calculated as 1.0 / (k0 + k1 * d + k2 * d * d), where d represents the distance from the light to the point being lit. The linearAttenuation property is represented in this calculation as k1. The default value is 0.0.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

position

The position of the light in world coordinates.

@property(nonatomic, assign) GLKVector4 position
Discussion

If the w component of the position is 0.0, the light is calculated using the directional light formula. The x, y, and z components of the vector specify the direction the light shines. The light is assumed to be infinitely far away; attenuation and spotlight properties are ignored.

If the w component of the position is a non-zero value, the coordinates specify the position of the light in homogenous coordinates, and the light is either calculated as a point light or a spotlight, depending on the value of the spotCutoff property.

The default value is [0.0, 0.0, 1.0, 0.0].

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

quadraticAttenuation

A quadratic factor applied to the attenuation of a point light or spotlight.

@property(nonatomic, assign) GLfloat quadraticAttenuation
Discussion

The distance attenuation factor is calculated as 1.0 / (k0 + k1 * d + k2 * d * d), where d represents the distance from the light to the point being lit. The quadraticAttenuation property is represented in this calculation as k2. The default value is 0.0.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

specularColor

The specular portion of the light.

@property(nonatomic, assign) GLKVector4 specularColor
Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

spotCutoff

The angle in degrees where the spotlight is cut off.

@property(nonatomic, assign) GLfloat spotCutoff
Discussion

If the w component of the position is not equal to 0.0, the value of the spotCutoff property determines whether the light is a point light or a spotlight. A cutoff value of 180.0 indicates that the light is a point light; for a point light, the spotDirection and spotExponent properties are ignored. Otherwise, the spotCutoff property represents the maximum angle at which the light contributes lighting to the scene. The angle is measured between the vector provided by the spotDirection property and a vector drawn from the light’s position to the point being lit. If the angle exceeds this amount, then the light contributes no light to the scene.

The default value is 180.0.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

spotDirection

A vector indicating the direction the spotlight is projecting.

@property(nonatomic, assign) GLKVector3 spotDirection
Discussion

The default direction is [0.0, 0.0, -1.0].

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

spotExponent

A value indicating how focused the spotlight is.

@property(nonatomic, assign) GLfloat spotExponent
Discussion

The higher the value stored in the spotExponent property, the tighter the focus of the spotlight. The default value is 0.0.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

transform

A transform applied to the light’s position and direction before calculating the contribution of the light.

@property(nonatomic, retain) GLKEffectPropertyTransform *transform
Discussion

The default value is the identity matrix.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKEffectPropertyLight.h

Constants

Determining How Lighting is Calculated

A constant that describes how lighting is calculated by an effect.

typedef enum
{
   GLKLightingTypePerVertex,
   GLKLightingTypePerPixel
} GLKLightingType;
Constants
GLKLightingTypePerVertex

Indicates that the lighting calculations are performed at each vertex in a triangle and then interpolated across the triangle.

Available in OS X v10.8 and later.

Declared in GLKEffectPropertyLight.h.

GLKLightingTypePerPixel

Indicates that the inputs to the lighting calculation are interpolated across a triangle and the lighting calculations are performed at each fragment.

Available in OS X v10.8 and later.

Declared in GLKEffectPropertyLight.h.

Discussion

Typically, per-pixel lighting should be enabled when it provides an improvement in image quality without greatly reducing your application’s performance. Calculating the lighting equation at each fragment greatly increases the number of calculations required to calculate the lighting for a scene. However, calculating lighting only at vertices sometimes produces unusual or inaccurate results, particularly when your application uses spotlights or specular highlighting. For example, when per-pixel lighting is disabled, a narrow spotlight projected at the center of a large triangle may disappear entirely because the vertices that define the triangle all lie outside the area covered by the spotlight. That same triangle, when rendered using per-pixel lighting, would be rendered correctly.