Consumer abstract service class. More...

#include <mlt_consumer.h>

Inheritance diagram for mlt_consumer_s:

Public Member Functions
void	mlt_consumer_close (mlt_consumer self)
	Close and destroy the consumer.
int	mlt_consumer_connect (mlt_consumer self, mlt_service producer)
	Connect the consumer to the producer.
mlt_frame	mlt_consumer_get_frame (mlt_consumer self)
	Protected method for consumer to get frames from connected service.
int	mlt_consumer_init (mlt_consumer self, void *child, mlt_profile profile)
	Initialize a consumer service.
int	mlt_consumer_is_stopped (mlt_consumer self)
	Determine if the consumer is stopped.
mlt_consumer	mlt_consumer_new (mlt_profile profile)
	Create a new consumer.
mlt_position	mlt_consumer_position (mlt_consumer consumer)
	Get the position of the last frame shown.
mlt_properties	mlt_consumer_properties (mlt_consumer self)
	Get the consumer properties.
void	mlt_consumer_purge (mlt_consumer self)
	Flush the read/render thread's buffer.
int	mlt_consumer_put_frame (mlt_consumer self, mlt_frame frame)
	An alternative method to feed frames into the consumer.
mlt_frame	mlt_consumer_rt_frame (mlt_consumer self)
	Get the next frame from the producer connected to a consumer.
mlt_service	mlt_consumer_service (mlt_consumer self)
	Get the parent service object.
int	mlt_consumer_start (mlt_consumer self)
	Start the consumer.
int	mlt_consumer_stop (mlt_consumer self)
	Stop the consumer.
void	mlt_consumer_stopped (mlt_consumer self)
	Callback for the implementation to indicate a stopped condition.
Data Fields
int	ahead
pthread_t	ahead_thread
void(*	close )(mlt_consumer)
	The destructor virtual function.
int	consecutive_dropped
int	consecutive_rendered
pthread_cond_t	done_cond
pthread_mutex_t	done_mutex
mlt_event	event_listener
mlt_image_format	format
int(*	is_stopped )(mlt_consumer)
	Get whether the consumer is running or stopped (virtual function).
struct mlt_service_s	parent
	A consumer is a service.
mlt_position	position
int	process_head
mlt_frame	put
int	put_active
pthread_cond_t	put_cond
pthread_mutex_t	put_mutex
mlt_deque	queue
pthread_cond_t	queue_cond
pthread_mutex_t	queue_mutex
int	real_time
int(*	start )(mlt_consumer)
	Start the consumer to pull frames (virtual function).
int	started
int(*	stop )(mlt_consumer)
	Stop the consumer (virtual function).
mlt_deque	worker_threads
Private Member Functions
static void	apply_profile_properties (mlt_consumer self, mlt_profile profile, mlt_properties properties)
	Convert the profile into properties on the consumer.
static void	consumer_read_ahead_start (mlt_consumer self)
	Start the read/render thread.
static void	consumer_read_ahead_stop (mlt_consumer self)
	Stop the read/render thread.
static void *	consumer_read_ahead_thread (void *arg)
	The thread procedure for asynchronously pulling frames through the service network connected to a consumer.
static void	consumer_work_start (mlt_consumer self)
	Start the worker threads.
static void	consumer_work_stop (mlt_consumer self)
	Stop the worker threads.
static void *	consumer_worker_thread (void *arg)
	The worker thread procedure for parallel processing frames.
static int	first_unprocessed_frame (mlt_consumer self)
	Locate the first unprocessed frame in the queue.
static void	mlt_consumer_frame_render (mlt_listener listener, mlt_properties owner, mlt_service self, void **args)
	The transmitter for the consumer-frame-render event.
static void	mlt_consumer_frame_show (mlt_listener listener, mlt_properties owner, mlt_service self, void **args)
	The transmitter for the consumer-frame-show event.
static void	mlt_consumer_property_changed (mlt_properties owner, mlt_consumer self, char *name)
	The property-changed event listener.
