[FFmpeg-devel] [PATCH] Doxument some of SwsContext.

[Kostya]

On Thu, Jan 14, 2010 at 04:13:36AM -0200, Ramiro Polla wrote:
> Hi,
> 
> This is an attempt to document most of SwsContext. It also reorders
> some fields and existing documentation around cosmetically.
> 
> I am not confident enough to document the yuv2rgb stuff since I still
> don't understand it (specially the tables generation). Michael,
> Kostya, could you please help out by describing a bit the cryptic
> variable names in ff_yuv2rgb_c_init_tables (such as yb) and the
> magical values (such as const int yoffs = fullRange ? 384 : 326;)?

Okay, here's the description.

 YUV2RGB conversion in principle performs by this formula:
 
 R = a*Y + b*Cr        = a*(Y + b/a * Cr)
 G = a*Y + c*Cr + d*Cb
 B = a*Y + e*Cb

 we can replace multiplying for R and B by lookup table which gives us
offset to Y values for input Cr or Cb. That offset is for scaled values
of Y too. For green component we should have an additional table for the
second chroma value.
And in C code:
  R = a*(Y + (b/a)* Cr);
  R = scaled_Y[Y + (b/a) * Cr];
  R = scaled_Y[Y + Cr_offset[b]]; //Cr_offset[] is integer
  if we make it Cr_offset[i] = &scaled_Y[i], then we can use
  R = Cr_offset[b][Y];

So far we have:
  c->yuvTable - scaled values of Y (aka a*Y)
  c->table_rV - LUT for red component
  c->table_bU - LUT for blue component
  c->table_gU - LUT for green component
  crv,cbu,cgu,cgv - scaling components (i.e b/a, c/a, d/a and e/a)
  c->table_gV - an additional LUT for green
  cy is exactly multiplier for Y (i.e. 'a')

Other variables:
  oy is an additional _o_ffset in _Y_ table for brightness manipulation
  yb is a _b_ase value for _Y_ table (i.e. its maximum or minimum) from
        which all values are derived (i.e. Y[i] = yb + a*i)

Now to range issues. As you may know, for different recommendations YUV
values may lay in range [0; 255] or [16; 239] and they both should map
to [0; 255] range in RGB. To achieve that Y value may be additionaly
scaled and some additional offset may be introduced, which is why yoffs
differs for full range.

Hope this helps.

> I believe it will take a few rounds to get most documentation ok, so
> I'd prefer if the good chunks were ok'd and could be applied in small
> steps instead of resending a new entire patch all the time.
> 
> Ramiro Polla