Merge pull request #904 from thayerandrews/develop

CCEffects - API documentation

Author: vlidholt

cocos2d/CCEffect.h

@@ -12,8 +12,21 @@
 #import "ccConfig.h"
 #import "ccTypes.h"
 
+
+/**
+ * CCEffect is the foundation of the Cocos2D effects system. Subclasses of CCEffect can be
+ * used to easily add exciting visual effects such has blur, bloom, reflection, refraction, and
+ * other image processing filters to your applications.
+ *
+ */
+
 @interface CCEffect : NSObject
 
+/// -----------------------------------------------------------------------
+/// @name Accessing Effect Attributes
+/// -----------------------------------------------------------------------
+
+/** An identifier for debugging effects. */
 @property (nonatomic, copy) NSString *debugName;
 
 @end

cocos2d/CCEffectBloom.h

@@ -8,27 +8,83 @@
 
 #import "CCEffect.h"
 
+/**
+ * CCEffectBloom simulates bloooming of bright light when viewed against a darker
+ * background. A threshold value allows for the selection of pixels above a certain
+ * brightness level while radius and intensity parameters how large the bloom is and
+ * how much it contributes to the resulting image.
+ */
+
 @interface CCEffectBloom : CCEffect
 
-// ranges between 0.0-1.0 - defines which part of the image should be glown via a luminance factor (brightness).
+/// -----------------------------------------------------------------------
+/// @name Accessing Effect Attributes
+/// -----------------------------------------------------------------------
+
+/** The luminance threshold at which pixels will contribute to the bloom.
+ *  This value is in the range [0..1]. Lower values mean that more pixels will
+ *  contribute to the blurry bloom image.
+ */
 @property (nonatomic) float luminanceThreshold;
 
-// intensity ranges between 0.0-1.0 - defines the contrast of the glowing image. A higher value will make the glow more prevelant.
+/** The intensity of the blurred out bloom image when added to the original
+ *  unmodified image. This value is in the range [0..1]. 0 results in no bloom
+ *  while higher values result in more bloom.
+ */
 @property (nonatomic) float intensity;
 
-// blurRadius number of pixels blur will extend to (6 is the maximum, because we are limited by the number
-// of varying variables that can be passed to a glsl program). TODO: create a slower bloom shader, that does not have this restriction.
+/** The size of the blur of the bloom image. This value is in the range [0..6].
+ */
 @property (nonatomic) NSUInteger blurRadius;
 
+
+/// -----------------------------------------------------------------------
+/// @name Initializing a CCEffectBloom object
+/// -----------------------------------------------------------------------
+
 /**
+ *  Initializes a CCEffectBloom object with the following default values:
+ *  blurRadius = 2, intensity = 1, luminanceThreshold = 0
+ *
+ *  @return The CCEffectBloom object.
+ */
+-(id)init;
+
+/**
+ *  Initializes a CCEffectBloom object with the following default parameters:
+ *
  *  @param blurRadius number of pixels blur will extend to (6 is the maximum, because we are limited by the number 
- *  of varying variables that can be passed to a glsl program). TODO: create a slower bloom shader, that does not have this restriction.
+ *  of varying variables that can be passed to a glsl program).
+ *
  *  @param intensity ranges between 0.0-1.0 - defines the contrast of the glowing image. A higher value will make the glow more prevelant.
- *  @param luminanceThreshold ranges between 0.0-1.0 - defines which part of the image should be glown via a luminance factor (brightness). 
+ *
+ *  @param luminanceThreshold ranges between 0.0-1.0 - defines which part of the image should be glown via a luminance factor (brightness).
  *  A value of 0.0 will apply bloom to the whole image, a value of 1.0 will only apply bloom to the brightest part of the image.
+ *
+ *  @return The CCEffectBloom object.
+ *
  */
--(id)init;
 -(id)initWithPixelBlurRadius:(NSUInteger)blurRadius intensity:(float)intensity luminanceThreshold:(float)luminanceThreshold;
