markdown/additional/design/interlaced-video.md

   1 # Interlaced Video
   2
   3 Video buffers have a number of states identifiable through a combination
   4 of caps and buffer flags.
   5
   6 Possible states:
   7 - Progressive
   8 - Interlaced
   9  - Plain
  10   - One field
  11   - Two fields
  12   - Three fields - this should be a progressive buffer with a repeated 'first'
  13     field that can be used for telecine pulldown
  14  - Telecine
  15    - One field
  16    - Two fields
  17     - Progressive
  18     - Interlaced (a.k.a. 'mixed'; the fields are from different frames)
  19    - Three fields - this should be a progressive buffer with a repeated 'first'
  20      field that can be used for telecine pulldown
  21
  22 Note: It can be seen that the difference between the plain interlaced
  23 and telecine states is that in the latter, buffers containing
  24 two fields may be progressive.
  25
  26 Tools for identification:
  27  - `GstVideoInfo`
  28   - `GstVideoInterlaceMode` - enum `GST_VIDEO_INTERLACE_MODE_...`
  29    - PROGRESSIVE
  30    - INTERLEAVED
  31    - MIXED
  32  - Buffers flags - `GST_VIDEO_BUFFER_FLAG_...`
  33    - TFF
  34    - RFF
  35    - ONEFIELD
  36    - INTERLACED
  37
  38 ## Identification of Buffer States
  39
  40 Note that flags are not necessarily interpreted in the same way for all
  41 different states nor are they necessarily required nor make sense in all
  42 cases.
  43
  44 ### Progressive
  45
  46 If the interlace mode in the video info corresponding to a buffer is
  47 **"progressive"**, then the buffer is progressive.
  48
  49 ### Plain Interlaced
  50
  51 If the video info interlace mode is **"interleaved"**, then the buffer is
  52 plain interlaced.
  53
  54 `GST_VIDEO_BUFFER_FLAG_TFF` indicates whether the top or bottom field
  55 is to be displayed first. The timestamp on the buffer corresponds to the
  56 first field.
  57
  58 `GST_VIDEO_BUFFER_FLAG_RFF` indicates that the first field (indicated
  59 by the TFF flag) should be repeated. This is generally only used for
  60 telecine purposes but as the telecine state was added long after the
  61 interlaced state was added and defined, this flag remains valid for
  62 plain interlaced buffers.
  63
  64 `GST_VIDEO_BUFFER_FLAG_ONEFIELD` means that only the field indicated
  65 through the TFF flag is to be used. The other field should be ignored.
  66
  67 ### Telecine
  68
  69 If video info interlace mode is **"mixed"** then the buffers are in some
  70 form of telecine state.
  71
  72 The `TFF` and `ONEFIELD` flags have the same semantics as for the plain
  73 interlaced state.
  74
  75 `GST_VIDEO_BUFFER_FLAG_RFF` in the telecine state indicates that the
  76 buffer contains only repeated fields that are present in other buffers
  77 and are as such unneeded. For example, in a sequence of three telecined
  78 frames, we might have:
  79
  80     AtAb AtBb BtBb
  81
  82 In this situation, we only need the first and third buffers as the
  83 second buffer contains fields present in the first and third.
  84
  85 Note that the following state can have its second buffer identified
  86 using the `ONEFIELD` flag (and `TFF` not set):
  87
  88     AtAb AtBb BtCb
  89
  90 The telecine state requires one additional flag to be able to identify
  91 progressive buffers.
  92
  93 The presence of the `GST_VIDEO_BUFFER_FLAG_INTERLACED` means that the
  94 buffer is an 'interlaced' or 'mixed' buffer that contains two fields
  95 that, when combined with fields from adjacent buffers, allow
  96 reconstruction of progressive frames. The absence of the flag implies
  97 the buffer containing two fields is a progressive frame.
  98
  99 For example in the following sequence, the third buffer would be mixed
 100 (yes, it is a strange pattern, but it can happen):
 101
 102     AtAb AtBb BtCb CtDb DtDb
 103
 104 ### Alternate fields
 105
 106 Since: 1.16
 107
 108 If the video info interlace mode is **"alternate"**, then each buffer
 109 carries a single field of interlaced video.
 110
 111 `GST_VIDEO_BUFFER_FLAG_TOP_FIELD` and `GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD`
 112 indicate whether the buffer carries a top or bottom field. The order of
 113 buffers/fields in the stream and the timestamps on the buffers indicate the
 114 temporal order of the fields.
 115
 116 Top and bottom fields are expected to alternate in this mode.
 117
 118 Caps for this interlace mode must also carry a `format:Interlaced` caps feature
 119 (`GST_CAPS_FEATURE_FORMAT_INTERLACED`) to ensure backwards compatibility for
 120 the new mode.
 121
 122 The frame rate in the caps still signals the frame rate, so the notional field
 123 rate will be twice the frame rate from the caps (see `GST_VIDEO_INFO_FIELD_RATE_N`).