Diffstat (limited to 'core/multimedia/opieplayer/libmpeg3/docs/index.html') (more/less context) (ignore whitespace changes)
-rw-r--r-- | core/multimedia/opieplayer/libmpeg3/docs/index.html | 306 |
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 @@ | |||
1 | <TITLE>LibMPEG3</TITLE> | ||
2 | |||
3 | <CENTER> | ||
4 | <FONT FACE=HELVETICA SIZE=+4><B>Using LibMPEG3 to make your own MPEG applications</B></FONT><P> | ||
5 | |||
6 | <TABLE> | ||
7 | <TR> | ||
8 | <TD> | ||
9 | <CODE> | ||
10 | Author: Adam Williams broadcast@earthling.net<BR> | ||
11 | Homepage: heroinewarrior.com<BR> | ||
12 | </CODE> | ||
13 | </TD> | ||
14 | </TR> | ||
15 | </TABLE> | ||
16 | </CENTER> | ||
17 | |||
18 | <P> | ||
19 | |||
20 | |||
21 | LibMPEG3 decodes the many many derivatives of MPEG standards into | ||
22 | uncompressed data suitable for editing and playback.<P> | ||
23 | |||
24 | libmpeg3 currently decodes:<P> | ||
25 | |||
26 | <BLOCKQUOTE>MPEG-2 video<BR> | ||
27 | MPEG-1 video<BR> | ||
28 | mp3 audio<BR> | ||
29 | mp2 audio<BR> | ||
30 | ac3 audio<BR> | ||
31 | MPEG-2 system streams<BR> | ||
32 | MPEG-1 system streams | ||
33 | </BLOCKQUOTE><P> | ||
34 | |||
35 | The video output can be in many different color models and frame | ||
36 | sizes. The audio output can be in twos compliment or floating | ||
37 | point.<P> | ||
38 | |||
39 | |||
40 | |||
41 | |||
42 | |||
43 | |||
44 | |||
45 | |||
46 | |||
47 | <FONT FACE=HELVETICA SIZE=+4><B>STEP 1: Verifying file compatibility</B></FONT><P> | ||
48 | |||
49 | Programs using libmpeg3 must <CODE>#include "libmpeg3.h"</CODE>.<P> | ||
50 | |||
51 | Call <CODE>mpeg3_check_sig</CODE> to verify if the file can be read by | ||
52 | libmpeg3. This returns a 1 if it is compatible and 0 if it isn't.<P> | ||
53 | |||
54 | |||
55 | |||
56 | |||
57 | |||
58 | |||
59 | |||
60 | |||
61 | |||
62 | |||
63 | |||
64 | <FONT FACE=HELVETICA SIZE=+4><B>STEP 2: Open the file</B></FONT><P> | ||
65 | |||
66 | You need an <CODE>mpeg3_t*</CODE> file descriptor:<P> | ||
67 | <CODE> | ||
68 | mpeg3_t* file; | ||
69 | </CODE> | ||
70 | <P> | ||
71 | |||
72 | Then you need to open the file:<P> | ||
73 | |||
74 | <CODE>file = mpeg3_open(char *path);</CODE><P> | ||
75 | |||
76 | <CODE>mpeg3_open</CODE> returns a NULL if the file couldn't be opened | ||
77 | for some reason. Be sure to check this. Everything you do with | ||
78 | libmpeg3 requires passing the <CODE>file</CODE> pointer.<P> | ||
79 | |||
80 | |||
81 | |||
82 | |||
83 | |||
84 | |||
85 | |||
86 | |||
87 | |||
88 | |||
89 | |||
90 | |||
91 | |||
92 | |||
93 | <FONT FACE=HELVETICA SIZE=+4><B>STEP 3: How many CPUs do you want to use?</B></FONT><P> | ||
94 | |||
95 | Call <CODE>mpeg3_set_cpus(mpeg3_t *file, int cpus)</CODE> to set how | ||
96 | many CPUs should be devoted to video decompression. LibMPEG3 can use | ||
97 | any number. If you don't call this right after opening the file, the | ||
98 | CPU number defaults to 1.<P> | ||
99 | |||
100 | |||
101 | |||
102 | |||
103 | |||
104 | |||
105 | |||
106 | <FONT FACE=HELVETICA SIZE=+4><B>STEP 4: Get some information about the file.</B></FONT><P> | ||
107 | |||
108 | There are a number of queries for the audio components of the stream:<P> | ||
109 | |||
110 | <CODE><PRE> | ||
111 | int mpeg3_has_audio(mpeg3_t *file); | ||
112 | int mpeg3_total_astreams(mpeg3_t *file); // Number of multiplexed audio streams | ||
113 | int mpeg3_audio_channels(mpeg3_t *file, int stream); | ||
114 | int mpeg3_sample_rate(mpeg3_t *file, int stream); | ||
115 | long mpeg3_audio_samples(mpeg3_t *file, int stream); // Total length | ||
116 | </PRE></CODE> | ||
117 | |||
118 | The audio is presented as a number of <B>streams</B> starting at 0 and | ||
119 | including <CODE>mpeg3_total_astreams</CODE> - 1. Each stream contains a | ||
120 | certain number of <B>channels</B> starting at 0 and including | ||
121 | <CODE>mpeg3_audio_channels</CODE> - 1. | ||
122 | |||
123 | The methodology is first determine if the file has audio, then get | ||
124 | the number of streams in the file, then for each stream get the number | ||
125 | of channels, sample rate, and length.<P> | ||
126 | |||
127 | There are also queries for the video components:<P> | ||
128 | |||
129 | <CODE><PRE> | ||
130 | int mpeg3_has_video(mpeg3_t *file); | ||
131 | int mpeg3_total_vstreams(mpeg3_t *file); // Number of multiplexed video streams | ||
132 | int mpeg3_video_width(mpeg3_t *file, int stream); | ||
133 | int mpeg3_video_height(mpeg3_t *file, int stream); | ||
134 | float mpeg3_frame_rate(mpeg3_t *file, int stream); // Frames/sec | ||
135 | long mpeg3_video_frames(mpeg3_t *file, int stream); // Total length | ||
136 | </PRE></CODE> | ||
137 | |||
138 | The video behavior is the same as with audio, except that video has no | ||
139 | subdivision under <B>streams</B>. Frame rate is a floating point | ||
140 | number of frames per second.<P> | ||
141 | |||
142 | |||
143 | |||
144 | |||
145 | |||
146 | |||
147 | |||
148 | <FONT FACE=HELVETICA SIZE=+4><B>STEP 5: Seeking to a point in the file</B></FONT><P> | ||
149 | |||
150 | Each audio stream and each video stream has a position in the file | ||
151 | independant of each other stream. A variety of methods are available | ||
152 | for specifying the position of a stream: percentage, frame, sample. | ||
153 | Which method you use depends on whether you're seeking audio or video | ||
154 | and whether you're seeking all tracks to a percentage of the file.<P> | ||
155 | |||
156 | The preferred seeking method if you're writing a player is:<P> | ||
157 | |||
158 | <CODE><PRE> | ||
159 | int mpeg3_seek_percentage(mpeg3_t *file, double percentage); | ||
160 | double mpeg3_tell_percentage(mpeg3_t *file); | ||
161 | </PRE></CODE> | ||
162 | |||
163 | This seeks all tracks to a percentage of the file length. The | ||
164 | percentage is from 0 to 1.<P> | ||
165 | |||
166 | The alternative is absolute seeking. The audio seeking is handled | ||
167 | by:<P> | ||
168 | |||
169 | <CODE><PRE> | ||
170 | int mpeg3_set_sample(mpeg3_t *file, long sample, int stream); // Seek | ||
171 | long mpeg3_get_sample(mpeg3_t *file, int stream); // Tell current position | ||
172 | </PRE></CODE> | ||
173 | |||
174 | and the video seeking is handled by:<P> | ||
175 | |||
176 | <CODE><PRE> | ||
177 | int mpeg3_set_frame(mpeg3_t *file, long frame, int stream); // Seek | ||
178 | long mpeg3_get_frame(mpeg3_t *file, int stream); // Tell current position | ||
179 | </PRE></CODE> | ||
180 | |||
181 | |||
182 | You can either perform percentage seeking or absolute seeking but not | ||
183 | both on the same file handle. Once you perform either method, the file | ||
184 | becomes configured for that method.<P> | ||
185 | |||
186 | If you're in percentage seeking mode and you want the current time | ||
187 | stamp in the file you can't use mpeg3_tell_percentage because you don't | ||
188 | know how many seconds the total length is. The | ||
189 | <CODE>mpeg3_audio_samples</CODE> and <CODE>mpeg3_video_frames</CODE> | ||
190 | commands don't work in percentage seeking. Instead use | ||
191 | |||
192 | <CODE><PRE> | ||
193 | double mpeg3_get_time(mpeg3_t *file); | ||
194 | </PRE></CODE> | ||
195 | |||
196 | which gives you the last timecode read in seconds. The MPEG standard | ||
197 | specifies timecodes being placed in the streams.<P> | ||
198 | |||
199 | |||
200 | |||
201 | |||
202 | |||
203 | |||
204 | |||
205 | |||
206 | |||
207 | |||
208 | |||
209 | <FONT FACE=HELVETICA SIZE=+4><B>STEP 6: Read the data</B></FONT><P> | ||
210 | |||
211 | To read <B>audio</B> data use:<P> | ||
212 | |||
213 | <CODE><PRE> | ||
214 | int mpeg3_read_audio(mpeg3_t *file, | ||
215 | float *output_f, // Pointer to pre-allocated buffer of floats | ||
216 | short *output_i, // Pointer to pre-allocated buffer if int16's | ||
217 | int channel, // Channel to decode | ||
218 | long samples, // Number of samples to decode | ||
219 | int stream); // Stream containing the channel | ||
220 | </PRE></CODE> | ||
221 | |||
222 | This decodes a buffer of sequential floats or int16's for a single | ||
223 | channel, depending on which *output... parameter has a nonzero | ||
224 | argument. To get a floating point buffer pass a pre-allocated buffer | ||
225 | to <CODE>output_f</CODE> and NULL to <CODE>output_i</CODE>. To get an | ||
226 | int16 buffer pass NULL to <CODE>output_f</CODE> and a pre-allocated | ||
227 | buffer to <CODE>output_i</CODE>.<P> | ||
228 | |||
229 | After reading an audio buffer, the current position in the one stream | ||
230 | is advanced. How then, do you read more than one channel of audio | ||
231 | data? Use | ||
232 | |||
233 | <CODE><PRE> | ||
234 | mpeg3_reread_audio(mpeg3_t *file, | ||
235 | float *output_f, /* Pointer to pre-allocated buffer of floats */ | ||
236 | short *output_i, /* Pointer to pre-allocated buffer of int16's */ | ||
237 | int channel, /* Channel to decode */ | ||
238 | long samples, /* Number of samples to decode */ | ||
239 | int stream); | ||
240 | </PRE></CODE> | ||
241 | |||
242 | to read each remaining channel after the first channel.<P> | ||
243 | |||
244 | To read <B>video</B> data there are two methods. RGB frames or YUV | ||
245 | frames. To get an RGB frame use:<BR> | ||
246 | |||
247 | <CODE><PRE> | ||
248 | int mpeg3_read_frame(mpeg3_t *file, | ||
249 | unsigned char **output_rows, // Array of pointers to the start of each output row | ||
250 | int in_x, // Location in input frame to take picture | ||
251 | int in_y, | ||
252 | int in_w, | ||
253 | int in_h, | ||
254 | int out_w, // Dimensions of output_rows | ||
255 | int out_h, | ||
256 | int color_model, // One of the color model #defines given above. | ||
257 | int stream); | ||
258 | </PRE></CODE> | ||
259 | |||
260 | The video decoding works like a camcorder taking copy of a movie | ||
261 | screen. The decoder "sees" a region of the movie screen defined by | ||
262 | <CODE>in_x, in_y, in_w, in_h</CODE> and transfers it to the frame | ||
263 | buffer defined by <CODE>**output_rows</CODE>. The input values must be | ||
264 | within the boundaries given by <CODE>mpeg3_video_width</CODE> and | ||
265 | <CODE>mpeg3_video_height</CODE>. The size of the frame buffer is | ||
266 | defined by <CODE>out_w, out_h</CODE>. Although the input dimensions | ||
267 | are constrained, the frame buffer can be any size.<P> | ||
268 | |||
269 | <CODE>color_model</CODE> defines which RGB color model the picture | ||
270 | should be decoded to and the possible values are given in | ||
271 | <B>libmpeg3.h</B>. The frame buffer pointed to by | ||
272 | <CODE>output_rows</CODE> must have enough memory allocated to store the | ||
273 | color model you select.<P> | ||
274 | |||
275 | <B>You must allocate 4 extra bytes in the last output_row.</B> This is | ||
276 | scratch area for the MMX routines.<P> | ||
277 | |||
278 | <CODE>mpeg3_read_frame</CODE> advances the position in the one stream by 1 frame.<P> | ||
279 | |||
280 | The alternative is YUV frames:<BR> | ||
281 | |||
282 | <CODE><PRE> | ||
283 | int mpeg3_read_yuvframe(mpeg3_t *file, | ||
284 | char *y_output, | ||
285 | char *u_output, | ||
286 | char *v_output, | ||
287 | int in_x, | ||
288 | int in_y, | ||
289 | int in_w, | ||
290 | int in_h, | ||
291 | int stream); | ||
292 | </PRE></CODE> | ||
293 | |||
294 | The behavior of in_x, in_y, in_w, in_h is identical to mpeg3_read_frame | ||
295 | except here you have no control over the output frame size. <B>You | ||
296 | must allocate in_w * in_h for the y_output, and in_w * in_h / 4 for the | ||
297 | chroma outputs.</B><P> | ||
298 | |||
299 | |||
300 | |||
301 | |||
302 | |||
303 | <FONT FACE=HELVETICA SIZE=+4><B>STEP 7: Close the file</B></FONT><P> | ||
304 | |||
305 | Be sure to close the file with <CODE>mpeg3_close(mpeg3_t *file)</CODE> | ||
306 | when you're done with it. | ||