gstlalcollectpads

gstlalcollectpads — Custom GstCollectPads to assist with combining input streams synchronously.

Synopsis

                    GstLALCollectData;
GstLALCollectData * gstlal_collect_pads_add_pad         (GstCollectPads *pads,
                                                         GstPad *pad,
                                                         guint size);
GstLALCollectData * gstlal_collect_pads_add_pad_full    (GstCollectPads *pads,
                                                         GstPad *pad,
                                                         guint size,
                                                         GstCollectDataDestroyNotify destroy_notify);
gboolean            gstlal_collect_pads_get_earliest_times
                                                        (GstCollectPads *pads,
                                                         GstClockTime *t_start,
                                                         GstClockTime *t_end);
gint                gstlal_collect_pads_get_rate        (GstPad *pad);
GstSegment *        gstlal_collect_pads_get_segment     (GstCollectPads *pads);
guint               gstlal_collect_pads_get_unit_size   (GstPad *pad);
gboolean            gstlal_collect_pads_remove_pad      (GstCollectPads *pads,
                                                         GstPad *pad);
void                gstlal_collect_pads_set_rate        (GstPad *pad,
                                                         gint rate);
void                gstlal_collect_pads_set_unit_size   (GstPad *pad,
                                                         guint unit_size);
GstBuffer *         gstlal_collect_pads_take_buffer_sync
                                                        (GstCollectPads *pads,
                                                         GstLALCollectData *data,
                                                         GstClockTime t_end);

Description

Custom GstCollectData structure with extra metadata to facilitate synchronous mixing of input streams. In fact, only the GstCollectData structure is customized, replaced here with the GstLALCollectData structure; however, a few shim functions are required to adapt function signatures to accept and return pointers to the custom type.

Details

GstLALCollectData

typedef struct {
	GstCollectData as_gstcollectdata;

	guint unit_size;
	gint rate;
} GstLALCollectData;

GstCollectData as_gstcollectdata;

the parent structure

guint unit_size;

size of one "unit", e.g. (multi-channel) audio sample, video frame, etc. For audio, = (sample width) / 8 * (channels).

gint rate;

number of units per second

gstlal_collect_pads_add_pad ()

GstLALCollectData * gstlal_collect_pads_add_pad         (GstCollectPads *pads,
                                                         GstPad *pad,
                                                         guint size);

Equivalent to #gst_collect_pads_add_pad().

pads :

passed to #gstlal_collect_pads_add_pad_full()

pad :

passed to #gstlal_collect_pads_add_pad_full()

size :

passed to #gstlal_collect_pads_add_pad_full()

Returns :

GstLALCollectData associated with the GstPad.

gstlal_collect_pads_add_pad_full ()

GstLALCollectData * gstlal_collect_pads_add_pad_full    (GstCollectPads *pads,
                                                         GstPad *pad,
                                                         guint size,
                                                         GstCollectDataDestroyNotify destroy_notify);

Wraps #gst_collect_pads_add_pad_full(), initializing the additional fields in the custom GstLALCollectData object.

pads :

passed to #gst_collect_pads_add_pad()

pad :

passed to #gst_collect_pads_add_pad()

size :

passed to #gst_collect_pads_add_pad()

destroy_notify :

passed to#gst_collect_pads_add_pad()

Returns :

GstLALCollectData associated with the GstPad.

gstlal_collect_pads_get_earliest_times ()

gboolean            gstlal_collect_pads_get_earliest_times
                                                        (GstCollectPads *pads,
                                                         GstClockTime *t_start,
                                                         GstClockTime *t_end);

Computes the earliest of the start and of the end times of the GstCollectPads' input buffers.

Upon the successful completion of this function, both time parameters will be set to GST_CLOCK_TIME_NONE if all input streams are at EOS. Otherwise, if at least one stream is not at EOS, the times are set to the earliest interval spanned by all the buffers that are available.

Note that if no input pads have data available, this condition is interpreted as EOS. EOS is, therefore, indistinguishable from the initial state, wherein no data has yet arrived. It is assumed this function will only be invoked from within the collected() method, and therefore only after at least one pad has received a buffer, and therefore the "no data available" condition is only seen at EOS.

