Frame class. More...

#include <mlt_frame.h>

Inheritance diagram for mlt_frame_s:

Public Member Functions
const char *	mlt_audio_format_name (mlt_audio_format format)
	Get the short name for an audio format.
int	mlt_audio_format_size (mlt_audio_format format, int samples, int channels)
	Get the amount of bytes needed for a block of audio.
mlt_frame	mlt_frame_clone (mlt_frame self, int is_deep)
	Make a copy of a frame.
void	mlt_frame_close (mlt_frame self)
	Destroy the frame.
uint8_t *	mlt_frame_get_alpha_mask (mlt_frame self)
	Get the alpha channel associated to the frame.
double	mlt_frame_get_aspect_ratio (mlt_frame self)
	Get the sample aspect ratio of the frame.
int	mlt_frame_get_audio (mlt_frame self, void *buffer, mlt_audio_format format, int frequency, int channels, int *samples)
	Get the audio associated to the frame.
int	mlt_frame_get_image (mlt_frame self, uint8_t *buffer, mlt_image_format format, int width, int height, int writable)
	Get the image associated to the frame.
mlt_producer	mlt_frame_get_original_producer (mlt_frame self)
	Get the end service that produced self frame.
mlt_position	mlt_frame_get_position (mlt_frame self)
	Get the time position of this frame.
unsigned char *	mlt_frame_get_waveform (mlt_frame self, int w, int h)
	Get audio on a frame as a waveform image.
mlt_frame	mlt_frame_init (mlt_service service)
	Construct a frame object.
int	mlt_frame_is_test_audio (mlt_frame self)
	Determine if the frame will produce audio from a test card.
int	mlt_frame_is_test_card (mlt_frame self)
	Determine if the frame will produce a test card image.
void *	mlt_frame_pop_audio (mlt_frame self)
	Pop an audio item from the stack.
mlt_frame	mlt_frame_pop_frame (mlt_frame self)
	Pop a frame.
mlt_get_image	mlt_frame_pop_get_image (mlt_frame self)
	Pop a get_image callback.
void *	mlt_frame_pop_service (mlt_frame self)
	Pop a service.
int	mlt_frame_pop_service_int (mlt_frame self)
	Pop a number.
mlt_properties	mlt_frame_properties (mlt_frame self)
	Get a frame's properties.
int	mlt_frame_push_audio (mlt_frame self, void *that)
	Push an audio item on the stack.
int	mlt_frame_push_frame (mlt_frame self, mlt_frame that)
	Push a frame.
int	mlt_frame_push_get_image (mlt_frame self, mlt_get_image get_image)
	Stack a get_image callback.
int	mlt_frame_push_service (mlt_frame self, void *that)
	Push a service.
int	mlt_frame_push_service_int (mlt_frame self, int that)
	Push a number.
void	mlt_frame_replace_image (mlt_frame self, uint8_t *image, mlt_image_format format, int width, int height)
	Replace image stack with the information provided.
mlt_deque	mlt_frame_service_stack (mlt_frame self)
	Return the service stack.
int	mlt_frame_set_alpha (mlt_frame self, uint8_t *alpha, int size, mlt_destructor destroy)
	Set a new alpha channel on the frame.
int	mlt_frame_set_aspect_ratio (mlt_frame self, double value)
	Set the sample aspect ratio of the frame.
int	mlt_frame_set_audio (mlt_frame self, void *buffer, mlt_audio_format format, int size, mlt_destructor destructor)
	Set the audio on a frame.
int	mlt_frame_set_image (mlt_frame self, uint8_t *image, int size, mlt_destructor destroy)
	Set a new image on the frame.
int	mlt_frame_set_position (mlt_frame self, mlt_position value)
	Set the time position of this frame.
mlt_properties	mlt_frame_unique_properties (mlt_frame self, mlt_service service)
	Get or create a properties object unique to this service instance.
const char *	mlt_image_format_name (mlt_image_format format)
	Get the short name for an image format.
int	mlt_image_format_size (mlt_image_format format, int width, int height, int *bpp)
	Get the number of bytes needed for an image.
int	mlt_sample_calculator (float fps, int frequency, int64_t position)
	Determine the number of samples that belong in a frame at a time position.
int64_t	mlt_sample_calculator_to_now (float fps, int frequency, int64_t position)
	Determine the number of samples that belong before a time position.
Data Fields
int(*	convert_audio )(mlt_frame self, void *audio, mlt_audio_format input, mlt_audio_format output)
	Convert the audio format (callback function).
int(*	convert_image )(mlt_frame self, uint8_t *image, mlt_image_format input, mlt_image_format output)
	Convert the image format (callback function).
