diff --git a/docs/design/part-interlaced-video.txt b/docs/design/part-interlaced-video.txt new file mode 100644 index 0000000000..caef5330e5 --- /dev/null +++ b/docs/design/part-interlaced-video.txt @@ -0,0 +1,88 @@ +Interlaced Video +================ + +Video buffers have a number of states identifiable through a combination of caps +and buffer flags. + +Possible states: +- Progressive +- Interlaced + - Plain + - One field + - Two fields + - Three fields - this should be a progressive buffer with a repeated 'first' + field that can be used for telecine pulldown + - Telecine + - One field + - Two fields + - Progressive + - Interlaced (a.k.a. 'mixed'; the fields are from different frames) + - Three fields - this should be a progressive buffer with a repeated 'first' + field that can be used for telecine pulldown + +Note: it can be seen that the different between the plain interlaced and +telecine states is that in the telecine state, buffers containing two fields may +be progressive. + +Tools for identification: +- Caps + - interlaced - boolean + - interlacing-method - string - "unknown"/"telecine" +- Flags - GST_VIDEO_BUFFER_... + - TFF + - RFF + - ONEFIELD + - PROGRESSIVE + + +Identification of Buffer States +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Note that flags are not necessarily interpreted in the same way for all +different states nor are they necessarily required nor make sense in all cases. + + +Progressive +........... + +If the caps have no interlaced field, or have interlaced=false, then the buffer +is progressive. Note the possibility for progressive buffers in telecine streams +as well. + + +Plain Interlaced +................ + +If the caps have interlaced=true and either do not contain the +interlacing-method field or contain interlacing-method=unknown, then the buffer +is plain interlaced. + +GST_VIDEO_BUFFER_TFF indicates whether the top or bottom field is to be +displayed first. The timestamp on the buffer corresponds to the first field. +(FIXME - is the duration of the buffer the duration of both fields; each field's +duration is half the buffer duration) + +GST_VIDEO_BUFFER_RFF indicates that the first field (indicated by the TFF flag) +should be repeated. This is generally only used for telecine purposes but as the +telecine state was added long after the interlaced state was added and defined, +this flag remains valid for plain interlaced buffers. + +GST_VIDEO_BUFFER_ONEFIELD means that only the field indicated through the TFF +flag is to be used. The other field should be ignored. + + +Telecine +........ + +If the caps have interlaced=true and interlacing-method=telecine then the +buffers are in some form of telecine state. + +The TFF, RFF and ONEFIELD flags have the same semantics as for the plain +interlaced state, however, for the telecine state require one additional flag to +be able to identify progressive buffers. + +GST_VIDEO_BUFFER_PROGRESSIVE means that the buffer containing two fields is a +progressive frame. The implication is that if this flag is not set, the buffer +is an 'interlaced' or 'mixed' buffer that contains two fields that, when +combined with fields from adjacent buffers, allow reconstruction of progressive +frames.