2016 README updates.
[movit] / README
1 <!-- Author's note; this was intended to become a home page at some point,
2      but I'm not interested enough in grokking HTML right now, so it became
3      the README instead. Most of it should be valid Markdown. -->
4
5 Announcing Movit
6 ================
7
8 Movit is the Modern Video Toolkit, notwithstanding that anything that's
9 called “modern” usually isn't, and it's really not a toolkit.
10
11 Movit aims to be a _high-quality_, _high-performance_, _open-source_
12 library for video filters.
13
14
15 TL;DR, please give me download link and system demands
16 ======================================================
17
18 OK, you need
19
20 * A C++98 compiler. GCC will do. (I haven't tried Windows, but it
21   works fine on Linux and OS X, and Movit is not very POSIX-bound.)
22 * GNU Make.
23 * A GPU capable of running GLSL fragment shaders,
24   processing floating-point textures, and a few other things (all are
25   part of OpenGL 3.0 or newer, although most OpenGL 2.0 cards also
26   have what's needed through extensions). If your machine is less than five
27   years old _and you have the appropriate drivers_, you're home free.
28   GLES3 (for mobile devices) will also work.
29 * The [Eigen 3], [FFTW3] and [Google Test] libraries. (The library itself
30   does not depend on the latter, but you probably want to run the unit tests.)
31 * The [epoxy] library, for dealing with OpenGL extensions on various
32   platforms.
33
34 Movit has been tested with Intel GPUs with the Mesa drivers
35 (you'll probably need at least Mesa 8.0), Radeon 3850 and GeForce GTX 550
36 on Linux with the manufacturer's drivers, and with GeForce 8800 on OS X.
37 Again, most likely, GPU compatibility shouldn't be a big issue. See below
38 for performance estimates.
39
40
41 Still TL;DR, please give me the list of filters
42 ===============================================
43
44 Blur, diffusion, FFT-based convolution, glow, lift/gamma/gain (color
45 correction), mirror, mix (add two inputs), luma mix (use a map to wipe between
46 two inputs), overlay (the Porter-Duff “over” operation), scale (bilinear and
47 Lanczos), sharpen (both by unsharp mask and by Wiener filters), saturation
48 (or desaturation), vignette, white balance, and a deinterlacer (YADIF).
49
50 Yes, that's a short list. But they all look great, are fast and don't give
51 you any nasty surprises. (I'd love to include denoise and
52 framerate up-/downconversion to the list, but doing them well are
53 all research-grade problems, and Movit is currently not there.)
54
55
56 TL;DR, but I am interested in a programming example instead
57 ===========================================================
58
59 Assuming you have an OpenGL context already set up (either a classic OpenGL
60 context, a GL 3.x forward-compatible or core context, or a GLES3 context):
61
62 <code>
63   using namespace movit;
64   EffectChain chain(1280, 720);
65
66   ImageFormat inout_format;
67   inout_format.color_space = COLORSPACE_sRGB;
68   inout_format.gamma_curve = GAMMA_sRGB;
69   FlatInput *input = new FlatInput(inout_format, FORMAT_BGRA_POSTMULTIPLIED_ALPHA, GL_UNSIGNED_BYTE, 1280, 720));
70   chain.add_input(input);
71
72   Effect *saturation_effect = chain.add_effect(new SaturationEffect());
73   saturation_effect->set_float("saturation", 0.7f);
74
75   Effect *lift_gamma_gain_effect = chain.add_effect(new LiftGammaGainEffect());
76   const float gain[] = { 0.8f, 1.0f, 1.0f };
77   lift_gamma_gain_effect->set_vec3("gain", &gain);
78
79   chain.add_output(inout_format, OUTPUT_ALPHA_FORMAT_POSTMULTIPLIED);
80   chain.finalize();
81
82   for ( ;; ) {
83     // Do whatever you need here to decode the next frame into <pixels>.
84     input->set_pixel_data(pixels);
85     chain.render_to_screen();
86   }
87 </code>
88
89
90 OK, I can read a bit. What do you mean by “modern”?
91 ===================================================
92
93 Backwards compatibility is fine and all, but sometimes we can do better
94 by observing that the world has moved on. In particular:
95
96 * It's 2016, so people want to edit HD video.
97 * It's 2016, so everybody has a GPU.
98 * It's 2016, so everybody has a working C++ compiler.
99   (Even Microsoft fixed theirs around 2003!)
100
101 While from a programming standpoint I'd love to say that it's 2016
102 and interlacing does no longer exist, but that's not true (and interlacing,
103 hated as it might be, is actually a useful and underrated technique for
104 bandwidth reduction in broadcast video). Movit may eventually provide
105 limited support for working with interlaced video; it has a deinterlacer,
106 but cannot currently process video in interlaced form.
107
108
109 What do you mean by “high-performance”?
110 =======================================
111
112 Today, you can hardly get a _cellphone_ without a multi-core, SIMD-capable
113 CPU, and a GPU. Yet, almost all open-source pixel processing I've seen
114 is written using straight-up single-threaded, scalar C! Clearly there is
115 room for improvement here, and that improvement is sorely needed.
116 We want to edit 1080p video, not watch slideshows.
117
118 Movit has chosen to run all pixel processing on the GPU, using GLSL—OpenCL is
119 way too young, and CUDA is single-vendor (and also surprisingly hard to
120 get good performance from for anything nontrivial). While “run on the GPU”
121 does not equal “infinite speed” (I am fairly certain that for many common
122 filters, I can beat the Intel-based GPU in my laptop with multithreaded SSE
123 code on the CPU—especially as moving the data to and from the GPU has a cost that is not
124 to be taken lightly), GPU programming is probably the _simplest_ way of writing
125 highly parallel code, and it also frees the CPU to do other things like video
126 decoding.
127
128 Exactly what speeds you can expect is of course highly dependent on
129 your GPU and the exact filter chain you are running. As a rule of thumb,
130 you can run a reasonable filter chain (a lift/gamma/gain operation,
131 a bit of diffusion, maybe a vignette) at 720p in around 30 fps on a four-year-old
132 Intel laptop. If you have a somewhat newer Intel card, you can do 1080p
133 video without much problems. And on a low-range nVidia card of today
134 (GTX 550 Ti), you can probably process 4K movies directly.
135
136
137 What do you mean by “high-quality”?
138 ===================================
139
140 Movit aims to be high-quality in two important aspects, namely _code quality_
141 and _output quality_. (Unfortunately, documentation quality is not on the
142 list yet. Sorry.)
143
144
145 High-quality output?
146 ====================
147
148 Movit works internally in linear floating-point all the way, strongly
149 reducing interim round-off and clipping errors. Furthermore, Movit is
150 (weakly) colorspace-aware. Why do colorspaces matter? Well, here's a video frame from a typical
151 camera, which records in Rec. 709 (the typical HDTV color space), and here's the 
152 same frame misinterpreted as Rec. 601 (the typical SDTV color space):
153
154 [insert picture here]
155
156 The difference might be subtle, but would you like that color cast?
157 Maybe you could correct for it manually, but what if it happened on output
158 instead of on input? And I can promise you that once we move to more
159 wide-gamut color spaces, like the one in Rec. 2020 (used for UHDTV), the
160 difference will be anything but subtle. As of [why working in linear
161 light matters](http://www.4p8.com/eric.brasseur/gamma.html),
162 others have explained it better than I can; note also that this makes Movit
163 future-proof when the world moves towards 10- and 12-bit color precision
164 (although the latter requires Movit to change from 16-bit to 32-bit floating
165 point, it is a simple switch). The extra power from the GPU makes all of this
166 simple, so do we not need to make too many concessions for the sake of speed.
167
168 Movit does not currently do ICC profiles or advanced gamut mapping;
169 if you have out-of-gamut colors, they will clip. Sorry.
170
171
172 OK, and high-quality code?
173 ==========================
174
175 Image processing code can be surprisingly subtle; it's easy to write
176 code that looks right, but that makes subtle artifacts that explode
177 when processed further in a later step. (Or code that simply never
178 worked, just that nobody cared to look at the output when a given
179 parameter was set. I've seen that, too.)
180
181 Movit tries to counteract this by three different strategies:
182
183 * First, _look at the output_. Does it look good? Really?
184   Even if you zoom in on the results? Don't settle for “meh, I'm 
185   sure that's the best it can get”.
186 * Second, _keep things simple_. Movit does not aim for including
187   every possible video effect under the sun (there are [others out there]
188   that want that); the [YAGNI] principle is applied quite strongly throughout
189   the code. It's much better to write less code but actually
190   understand what it does; whenever I can replace some magic matrix
191   or obscure formula from the web with a clean calculation and a descriptive
192   comment on top, it makes me a bit happier. (Most of the time,
193   it turns out that I had used the matrix or formula in a wrong
194   way anyway. My degree is in multimedia signal processing, but it
195   does not mean I have a deep understanding of everything people do
196   in graphics.)
197 * Third, _have unit tests_. Tests are boring, but they are unforgiving
198   (much more unforgiving than your eye), and they keep stuff from breaking
199   afterwards. Almost every single test I wrote has uncovered bugs in Movit,
200   so they have already paid for themselves.
201
202 There is, of course, always room for improvement. I'm sure you can find
203 things that are stupid, little-thought-out, or buggy. If so, please let me
204 know.
205
206
207 What do you mean by “open-source”?
208 ==================================
209
210 Movit is licensed under the [GNU GPL](http://www.gnu.org/licenses/gpl.html),
211 either version 2 or (at your option) any later version.