docs/random/wtay/events2

   1 some random ramblings about the event system:
   2
   3 Possible candidates for events
   4 ------------------------------
   5
   6   - QoS
   7   - EOS
   8   - Seek
   9   - caps nego??
  10   - bufferpool get??
  11   - ...
  12
  13 Assumptions for events
  14 ----------------------
  15
  16 - They are tied to a pad.
  17 - get rid of gst_pad_set_*_function (except for the chain/get ones)
  18 - occur async to dataflow. (need locking?)
  19 - fixed set of events only for core features. (elements cannot abuse
  20      events for doing dataflow)
  21
  22 Questions
  23 ---------
  24
  25 limit the valid directions an event can travel in? ie. Can EOS only
  26 travel downstream (left to right)?
  27
  28 eg. Seek travels upstream, but it makes sense to also make it travel
  29     downstream (the case of a disksink, where we overwrite the header)
  30
  31
  32 Setting an event function
  33 -------------------------
  34
  35 void gst_pad_set_event_function (GstPad *pad, gint event_mask,
  36                                  GstEventFunction *function);
  37
  38
  39 event masks:
  40
  41 typedef enum {
  42   GST_EVENT_EOS                 = (1 << 0),
  43   GST_EVENT_QOS                 = (1 << 1),
  44   GST_EVENT_SEEK                = (1 << 2),
  45   GST_EVENT_CAPS                = (1 << 3),
  46 } GstEventType;
  47
  48 Event structure
  49 ---------------
  50
  51 typedef struct {
  52   GstEventType type;
  53   GstEventMinorType minor;
  54   guint64 timestamp;  /* also sequence number ?? */
  55
  56   union {
  57     /* EOS stuff */
  58     /* QoS stuff */
  59     /* Seek stuff */
  60     GstSeekType type; /* time, bytes, ... */
  61     gint64 offset;
  62     gint64 lenth;
  63     /* Caps stuff */
  64     GstCaps *caps;
  65   } data;
  66 } GstEvent;
  67
  68
  69 typedef enum {
  70   GST_EVENT_MINOR_NONE,
  71   /* EOS stuff */
  72
  73   /* QoS stuff */
  74   /* Seek stuff */
  75   GST_EVENT_MINOR_OFFSET,
  76   GST_EVENT_MINOR_TIME,
  77
  78   /* caps nego stuff */
  79   GST_EVENT_MINOR_CAPS_TRY,
  80   GST_EVENT_MINOR_CAPS_START,
  81   GST_EVENT_MINOR_CAPS_FINAL,
  82 } GstEventMinorType;
  83
  84
  85 Receiving events
  86 ----------------
  87
  88 a sample GstEventFunction, the event functions returns TRUE if the event is handled,
  89 FALSE otherwise.
  90
  91 gboolean
  92 gst_anelement_handle_event (GstPad *pad, GstEvent *event)
  93 {
  94   if (event->type == GST_EVENT_EOS) {
  95     /* do something */
  96     return TRUE;
  97   }
  98   else if (event->type == GST_EVENT_CAPS) {
  99     if (event->minor == GST_EVENT_CAPS_TRY) {
 100       /* try using this caps structure */
 101       return TRUE; /* return FALSE to proxy ???*/
 102     }
 103   }
 104   return FALSE;
 105 }
 106
 107
 108 Default event handler for pads
 109 ------------------------------
 110
 111 gboolean
 112 gst_pad_handle_event (GstPad *pad, GstEvent *event)
 113 {
 114   GstElement *element;
 115   GList *pads;
 116   GstPad *srcpad;
 117   gboolean result = TRUE;
 118   GstPadDirection dir = GST_PAD_DIRECTION (pad);
 119
 120   g_return_val_if_fail (pad != NULL, FALSE);
 121   g_return_val_if_fail (GST_IS_REAL_PAD(pad), FALSE);   // NOTE the restriction
 122
 123   element = GST_ELEMENT (gst_object_get_parent (GST_OBJECT (pad)));
 124
 125   /* send out the events to all pad with opposite direction */
 126   pads = gst_element_get_pad_list(element);
 127   while (pads) {
 128     otherpad = GST_PAD(pads->data);
 129     pads = g_list_next(pads);
 130
 131     if (gst_pad_get_direction(otherpad) != dir) {
 132       result &= gst_pad_send_event (GST_REAL_PAD(otherpad), event);
 133     }
 134   }
 135
 136   /* result is combined result of all handlers? */
 137   return result;
 138 }
 139
 140