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