diff options
Diffstat (limited to 'docs/design/part-events.txt')
| -rw-r--r-- | docs/design/part-events.txt | 53 |
1 files changed, 34 insertions, 19 deletions
diff --git a/docs/design/part-events.txt b/docs/design/part-events.txt index 3193698..c8ffde6 100644 --- a/docs/design/part-events.txt +++ b/docs/design/part-events.txt @@ -13,6 +13,7 @@ Different types of events exist to implement various functionalities. GST_EVENT_FLUSH_START: data is to be discarded GST_EVENT_FLUSH_STOP: data is allowed again GST_EVENT_CAPS: Format information about the following buffers + GST_EVENT_STREAM_CONFIG: Stream config: stream headers and codec setup data GST_EVENT_SEGMENT: Timing information for the following buffers GST_EVENT_TAG: Stream metadata. GST_EVENT_BUFFERSIZE: Buffer size requirements @@ -34,27 +35,23 @@ Different types of events exist to implement various functionalities. src pads -------- -A gst_pad_push_event() on a srcpad will first store the event in the sticky -array before sending the event to the peer pad. If there is no peer pad, the -gst_pad_push_event() function returns NOT_LINKED. +A gst_pad_push_event() on a srcpad will first store the sticky event in the +sticky array before sending the event to the peer pad. If there is no peer pad +and the event was not stored in the sticky array, FALSE is returned. -Note that the behaviour is not influenced by a flushing pad. +Flushing pads will refuse the events and will not store the sticky events. -FLUSH_START and FLUSH_STOP events are dropped on blocked pads. sink pads --------- -A gst_pad_send_event() on a sinkpad will check the new event against the -existing event. If they are different, the new event is stored as a pending -event. If the events are the same, nothing changes. +A gst_pad_send_event() on a sinkpad will call the event function on the pad. If +the event function returns success, the sticky event is stored in the sticky +event array and the event is marked for update. -When the pad is flushing, the _send_event() function returns WRONG_STATE -immediately. +When the pad is flushing, the _send_event() function returns FALSE immediately. -The event function is then called for all pending events. If the function -returns success, the pending event is copied to the active events, else the -pending event is removed and the current active event is unchanged. +When the next data item is pushed, the pending events are pushed first. This ensures that the event function is never called for flushing pads and that the sticky array only contains events for which the event function returned @@ -64,9 +61,9 @@ success. pad link -------- -When linking pads, all the sticky events from the srcpad are copied to the -pending array on the sinkpad. The pending events will be sent to the event -function of the sinkpad on the next event or buffer. +When linking pads, the srcpad sticky events are marked for update when they are +different from the sinkpad events. The next buffer push will push the events to +the sinkpad. FLUSH_START/STOP @@ -112,8 +109,6 @@ The EOS event can only be sent on a sinkpad. It is typically emited by the source element when it has finished sending data. This event is mainly sent in the streaming thread but can also be sent from the application thread. -An EOS event sent on a srcpad returns GST_FLOW_UNEXPECTED. - The downstream element should forward the EOS event to its downstream peer elements. This way the event will eventually reach the sinks which should then post an EOS message on the bus when in PLAYING. @@ -131,7 +126,7 @@ GStreamer core will take the STREAM_LOCK. Sometimes the EOS event is generated by another element than the source, for example a demuxer element can generate an EOS event before the source element. This is not a problem, the demuxer does not send an EOS event to the upstream -element but returns GST_FLOW_UNEXPECTED, causing the source element to stop +element but returns GST_FLOW_EOS, causing the source element to stop sending data. An element that sends EOS on a pad should stop sending data on that pad. Source @@ -147,6 +142,26 @@ goes to PLAYING. A FLUSH_STOP event on an element flushes the EOS state and all pending EOS messages. +GST_EVENT_STREAM_CONFIG +~~~~~~~~~~~~~~~~~~~~~~~ + +A stream config event is sent downstream by an element to pass stream headers +or codec/stream setup data to elements downstream. + +Stream headers are buffers that are to be pre-pended to a stream to create +a valid decodable bitstream. This is useful for e.g. network elements who +will send such stream headers first when a new client connects in the middle +of a streaming session. The stream headers and the current data will then +create a valid decodable stream. Stream headers are usually also sent as +buffers at the beginning of a stream in addition to the rest of the stream +data. + +Setup data is codec config data that must be communicated outside of the +data stream and is required by the consumer / downstream element in order +to interpret the data stream correctly. Prepending it to the data stream is +usually not allowed and will not yield a valid stream. + + SEGMENT ~~~~~~~ |