+
+
+/// -----------------------------------------------------------------------
+/// @name Creating a CCEffectBloom object
+/// -----------------------------------------------------------------------
+
+/**
+ *  Creates a CCEffectBloom object with the specified parameters.
+ *
+ *  @param blurRadius number of pixels blur will extend to (6 is the maximum, because we are limited by the number
+ *  of varying variables that can be passed to a glsl program).
+ *
+ *  @param intensity ranges between 0.0-1.0 - defines the contrast of the glowing image. A higher value will make the glow more prevelant.
+ *
+ *  @param luminanceThreshold ranges between 0.0-1.0 - defines which part of the image should be glown via a luminance factor (brightness).
+ *  A value of 0.0 will apply bloom to the whole image, a value of 1.0 will only apply bloom to the brightest part of the image.
+ *
+ *  @return The CCEffectBloom object.
+ *
+ */
 +(id)effectWithPixelBlurRadius:(NSUInteger)blurRadius intensity:(float)intensity luminanceThreshold:(float)luminanceThreshold;
 
 @end

cocos2d/CCEffectBrightness.h

@@ -8,12 +8,59 @@
 
 #import "CCEffect.h"
 
+
+/**
+ * CCEffectBrightness adjusts the brightness of the sprite or effect node
+ * it is attached to.
+ *
+ */
+
 @interface CCEffectBrightness : CCEffect
 
+/// -----------------------------------------------------------------------
+/// @name Accessing Effect Attributes
+/// -----------------------------------------------------------------------
+
+/** The brightness adjustment value that is added to the pixel colors of the
+ *  affected node. This is a normalized value in the range of [-1..1]. A value 
+ *  of -1 reduces the affected color to 0 (black), 0 results in no change, 1
+ *  increases the affected color to 1 (white).
+ */
 @property (nonatomic) float brightness;
 
+
+/// -----------------------------------------------------------------------
+/// @name Initializing a CCEffectBrightness object
+/// -----------------------------------------------------------------------
+
+/**
+ *  Initializes a CCEffectBrightness object with a brightness adjustment of 0.
+ *
+ *  @return The CCEffectBrightness object.
+ */
 -(id)init;
+
+/**
+ *  Initializes a CCEffectBrightness object with the supplied parameters.
+ *
+ *  @param brightness The desired brightness adjustment.
+ * 
+ *  @return The CCEffectBrightness object.
+ */
 -(id)initWithBrightness:(float)brightness;
+
+
+/// -----------------------------------------------------------------------
+/// @name Creating a CCEffectBrightness object
+/// -----------------------------------------------------------------------
+
+/**
+ *  Creates a CCEffectBrightness object with the supplied parameters.
+ *
+ *  @param brightness The desired brightness adjustment.
+ *
+ *  @return The CCEffectBrightness object.
+ */
 +(id)effectWithBrightness:(float)brightness;
 
 @end

cocos2d/CCEffectContrast.h

@@ -8,12 +8,59 @@
 
 #import "CCEffect.h"
 
+/**
+ * CCEffectContrast adjusts the contrast of the sprite or effect node
+ * it is attached to.
+ *
+ */
+
 @interface CCEffectContrast : CCEffect
 
+/// -----------------------------------------------------------------------
+/// @name Accessing Effect Attributes
+/// -----------------------------------------------------------------------
+
+/** The contrast adjustment value that is used to scale the pixel colors of the
+ *  affected node. This value is in the range [-1..1], and the napping of this value
+ *  to the color scale factor is: pow(4.0, contrast). This means that
+ *  an adjustment value of -1 scales the affected color by 0.25, 0 results in no
+ *  change, and 1 scales the affected color by 4.
+ */
 @property (nonatomic) float contrast;
 
