qtdemux: Add/Fix comments on the various structure variables

No variables were added/removed. This was just a good excuse to:
* Comment what most variables are used for (and when)
* Order them in such a way as to show first the common variables used
  in all cases, followed by those only used in push-mode

2 files changed, 124 insertions, 47 deletions

diff --git a/gst/isomp4/qtdemux.c b/gst/isomp4/qtdemux.c
index e0798714e..b6a0c69dc 100644
--- a/gst/isomp4/qtdemux.c
+++ b/gst/isomp4/qtdemux.c
@@ -219,7 +219,10 @@ struct _QtDemuxStream
   guint32 fourcc;
   gboolean sparse;
 
-  gboolean new_caps;
+  gboolean new_caps;            /* If TRUE, caps need to be generated (by
+                                 * calling _configure_stream()) This happens
+                                 * for MSS and fragmented streams */
+
   gboolean new_stream;          /* signals that a stream_start is required */
   gboolean on_keyframe;         /* if this stream last pushed buffer was a
                                  * keyframe. This is important to identify
@@ -233,7 +236,7 @@ struct _QtDemuxStream
   guint track_id;
 
   /* duration/scale */
-  guint64 duration;             /* in timescale */
+  guint64 duration;             /* in timescale units */
   guint32 timescale;
 
   /* language */
@@ -244,12 +247,17 @@ struct _QtDemuxStream
   QtDemuxSample *samples;
   gboolean all_keyframe;        /* TRUE when all samples are keyframes (no stss) */
   guint32 first_duration;       /* duration in timescale of first sample, used for figuring out
-                                   the framerate, in timescale units */
+                                   the framerate */
   guint32 n_samples_moof;       /* sample count in a moof */
   guint64 duration_moof;        /* duration in timescale of a moof, used for figure out
                                  * the framerate of fragmented format stream */
-  guint32 offset_in_sample;
-  guint32 max_buffer_size;
+
+  guint32 offset_in_sample;     /* Offset in the current sample, used for
+                                 * streams which have got exceedingly big
+                                 * sample size (such as 24s of raw audio).
+                                 * Only used when max_buffer_size is non-NULL */
+  guint32 max_buffer_size;      /* Maximum allowed size for output buffers.
+                                 * Currently only set for raw audio streams*/
 
   /* if we use chunks or samples */
   gboolean sampled;
