iOS Developer Library — Prerelease

Developer

GLKit Framework Reference GLKEffectPropertyLight Class Reference

Options
Deployment Target:

On This Page
Language:

GLKEffectPropertyLight

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.

  • A directional light is considered to be infinitely far away, and always directs light in the same direction. To create a directional light, set the position property to a vector whose x, y, and z components specify the direction to the light (that is, the negation of the direction the light is travelling in), and whose w component is set to 0.0.

  • A point light is placed at a position within the scene, and emits light in all directions. To create a directional light, set the position property to a vector whose x, y, z and w components specify the homogenous coordinates for the position of the light in the scene. The w component is typically set to 1.0 and must not be set to 0.0.

    The intensity of a point light is adjusted using an distance attenuation function. This function is controlled by adjusting the constantAttenuation, linearAttenuation or quadraticAttenuation properties. The default values for these properties create a light whose intensity is constant over distance.

  • A spotlight is placed at a position within the scene, and emits light in a specific direction in a cone. To create a spotlight, set the position property to a vector whose x, y, z and w components specify the homogenous coordinates for the position of the light in the scene. The w component must not be set to 0.0. Then, set the spotDirection property to a vector that specifies the direction of the light and the spotCutoff to a value less than 180.0.

    Like a point light, a spotlight’s intensity can be adjusted using the distance attenuation properties. A spotlight’s intensity can also be changed as a function of the spotlight angle by setting the spotExponent property. The default value for a spotlight creates a spotlight whose intensity is not affected by the angle. That is, the spotlight radiates the same amount of light at the center and at the edge of the cone.

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.

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

    Declaration

    Swift

    var enabled: GLboolean

    Objective-C

    @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 iOS 5.0 and later.

  • The position of the light in world coordinates.

    Declaration

    Swift

    var position: GLKVector4

    Objective-C

    @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 iOS 5.0 and later.

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

    Declaration

    Swift

    var transform: GLKEffectPropertyTransform

    Objective-C

    @property(nonatomic, retain) GLKEffectPropertyTransform * _Nonnull transform

    Discussion

    The default value is the identity matrix.

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var constantAttenuation: GLfloat

    Objective-C

    @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 iOS 5.0 and later.

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

    Declaration

    Swift

    var linearAttenuation: GLfloat

    Objective-C

    @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 iOS 5.0 and later.

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

    Declaration

    Swift

    var quadraticAttenuation: GLfloat

    Objective-C

    @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 iOS 5.0 and later.

  • The angle in degrees where the spotlight is cut off.

    Declaration

    Swift

    var spotCutoff: GLfloat

    Objective-C

    @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 iOS 5.0 and later.

  • A vector indicating the direction the spotlight is projecting.

    Declaration

    Swift

    var spotDirection: GLKVector3

    Objective-C

    @property(nonatomic, assign) GLKVector3 spotDirection

    Discussion

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

    Availability

    Available in iOS 5.0 and later.

  • A value indicating how focused the spotlight is.

    Declaration

    Swift

    var spotExponent: GLfloat

    Objective-C

    @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 iOS 5.0 and later.

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

    Declaration

    Swift

    enum GLKLightingType : GLint { case PerVertex case PerPixel }

    Objective-C

    typedef enum { GLKLightingTypePerVertex, GLKLightingTypePerPixel } GLKLightingType;

    Constants

    • PerVertex

      GLKLightingTypePerVertex

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

      Available in iOS 5.0 and later.

    • PerPixel

      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 iOS 5.0 and later.

    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.

    Import Statement

    Objective-C

    @import GLKit;

    Swift

    import GLKit

    Availability

    Available in iOS 5.0 and later.