+
+/// -----------------------------------------------------------------------
+/// @name Initializing a CCEffectContrast object
+/// -----------------------------------------------------------------------
+
+/**
+ *  Initializes a CCEffectContrast object with a contrast adjustment of 0.
+ *
+ *  @return The CCEffectContrast object.
+ */
 -(id)init;
+
+/**
+ *  Initializes a CCEffectContrast object with the supplied parameters.
+ *
+ *  @param contrast The desired contrast adjustment.
+ *
+ *  @return The CCEffectContrast object.
+ */
 -(id)initWithContrast:(float)contrast;
+
+
+/// -----------------------------------------------------------------------
+/// @name Creating a CCEffectContrast object
+/// -----------------------------------------------------------------------
+
+/**
+ *  Initializes a CCEffectContrast object with the supplied parameters.
+ *
+ *  @param contrast The desired contrast adjustment.
+ *
+ *  @return The CCEffectContrast object.
+ */
 +(id)effectWithContrast:(float)contrast;
 
 @end

cocos2d/CCEffectGaussianBlur.h

@@ -8,18 +8,58 @@
 
 #import "CCEffect.h"
 
+
+/**
+ * CCEffectGaussianBlur performs blur operation on the pixels of the attached node.
+ */
+
 @interface CCEffectGaussianBlur : CCEffect
 
-// blurRadius number of pixels blur will extend to (6 is the maximum, because we are limited by the number
-// of varying variables that can be passed to a glsl program). TODO: create a slower bloom shader, that does not have this restriction.
+
+/// -----------------------------------------------------------------------
+/// @name Accessing Effect Attributes
+/// -----------------------------------------------------------------------
+
+/** The size of the blur. This value is in the range [0..6].
+ */
 @property (nonatomic) NSUInteger blurRadius;
 
+
+/// -----------------------------------------------------------------------
+/// @name Initializing a CCEffectGaussianBlur object
+/// -----------------------------------------------------------------------
+
 /**
- *  @param blurRadius number of pixels blur will extend to (6 is the maximum, because we are limited by the number
- *  of varying variables that can be passed to a glsl program). TODO: create a slower bloom shader, that does not have this restriction.
+ *  Initializes a CCEffectGaussianBlur object with the following default parameters:
+ *  blurRadius = 2
+ *
+ *  @return The CCEffectGaussianBlur object.
  */
 -(id)init;
+
+/**
+ *  Initializes a CCEffectGaussianBlur object with the specified parameters.
+ *
+ *  @param blurRadius number of pixels blur will extend to (6 is the maximum, because we are limited by the number
+ *  of varying variables that can be passed to a glsl program).
+ *
+ *  @return The CCEffectGaussianBlur object.
+ */
 -(id)initWithPixelBlurRadius:(NSUInteger)blurRadius;
+
+
+/// -----------------------------------------------------------------------
+/// @name Creating a CCEffectGaussianBlur object
+/// -----------------------------------------------------------------------
+
+/**
+ *  Creates a CCEffectGaussianBlur object with the specified parameters.
+ *
+ *  @param blurRadius number of pixels blur will extend to (6 is the maximum, because we are limited by the number
+ *  of varying variables that can be passed to a glsl program).
+ *
+ *  @return The CCEffectGaussianBlur object.
+ */
 +(id)effectWithPixelBlurRadius:(NSUInteger)blurRadius;
 
 @end

cocos2d/CCEffectGlass.h

@@ -8,17 +8,97 @@
 
 #import "CCEffect.h"
 
+/**
+ * CCEffectGlass uses reflection and refraction to simulate the appearance of a transparent object
+ * contained within an environment. Refraction is controlled with a single refraction strength value, 
+ * the normal map, and a refraction environment sprite. Reflection is controlled with two fresnel 
+ * reflectance values, the normal map, and a reflection environment sprite (which may be different 
+ * from the refraction environment).
+ *
+ */
 @interface CCEffectGlass : CCEffect
 
