Comment all of *_effect.h.

diff --git a/blur_effect.h b/blur_effect.h
index ee890c25543fa41599e67d3e9284bfd68d8ee196..0c7dccc826b9ae9ccb4be6b352aa1e288fb787e9 100644 (file)
--- a/blur_effect.h
+++ b/blur_effect.h
@@ -1,6 +1,14 @@
 #ifndef _BLUR_EFFECT_H
 #define _BLUR_EFFECT_H 1
 
 #ifndef _BLUR_EFFECT_H
 #define _BLUR_EFFECT_H 1
 

+// A separable 2D blur implemented by a combination of mipmap filtering
+// and convolution (essentially giving a convolution with a piecewise linear
+// approximation to the true impulse response).
+//
+// Works in two passes; first horizontal, then vertical (BlurEffect,
+// which is what the user is intended to use, instantiates two copies of
+// SingleBlurPassEffect behind the scenes).
+

 #include "effect.h"
 
 class SingleBlurPassEffect;
 #include "effect.h"
 
 class SingleBlurPassEffect;

diff --git a/colorspace_conversion_effect.h b/colorspace_conversion_effect.h
index 323526b4978d53a9250b352be56371e5082d800a..e3c60ea81730af2a2eaaffe0370e23b3a71cf35c 100644 (file)
--- a/colorspace_conversion_effect.h
+++ b/colorspace_conversion_effect.h
@@ -1,6 +1,13 @@
 #ifndef _COLORSPACE_CONVERSION_EFFECT_H
 #define _COLORSPACE_CONVERSION_EFFECT_H 1
 
 #ifndef _COLORSPACE_CONVERSION_EFFECT_H
 #define _COLORSPACE_CONVERSION_EFFECT_H 1
 

+// An effect to convert between different color spaces.
+// Can convert freely between sRGB/Rec. 709 and the two different Rec. 601
+// color spaces (which thankfully have the same white point).
+//
+// We don't do any fancy gamut mapping or similar; colors that are out-of-gamut
+// will simply stay out-of-gamut, and probably clip in the output stage.
+

 #include "effect.h"
 #include "effect_chain.h"
 
 #include "effect.h"
 #include "effect_chain.h"
 

diff --git a/gamma_compression_effect.h b/gamma_compression_effect.h
index e4c79ab0c9faac750e877a84d5b7d768a65ef8ab..4c77b4c2cb2268af48f662b321cdfe4e2972a68f 100644 (file)
--- a/gamma_compression_effect.h
+++ b/gamma_compression_effect.h
@@ -1,6 +1,12 @@
 #ifndef _GAMMA_COMPRESSION_EFFECT_H 
 #define _GAMMA_COMPRESSION_EFFECT_H 1
 
 #ifndef _GAMMA_COMPRESSION_EFFECT_H 
 #define _GAMMA_COMPRESSION_EFFECT_H 1
 

+// An effect to convert linear light to the given gamma curve,
+// typically inserted by the framework automatically at the end
+// of the processing chain.
+//
+// Currently supports sRGB and Rec. 601/709.
+

 #include "effect.h"
 #include "effect_chain.h"
 
 #include "effect.h"
 #include "effect_chain.h"
 

diff --git a/gamma_expansion_effect.h b/gamma_expansion_effect.h
index f3e20c59ed95eba6030750cb04bf1846b37898fe..79926176ddf21688b80a8739ed991ec701d00b81 100644 (file)
--- a/gamma_expansion_effect.h
+++ b/gamma_expansion_effect.h
@@ -1,6 +1,12 @@
 #ifndef _GAMMA_EXPANSION_EFFECT_H 
 #define _GAMMA_EXPANSION_EFFECT_H 1
 
 #ifndef _GAMMA_EXPANSION_EFFECT_H 
 #define _GAMMA_EXPANSION_EFFECT_H 1
 

+// An effect to convert the given gamma curve into linear light,
+// typically inserted by the framework automatically at the beginning
+// of the processing chain.
+//
+// Currently supports sRGB and Rec. 601/709.
+

 #include "effect.h"
 #include "effect_chain.h"
 
 #include "effect.h"
 #include "effect_chain.h"
 

diff --git a/lift_gamma_gain_effect.frag b/lift_gamma_gain_effect.frag
index 80e04d0659d52969bc287ffa3d96dca4010e129d..43766a6265218621888cbf7a11ffe862ddb0fbba 100644 (file)
--- a/lift_gamma_gain_effect.frag
+++ b/lift_gamma_gain_effect.frag
@@ -1,10 +1,3 @@
-// Standard lift/gamma/gain color correction tools.
-//
-// We do lift in a nonlinear (gamma-2.2) space since that looks a lot better
-// than in linear (blacks stay a lot closer to black). The two others don't
-// really care; they are (sans some constants) commutative with the x^2.2
-// operation.
-

 // These are calculated in the host code to save some arithmetic.
 uniform vec3 PREFIX(gain_pow_inv_gamma);  // gain^(1/gamma).
 uniform vec3 PREFIX(inv_gamma_22);  // 2.2 / gamma.
 // These are calculated in the host code to save some arithmetic.
 uniform vec3 PREFIX(gain_pow_inv_gamma);  // gain^(1/gamma).
 uniform vec3 PREFIX(inv_gamma_22);  // 2.2 / gamma.