uint8_t (	get_alpha_mask )(mlt_frame self)
	Get the alpha channel (callback function).
Private Attributes
int	is_processing
	indicates if a frame is or was processed by the parallel consumer
struct mlt_properties_s	parent
	A frame extends properties.
mlt_deque	stack_audio
	the audio processing stack of operations and data
mlt_deque	stack_image
	the image processing stack of operations and data
mlt_deque	stack_service
	a general purpose data stack

Detailed Description

Frame class.

The frame is the primary data object that gets passed around to and through services.

Property:: test_image set if the frame holds a "test card" image

Property:: test_audio set if the frame holds "test card" audio

Property:: _producer holds a reference to the frame's end producer

Property:: _speed the current speed of the producer that generated the frame

Property:: _position the position of the frame

Property:: meta.* holds metadata

Property:: hide set to 1 to hide the video, 2 to mute the audio

Property:: last_track a flag to indicate an end-of-tracks frame

Property:: previous frame a reference to the unfiltered preceding frame (no speed factor applied, only available when _need_previous_next is set on the producer)

Property:: next frame a reference to the unfiltered following frame (no speed factor applied, only available when _need_previous_next is set on the producer)

Property:: colorspace the standard for luma coefficients

Property:: force_full_luma luma range handling, set to -1 for pass-through, 1 for full range, 0 for scaling

Property:: audio_frequency the sample rate of the audio

Property:: audio_channels the number of audio channels

Property:: audio_samples the number of audio samples

Property:: audio_format the mlt_audio_format for the audio on this frame

Property:: format the mlt_image_format of the image on this frame

Property:: width the horizontal resolution of the image

Property:: height the vertical resolution of the image

Property:: aspect_ratio the sample aspect ratio of the image

Member Function Documentation

const char * mlt_audio_format_name ( mlt_audio_format format )

Get the short name for an audio format.

You do not need to deallocate the returned string.

Parameters:

format an audio format enum

Returns:: a string for the name of the image format

int mlt_audio_format_size	(	mlt_audio_format	format,
		int	samples,
		int	channels
	)

Get the amount of bytes needed for a block of audio.

Parameters:

format	an audio format enum
samples	the number of samples per channel
channels	the number of channels

Returns:: the number of bytes

mlt_frame mlt_frame_clone	(	mlt_frame	self,
		int	is_deep
	)

Make a copy of a frame.

This does not copy the get_image/get_audio processing stacks or any data properties other than the audio and image.

Parameters:

self	the frame to clone
is_deep	a boolean to indicate whether to make a deep copy of the audio and video data chunks or to make a shallow copy by pointing to the supplied frame

Returns:: a almost-complete copy of the frame

Todo:: copy the processing deques

void mlt_frame_close ( mlt_frame self )

Destroy the frame.

Parameters:

self a frame

uint8_t * mlt_frame_get_alpha_mask ( mlt_frame self )

Get the alpha channel associated to the frame.

Parameters:

self a frame

Returns:: the alpha channel

double mlt_frame_get_aspect_ratio ( mlt_frame self )

Get the sample aspect ratio of the frame.

Parameters:

self a frame

Returns:: the aspect ratio

int mlt_frame_get_audio	(	mlt_frame	self,
		void **	buffer,
		mlt_audio_format *	format,
		int *	frequency,
		int *	channels,
		int *	samples
	)

Get the audio associated to the frame.

You should express the desired format, frequency, channels, and samples as inputs. As long as the loader producer was used to generate this or the audioconvert filter was attached, then you will get the audio back in the format you desire. However, you do not always get the channels and samples you request depending on properties and filters. You do not need to supply a pre-allocated buffer, but you should always supply the desired audio format. The audio is always in interleaved format. You should use the mlt_sample_calculator to determine the number of samples you want.

Parameters:

	self	a frame
[out]	buffer	an audio buffer
[in,out]	format	the audio format
[in,out]	frequency	the sample rate
[in,out]	channels
[in,out]	samples	the number of samples per frame

Returns:: true if error

int mlt_frame_get_image	(	mlt_frame	self,
		uint8_t **	buffer,
		mlt_image_format *	format,
		int *	width,
		int *	height,
		int	writable
	)

Get the image associated to the frame.

You should express the desired format, width, and height as inputs. As long as the loader producer was used to generate this or the imageconvert filter was attached, then you will get the image back in the format you desire. However, you do not always get the width and height you request depending on properties and filters. You do not need to supply a pre-allocated buffer, but you should always supply the desired image format.

Parameters:

	self	a frame
[out]	buffer	an image buffer
[in,out]	format	the image format
[in,out]	width	the horizontal size in pixels
[in,out]	height	the vertical size in pixels
	writable	whether or not you will need to be able to write to the memory returned in `buffer`

