docs: Add an interlaced video design document

diff --git a/docs/design/part-interlaced-video.txt b/docs/design/part-interlaced-video.txt
new file mode 100644 (file)
index 0000000..caef533
--- /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.