Initial revision

1 files changed, 306 insertions, 0 deletions

diff --git a/core/multimedia/opieplayer/libmpeg3/docs/index.html b/core/multimedia/opieplayer/libmpeg3/docs/index.html
new file mode 100644
index 0000000..2d79978
--- a/dev/null
+++ b/core/multimedia/opieplayer/libmpeg3/docs/index.html
@@ -0,0 +1,306 @@
+<TITLE>LibMPEG3</TITLE>
+
+<CENTER>
+<FONT FACE=HELVETICA SIZE=+4><B>Using LibMPEG3 to make your own MPEG applications</B></FONT><P>
+
+<TABLE>
+<TR>
+<TD>
+<CODE>
+Author: Adam Williams    broadcast@earthling.net<BR>
+Homepage: heroinewarrior.com<BR>
+</CODE>
+</TD>
+</TR>
+</TABLE>
+</CENTER>
+
+<P>
+
+
+LibMPEG3 decodes the many many derivatives of MPEG standards into
+uncompressed data suitable for editing and playback.<P>
+
+libmpeg3 currently decodes:<P>
+
+<BLOCKQUOTE>MPEG-2 video<BR>
+MPEG-1 video<BR>
+mp3 audio<BR>
+mp2 audio<BR>
+ac3 audio<BR>
+MPEG-2 system streams<BR>
+MPEG-1 system streams
+</BLOCKQUOTE><P>
+
+The video output can be in many different color models and frame
+sizes.  The audio output can be in twos compliment or floating
+point.<P>
+
+
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 1: Verifying file compatibility</B></FONT><P>
+
+Programs using libmpeg3 must <CODE>#include "libmpeg3.h"</CODE>.<P>
+
+Call <CODE>mpeg3_check_sig</CODE> to verify if the file can be read by
+libmpeg3.  This returns a 1 if it is compatible and 0 if it isn't.<P>
+
+
+
+
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 2: Open the file</B></FONT><P>
+
+You need an <CODE>mpeg3_t*</CODE> file descriptor:<P>
+<CODE>
+mpeg3_t* file;
+</CODE>
+<P>
+
+Then you need to open the file:<P>
+
+<CODE>file = mpeg3_open(char *path);</CODE><P>
+
+<CODE>mpeg3_open</CODE> returns a NULL if the file couldn't be opened
+for some reason.  Be sure to check this.  Everything you do with
+libmpeg3 requires passing the <CODE>file</CODE> pointer.<P>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 3: How many CPUs do you want to use?</B></FONT><P>
+
+Call <CODE>mpeg3_set_cpus(mpeg3_t *file, int cpus)</CODE> to set how
+many CPUs should be devoted to video decompression.  LibMPEG3 can use
+any number.  If you don't call this right after opening the file, the
+CPU number defaults to 1.<P>
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 4: Get some information about the file.</B></FONT><P>
+
+There are a number of queries for the audio components of the stream:<P>
+
+<CODE><PRE>
+int mpeg3_has_audio(mpeg3_t *file);
+int mpeg3_total_astreams(mpeg3_t *file);             // Number of multiplexed audio streams
+int mpeg3_audio_channels(mpeg3_t *file, int stream);
+int mpeg3_sample_rate(mpeg3_t *file, int stream);
+long mpeg3_audio_samples(mpeg3_t *file, int stream); // Total length
+</PRE></CODE>
+
+The audio is presented as a number of <B>streams</B> starting at 0 and
+including <CODE>mpeg3_total_astreams</CODE> - 1.  Each stream contains a
+certain number of <B>channels</B> starting at 0 and including
+<CODE>mpeg3_audio_channels</CODE> - 1.
+
+The methodology is first determine if the file has audio, then get
+the number of streams in the file, then for each stream get the number
+of channels, sample rate, and length.<P>
+
+There are also queries for the video components:<P>
+
+<CODE><PRE>
+int mpeg3_has_video(mpeg3_t *file);
+int mpeg3_total_vstreams(mpeg3_t *file);            // Number of multiplexed video streams
+int mpeg3_video_width(mpeg3_t *file, int stream);
+int mpeg3_video_height(mpeg3_t *file, int stream);
+float mpeg3_frame_rate(mpeg3_t *file, int stream);  // Frames/sec
+long mpeg3_video_frames(mpeg3_t *file, int stream); // Total length
+</PRE></CODE>
+
+The video behavior is the same as with audio, except that video has no
+subdivision under <B>streams</B>.  Frame rate is a floating point
+number of frames per second.<P>
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 5: Seeking to a point in the file</B></FONT><P>
+
+Each audio stream and each video stream has a position in the file
+independant of each other stream.  A variety of methods are available
+for specifying the position of a stream: percentage, frame, sample. 
+Which method you use depends on whether you're seeking audio or video
+and whether you're seeking all tracks to a percentage of the file.<P>
+
+The preferred seeking method if you're writing a player is:<P>
+
+<CODE><PRE>
+int mpeg3_seek_percentage(mpeg3_t *file, double percentage);
+double mpeg3_tell_percentage(mpeg3_t *file);
+</PRE></CODE>
+
+This seeks all tracks to a percentage of the file length.  The
+percentage is from 0 to 1.<P>
+
+The alternative is absolute seeking.  The audio seeking is handled
+by:<P>
+
+<CODE><PRE>
+int mpeg3_set_sample(mpeg3_t *file, long sample, int stream);    // Seek
+long mpeg3_get_sample(mpeg3_t *file, int stream);    // Tell current position
+</PRE></CODE>
+
+and the video seeking is handled by:<P>
+
+<CODE><PRE>
+int mpeg3_set_frame(mpeg3_t *file, long frame, int stream); // Seek
+long mpeg3_get_frame(mpeg3_t *file, int stream);            // Tell current position
+</PRE></CODE>
+
+
+You can either perform percentage seeking or absolute seeking but not
+both on the same file handle.  Once you perform either method, the file
+becomes configured for that method.<P>
+
+If you're in percentage seeking mode and you want the current time
+stamp in the file you can't use mpeg3_tell_percentage because you don't
+know how many seconds the total length is.  The
+<CODE>mpeg3_audio_samples</CODE> and <CODE>mpeg3_video_frames</CODE>
+commands don't work in percentage seeking.  Instead use
+
+<CODE><PRE>
+double mpeg3_get_time(mpeg3_t *file);
+</PRE></CODE>
+
+which gives you the last timecode read in seconds.  The MPEG standard
+specifies timecodes being placed in the streams.<P>
+
+
+
+
+
+
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 6: Read the data</B></FONT><P>
+
+To read <B>audio</B> data use:<P>
+
+<CODE><PRE>
+int mpeg3_read_audio(mpeg3_t *file, 
+                float *output_f,      // Pointer to pre-allocated buffer of floats
+                short *output_i,      // Pointer to pre-allocated buffer if int16's
+                int channel,          // Channel to decode
+                long samples,         // Number of samples to decode
+                int stream);          // Stream containing the channel
+</PRE></CODE>
+
+This decodes a buffer of sequential floats or int16's for a single
+channel, depending on which *output... parameter has a nonzero
+argument.  To get a floating point buffer pass a pre-allocated buffer
+to <CODE>output_f</CODE> and NULL to <CODE>output_i</CODE>. To get an
+int16 buffer pass NULL to <CODE>output_f</CODE> and a pre-allocated
+buffer to <CODE>output_i</CODE>.<P>
+
+After reading an audio buffer, the current position in the one stream
+is advanced.  How then, do you read more than one channel of audio
+data?  Use
+
+<CODE><PRE>
+mpeg3_reread_audio(mpeg3_t *file, 
+                float *output_f,      /* Pointer to pre-allocated buffer of floats */
+                short *output_i,      /* Pointer to pre-allocated buffer of int16's */
+                int channel,          /* Channel to decode */
+                long samples,         /* Number of samples to decode */
+                int stream);
+</PRE></CODE>
+
+to read each remaining channel after the first channel.<P>
+
+To read <B>video</B> data there are two methods.  RGB frames or YUV
+frames.  To get an RGB frame use:<BR>
+
+<CODE><PRE>
+int mpeg3_read_frame(mpeg3_t *file, 
+                unsigned char **output_rows, // Array of pointers to the start of each output row
+                int in_x,                    // Location in input frame to take picture
+                int in_y, 
+                int in_w, 
+                int in_h, 
+                int out_w,                   // Dimensions of output_rows
+                int out_h, 
+                int color_model,             // One of the color model #defines given above.
+                int stream);
+</PRE></CODE>
+
+The video decoding works like a camcorder taking copy of a movie
+screen.  The decoder "sees" a region of the movie screen defined by
+<CODE>in_x, in_y, in_w, in_h</CODE> and transfers it to the frame
+buffer defined by <CODE>**output_rows</CODE>.  The input values must be
+within the boundaries given by <CODE>mpeg3_video_width</CODE> and
+<CODE>mpeg3_video_height</CODE>.  The size of the frame buffer is
+defined by <CODE>out_w, out_h</CODE>.  Although the input dimensions
+are constrained, the frame buffer can be any size.<P>
+
+<CODE>color_model</CODE> defines which RGB color model the picture
+should be decoded to and the possible values are given in
+<B>libmpeg3.h</B>.  The frame buffer pointed to by
+<CODE>output_rows</CODE> must have enough memory allocated to store the
+color model you select.<P>
+
+<B>You must allocate 4 extra bytes in the last output_row.</B>  This is
+scratch area for the MMX routines.<P>
+
+<CODE>mpeg3_read_frame</CODE> advances the position in the one stream by 1 frame.<P>
+
+The alternative is YUV frames:<BR>
+
+<CODE><PRE>
+int mpeg3_read_yuvframe(mpeg3_t *file,
+                char *y_output,
+                char *u_output,
+                char *v_output,
+                int in_x,
+                int in_y,
+                int in_w,
+                int in_h,
+                int stream);
+</PRE></CODE>
+
+The behavior of in_x, in_y, in_w, in_h is identical to mpeg3_read_frame
+except here you have no control over the output frame size.  <B>You
+must allocate in_w * in_h for the y_output, and in_w * in_h / 4 for the
+chroma outputs.</B><P>
+
+
+
+
+
+<FONT FACE=HELVETICA SIZE=+4><B>STEP 7: Close the file</B></FONT><P>
+
+Be sure to close the file with <CODE>mpeg3_close(mpeg3_t *file)</CODE>
+when you're done with it.