Browse files

Merged 1603

  • Loading branch information...
1 parent d4cce9c commit ba0f7afecdff1071efb2369e1d1fa48a3239a935 @mbunkus committed Mar 21, 2004
Showing with 62 additions and 9 deletions.
  1. +4 −2 librmff/README
  2. +58 −7 librmff/librmff.h
View
6 librmff/README
@@ -1,5 +1,5 @@
-librmff 0.1
-===========
+librmff 0.5.0
+=============
librmff is short for 'RealMedia file format access library'. It aims
at providing the programmer an easy way to read and write RealMedia
@@ -8,3 +8,5 @@ files. It does not contain any codecs for audio/video handling.
The library was written by Moritz Bunkus <moritz@bunkus.org>. It is
licensed under the terms of the GNU Lesser General Public License (GNU
LGPL) which can be found in the file COPYING.
+
+Documentation is provided in doxygen compatible comments in librmff.h.
View
65 librmff/librmff.h
@@ -23,7 +23,7 @@
\brief The RealMedia file format library
\author Moritz Bunkus <moritz@bunkus.org>
- \version $Id$
+ $Id$
*/
/** \mainpage
@@ -57,7 +57,7 @@
rmff_frame_t *frame;
file = rmff_open_file("sample_file.rm", RMFF_OPEN_MODE_READING);
- if (file != NULL) {
+ if (file == NULL) {
// Handle the error.
return;
}
@@ -72,12 +72,57 @@
rmff_close_file(file);
\endcode
+ \subsection creating_new Creating a new file
+
+ Creating a new file is a bit more complex. This library only provides a
+ low level codec independant layer to the RealMedia file format.
+
+ Creating a new file involves the following step in this particular order:
+ -# open a new file with \c RMFF_OPEN_MODR_WRITING,
+ -# add track entries with ::rmff_add_track,
+ -# write the headers with ::rmff_write_headers,
+ -# write all the frames with ::rmff_write_frame,
+ -# optionally write the indexes with ::rmff_write_index,
+ -# fix all the headers with ::rmff_fix_headers and
+ -# close the file with ::rmff_close_file.
+
+ Please note that the error handling is not shown in the following example:
+ \code
+ rmff_file_t *file;
+ rmff_track_t *track;
+ rmff_frame_t *frame;
+
+ file = rmff_open_file("new_file.rm", RMFF_OPEN_MODE_WRITING);
+ track = rmff_add_track(file, 1); // Also create an index for this track.
+ // The track types etc are stored in the ::rmff_mdpr_t#type_specific_data
+ // It usually contains a ::real_audio_v4_props_t, ::real_audio_v5_props_t
+ // or ::real_video_props_t structures which have to be set by the
+ // calling application.
+
+ // After setting the structures:
+ rmff_write_headers(file);
+ while (!done) {
+ // Generate frames.
+ ...
+ frame = rmff_allocate_frame(size, NULL);
+ rmff_write_frame(track, frame);
+ rmff_release_frame(frame);
+ }
+ rmff_write_index(file);
+ rmff_fix_headers(file);
+ rmff_close_file(file);
+ \endcode
+
\section memory_handling Memory handling
Generally \a librmff allocates and frees memory itself. You should
\b never mess with pointers inside the structures directly but use
- the provided functions for manipulating it. There's one exception to
- this rule: the frame handling.
+ the provided functions for manipulating it. There are two exceptions to
+ this rule: the frame handling and the \c app_data pointers.
+
+ The \c app_data members in ::rmff_file_t and ::rmff_track_t are never
+ touched by \a librmff and can be used by the application to store
+ its own data.
The functions ::rmff_read_next_frame, ::rmff_release_frame and
::rmff_allocate_frame allow the application to provide its
@@ -120,6 +165,12 @@ extern "C" {
#include "mb_file_io.h"
+#define RMFF_VERSION_MAJOR 0
+#define RMFF_VERSION_MINOR 5
+#define RMFF_VERSION_MICRO 0
+#define RMFF_VERSION (RMFF_VERSION_MAJOR * 10000 + RMFF_VERSION_MINOR * 100 + \
+ RMFF_VERSION_MICRO)
+
/** \brief The stream may be saved to disc. Can be set in the
\link ::rmff_prop_t PROP header\endlink. */
#define RMFF_FILE_FLAG_SAVE_ENABLED 0x0001
@@ -138,7 +189,7 @@ extern "C" {
::rmff_get_uint32_be, ::rmff_put_uint16_be and
::rmff_put_uint32_be for accessing the members.
*/
-typedef struct {
+typedef struct rmff_prop_t {
uint32_t max_bit_rate;
uint32_t avg_bit_rate;
uint32_t max_packet_size;
@@ -158,7 +209,7 @@ typedef struct {
strings must not be modified by the application. The function
::rmff_set_cont_header must be used instead.
*/
-typedef struct {
+typedef struct rmff_cont_t {
char *title;
char *author;
char *copyright;
@@ -173,7 +224,7 @@ typedef struct {
::rmff_get_uint32_be, ::rmff_put_uint16_be and
::rmff_put_uint32_be for accessing the members.
*/
-typedef struct {
+typedef struct rmff_mdpr_t {
/** \brief The track number. It is unique regarding the file. */
uint16_t id;
/** \brief The maximum bitrate in bits/second.

0 comments on commit ba0f7af

Please sign in to comment.