Comment all of *_effect.h.
authorSteinar H. Gunderson <sgunderson@bigfoot.com>
Wed, 3 Oct 2012 15:53:10 +0000 (17:53 +0200)
committerSteinar H. Gunderson <sgunderson@bigfoot.com>
Wed, 3 Oct 2012 15:53:10 +0000 (17:53 +0200)
blur_effect.h
colorspace_conversion_effect.h
gamma_compression_effect.h
gamma_expansion_effect.h
lift_gamma_gain_effect.frag
lift_gamma_gain_effect.h
mirror_effect.h
saturation_effect.h
vignette_effect.h

index ee890c2..0c7dccc 100644 (file)
@@ -1,6 +1,14 @@
 #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;
index 323526b..e3c60ea 100644 (file)
@@ -1,6 +1,13 @@
 #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"
 
index e4c79ab..4c77b4c 100644 (file)
@@ -1,6 +1,12 @@
 #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"
 
index f3e20c5..7992617 100644 (file)
@@ -1,6 +1,12 @@
 #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"
 
index 80e04d0..43766a6 100644 (file)
@@ -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.
index 6364eeb..b57a899 100644 (file)
@@ -1,6 +1,22 @@
 #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 {
index 6b07ea9..0526c25 100644 (file)
@@ -1,6 +1,8 @@
 #ifndef _MIRROR_EFFECT_H
 #define _MIRROR_EFFECT_H 1
 
+// A simple horizontal mirroring.
+
 #include "effect.h"
 
 class MirrorEffect : public Effect {
index 6cfc3d0..180210c 100644 (file)
@@ -1,6 +1,12 @@
 #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 {
index 82c648c..c9a08bf 100644 (file)
@@ -1,6 +1,9 @@
 #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 {