A/V sources
[A/V pipeline building elements]


Defines

#define GAVL_SOURCE_SRC_ALLOC   (1<<0)
 Source provides a pointer to an internal structure.
#define GAVL_SOURCE_SRC_FRAMESIZE_MAX   (1<<2)
 Samples per frame is just an upper bound. Frames can have smaller sizes also. The last frame is always allowed to have fewer samples, even if this flag is not set.
#define GAVL_SOURCE_SRC_DISCONTINUOUS   (1<<3)
 Stream is discontinuous. Set this for video sources delivering graphical subtitles.

Typedefs

typedef struct gavl_video_source_s gavl_video_source_t
 Forward declaration of the video source.
typedef struct gavl_audio_source_s gavl_audio_source_t
 Forward declaration of the audio source.
typedef struct gavl_packet_source_s gavl_packet_source_t
 Forward declaration of the packet source.
typedef gavl_source_status_t(* gavl_audio_source_func_t )(void *priv, gavl_audio_frame_t **frame)
 Prototype for obtaining one audio frame.
typedef gavl_source_status_t(* gavl_video_source_func_t )(void *priv, gavl_video_frame_t **frame)
 Prototype for obtaining one video frame.
typedef gavl_source_status_t(* gavl_packet_source_func_t )(void *priv, gavl_packet_t **p)
 Prototype for obtaining one packet.

Enumerations

enum  gavl_source_status_t {
  GAVL_SOURCE_EOF = 0,
  GAVL_SOURCE_OK = 1,
  GAVL_SOURCE_AGAIN = 2
}
 Return value of the source function. More...

Functions

GAVL_PUBLIC gavl_video_source_tgavl_video_source_create (gavl_video_source_func_t func, void *priv, int src_flags, const gavl_video_format_t *src_format)
 Create a video source.
GAVL_PUBLIC gavl_video_source_tgavl_video_source_create_source (gavl_video_source_func_t func, void *priv, int src_flags, gavl_video_source_t *src)
 Create a video source from another source.
GAVL_PUBLIC void gavl_video_source_set_lock_funcs (gavl_video_source_t *src, gavl_connector_lock_func_t lock_func, gavl_connector_lock_func_t unlock_func, void *priv)
 Set lock functions.
GAVL_PUBLIC gavl_video_options_tgavl_video_source_get_options (gavl_video_source_t *s)
 Get coversion options of a video source.
GAVL_PUBLIC void gavl_video_source_reset (gavl_video_source_t *s)
 Reset a video source.
GAVL_PUBLIC void gavl_video_source_destroy (gavl_video_source_t *s)
 Destroy a video source.
GAVL_PUBLIC const
gavl_video_format_t
gavl_video_source_get_src_format (gavl_video_source_t *s)
 Get the native format.
GAVL_PUBLIC const
gavl_video_format_t
gavl_video_source_get_dst_format (gavl_video_source_t *s)
 Get the output format.
GAVL_PUBLIC void gavl_video_source_set_dst (gavl_video_source_t *s, int dst_flags, const gavl_video_format_t *dst_format)
 Set the destination mode.
GAVL_PUBLIC gavl_source_status_t gavl_video_source_read_frame (void *s, gavl_video_frame_t **frame)
 Read a video frame.
GAVL_PUBLIC gavl_audio_source_tgavl_audio_source_create (gavl_audio_source_func_t func, void *priv, int src_flags, const gavl_audio_format_t *src_format)
 Create an audio source.
GAVL_PUBLIC gavl_audio_source_tgavl_audio_source_create_source (gavl_audio_source_func_t func, void *priv, int src_flags, gavl_audio_source_t *src)
 Create an audio source from another source.
GAVL_PUBLIC void gavl_audio_source_set_lock_funcs (gavl_audio_source_t *src, gavl_connector_lock_func_t lock_func, gavl_connector_lock_func_t unlock_func, void *priv)
 Set lock functions.
GAVL_PUBLIC const
gavl_audio_format_t
gavl_audio_source_get_src_format (gavl_audio_source_t *s)
 Get the native format.