@@ -9188,7 +9196,7 @@ qtdemux_parse_trak (GstQTDemux * qtdemux, GNode * trak)
 
     /* HACK:
      * some of those trailers, nowadays, have prologue images that are
-     * themselves vide tracks as well. I haven't really found a way to
+     * themselves video tracks as well. I haven't really found a way to
      * identify those yet, except for just looking at their duration. */
     if (tdur1 != 0 && (tdur2 * 10 / tdur1) < 2) {
       GST_WARNING_OBJECT (qtdemux,
@@ -12227,7 +12235,7 @@ qtdemux_add_container_format (GstQTDemux * qtdemux, GstTagList * tags)
   return tags;
 }
 
-/* we have read th complete moov node now.
+/* we have read the complete moov node now.
  * This function parses all of the relevant info, creates the traks and
  * prepares all data structures for playback
  */
diff --git a/gst/isomp4/qtdemux.h b/gst/isomp4/qtdemux.h
index 40dd3a735..771ddcc5b 100644
--- a/gst/isomp4/qtdemux.h
+++ b/gst/isomp4/qtdemux.h
@@ -65,9 +65,17 @@ enum QtDemuxState
 struct _GstQTDemux {
   GstElement element;
 
-  /* pads */
+  /* Global state */
+  enum QtDemuxState state;
+
+  /* static sink pad */
   GstPad *sinkpad;
 
+  /* TRUE if pull-based */
+  gboolean pullbased;
+
+  gboolean posted_redirect;
+
   QtDemuxStream *streams[GST_QTDEMUX_MAX_STREAMS];
   gint     n_streams;
   gint     n_video_streams;
@@ -76,62 +84,130 @@ struct _GstQTDemux {
 
   GstFlowCombiner *flowcombiner;
 
+  /* Incoming stream group-id to set on downstream STREAM_START events.
+   * If upstream doesn't contain one, a global one will be generated */
   gboolean have_group_id;
   guint group_id;
 
   guint  major_brand;
   GstBuffer *comp_brands;
+
+  /* [moov] header.
+   * FIXME : This is discarded just after it's created. Just move it
+   * to a temporary variable ? */
   GNode *moov_node;
+
+  /* FIXME : This is never freed. It is only assigned once. memleak ? */
   GNode *moov_node_compressed;
 
+  /* Set to TRUE when the [moov] header has been fully parsed */
+  gboolean got_moov;
+
+  /* Global timescale for the incoming stream. Use the QTTIME macros
+   * to convert values to/from GstClockTime */
   guint32 timescale;
-  GstClockTime duration;
 
+  /* Global duration (in global timescale). Use QTTIME macros to get GstClockTime */
+  guint64 duration;
+
+  /* Total size of header atoms. Used to calculate fallback overall bitrate */
+  guint header_size;
+
+  GstTagList *tag_list;
+
+  /* configured playback region */
+  GstSegment segment;
+
+  /* The SEGMENT_EVENT from upstream *OR* generated from segment (above) */
+  GstEvent *pending_newsegment;
+
+  guint32 segment_seqnum;
+
+  /* flag to indicate that we're working with a smoothstreaming fragment
+   * Mss doesn't have 'moov' or any information about the streams format,
+   * requiring qtdemux to expose and create the streams */
+  gboolean mss_mode;
+
+  /* Set to TRUE if the incoming stream is either a MSS stream or
+   * a Fragmented MP4 (containing the [mvex] atom in the header) */
   gboolean fragmented;
+
+  /* PULL-BASED only : If TRUE there is a pending seek */
   gboolean fragmented_seek_pending;
+
+  /* PULL-BASED : offset of first [moof] or of fragment to seek to
+   * PUSH-BASED : offset of latest [moof] */
   guint64 moof_offset;
 
-  gint state;
+  /* MSS streams have a single media that is unspecified at the atoms, so
+   * upstream provides it at the caps */
+  GstCaps *media_caps;
 
-  gboolean pullbased;
-  gboolean posted_redirect;
+  /* Set to TRUE when all streams have been exposed */
+  gboolean exposed;
+    
+  gint64 chapters_track_id;
 
-  /* push based variables */
+  /* protection support */
+  GPtrArray *protection_system_ids; /* Holds identifiers of all content protection systems for all tracks */
+  GQueue protection_event_queue; /* holds copy of upstream protection events */
+  guint64 cenc_aux_info_offset;
+  guint8 *cenc_aux_info_sizes;
+  guint32 cenc_aux_sample_count;
+
+
+  /*
+   * ALL VARIABLES BELOW ARE ONLY USED IN PUSH-BASED MODE 
+   */
+  GstAdapter *adapter;
   guint neededbytes;
   guint todrop;
-  GstAdapter *adapter;
+  /* Used to store data if [mdat] is before the headers */
   GstBuffer *mdatbuffer;
+  /* Amount of bytes left to read in the current [mdat] */
   guint64 mdatleft;
-  /* When restoring the mdat to the adatpter, this buffer
-   * stores any trailing data that was after the last atom parsed as it
-   * has to be restored later along with the correct offset. Used in
-   * fragmented scenario where mdat/moof are one after the other
-   * in any order.
+
+  /* When restoring the mdat to the adapter, this buffer stores any
+   * trailing data that was after the last atom parsed as it has to be
+   * restored later along with the correct offset. Used in fragmented
+   * scenario where mdat/moof are one after the other in any order.
    *
    * Check https://bugzilla.gnome.org/show_bug.cgi?id=710623 */
   GstBuffer *restoredata_buffer;
   guint64 restoredata_offset;
 
+  /* The current offset in bytes from upstream.
+   * Note: While it makes complete sense when we are PULL-BASED (pulling
+   * in BYTES from upstream) and PUSH-BASED with a BYTE SEGMENT (receiving
+   * buffers with actual offsets), it is undefined in PUSH-BASED with a
+   * TIME SEGMENT */
   guint64 offset;
+
   /* offset of the mdat atom */
   guint64 mdatoffset;
+  /* Offset of the first mdat */
   guint64 first_mdat;
-  gboolean got_moov;
+  /* offset of last [moov] seen */
   guint64 last_moov_offset;
-  guint header_size;
 
-  GstTagList *tag_list;
+  /* If TRUE, qtdemux received upstream newsegment in TIME format
+   * which likely means that upstream is driving the pipeline (such as
+   * adaptive demuxers or dlna sources) */
+  gboolean upstream_format_is_time;
 
-  /* configured playback region */
-  GstSegment segment;
-  GstEvent *pending_newsegment;
-  guint32 segment_seqnum;
-  gboolean upstream_format_is_time; /* qtdemux received upstream
-                                     * newsegment in TIME format which likely
-                                     * means that upstream is driving the pipeline
-                                     * (adaptive demuxers / dlna) */
+  /* Seqnum of the seek event sent upstream.  Will be used to
+   * detect incoming FLUSH events corresponding to that */
   guint32 offset_seek_seqnum;
+
+  /* UPSTREAM BYTE: Requested upstream byte seek offset.
+   * Currently it is only used to check if an incoming BYTE SEGMENT
+   * corresponds to a seek event that was sent upstream */
   gint64 seek_offset;
+
+  /* UPSTREAM BYTE: Requested start/stop TIME values from
+   * downstream.
+   * Used to set on the downstream segment once the corresponding upstream
+   * BYTE SEEK has succeeded */
   gint64 push_seek_start;
   gint64 push_seek_stop;
 
@@ -141,28 +217,21 @@ struct _GstQTDemux {
   gint index_id;
 #endif
 
+  /* Whether upstream is seekable in BYTES */
   gboolean upstream_seekable;
+  /* UPSTREAM BYTE: Size of upstream content.
+   * Note : This is only computed once ! If upstream grows in the meantime
+   * it will not be updated */
   gint64 upstream_size;
 
-  /* MSS streams have a single media that is unspecified at the atoms, so
-   * upstream provides it at the caps */
-  GstCaps *media_caps;
-  gboolean exposed;
-  gboolean mss_mode; /* flag to indicate that we're working with a smoothstreaming fragment
-                      * Mss doesn't have 'moov' or any information about the streams format,
-                      * requiring qtdemux to expose and create the streams */
+  /* UPSTREAM TIME : Contains the PTS (if any) of the
+   * buffer that contains a [moof] header. Will be used to establish
+   * the actual PTS of the samples contained within that fragment. */
   guint64 fragment_start;
+  /* UPSTREAM TIME : The offset in bytes of the [moof]
+   * header start.
+   * Note : This is not computed from the GST_BUFFER_OFFSET field */
   guint64 fragment_start_offset;
-    
-  gint64 chapters_track_id;
-
-  /* protection support */
-  GPtrArray *protection_system_ids; /* Holds identifiers of all content protection systems for all tracks */
-  GQueue protection_event_queue; /* holds copy of upstream protection events */
-  guint64 cenc_aux_info_offset;
-  guint8 *cenc_aux_info_sizes;
-  guint32 cenc_aux_sample_count;
-
 };
 
 struct _GstQTDemuxClass {