docs/random/sources

   1 There are a number of different ways of coding a GstSrc.  I'll try to
   2 outline them and how the function here:
   3
   4 1a) Simple push-function based with single output
   5
   6
   7  *------*      *------
   8  !      !      !
   9  ! src  !--->--! plugin
  10  !      !      !
  11  *------*      *------
  12
  13 This is the style that all the existing sources use.  There is a single
  14 output pad, and a _push function that's global to the whole element.  The
  15 _push function simply constructs buffers and pushes them out the pad.
  16
  17 Chained (current implementation):
  18
  19
  20       bin               src               pad1           pad2            plugin
  21        !                                              (= pad1->peer)
  22  gst_bin_iterate
  23        !
  24        ! (find entry)
  25        !
  26        ! gst_src_push
  27        !---------------->!
  28                          ! (create buffer)
  29                          !
  30                          ! gst_pad_push
  31                          !---------------->!
  32                                            !
  33                                            ! pad1->chainfunc (pad1->peer)
  34                                            !------------------------------->!
  35                                            !                                !
  36                                            :                                :
  37                                                                       (more chaining)
  38                                            :                                :
  39                                            !<-------------------------------!
  40                          !<----------------!
  41       !<-----------------!
  42       !
  43   iteration ends
  44       !
  45      ---
  46       -
  47
  48 Typically this will be the/an entry into the Bin.  The Bin's iterate
  49 function simply calls the Src's _push function.  When the _push function
  50 pushes a buffer out it's pad, the chain function of the peer pad is
  51 called, presumably causing a push out the other side of that element, and
  52 eventually data gets to the other end.  The stack unrolls, and the
  53 iteration ends for that Src.
  54
  55 chained (alternative implementation)
  56
  57       bin               src               pad1           pad2            plugin
  58        !                                              (= pad1->peer)
  59  gst_bin_iterate
  60        !
  61        ! (find entry)
  62        !
  63        ! (find src pad
  64        !  of entry element)
  65        !
  66        ! gst_pad_pull
  67        !------------------------------------------------>!
  68                                  ?                       !
  69                          !<------------------------------!
  70                          !
  71                          ! (create buffer)
  72                          !
  73                          ! gst_pad_push
  74                          !------------------------------>!
  75                                                          ! (bufpen filled)
  76                         (return buffer)                  !
  77        !<------------------------------------------------!
  78        !
  79        ! gst_pad_chain
  80        !------------------------------------------------------------------->!
  81                                                                             !
  82                                                                             :
  83                                                                       (more chaining)
  84                                                                             :
  85        !<-------------------------------------------------------------------!
  86        !
  87   iteration ends
  88        !
  89       ---
  90        -
  91
  92
  93 Cothreaded:
  94
  95 Again, the source would generally be an entry into the Bin.  A loopfunc
  96 will be constructed around it, which will simply loop calling the Src's
  97 _push function as in the non-cothreaded case.  When the _push function
  98 pushes a buffer, it finds a pushfunc attached to the pad, drops the buffer
  99 in the pen, and calls the pushfunc provided by the Bin.  This causes a
 100 switch to the next element, then the next, to the end, at which point a
 101 buffer pull will travel back down the chain.  The _push function gets
 102 context and finishes, at which point the loopfunc wrapper simply calls it
 103 again in the next iteration.
 104
 105 (current implementation):
 106
 107
 108       bin               cothread1         src               pad1           pad2       cothread2      plugin
 109        !                 (src)                          (= pad1->peer)                (plugin)
 110  gst_bin_iterate
 111        !
 112        ! (first entry)
 113        !
 114        ! cothread_switch
 115        !---------------->!
 116                          ! gst_src_push
 117                          !---------------->!
 118                                            ! (create buffer)
 119                                            !
 120                                            ! gst_pad_push (pad1)
 121                                            !
 122                                            !--------------------!
 123                                                                 ! (fill bufpen)
 124                                                                 !
 125                                                                 ! cothread switch
 126                                                                 ----------------------->!
 127                                                                                         ! gst_pad_pull (pad2)
 128                                                                                         !
 129                                                                             !<----------!
 130                                                                             !
 131                                                                             ! (get buffer from bufpen)
 132                                                                             !
 133                                                                             !---------->!
 134                                                                                         ! pad2->chainfunc
 135                                                                                         !------------->!
 136                                                                                                        !
 137                                                                                                        :
 138
 139                                                                                                        :
 140                                                                                         !<-------------!
 141                                                                                         ! gst_pad_pull (pad2)
 142                                                                             !<----------!
 143                                                                             !
 144                                                                             ! (bufpen empty)
 145                                                                 !<----------!
 146                          !<-------------------------------------! cothread switch
 147        !<----------------!
 148        !
 149   iteration ends
 150        !
 151        :
 152
 153        :
 154        !
 155   next iteration
 156        !
 157        ! cothread_switch
 158        !---------------->!
 159                          ! gst_src_push
 160                          !---------------->!
 161                                            ! (create buffer)
 162                                            !
 163                                            ! gst_pad_push (pad1)
 164                                            !
 165                                            !--------------------!
 166                                                                 ! (fill bufpen)
 167                                                                 !
 168                                                                 ! cothread switch
 169                                                                 !---------->!
 170                                                                             ! (get buffer from bufpen)
 171                                                                             !
 172                                                                             !---------->!
 173                                                                                         ! pad2->chainfunc
 174                                                                                         !------------->!
 175                                                                                                        !
 176                                                                                                        :
 177
 178                                                                                                        :
 179                                                                                         !<-------------!
 180                                                                                         ! gst_pad_pull (pad2)
 181                                                                             !<----------!
 182                                                                             !
 183                                                                             ! (bufpen empty)
 184                                                                 !<----------!
 185                          !<-------------------------------------! cothread switch
 186        !<----------------!
 187        !
 188   iteration ends
 189        !
 190        :
 191
 192
 193 (alternative implementation):
 194
 195
 196       bin               cothread1         src               pad1           pad2       cothread2      plugin
 197        !                 (src)                          (= pad1->peer)                (plugin)
 198  gst_bin_iterate
 199        !
 200        ! (first entry)
 201        !
 202        ! cothread_switch
 203        !---------------->! gst_pad_pull
 204                          !------------------------------------------------>!
 205                                                    ?                       !
 206                                            !<------------------------------!
 207                                            !
 208                                            ! (create buffer)
 209                                            !
 210                                            ! gst_pad_push
 211                                            !------------------------------>!
 212                                                                            ! (bufpen filled)
 213                                                 (return buffer)            !
 214                          !<------------------------------------------------!
 215                          !
 216                          ! pad_chain
 217                          !--------------------------------------! cothread switch
 218                                                                 |---------------------->!
 219                                                                                         ! gst_pad_pull (pad2)
 220                                                                                         !
 221                                                                             !<----------!
 222                                                                             !
 223                                                                             ! (get buffer from bufpen)
 224                                                                             !
 225                                                                             !---------->!
 226                                                                                         ! pad2->chainfunc
 227                                                                                         !------------->!
 228                                                                                                        !
 229                                                                                                        :
 230
 231                                                                                                        :
 232                                                                                         !<-------------!
 233                                                                                         ! gst_pad_pull (pad2)
 234                                                                             !<----------!
 235                                                                             !
 236                                                                             ! (bufpen empty)
 237                                                                !<-----------!
 238                                                                !   cothread switch
 239                          !<------------------------------------!
 240        !<----------------!
 241        !
 242   iteration ends
 243        !
 244        :
 245
 246 -----------------------------------------------------------------------------------------------
 247 1b) Simple push-function based with multiple output
 248
 249 Chained:
 250
 251 Similar to the single output variant, except several chains are spawned
 252 off, one per push, hanging off whichever pad the buffer is pushed off of.
 253 The stack will grow and unwind as many times as buffers are pushed out.
 254
 255 Cothreaded:
 256
 257 Also similar to the single output variant.  When the pull winds its way
 258 back from the first push, execution returns to the Src's _push function,
 259 which simply goes off and pushes out another buffer, causing another
 260 series of context switches.  Eventually the loopfunc wrapper starts over,
 261 round and round we go.
 262
 263
 264
 265 -----------------------------------------------------------------------------------------------
 266 2) Pull-function based with single output
 267
 268 Similar to a regular filter with a chain function associated with each
 269 pad, this kind of source doesn't provide a src-wide push function, but
 270 does provide pullfuncs for its pad.  A pullfunc puts a buffer in the pen
 271 and exits.
 272
 273 Chained:
 274
 275 As usual, is likely to be an entry into a Bin.  The Bin iterate code must
 276 explicitely pull a buffer and pass it on to the peer.
 277
 278 Cothreaded:
 279
 280
 281 ---- ok, I'll finish this tomorrow when my brain's working again.... ----
 282