GAVL_PUBLIC const
gavl_audio_format_t
gavl_audio_source_get_dst_format (gavl_audio_source_t *s)
 Get the output format.
GAVL_PUBLIC void gavl_audio_source_set_dst (gavl_audio_source_t *s, int dst_flags, const gavl_audio_format_t *dst_format)
 Set the destination mode.
GAVL_PUBLIC gavl_source_status_t gavl_audio_source_read_frame (void *s, gavl_audio_frame_t **frame)
 Read an audio frame.
GAVL_PUBLIC void gavl_audio_source_skip_src (gavl_audio_source_t *s, int num_samples)
 Skip audio samples at the input.
GAVL_PUBLIC int gavl_audio_source_read_samples (void *s, gavl_audio_frame_t *frame, int num_samples)
 Read audio samples.
GAVL_PUBLIC gavl_audio_options_tgavl_audio_source_get_options (gavl_audio_source_t *s)
 Get coversion options of an audio source.
GAVL_PUBLIC void gavl_audio_source_reset (gavl_audio_source_t *s)
 Reset an audio source.
GAVL_PUBLIC void gavl_audio_source_destroy (gavl_audio_source_t *s)
 Destroy an audio source.
GAVL_PUBLIC gavl_packet_source_tgavl_packet_source_create_audio (gavl_packet_source_func_t func, void *priv, int src_flags, const gavl_compression_info_t *ci, const gavl_audio_format_t *afmt)
 Create an audio packet source.
GAVL_PUBLIC gavl_packet_source_tgavl_packet_source_create_video (gavl_packet_source_func_t func, void *priv, int src_flags, const gavl_compression_info_t *ci, const gavl_video_format_t *vfmt)
 Create a video packet source.
GAVL_PUBLIC gavl_packet_source_tgavl_packet_source_create_text (gavl_packet_source_func_t func, void *priv, int src_flags, int timescale)
 Create a text packet source.
GAVL_PUBLIC gavl_packet_source_tgavl_packet_source_create_source (gavl_packet_source_func_t func, void *priv, int src_flags, gavl_packet_source_t *src)
 Create a packet source from another packet source.
GAVL_PUBLIC void gavl_packet_source_set_lock_funcs (gavl_packet_source_t *src, gavl_connector_lock_func_t lock_func, gavl_connector_lock_func_t unlock_func, void *priv)
 Set lock functions.
GAVL_PUBLIC const
gavl_compression_info_t
gavl_packet_source_get_ci (gavl_packet_source_t *s)
 Get the compression info.
GAVL_PUBLIC const
gavl_audio_format_t
gavl_packet_source_get_audio_format (gavl_packet_source_t *s)
 Get the audio format.
GAVL_PUBLIC const
gavl_video_format_t
gavl_packet_source_get_video_format (gavl_packet_source_t *s)
 Get the video format.
GAVL_PUBLIC int gavl_packet_source_get_timescale (gavl_packet_source_t *s)
 Get the time scale.
GAVL_PUBLIC gavl_source_status_t gavl_packet_source_read_packet (void *s, gavl_packet_t **p)
 Read one packet.
GAVL_PUBLIC void gavl_packet_source_destroy (gavl_packet_source_t *s)
 Destroy a packet source.

Detailed Description

A/V sources are elements, which can be used to conveniently pass audio or video frames from one program module to another. They do implicit format conversion and optimized buffer handling.

A module, which provides A/V frames, creates a source module and tells the native format in which it provides the frames. If you want to obtain the frames from the source, you tell the desired output format and if you intend to overwrite the frames.

To obtain the frames, you pass the address of the pointer of the frame. If the pointer is NULL, it will be set to an internal buffer.

The return value is of the type gavl_source_status_t, which can have 3 states depending on whether the stream ended (EOF) or a frame is available or if no frame is available right now. The latter can be used to implement parts of the pipeline in pull mode (the default) and others in push mode.


Define Documentation

#define GAVL_SOURCE_SRC_ALLOC   (1<<0)