Returns:: true if error

Todo:: Better describe the width and height as inputs.

mlt_producer mlt_frame_get_original_producer ( mlt_frame self )

Get the end service that produced self frame.

This fetches the first producer of the frame and not any producers that encapsulate it.

Parameters:

self a frame

Returns:: a producer

mlt_position mlt_frame_get_position ( mlt_frame self )

Get the time position of this frame.

Parameters:

self a frame

Returns:: the position

unsigned char * mlt_frame_get_waveform	(	mlt_frame	self,
		int	w,
		int	h
	)

Get audio on a frame as a waveform image.

This generates an 8-bit grayscale image representation of the audio in a frame. Currently, this only really works for 2 channels. This allocates the bitmap using mlt_pool so you should release the return value with mlt_pool_release.

Parameters:

self	a frame
w	the width of the image
h	the height of the image to create

Returns:: a pointer to a new bitmap

mlt_frame mlt_frame_init ( mlt_service service )

Construct a frame object.

Parameters:

service the pointer to any service that can provide access to the profile

Returns:: a frame object on success or NULL if there was an allocation error

int mlt_frame_is_test_audio ( mlt_frame self )

Determine if the frame will produce audio from a test card.

Parameters:

self a frame

Returns:: true (non-zero) if this will produce from a test card

int mlt_frame_is_test_card ( mlt_frame self )

Determine if the frame will produce a test card image.

Parameters:

self a frame

Returns:: true (non-zero) if this will produce from a test card

void * mlt_frame_pop_audio ( mlt_frame self )

Pop an audio item from the stack.

Parameters:

self a frame

Returns:: an opaque pointer to something that was pushed onto the frame's audio stack

mlt_frame mlt_frame_pop_frame ( mlt_frame self )

Pop a frame.

Parameters:

self a frame

Returns:: a frame that was previously pushed

mlt_get_image mlt_frame_pop_get_image ( mlt_frame self )

Pop a get_image callback.

Parameters:

self a frame

Returns:: the get_image callback

void * mlt_frame_pop_service ( mlt_frame self )

Pop a service.

Parameters:

self a frame

Returns:: an opaque pointer to something previously pushed

int mlt_frame_pop_service_int ( mlt_frame self )

Pop a number.

Parameters:

self a frame

Returns:: an integer that was previously pushed

mlt_properties mlt_frame_properties ( mlt_frame self )

Get a frame's properties.

Parameters:

self a frame

Returns:: the frame's properties or NULL if an invalid frame is supplied

int mlt_frame_push_audio	(	mlt_frame	self,
		void *	that
	)

Push an audio item on the stack.

Parameters:

self	a frame
that	an opaque pointer

Returns:: true if error

int mlt_frame_push_frame	(	mlt_frame	self,
		mlt_frame	that
	)

Push a frame.

Parameters:

self	a frame
that	the frame to push onto `self`

Returns:: true if error

int mlt_frame_push_get_image	(	mlt_frame	self,
		mlt_get_image	get_image
	)

Stack a get_image callback.

Parameters:

self	a frame
the	get_image callback

Returns:: true if error

int mlt_frame_push_service	(	mlt_frame	self,
		void *	that
	)

Push a service.

Parameters:

self	a frame
that	an opaque pointer

Returns:: true if error

int mlt_frame_push_service_int	(	mlt_frame	self,
		int	that
	)

Push a number.

Parameters:

self	a frame
that	an integer

Returns:: true if error

void mlt_frame_replace_image	(	mlt_frame	self,
		uint8_t *	image,
		mlt_image_format	format,
		int	width,
		int	height
	)

Replace image stack with the information provided.

This might prove to be unreliable and restrictive - the idea is that a transition which normally uses two images may decide to only use the b frame (ie: in the case of a composite where the b frame completely obscures the a frame).

The image must be writable and the destructor for the image itself must be taken care of on another frame and that frame cannot have a replace applied to it... Further it assumes that no alpha mask is in use.

For these reasons, it can only be used in a specific situation - when you have multiple tracks each with their own transition and these transitions are applied in a strictly reversed order (ie: highest numbered [lowest track] is processed first).

More reliable approach - the cases should be detected during the process phase and the upper tracks should simply not be invited to stack...

Parameters:

self	a frame
image	a new image
format	the image format
width	the width of the new image
height	the height of the new image

mlt_deque mlt_frame_service_stack ( mlt_frame self )

Return the service stack.

Parameters:

self a frame

Returns:: the service stack

int mlt_frame_set_alpha	(	mlt_frame	self,
		uint8_t *	alpha,
		int	size,
		mlt_destructor	destroy
	)