diff --git a/lift_gamma_gain_effect.h b/lift_gamma_gain_effect.h
index 6364eeb00b6c41b79f894b1da231cb44cdfac240..b57a89964204fa5622635ac852d8678721a090ce 100644 (file)
--- a/lift_gamma_gain_effect.h
+++ b/lift_gamma_gain_effect.h
@@ -1,6 +1,22 @@
 #ifndef _LIFT_GAMMA_GAIN_EFFECT_H
 #define _LIFT_GAMMA_GAIN_EFFECT_H 1
 
 #ifndef _LIFT_GAMMA_GAIN_EFFECT_H
 #define _LIFT_GAMMA_GAIN_EFFECT_H 1
 

+// A simple lift/gamma/gain effect, used for color grading.
+//
+// Very roughly speaking, lift=shadows, gamma=midtones and gain=highlights,
+// although all parameters affect the entire curve. Mathematically speaking,
+// it is a bit unusual to look at gamma as a color, but it works pretty well
+// in practice.
+//
+// The classic formula is: output = (gain * (x + lift * (1-x)))^(1/gamma).
+//
+// The lift is actually a case where we actually would _not_ want linear light;
+// since black by definition becomes equal to the lift color, we want lift to
+// be pretty close to black, but in linear light that means lift affects the
+// rest of the curve relatively little. Thus, we actually convert to gamma 2.2
+// before lift, and then back again afterwards. (Gain and gamma are,
+// up to constants, commutative with the de-gamma operation.)
+

 #include "effect.h"
 
 class LiftGammaGainEffect : public Effect {
 #include "effect.h"
 
 class LiftGammaGainEffect : public Effect {

diff --git a/mirror_effect.h b/mirror_effect.h
index 6b07ea9433622e0b93c87b319d1ee31267978d68..0526c25bcb869a9e50da2885a20988bdf514e4ab 100644 (file)
--- a/mirror_effect.h
+++ b/mirror_effect.h
@@ -1,6 +1,8 @@
 #ifndef _MIRROR_EFFECT_H
 #define _MIRROR_EFFECT_H 1
 
 #ifndef _MIRROR_EFFECT_H
 #define _MIRROR_EFFECT_H 1
 

+// A simple horizontal mirroring.
+

 #include "effect.h"
 
 class MirrorEffect : public Effect {
 #include "effect.h"
 
 class MirrorEffect : public Effect {

diff --git a/saturation_effect.h b/saturation_effect.h
index 6cfc3d0ee0392c49d18e5a0b3f782c40fc5889e9..180210c7edc9682e97ca7db77ae2c78e62287543 100644 (file)
--- a/saturation_effect.h
+++ b/saturation_effect.h
@@ -1,6 +1,12 @@
 #ifndef _SATURATION_EFFECT_H
 #define _SATURATION_EFFECT_H 1
 
 #ifndef _SATURATION_EFFECT_H
 #define _SATURATION_EFFECT_H 1
 

+// A simple desaturation/saturation effect. We use the Rec. 709
+// definition of luminance (in linear light, of course) and linearly
+// interpolate between that (saturation=0) and the original signal
+// (saturation=1). Extrapolating that curve further (ie., saturation > 1)
+// gives us increased saturation if so desired.
+

 #include "effect.h"
 
 class SaturationEffect : public Effect {
 #include "effect.h"
 
 class SaturationEffect : public Effect {

diff --git a/vignette_effect.h b/vignette_effect.h
index 82c648cf7b3f834ee876b8dbb89dac3150f4820f..c9a08bfd8f85091ec711175b274de77cb9b09359 100644 (file)
--- a/vignette_effect.h
+++ b/vignette_effect.h
@@ -1,6 +1,9 @@
 #ifndef _VIGNETTE_EFFECT_H
 #define _VIGNETTE_EFFECT_H 1
 
 #ifndef _VIGNETTE_EFFECT_H
 #define _VIGNETTE_EFFECT_H 1
 

+// A circular vignette, falling off as cos² of the distance from the center
+// (the classic formula for approximating a real lens).
+

 #include "effect.h"
 
 class VignetteEffect : public Effect {
 #include "effect.h"
 
 class VignetteEffect : public Effect {