CCEffectLighting + CCLightNode - Light depth

Even though cocos2d scenes, nodes, and sprites are two dimensional, it is unavoidable
that some lighting math involves a third dimension. Because normal maps define normal
vectors in three dimensions, we need a way to specify a virtual Z value for our lights or
otherwise all lights will appear to be coplanar with the sprites they are lighting. In this case
all lighting would appear to be from the side (or above or below) and would be unpleasantly
harsh looking.

This change adds support for a light Z coordinate by adding a depth property (I've avoided
using the name z or Z since this name is already used for render order sorting).

Author: Thayer J Andrews

cocos2d/CCEffectLighting.m

@@ -193,11 +193,11 @@ -(void)buildRenderPasses
             GLKVector4 lightVector = GLKVector4Make(0.0f, 0.0f, 0.0f, 0.0f);
             if (light.type == CCLightDirectional)
             {
-                lightVector = GLKVector4Normalize(GLKMatrix4MultiplyVector4(lightNodeToEffectNode, GLKVector4Make(0.0f, 1.0f, 1.0f, 0.0f)));
+                lightVector = GLKVector4Normalize(GLKMatrix4MultiplyVector4(lightNodeToEffectNode, GLKVector4Make(0.0f, 1.0f, light.depth, 0.0f)));
             }
             else
             {
-                lightVector = GLKMatrix4MultiplyVector4(lightNodeToEffectNode, GLKVector4Make(light.anchorPointInPoints.x, light.anchorPointInPoints.y, 500.0f, 1.0f));
+                lightVector = GLKMatrix4MultiplyVector4(lightNodeToEffectNode, GLKVector4Make(light.anchorPointInPoints.x, light.anchorPointInPoints.y, light.depth, 1.0f));
 
                 float falloff = (light.cutoffRadius > 0.0f) ? 1.0f / light.cutoffRadius : 0.0f;
                 NSString *lightFalloffLabel = [NSString stringWithFormat:@"u_lightFalloff%lu", (unsigned long)lightIndex];

cocos2d/CCLightNode.h

@@ -74,6 +74,16 @@ typedef NS_ENUM(NSUInteger, CCLightType)
  */
 @property (nonatomic, assign) float cutoffRadius;
 
+/** The light's depth value within the scene. This value is independent of the node
+ *  z-order which is used for sorting and is instead used by the lighting equations
+ *  when computing the light's direction vector relative to the nodes it is lighting.
+ *  Only values greater than or equal to 0 are valid. A depth value of 0 makes the light 
+ *  coplanar with any nodes it is lighting which results in a very hard looking side light. 
+ *  Increasingly positive values move the light farther and farther out of the plane of 
+ *  the lit nodes resulting in a softer looking front light.
+ */
+@property (nonatomic, assign) float depth;
+
 
 
 /// -----------------------------------------------------------------------

cocos2d/CCLightNode.m

@@ -27,6 +27,14 @@ -(id)initWithType:(CCLightType)type color:(CCColor *)color intensity:(float)inte
         _ambientColor = ambientColor;
         _ambientIntensity = ambientIntensity;
         _cutoffRadius = 0.0f;
+        if (type == CCLightDirectional)
+        {
+            _depth = 1.0f;
+        }
+        else
+        {
+            _depth = 500.0f;
+        }
     }
 
     return self;