Table 1. Return Values

condition return value t_end, t_start
bad input FALSE undefined
EOS TRUE GST_CLOCK_TIME_NONE
success TRUE ≥0


Should be called with the GstCollectPads' lock held (i.e., from the collected() method).

pads :

GstCollectPads

t_start :

address of GstClockTime where start time will be stored

t_end :

address of GstClockTime where end time will be stored

Returns :

TRUE indicates the function was able to procede to a successful conclusion, FALSE indicates that one or more errors occured (see above).

gstlal_collect_pads_get_rate ()

gint                gstlal_collect_pads_get_rate        (GstPad *pad);

Get the unit rate (e.g., sample rate, frame rate, etc.) on the given input stream.

Should be called with the GstCollectPads' lock held (i.e., from the collected() method).

pad :

the GstPad whose unit rate is to be retrieved

Returns :

unit rate in Hertz.

gstlal_collect_pads_get_segment ()

GstSegment *        gstlal_collect_pads_get_segment     (GstCollectPads *pads);

Compute the smallest segment that contains the segments (from the most recent newsegment events) of all pads. The segments must be in the same format on all pads. The return value is a newly allocated GstSegment owned by the calling code.

Should be called with the GstCollectPads' lock held (i.e., from the collected() method).

pads :

GstCollectPads

Returns :

newly-allocated GstSegment. #gst_segment_free() when no longer needed.

gstlal_collect_pads_get_unit_size ()

guint               gstlal_collect_pads_get_unit_size   (GstPad *pad);

Get the number of bytes per unit (e.g., sample, frame, etc.) on the given input stream.

Should be called with the GstCollectPads' lock held (i.e., from the collected() method).

pad :

the GstPad whose unit size is to be retrieved

Returns :

unit size in bytes.

gstlal_collect_pads_remove_pad ()

gboolean            gstlal_collect_pads_remove_pad      (GstCollectPads *pads,
                                                         GstPad *pad);

Equivalent to #gst_collect_pads_remove_pad().

pads :

passed to #gst_collect_pads_remove_pad()

pad :

passed to #gst_collect_pads_remove_pad()

Returns :

TRUE if GstPad was removed successfully, FALSE if not.

gstlal_collect_pads_set_rate ()

void                gstlal_collect_pads_set_rate        (GstPad *pad,
                                                         gint rate);

Set the unit rate (e.g., sample rate, frame rate, etc.) on the given input stream.

Should be called with the GstCollectPads' lock held (e.g., from the collected() method).

pad :

the GstPad whose unit rate (in Hertz) is to be set

rate :

the number of units per second.

gstlal_collect_pads_set_unit_size ()

void                gstlal_collect_pads_set_unit_size   (GstPad *pad,
                                                         guint unit_size);

Set the number of bytes per unit (e.g., sample, frame, etc.) on the given input stream.

Should be called with the GstCollectPads' lock held (e.g., from the collected() method).

pad :

the GstPad whose unit size is to be set

unit_size :

the size in bytes of one unit

gstlal_collect_pads_take_buffer_sync ()

GstBuffer *         gstlal_collect_pads_take_buffer_sync
                                                        (GstCollectPads *pads,
                                                         GstLALCollectData *data,
                                                         GstClockTime t_end);

Wrapper for #gst_collect_pads_take_buffer(). Returns a GstBuffer containing the samples taken from the start of the current buffer upto (not including) the offset corresponding to t_end. The buffer returned might be shorter if the pad does not have data upto the requested time. The buffer returned by this function has its offset and offset_end set to indicate its location in the input stream. Calling this function has the effect of flushing the pad upto the offset corresponding to t_end or the upper bound of the available data, whichever comes first.

If the pad has no data available then NULL is returned, this indicates EOS. If the pad has data available but it is subsequent to the requested interval then a zero-length buffer is returned.

Should be called with the GstCollectPads' lock held (i.e., from the collected() method).

pads :

GstCollectPads

data :

GstLALCollectData associated with the GstPad from which to take the data

t_end :

the GstClockTime up to which to retrieve data

Returns :

GstBuffer. #gst_buffer_unref() when no longer needed.