+/// -----------------------------------------------------------------------
+/// @name Accessing Effect Attributes
+/// -----------------------------------------------------------------------
+
+/** The refraction strength value. This value is in the range [-1..1] with -1
+ *  resulting in maximum minification of the refracted image, 0 resulting in no
+ *  refraction, and 1 resulting in maximum magnification of the refracted image.
+ */
 @property (nonatomic) float refraction;
+
+/** The bias term in the fresnel reflectance equation:
+ *    reflectance = max(0.0, fresnelBias + (1 - fresnelBias) * pow((1 - nDotV), fresnelPower))
+ *  This value is in the range [0..1] and it controls the constant (view angle independent) contribution 
+ *  to the reflectance equation.
+ */
 @property (nonatomic) float fresnelBias;
+
+/** The power term in the fresnel reflectance equation:
+ *    reflectance = max(0.0, fresnelBias + (1 - fresnelBias) * pow((1 - nDotV), fresnelPower))
+ *  This value is in the range [0..inf] and it controls the view angle dependent contribution
+ *  to the reflectance equation.
+ */
 @property (nonatomic) float fresnelPower;
+
+/** The environment that will be refracted by the affected node. Typically this is a 
+ *  sprite that serves as the background for the affected node so it appears that the viewer
+ *  is seeing the refracted environment through the refracting node.
+ */
 @property (nonatomic) CCSprite *refractionEnvironment;
+
+/** The environment that will be reflected by the affected node. Typically this is a sprite
+ *  that is not visible in the scene as it is conceptually "behind the viewer" and only visible
+ *  where reflected by the affected node.
+ */
 @property (nonatomic) CCSprite *reflectionEnvironment;
+
+/** The normal map that encodes the normal vectors of the affected node. Each pixel in the normal
+ *  map is a 3 component vector that is perpendicular to the surface of the sprite at that point.
+ */
 @property (nonatomic) CCSpriteFrame *normalMap;
 
+
+/// -----------------------------------------------------------------------
+/// @name Initializing a CCEffectGlass object
+/// -----------------------------------------------------------------------
+
+/**
+ *  Initializes a CCEffectGlass object with the following default parameters:
+ *  refraction = 1.0, fresnelBias = 0.1, fresnelPower = 2.0, refractionEnvironment = nil, reflectionEnvironment = nil, normalMap = nil
+ *
+ *  @return The CCEffectGlass object.
+ */
 -(id)init;
+
+/**
+ *  Initializes a CCEffectGlass object with the supplied parameters.
+ *
+ *  @param refraction The refraction strength.
+ *  @param refractionEnvironment The environment image that will be refracted by the affected node.
+ *  @param reflectionEnvironment The environment image that will be reflected by the affected node.
+ *  @param normalMap The normal map of the affected node. This can also be specified as a property of the affected sprite.
+ *
+ *  @return The CCEffectGlass object.
+ */
 -(id)initWithRefraction:(float)refraction refractionEnvironment:(CCSprite *)refractionEnvironment reflectionEnvironment:(CCSprite *)reflectionEnvironment normalMap:(CCSpriteFrame *)normalMap;
+
+
+/// -----------------------------------------------------------------------
+/// @name Creating a CCEffectGlass object
+/// -----------------------------------------------------------------------
+
+/**
+ *  Creates a CCEffectGlass object with the supplied parameters.
+ *
+ *  @param refraction The refraction strength.
+ *  @param refractionEnvironment The environment image that will be refracted by the affected node.
+ *  @param reflectionEnvironment The environment image that will be reflected by the affected node.
+ *  @param normalMap The normal map of the affected node. This can also be specified as a property of the affected sprite.
+ *
+ *  @return The CCEffectGlass object.
+ */
 +(id)effectWithRefraction:(float)refraction refractionEnvironment:(CCSprite *)refractionEnvironment reflectionEnvironment:(CCSprite *)reflectionEnvironment normalMap:(CCSpriteFrame *)normalMap;
 
 @end