Source provides a pointer to an internal structure.

#define GAVL_SOURCE_SRC_FRAMESIZE_MAX   (1<<2)

Samples per frame is just an upper bound. Frames can have smaller sizes also. The last frame is always allowed to have fewer samples, even if this flag is not set.

#define GAVL_SOURCE_SRC_DISCONTINUOUS   (1<<3)

Stream is discontinuous. Set this for video sources delivering graphical subtitles.


Typedef Documentation

typedef struct gavl_video_source_s gavl_video_source_t

Forward declaration of the video source.

You don't want to know what's inside

typedef struct gavl_audio_source_s gavl_audio_source_t

Forward declaration of the audio source.

You don't want to know what's inside

typedef struct gavl_packet_source_s gavl_packet_source_t

Forward declaration of the packet source.

You don't want to know what's inside

Prototype for obtaining one audio frame.

Parameters:
priv Client data
frame Where to store the frame
If *frame is non-null, the data will be copied there, otherwise the address of an internally allocated frame is returned

Prototype for obtaining one video frame.

Parameters:
priv Client data
frame Where to store the frame
If *frame is non-null, the data will be copied there, otherwise the address of an internally allocated frame is returned.

Prototype for obtaining one packet.

Parameters:
priv Client data
frame Where to store the packet
If *packet is non-null, the data will be copied there, otherwise the address of an internally allocated packet is returned.


Enumeration Type Documentation

Return value of the source function.

Enumerator:
GAVL_SOURCE_EOF  End of file, no more frames available.
GAVL_SOURCE_OK  Frame available.
GAVL_SOURCE_AGAIN  No frame available right now, might try later.


Function Documentation

GAVL_PUBLIC gavl_video_source_t* gavl_video_source_create ( gavl_video_source_func_t  func,
void *  priv,
int  src_flags,
const gavl_video_format_t src_format 
)

Create a video source.

Parameters:
func Function to get the frames from
priv Client data to pass to func
src_flags Flags describing the source
src_format Native source format
Returns:
A newly created video source

GAVL_PUBLIC gavl_video_source_t* gavl_video_source_create_source ( gavl_video_source_func_t  func,
void *  priv,
int  src_flags,
gavl_video_source_t src 
)

Create a video source from another source.

Parameters:
func Function to get the frames from
priv Client data to pass to func
src_flags Flags describing the source
src preceeding source in the pipeline
Returns:
A newly created video source
This will take the destination format of the preceeding source as the input format

GAVL_PUBLIC void gavl_video_source_set_lock_funcs ( gavl_video_source_t src,
gavl_connector_lock_func_t  lock_func,
gavl_connector_lock_func_t  unlock_func,
void *  priv 
)

Set lock functions.

Parameters:
src A video source
lock_func Function called before a frame is read
unlock_func Function called after a frame is read
priv Client data (e.g. a mutex) to pass to the functions

GAVL_PUBLIC gavl_video_options_t* gavl_video_source_get_options ( gavl_video_source_t s  ) 

Get coversion options of a video source.

Parameters:
s A video source
Returns:
Conversion options

GAVL_PUBLIC void gavl_video_source_reset ( gavl_video_source_t s  ) 

Reset a video source.

Parameters:
s A video source
Call this after seeking to reset the internal state

GAVL_PUBLIC void gavl_video_source_destroy ( gavl_video_source_t s  ) 

Destroy a video source.

Parameters:
s A video source
Destroy a video source including all video frames ever created by it.

GAVL_PUBLIC const gavl_video_format_t* gavl_video_source_get_src_format ( gavl_video_source_t s  ) 

Get the native format.

Parameters:
s A video source
Returns:
The native video format

GAVL_PUBLIC const gavl_video_format_t* gavl_video_source_get_dst_format ( gavl_video_source_t s  ) 

Get the output format.

Parameters:
s A video source
Returns:
The video format in which frames are read

GAVL_PUBLIC void gavl_video_source_set_dst ( gavl_video_source_t s,
int  dst_flags,
const gavl_video_format_t dst_format 
)

Set the destination mode.

Parameters:
s A video source
dst_flags Flags
dst_format Format in which the frames will be read
If you accept the source format (as returned by gavl_video_source_get_src_format) you can pass NULL for the dst_format.

If the destination format differs from the source format, the frames will converted. For this, we have a gavl_video_converter_t and also do simple framerate conversion which repeats/drops frames.

GAVL_PUBLIC gavl_source_status_t gavl_video_source_read_frame ( void *  s,
gavl_video_frame_t **  frame 
)

Read a video frame.

Parameters:
s A video source
frame Address of a frame.
This reads one frame from the source. If *frame is NULL it will be set to an internal buffer, otherwise the data is copied to the frame you pass.

GAVL_PUBLIC gavl_audio_source_t* gavl_audio_source_create ( gavl_audio_source_func_t  func,
void *  priv,
int  src_flags,
const gavl_audio_format_t src_format 
)

Create an audio source.

Parameters:
func Function to get the frames from
priv Client data to pass to func
src_flags Flags describing the source
src_format Native source format
Returns:
A newly created audio source

GAVL_PUBLIC gavl_audio_source_t* gavl_audio_source_create_source ( gavl_audio_source_func_t  func,
void *  priv,
int  src_flags,
gavl_audio_source_t src 
)

Create an audio source from another source.

Parameters:
func Function to get the frames from
priv Client data to pass to func
src_flags Flags describing the source
src preceeding source in the pipeline
Returns:
A newly created audio source
This will take the destination format of the preceeding source as the input format

GAVL_PUBLIC void gavl_audio_source_set_lock_funcs ( gavl_audio_source_t src,
gavl_connector_lock_func_t  lock_func,
gavl_connector_lock_func_t  unlock_func,
void *  priv 
)

Set lock functions.

Parameters:
src An audio source
lock_func Function called before a frame is read
unlock_func Function called after a frame is read
priv Client data (e.g. a mutex) to pass to the functions

GAVL_PUBLIC const gavl_audio_format_t* gavl_audio_source_get_src_format ( gavl_audio_source_t s  ) 

Get the native format.

Parameters:
s An audio source
Returns:
The native audio format

GAVL_PUBLIC const gavl_audio_format_t* gavl_audio_source_get_dst_format ( gavl_audio_source_t s  ) 

Get the output format.

Parameters:
s An audio source
Returns:
The format in which frames will be read

GAVL_PUBLIC void gavl_audio_source_set_dst ( gavl_audio_source_t s,
int  dst_flags,
const gavl_audio_format_t dst_format 
)

Set the destination mode.

Parameters:
s An audio source
dst_flags Flags
dst_format Format in which the frames will be read
If you accept the source format (as returned by gavl_video_source_get_src_format) you can pass NULL for the dst_format.

If the destination format differs from the source format, the frames will converted. For this, we have a gavl_audio_converter_t. In addition, if the samples_per_frame members are different, the frames will be repackaged.

GAVL_PUBLIC gavl_source_status_t gavl_audio_source_read_frame ( void *  s,
gavl_audio_frame_t **  frame 
)

Read an audio frame.

Parameters:
s An audio source
frame Address of a frame.
Returns:
The status
This reads one frame from the source. If *frame is NULL it will be set to an internal buffer, otherwise the data is copied to the frame you pass.

If the return value is GAVL_SOURCE_AGAIN, you might have an imcomplete frame. In this case you must call this function again with exactly the same frame argument.

GAVL_PUBLIC void gavl_audio_source_skip_src ( gavl_audio_source_t s,
int  num_samples 
)

Skip audio samples at the input.

Parameters:
s An audio source
num_samples Number of samples to skip
This skips a number of input samples. It can be used after seeking if the sample position after a seek is no multiple of the frame size.

GAVL_PUBLIC int gavl_audio_source_read_samples ( void *  s,
gavl_audio_frame_t frame,
int  num_samples 
)

Read audio samples.

Parameters:
s An audio source
frame An audio frame
num_samples Number of samples to read
This is for APIs, which pass the number of samples to each read() call and the number is not known in advance.

GAVL_PUBLIC gavl_audio_options_t* gavl_audio_source_get_options ( gavl_audio_source_t s  ) 

Get coversion options of an audio source.

Parameters:
s An audio source
Returns:
Conversion options

GAVL_PUBLIC void gavl_audio_source_reset ( gavl_audio_source_t s  ) 

Reset an audio source.

Parameters:
s An audio source
This resets the internal state as if no frame was read yet.

GAVL_PUBLIC void gavl_audio_source_destroy ( gavl_audio_source_t s  ) 

Destroy an audio source.

Parameters:
s An audio source
Destroy an audio source including all audio frames ever created by it.

GAVL_PUBLIC gavl_packet_source_t* gavl_packet_source_create_audio ( gavl_packet_source_func_t  func,
void *  priv,
int  src_flags,
const gavl_compression_info_t ci,
const gavl_audio_format_t afmt 
)

Create an audio packet source.

Parameters:
func Callback for reading one frame
priv Client data to be passed to func
src_flags Flags
ci Compression info
afmt Format of the audio stream

GAVL_PUBLIC gavl_packet_source_t* gavl_packet_source_create_video ( gavl_packet_source_func_t  func,
void *  priv,
int  src_flags,
const gavl_compression_info_t ci,
const gavl_video_format_t vfmt 
)

Create a video packet source.

Parameters:
func Callback for reading one frame
priv Client data to be passed to func
src_flags Flags
ci Compression info
vfmt Format of the video stream

GAVL_PUBLIC gavl_packet_source_t* gavl_packet_source_create_text ( gavl_packet_source_func_t  func,
void *  priv,
int  src_flags,
int  timescale 
)

Create a text packet source.

Parameters:
func Callback for reading one frame
priv Client data to be passed to func
src_flags Flags
scale Timescale of the text packets

GAVL_PUBLIC gavl_packet_source_t* gavl_packet_source_create_source ( gavl_packet_source_func_t  func,
void *  priv,
int  src_flags,
gavl_packet_source_t src 
)

Create a packet source from another packet source.

Parameters:
func Callback for reading one frame
priv Client data to be passed to func
src_flags Flags
src Source to copy the stream specific data from

GAVL_PUBLIC void gavl_packet_source_set_lock_funcs ( gavl_packet_source_t src,
gavl_connector_lock_func_t  lock_func,
gavl_connector_lock_func_t  unlock_func,
void *  priv 
)

Set lock functions.

Parameters:
src A packet source
lock_func Function called before a packet is read
unlock_func Function called after a packet is read
priv Client data (e.g. a mutex) to pass to the functions

GAVL_PUBLIC const gavl_compression_info_t* gavl_packet_source_get_ci ( gavl_packet_source_t s  ) 

Get the compression info.

Parameters:
s A packet source
Returns:
The compression info or NULL

GAVL_PUBLIC const gavl_audio_format_t* gavl_packet_source_get_audio_format ( gavl_packet_source_t s  ) 

Get the audio format.

Parameters:
s A packet source
Returns:
The audio format or NULL

GAVL_PUBLIC const gavl_video_format_t* gavl_packet_source_get_video_format ( gavl_packet_source_t s  ) 

Get the video format.

Parameters:
s A packet source
Returns:
The video format or NULL

GAVL_PUBLIC int gavl_packet_source_get_timescale ( gavl_packet_source_t s  ) 

Get the time scale.

Parameters:
s A packet source
Returns:
The time scale

GAVL_PUBLIC gavl_source_status_t gavl_packet_source_read_packet ( void *  s,
gavl_packet_t **  p 
)

Read one packet.

Parameters:
s A packet source
Returns:
The status

GAVL_PUBLIC void gavl_packet_source_destroy ( gavl_packet_source_t s  ) 

Destroy a packet source.

Parameters:
s A packet source


Generated on Sun Sep 6 17:35:01 2015 for gavl by  doxygen 1.5.6