[Gnash-dev] NetStream design - episode 2: The PlayHead

[strk]

Previous episode summary: the buffers
-------------------------------------

                 +------------+
                 | input      |
                 +------------+
                 | bytes      |
                 +------------+
                       |
                       v
                  ( parser )
                       |
            +----------+---------+
            |                    |
            v                    v
    +----------------+    +----------------+   
    | video_buffer   |    | audio_buffer   |   
    +----------------+    +----------------+   
    | encoded_frames |    | encoded_frames |   
    +----------------+    +----------------+   
                                               
The (parser) process would run in its thread and fill the video/audio buffers
till end of input stream is reached.
The buffers will contain an ordered list of encoded frames each with an
associated timestamp, which would determine their order.

Episode 2: the PlayHead
-----------------------

The PlayHead is the device controlling final output.
It is either moving or still and has a current position.

    +-----------+
    | PlayHead  |
    +-----------+
    | position  |
    | state     |
    +-----------+

The position starts at 0 and moves as frames are consumed.
Position can be queried from ActionScript using 'NetBuffer.time'.
The state can be either UP or DOWN (if we like the phonograph analogy)
or more simply PLAYING/PAUSED.

State is only changed on user (ActionScript) request,
using 'NetStream.pause()'.

How position is changed bring us to more issues.
The problem is basically about the fact we have two buffers
but are trying to have a single PlayHead.

Theoretically position should only move forward when all
frames at the current one have been consumed, but as long as
we have 2 consumers in two different threads it is not clear which one
(if not an external actor) would be responsible to mark total consumption.
Note that this would be a non-problem if both consumers would run in the same 
thread,
in that we'd have a single 'consumer' process doing all the PlayHead management.

One solution might be keeping "consume state" in PlayHead:

         +------------------+
         | PlayHead         |
         +------------------+
         | position         |
         | state            |
         |                  |
         | consumersMask    |
         | positionConsumed |
         +------------------+

The 'consumersMask' would be initialized at construction time to reflect
the contents in the stream (A/V enum).
The 'positionConsumed' flag will be set to 0 everytime the position is advanced,
and will be OR-ed with A/V enum by A/V consumers.
Each consumer at that point can be responsible to advance position when
positionConsumed == consumersMask.
Also, a consumer could use the flag to avoid feeding the same frame to actual
output twice, in case the other consumer hasn't done with it yet.

Questions/comments welcome.


--strk;

 ()   ASCII Ribbon Campaign
 /\   Keep it simple!