static void	on_consumer_frame_show (mlt_properties owner, mlt_consumer consumer, mlt_frame frame)
	A listener on the consumer-frame-show event.
static long	time_difference (struct timeval *time1)
	Compute the time difference between now and a time value.
Private Attributes
void *	child
	the object of a subclass
void *	local
	instance object

Detailed Description

Consumer abstract service class.

A consumer is a service that pulls audio and video from the connected producers, filters, and transitions. Typically a consumer is used to output audio and/or video to a device, file, or socket.

Property:

rescale the scaling algorithm to pass on to all scaling filters, defaults to "bilinear"

buffer the number of frames to use in the asynchronous render thread, defaults to 25

prefill the number of frames to render before commencing output when real_time <> 0, defaults to the size of buffer

drop_max the maximum number of consecutively dropped frames, defaults to 5

frequency the audio sample rate to use in Hertz, defaults to 48000

channels the number of audio channels to use, defaults to 2

real_time the asynchronous behavior: 1 (default) for asynchronous with frame dropping, -1 for asynchronous without frame dropping, 0 to disable (synchronous)

test_card the name of a resource to use as the test card, defaults to environment variable MLT_TEST_CARD. If undefined, the hard-coded default test card is white silence. A test card is what appears when nothing is produced.

frame_rate_num the numerator of the video frame rate, overrides mlt_profile_s

frame_rate_den the denominator of the video frame rate, overrides mlt_profile_s

width the horizontal video resolution, overrides mlt_profile_s

height the vertical video resolution, overrides mlt_profile_s

progressive a flag that indicates if the video is interlaced or progressive, overrides mlt_profile_s

aspect_ratio the video sample (pixel) aspect ratio as floating point (read only)

sample_aspect_num the numerator of the sample aspect ratio, overrides mlt_profile_s

sample_aspect_den the denominator of the sample aspect ratio, overrides mlt_profile_s

display_ratio the video frame aspect ratio as floating point (read only)

display_aspect_num the numerator of the video frame aspect ratio, overrides mlt_profile_s

display_aspect_den the denominator of the video frame aspect ratio, overrides mlt_profile_s

priority the OS scheduling priority for the render threads when real_time is not 0.

top_field_first when not progressive, whether interlace field order is top-field-first, defaults to 0

mlt_image_format the image format to request in rendering threads, defaults to yuv422

mlt_audio_format the audio format to request in rendering threads, defaults to S16

Event:

consumer-frame-show Subclass implementations should fire this.

consumer-frame-render The abstract class fires this.

consumer-stopped

Property:: fps video frames per second as floating point (read only)

Member Function Documentation

static void apply_profile_properties	(	mlt_consumer	self,
		mlt_profile	profile,
		mlt_properties	properties
	)		`[private]`

Convert the profile into properties on the consumer.

Parameters:

self	a consumer
profile	a profile
properties	a properties list (typically, the consumer's)

static void consumer_read_ahead_start ( mlt_consumer self ) [private]

Start the read/render thread.

Parameters:

self	a consumer

static void consumer_read_ahead_stop ( mlt_consumer self ) [private]

Stop the read/render thread.

Parameters:

self	a consumer

static void * consumer_read_ahead_thread ( void * arg ) [private]

The thread procedure for asynchronously pulling frames through the service network connected to a consumer.

Parameters:

arg	a consumer

static void consumer_work_start ( mlt_consumer self ) [private]

Start the worker threads.

Parameters:

self	a consumer

static void consumer_work_stop ( mlt_consumer self ) [private]

Stop the worker threads.

Parameters:

self	a consumer

static void * consumer_worker_thread ( void * arg ) [private]

The worker thread procedure for parallel processing frames.

Parameters:

arg	a consumer

static int first_unprocessed_frame ( mlt_consumer self ) [inline, private]

Locate the first unprocessed frame in the queue.

When playing with realtime behavior, we do not use the true head, but rather an adjusted process_head. The process_head is adjusted based on the rate of frame-dropping or recovery from frame-dropping. The idea is that as the level of frame-dropping increases to move the process_head closer to the tail because the frames are not completing processing prior to their playout! Then, as frames are not dropped the process_head moves back closer to the head of the queue so that worker threads can work ahead of the playout point (queue head).

Parameters:

self	a consumer

Returns:: an index into the queue

void mlt_consumer_close ( mlt_consumer self )

Close and destroy the consumer.

Parameters:

self	a consumer

int mlt_consumer_connect	(	mlt_consumer	self,
		mlt_service	producer
	)

Connect the consumer to the producer.

Parameters:

self	a consumer
producer	a producer

Returns:: > 0 warning, == 0 success, < 0 serious error, 1 = this service does not accept input, 2 = the producer is invalid, 3 = the producer is already registered with this consumer

static void mlt_consumer_frame_render	(	mlt_listener	listener,
		mlt_properties	owner,
		mlt_service	self,
		void **	args
	)		`[private]`

The transmitter for the consumer-frame-render event.

Invokes the listener.

Parameters:

listener	a function pointer that will be invoked
owner	the events object that will be passed to `listener`
self	a service that will be passed to `listener`
args	an array of pointers - the first entry is passed as a string to `listener`

static void mlt_consumer_frame_show	(	mlt_listener	listener,
		mlt_properties	owner,
		mlt_service	self,
		void **	args
	)		`[private]`

The transmitter for the consumer-frame-show event.

Invokes the listener.

Parameters:

listener	a function pointer that will be invoked
owner	the events object that will be passed to `listener`
self	a service that will be passed to `listener`
args	an array of pointers - the first entry is passed as a string to `listener`

mlt_frame mlt_consumer_get_frame ( mlt_consumer self )

Protected method for consumer to get frames from connected service.

Parameters:

self	a consumer

Returns:: a frame

int mlt_consumer_init	(	mlt_consumer	self,
		void *	child,
		mlt_profile	profile
	)

Initialize a consumer service.

Parameters:

self	the consumer to initialize
child	a pointer to the object for the subclass
profile	the `mlt_profile_s` to use (optional but recommended, uses the environment variable MLT if self is NULL)

Returns:: true if there was an error

int mlt_consumer_is_stopped ( mlt_consumer self )

Determine if the consumer is stopped.

Parameters:

self	a consumer

Returns:: true if the consumer is stopped

mlt_consumer mlt_consumer_new ( mlt_profile profile )

Create a new consumer.

Parameters:

profile a profile (optional, but recommended)

Returns:: a new consumer

mlt_position mlt_consumer_position ( mlt_consumer consumer )

Get the position of the last frame shown.

Parameters:

consumer a consumer

Returns:: the position

mlt_properties mlt_consumer_properties ( mlt_consumer self )

Get the consumer properties.

Parameters:

self	a consumer

Returns:: the consumer's properties list

See also:: MLT_CONSUMER_PROPERTIES

static void mlt_consumer_property_changed	(	mlt_properties	owner,
		mlt_consumer	self,
		char *	name
	)		`[private]`

The property-changed event listener.

Parameters:

owner	the events object
self	the consumer
name	the name of the property that changed

void mlt_consumer_purge ( mlt_consumer self )

Flush the read/render thread's buffer.

Parameters:

self	a consumer

int mlt_consumer_put_frame	(	mlt_consumer	self,
		mlt_frame	frame
	)

An alternative method to feed frames into the consumer.

Only valid if the consumer itself is not connected.

Parameters:

self	a consumer
frame	a frame

Returns:: true (ignore self for now)

mlt_frame mlt_consumer_rt_frame ( mlt_consumer self )

Get the next frame from the producer connected to a consumer.

Typically, one uses this instead of mlt_consumer_get_frame to make the asynchronous/real-time behavior configurable at runtime. You should close the frame returned from this when you are done with it.

Parameters: