Main Page | Modules | Data Structures | Directories | Data Fields | Related Pages

Input/Output Interfaces


Data Structures

struct  rte_buffer

Typedefs

typedef rte_bool(* rte_buffer_callback )(rte_context *context, rte_codec *codec, rte_buffer *buffer)
typedef rte_bool(* rte_seek_callback )(rte_context *context, long long offset, int whence)

Functions

rte_bool rte_set_input_callback_master (rte_codec *codec, rte_buffer_callback read_cb, rte_buffer_callback unref_cb, unsigned int *queue_length)
rte_bool rte_set_input_callback_slave (rte_codec *codec, rte_buffer_callback read_cb)
rte_bool rte_set_input_push_master (rte_codec *codec, rte_buffer_callback unref_cb, unsigned int queue_request, unsigned int *queue_length)
rte_bool rte_set_input_push_slave (rte_codec *codec, unsigned int queue_request, unsigned int *queue_length)
rte_bool rte_push_buffer (rte_codec *codec, rte_buffer *buffer, rte_bool blocking)
rte_bool rte_set_output_callback_slave (rte_context *context, rte_buffer_callback write_cb, rte_seek_callback seek_cb)
rte_bool rte_set_output_stdio (rte_context *context, int fd)
rte_bool rte_set_output_file (rte_context *context, const char *filename)
rte_bool rte_set_output_discard (rte_context *context)

Typedef Documentation

typedef rte_bool(* rte_buffer_callback)(rte_context *context, rte_codec *codec, rte_buffer *buffer)
 

Parameters:
context rte_context this operation refers to.
codec rte_codec this operation refers to (if any).
buffer Pointer to rte_buffer.
When a function of this type is called to read more data in master callback mode, the rte client must initialize the buffer fields .data, .size and .timestamp. In slave callback mode .data points to the buffer space to store the data and .size is the free space, so the client must set .timestamp and may set .size and .user_data.

When a function of this type is called to unreference data, it passes the same buffer contents (but not necessarily the same buffer pointer) exchanged at the respective read callback or rte_push_buffer() before.

When a function of this type is called to write data, codec is NULL and the buffer fields .data and .size are initialized. buffer will be NULL once to indicate the end of the stream.

Do not depend on the value of the buffer pointer, use buffer->user_data instead.

Warning:
A codec may read more than once before unreferencing the data, and it may also unreference the data in a different order than it has been read.
Returns:
On error the callback can return FALSE to abort encoding.

typedef rte_bool(* rte_seek_callback)(rte_context *context, long long offset, int whence)
 

Parameters:
context rte_context this operation refers to.
offset Position to seek to. NOTE: On GNU/Linux files are opened with O_LARGEFILE, so clients should use lseek64(). When only 32 bit I/O is available and offset is > INT_MAX the callback should return FALSE. (I would define this as off64_t if I knew a clean & portable way.)
whence SEEK_SET..., see man lseek.
The context requests to seek to the given stream position. offset and whence follow lseek semantics. The first byte of the next buffer passed shall be stored at the new position.

Returns:
On error the callback can return FALSE to abort encoding.


Function Documentation

rte_bool rte_set_input_callback_master rte_codec codec,
rte_buffer_callback  read_cb,
rte_buffer_callback  unref_cb,
unsigned int *  queue_length
 

Parameters:
codec Pointer to a rte_codec returned by rte_get_codec() or rte_set_codec().
read_cb Function called by the codec to read more data to encode.
unref_cb Optional function called by the codec to free the data.
queue_length When non-zero, the codec queue length is returned here. That is the maximum number of buffers read before freeing the oldest. When for example read_cb and unref_cb calls always pair, this number is 1.
Sets the input mode for the codec and puts the codec into ready state. Using this method, when the codec needs more data it will call read_cb with a rte_buffer to be initialized by the rte client. After using the data, it is released by calling unref_cb. See rte_buffer_callback for the handshake details.

Warning:
A codec may read more than once before freeing the data, and it may also free the data in a different order than it has been read. As of RTE version 0.5, this is the only input method all codecs must implement.
Typical usage of rte_set_input_callback_master():
 rte_bool
 my_read_cb (rte_context *context, rte_codec *codec, rte_buffer *buffer)
 {
         buffer->data = malloc ();
         read (buffer->data, &buffer->timestamp);
         return TRUE;
 }
 
 rte_bool
 my_unref_cb (rte_context *context, rte_codec *codec, rte_buffer *buffer)
 {
         free (buffer->data);
 }

Returns:
Before selecting an input method you must negotiate sample parameters with rte_parameters_set(), else this function fails with a return value of FALSE. Setting codec options invalidates previously selected sample parameters, and thus also the input method selection. The function can also fail when the codec does not support this input method.

rte_bool rte_set_input_callback_slave rte_codec codec,
rte_buffer_callback  read_cb
 

Parameters:
codec Pointer to a rte_codec returned by rte_get_codec() or rte_set_codec().
read_cb Function called by the codec to read more data to encode.
Sets the input mode for the codec and puts the codec into ready state. Using this method the codec allocates the necessary buffers. When it needs more data it calls read_cb, passing a pointer to the buffer space where the client shall copy the data.

Typical usage of rte_set_input_callback_slave():

 rte_bool
 my_read_cb (rte_context *context, rte_codec *codec, rte_buffer *buffer)
 {
         read (buffer->data, &buffer->timestamp);
         return TRUE;
 }

Returns:
Before selecting an input method you must negotiate sample parameters with rte_parameters_set(), else this function fails with a return value of FALSE. Setting codec options invalidates previously selected sample parameters, and thus also the input method selection. The function can also fail when the codec does not support this input method.

rte_bool rte_set_input_push_master rte_codec codec,
rte_buffer_callback  unref_cb,
unsigned int  queue_request,
unsigned int *  queue_length
 

Parameters:
codec Pointer to a rte_codec returned by rte_get_codec() or rte_set_codec().
unref_cb Optional function called as subroutine of rte_push_buffer() to free the data.
queue_request The minimum number of buffers you will be able to push before rte_push_buffer() blocks.
queue_length When non-zero the codec queue length is returned here. This is at least the number of buffers read before freeing the oldest, and at most queue_request. When for example rte_push_buffer() and unref_cb calls always pair, the length is 1.
Sets the input mode for the codec and puts the codec into ready state. Using this method, when the codec needs data it waits until the rte client calls rte_push_buffer(). After using the data, it is released by calling unref_cb. See rte_buffer_callback for the handshake details.

Warning:
A codec may wait for more than one buffer before releasing the oldest, it may also unref in a different order than has been pushed.
Typical usage of rte_set_input_push_master():
 rte_bool
 my_unref_cb (rte_context *context, rte_codec *codec, rte_buffer *buffer)
 {
         free (buffer->data);
 }
 
 while (have_data) {
         rte_buffer buffer;
 
           buffer.data = malloc ();
         read (buffer.data, &buffer.timestamp);
         if (!rte_push_buffer (codec, &buffer, FALSE)) {
                 // The codec is not fast enough, we drop the frame.
                 free (buffer.data);
         }
 }

Returns:
Before selecting an input method you must negotiate sample parameters with rte_parameters_set(), else this function fails with a return value of FALSE. Setting codec options invalidates previously selected sample parameters, and thus also the input method selection. The function can also fail when the codec does not support this input method.

rte_bool rte_set_input_push_slave rte_codec codec,
unsigned int  queue_request,
unsigned int *  queue_length
 

Parameters:
codec Pointer to a rte_codec returned by rte_get_codec() or rte_set_codec().
queue_request The minimum number of buffers you will be able to push before rte_push_buffer() blocks.
queue_length When non-zero the actual codec queue length is returned here, this may be more or less than queue_request.
Sets the input mode for the codec and puts the codec into ready state. Using this method the codec allocates the necessary buffers. When it needs more data it waits until the rte client calls rte_push_buffer(). In buffer->data this function always returns a pointer to buffer space where the rte client shall store the data. You can pass NULL as buffer->data to start the cycle.

Typical usage of rte_set_input_push_slave():

 rte_buffer buffer;
 
 buffer.data = NULL;

 rte_push_buffer (codec, &buffer, FALSE); // cannot fail
 
 while (have_data) {
         read (buffer.data, &buffer.timestamp);
         if (!rte_push_buffer(codec, &buffer, FALSE)) {
         // The codec is not fast enough, we drop the frame.
         }
 }

Returns:
Before selecting an input method you must negotiate sample parameters with rte_parameters_set(), else this function fails with a return value of FALSE. Setting codec options invalidates previously selected sample parameters, and thus also the input method selection. The function can also fail when the codec does not support this input method.

rte_bool rte_push_buffer rte_codec codec,
rte_buffer buffer,
rte_bool  blocking
 

Parameters:
codec Pointer to a rte_codec returned by rte_get_codec() or rte_set_codec().
buffer Pointer to a rte_buffer, can be NULL.
blocking TRUE to enable blocking behaviour.
Passes data for encoding to the codec when the input method is 'push'. When the codec input queue is full and blocking is TRUE this function waits until space becomes available, when blocking is FALSE it immediately returns FALSE.

Returns:
FALSE if the function would block. In master push mode and when the function fails, the contents of buffer are unmodified on return. Otherwise in slave push mode, buffer->data points to the next buffer space to be filled. You can always obtain a pointer by calling rte_push_buffer() with buffer->data set to NULL, in master push mode this does nothing.

rte_bool rte_set_output_callback_slave rte_context context,
rte_buffer_callback  write_cb,
rte_seek_callback  seek_cb
 

Parameters:
context Initialized rte_context as returned by rte_context_new().
write_cb Function called by the context to write encoded data. The codec parameter of the callback is not used (NULL).
seek_cb Optional function called by the context to move the output file pointer, for example to complete a header.
Sets the output mode for the context and makes the context ready to start encoding. Using this method the codec allocates the necessary buffers, when data is available for writing it calls write_cb with buffer->data and buffer->size initialized.

Typical usage of rte_set_output_callback_slave():

 rte_bool
 my_write_cb (rte_context *context, rte_codec *codec, rte_buffer *buffer)
 {
         ssize_t actual;
 
         if (!buffer) // EOF
                 return TRUE;
 
         do actual = write (STDOUT_FILENO, buffer->data, buffer->size);
         while (actual == -1 && errno == EINTR);
 
         return actual == buffer->size; // no error
 }
 
 rte_bool
 my_seek_cb (rte_context *context, long long offset, int whence)
 {
         return lseek64 (STDOUT_FILENO, offset, whence) != (off64_t) -1;
 }

Returns:
Before selecting an output method you must select input methods for all codecs, else this function fails with a return value of FALSE. Setting context options or selecting or removing codecs cancels the output method selection.

rte_bool rte_set_output_stdio rte_context context,
int  fd
 

Parameters:
context Initialized rte_context as returned by rte_context_new().
fd File descriptor to write to.
Sets the output mode for the context and makes the context ready to start encoding. All output of the codec will be written into the given file. Where possible the file must be opened in 64 bit mode (O_LARGEFILE flag). The context may need to seek(), see rte_context_info.

Returns:
Before selecting an output method you must select input methods for all codecs, else this function fails with a return value of FALSE. Setting context options or selecting or removing codecs cancels the output method selection.

rte_bool rte_set_output_file rte_context context,
const char *  filename
 

Parameters:
context Initialized rte_context as returned by rte_context_new().
filename Name of the file to create.
Sets the output mode for the context and makes the context ready to start encoding. This function creates a file where all output of the codec will be written to.

Returns:
Before selecting an output method you must select input methods for all codecs, else this function fails with a return value of FALSE. Setting context options or selecting or removing codecs cancels the output method selection. When the file could not be created this function also returns FALSE.

rte_bool rte_set_output_discard rte_context context  ) 
 

Parameters:
context Initialized rte_context as returned by rte_context_new().
Sets the output mode for the context and makes the context ready to start encoding. All output of the codec will be discarded (for testing purposes).

Returns:
Before selecting an output method you must select input methods for all codecs, else this function fails with a return value of FALSE. Setting context options or selecting or removing codecs cancels the output method selection.


Generated on Wed Apr 27 17:00:25 2005 for RTE Library by  doxygen 1.4.2