From: Steinar H. Gunderson <sgunderson@bigfoot.com>
Date: Wed, 3 Oct 2012 15:53:10 +0000 (+0200)
Subject: Comment all of *_effect.h.
X-Git-Tag: 1.0~401
X-Git-Url: https://git.sesse.net/?p=movit;a=commitdiff_plain;h=e8650c7b7814c5beef59059b8acac3e5e7b8ddc6;ds=sidebyside

Comment all of *_effect.h.
---

diff --git a/blur_effect.h b/blur_effect.h
index ee890c2..0c7dccc 100644
--- a/blur_effect.h
+++ b/blur_effect.h
@@ -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;
diff --git a/colorspace_conversion_effect.h b/colorspace_conversion_effect.h
index 323526b..e3c60ea 100644
--- 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
 
+// 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"
 
diff --git a/gamma_compression_effect.h b/gamma_compression_effect.h
index e4c79ab..4c77b4c 100644
--- 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
 
+// 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"
 
diff --git a/gamma_expansion_effect.h b/gamma_expansion_effect.h
index f3e20c5..7992617 100644
--- 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
 
+// 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"
 
diff --git a/lift_gamma_gain_effect.frag b/lift_gamma_gain_effect.frag
index 80e04d0..43766a6 100644
--- 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.
diff --git a/lift_gamma_gain_effect.h b/lift_gamma_gain_effect.h
index 6364eeb..b57a899 100644
--- 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
 
+// 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 {
diff --git a/mirror_effect.h b/mirror_effect.h
index 6b07ea9..0526c25 100644
--- a/mirror_effect.h
+++ b/mirror_effect.h
@@ -1,6 +1,8 @@
 #ifndef _MIRROR_EFFECT_H
 #define _MIRROR_EFFECT_H 1
 
+// A simple horizontal mirroring.
+
 #include "effect.h"
 
 class MirrorEffect : public Effect {
diff --git a/saturation_effect.h b/saturation_effect.h
index 6cfc3d0..180210c 100644
--- a/saturation_effect.h
+++ b/saturation_effect.h
@@ -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 {
diff --git a/vignette_effect.h b/vignette_effect.h
index 82c648c..c9a08bf 100644
--- a/vignette_effect.h
+++ b/vignette_effect.h
@@ -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 {