Set a new alpha channel on the frame.

Parameters:

self	a frame
alpha	a pointer to the alpha channel
size	the size of the alpha channel in bytes (optional)
destroy	a function to deallocate `alpha` when the frame is closed (optional)

Returns:: true if error

int mlt_frame_set_aspect_ratio	(	mlt_frame	self,
		double	value
	)

Set the sample aspect ratio of the frame.

Parameters:

self	a frame
value	the new image sample aspect ratio

Returns:: true if error

int mlt_frame_set_audio	(	mlt_frame	self,
		void *	buffer,
		mlt_audio_format	format,
		int	size,
		mlt_destructor	destructor
	)

Set the audio on a frame.

Parameters:

self	a frame
buffer	an buffer containing audio samples
format	the format of the audio in the `buffer`
size	the total size of the buffer (optional)
destructor	a function that releases or deallocates the `buffer`

Returns:: true if error

int mlt_frame_set_image	(	mlt_frame	self,
		uint8_t *	image,
		int	size,
		mlt_destructor	destroy
	)

Set a new image on the frame.

Parameters:

self	a frame
image	a pointer to the raw image data
size	the size of the image data in bytes (optional)
destroy	a function to deallocate `image` when the frame is closed (optional)

Returns:: true if error

int mlt_frame_set_position	(	mlt_frame	self,
		mlt_position	value
	)

Set the time position of this frame.

Parameters:

self	a frame
value	the position

Returns:: true if error

mlt_properties mlt_frame_unique_properties	(	mlt_frame	self,
		mlt_service	service
	)

Get or create a properties object unique to this service instance.

Use this function to hold a service's processing parameters for this particular frame. Set the parameters in the service's process function. Then, get the parameters in the function it pushes to the frame's audio or image stack. This makes the service more parallel by reducing race conditions and less sensitive to multiple instances (by not setting a non-unique property on the frame). Creation and destruction of the properties object is handled automatically.

Parameters:

self	a frame
service	a service

Returns:: a properties object

const char * mlt_image_format_name ( mlt_image_format format )

Get the short name for an image format.

Parameters:

format the image format

Returns:: a string

int mlt_image_format_size	(	mlt_image_format	format,
		int	width,
		int	height,
		int *	bpp
	)

Get the number of bytes needed for an image.

Parameters:

	format	the image format
	width	width of the image in pixels
	height	height of the image in pixels
[out]	bpp	the number of bytes per pixel (optional)

Returns:: the number of bytes

int mlt_sample_calculator	(	float	fps,
		int	frequency,
		int64_t	position
	)

Determine the number of samples that belong in a frame at a time position.

Parameters:

fps	the frame rate
frequency	the sample rate
position	the time position

Returns:: the number of samples per channel

int64_t mlt_sample_calculator_to_now	(	float	fps,
		int	frequency,
		int64_t	position
	)

Determine the number of samples that belong before a time position.

Parameters:

fps	the frame rate
frequency	the sample rate
position	the time position

Returns:: the number of samples per channel

Bug:: Will this break when mlt_position is converted to double?

Field Documentation

int( * mlt_frame_s::convert_audio)(mlt_frame self, void **audio, mlt_audio_format *input, mlt_audio_format output)

Convert the audio format (callback function).

Parameters:

	self	a frame
[in,out]	audio	a buffer of audio data
[in,out]	input	the audio format of supplied data
	output	the audio format to which to convert

Returns:: true if error

int( * mlt_frame_s::convert_image)(mlt_frame self, uint8_t **image, mlt_image_format *input, mlt_image_format output)

Convert the image format (callback function).

Parameters:

	self	a frame
[in,out]	image	a buffer of image data
[in,out]	input	the image format of supplied image data
	output	the image format to which to convert

Returns:: true if error

uint8_t*( * mlt_frame_s::get_alpha_mask)(mlt_frame self)

Get the alpha channel (callback function).

Parameters:

self a frame

Returns:: the 8-bit alpha channel

int mlt_frame_s::is_processing [private]

indicates if a frame is or was processed by the parallel consumer

struct mlt_properties_s mlt_frame_s::parent [private]

A frame extends properties.

mlt_deque mlt_frame_s::stack_audio [private]

the audio processing stack of operations and data

mlt_deque mlt_frame_s::stack_image [private]

the image processing stack of operations and data

mlt_deque mlt_frame_s::stack_service [private]

a general purpose data stack

The documentation for this struct was generated from the following files:

mlt_frame_s Struct Reference

Public Member Functions

Data Fields

Private Attributes

Detailed Description

Member Function Documentation

Field Documentation