title: Does H.264 encoded video with BT.709 matrix include any gamma adjustment?
body: <p>I have read the <a href="https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.709-6-201506-I!!PDF-E.pdf" rel="noreferrer">BT.709 spec</a> a number of times and the thing that is just not clear is should an encoded H.264 bitstream actually apply any gamma curve to the encoded data? Note the specific mention of a gamma like formula in the BT.709 spec. Apple provided examples of OpenGL or Metal shaders that read YUV data from CoreVideo provided buffers do not do any sort of gamma adjustment. YUV values are being read and processed as though they are simple linear values. I also examined the source code of ffmpeg and found no gamma adjustments being applied after the BT.709 scaling step. I then <a href="https://stackoverflow.com/a/53806290/763355">created a test video</a> with just two linear grayscale colors 5 and 26 corresponding to 2% and 10% levels. When converted to H.264 with both ffmpeg and iMovie, the output BT.709 values are (YCbCr) (20 128 128) and (38 128 128) and these values exactly match the output of the BT.709 conversion matrix without any gamma adjustment.</p>
  
  <p>A great piece of background on this topic can be found at <a href="https://vitrolite.wordpress.com/2010/12/31/quicktime_gamma_bug/" rel="noreferrer">Quicktime Gamma Bug</a>. It seems that some historical issues with Quicktime and Adobe encoders were improperly doing different gamma adjustments and the results made video streams look awful on different players. This is really confusing because if you compare to <a href="https://en.wikipedia.org/wiki/SRGB" rel="noreferrer">sRGB</a>, it clearly indicates how to apply a gamma encoding and then decode it to convert between sRGB and linear. Why does BT.709 go into so much detail about the same sort of gamma adjustment curve if no gamma adjustment is applied after the matrix step when creating a h.264 data stream? Are all the color steps in a h.264 stream meant to be coded as straight linear (gamma 1.0) values?</p>
  
  <p>In case specific example input would make things more clear, I am attaching 3 color bar images, the exact values of different colors can be displayed in an image editor with these image files.</p>
  
  <p>This first image is in the sRGB colorspace and is tagged as sRGB.</p>
  
  <p><a href="https://i.stack.imgur.com/gTqot.png" rel="noreferrer"><img src="https://i.stack.imgur.com/gTqot.png" alt="sRGB colorspace"></a></p>
  
  <p>This second image has been converted to the linear RGB colorspace and is tagged with a linear RGB profile.</p>
  
  <p><a href="https://i.stack.imgur.com/FpVNn.png" rel="noreferrer"><img src="https://i.stack.imgur.com/FpVNn.png" alt="linear RGB colorspace"></a></p>
  
  <p>This third image has been converted to REC.709 profile levels with Rec709-elle-V4-rec709.icc from <a href="https://github.com/ellelstone/elles_icc_profiles" rel="noreferrer">elles_icc_profiles
  </a>. This seems to be what one would need to do to simulate "camera" gamma as described in BT.709.</p>
  
  <p><a href="https://i.stack.imgur.com/EkjUn.png" rel="noreferrer"><img src="https://i.stack.imgur.com/EkjUn.png" alt="BT.709 colorspace ICC"></a></p>
  
  <p>Note how the sRGB value in the lower right corner (0x555555) becomes linear RGB (0x171717) and the BT.709 gamma encoded value becomes (0x464646). What is unclear is if I should be passing a linear RGB value into ffmpeg or if I should be passing an already BT.709 gamma encoded value which would then need to be decoded in the client before the linear conversion Matrix step to get back to RGB.</p>
  
  <p>Update:</p>
  
  <p>Based on the feedback, I have updated my C based implementation and Metal shader and uploaded to github as an iOS example project <a href="https://github.com/mdejong/MetalBT709Decoder" rel="noreferrer">MetalBT709Decoder</a>.</p>
  
  <p>Encoding a normalized linear RGB value is implemented like this:</p>
  
  <pre><code>static inline
  int BT709_convertLinearRGBToYCbCr(
                              float Rn,
                              float Gn,
                              float Bn,
                              int *YPtr,
                              int *CbPtr,
                              int *CrPtr,
                              int applyGammaMap)
  {
    // Gamma adjustment to non-linear value
  
    if (applyGammaMap) {
      Rn = BT709_linearNormToNonLinear(Rn);
      Gn = BT709_linearNormToNonLinear(Gn);
      Bn = BT709_linearNormToNonLinear(Bn);
    }
  
    // https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.709-6-201506-I!!PDF-E.pdf
  
    float Ey = (Kr * Rn) + (Kg * Gn) + (Kb * Bn);
    float Eb = (Bn - Ey) / Eb_minus_Ey_Range;
    float Er = (Rn - Ey) / Er_minus_Ey_Range;
  
    // Quant Y to range [16, 235] (inclusive 219 values)
    // Quant Eb, Er to range [16, 240] (inclusive 224 values, centered at 128)
  
    float AdjEy = (Ey * (YMax-YMin)) + 16;
    float AdjEb = (Eb * (UVMax-UVMin)) + 128;
    float AdjEr = (Er * (UVMax-UVMin)) + 128;
  
    *YPtr = (int) round(AdjEy);
    *CbPtr = (int) round(AdjEb);
    *CrPtr = (int) round(AdjEr);
  
    return 0;
  }
  </code></pre>
  
  <p>Decoding from YCbCr to linear RGB is implemented like so:</p>
  
  <pre><code>static inline
  int BT709_convertYCbCrToLinearRGB(
                               int Y,
                               int Cb,
                               int Cr,
                               float *RPtr,
                               float *GPtr,
                               float *BPtr,
                               int applyGammaMap)
  {
    // https://en.wikipedia.org/wiki/YCbCr#ITU-R_BT.709_conversion
    // http://www.niwa.nu/2013/05/understanding-yuv-values/
  
    // Normalize Y to range [0 255]
    //
    // Note that the matrix multiply will adjust
    // this byte normalized range to account for
    // the limited range [16 235]
  
    float Yn = (Y - 16) * (1.0f / 255.0f);
  
    // Normalize Cb and CR with zero at 128 and range [0 255]
    // Note that matrix will adjust to limited range [16 240]
  
    float Cbn = (Cb - 128) * (1.0f / 255.0f);
    float Crn = (Cr - 128) * (1.0f / 255.0f);
  
    const float YScale = 255.0f / (YMax-YMin);
    const float UVScale = 255.0f / (UVMax-UVMin);
  
    const
    float BT709Mat[] = {
      YScale,   0.000f,  (UVScale * Er_minus_Ey_Range),
      YScale, (-1.0f * UVScale * Eb_minus_Ey_Range * Kb_over_Kg),  (-1.0f * UVScale * Er_minus_Ey_Range * Kr_over_Kg),
      YScale, (UVScale * Eb_minus_Ey_Range),  0.000f,
    };
  
    // Matrix multiply operation
    //
    // rgb = BT709Mat * YCbCr
  
    // Convert input Y, Cb, Cr to normalized float values
  
    float Rn = (Yn * BT709Mat[0]) + (Cbn * BT709Mat[1]) + (Crn * BT709Mat[2]);
    float Gn = (Yn * BT709Mat[3]) + (Cbn * BT709Mat[4]) + (Crn * BT709Mat[5]);
    float Bn = (Yn * BT709Mat[6]) + (Cbn * BT709Mat[7]) + (Crn * BT709Mat[8]);
  
    // Saturate normalzied linear (R G B) to range [0.0, 1.0]
  
    Rn = saturatef(Rn);
    Gn = saturatef(Gn);
    Bn = saturatef(Bn);
  
    // Gamma adjustment for RGB components after matrix transform
  
    if (applyGammaMap) {
      Rn = BT709_nonLinearNormToLinear(Rn);
      Gn = BT709_nonLinearNormToLinear(Gn);
      Bn = BT709_nonLinearNormToLinear(Bn);
    }
  
    *RPtr = Rn;
    *GPtr = Gn;
    *BPtr = Bn;
  
    return 0;
  }
  </code></pre>
  
  <p>I believe this logic is implemented correctly, but I am having a very difficult time validating the results. When I generate a .m4v file that contains gamma adjusted color values (osxcolor_test_image_24bit_BT709.m4v), the result come out as expected. But a test case like (bars_709_Frame01.m4v) that I found <a href="https://lists.libav.org/pipermail/ffmpeg-user/2010-December/028210.html" rel="noreferrer">here</a> does not seem to work as the color bar values seem to be encoded as linear (no gamma adjustment).</p>
  
  <p>For a SMPTE test pattern, the 0.75 graylevel is linear RGB (191 191 191), should this RGB be encoded with no gamma adjustment as (Y Cb Cr) (180 128 128) or should the value in the bitstream appear as the gamma adjusted (Y Cb Cr) (206 128 128)?</p>
  
  <p>(follow up)
  After doing additional research into this gamma issue, it has become clear that what Apple is actually doing in AVFoundation is using a 1.961 gamma function. This is the case when encoding with AVAssetWriterInputPixelBufferAdaptor, when using vImage, or with CoreVideo APIs. This piecewise gamma function is defined as follows:</p>
  
  <pre><code>#define APPLE_GAMMA_196 (1.960938f)
  
  static inline
  float Apple196_nonLinearNormToLinear(float normV) {
    const float xIntercept = 0.05583828f;
  
    if (normV &lt; xIntercept) {
      normV *= (1.0f / 16.0f);
    } else {
      const float gamma = APPLE_GAMMA_196;
      normV = pow(normV, gamma);
    }
  
    return normV;
  }
  
  static inline
  float Apple196_linearNormToNonLinear(float normV) {
    const float yIntercept = 0.00349f;
  
    if (normV &lt; yIntercept) {
      normV *= 16.0f;
    } else {
      const float gamma = 1.0f / APPLE_GAMMA_196;
      normV = pow(normV, gamma);
    }
  
    return normV;
  }
  </code></pre>