MediaTrack.h revision 218a8c03
1/*
2 * Copyright 2002-2010, Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 */
5#ifndef _MEDIA_TRACK_H
6#define _MEDIA_TRACK_H
7
8
9#include <MediaFormats.h>
10
11
12namespace BPrivate { namespace media {
13	class Decoder;
14	class Encoder;
15	class MediaExtractor;
16	class MediaWriter;
17} }
18
19class BMessage;
20class BView;
21class BParameterWeb;
22
23
24enum media_seek_type {
25	B_MEDIA_SEEK_CLOSEST_FORWARD	= 1,
26	B_MEDIA_SEEK_CLOSEST_BACKWARD	= 2,
27	B_MEDIA_SEEK_DIRECTION_MASK		= 3
28};
29
30
31// BMediaTrack gives access to a particular media track in a media file
32// (as represented by BMediaFile).
33//
34// You always instantiate a BMediaTrack through BMediaFile::TrackAt()
35// or BMediaFile::CreateTrack().  When a BMediaTrack object is
36// constructed it finds the necessary decoder or encoder for the type
37// of data stored in the track.
38//
39// Unless you created the BMediaFile() in B_MEDIA_REPLACE_MODE, you
40// can only access a track for reading or writing, not both.
41//
42// If InitCheck() indicates no errors, then the track is ready to be
43// used to read and write frames using ReadFrames() and WriteFrames().
44// For video data you should always only read one frame.
45//
46// You can seek a track with SeekToTime() and SeekToFrame().
47//
48// If no codec could be found for the track, it is still possible to
49// access the encoded data using ReadChunk().
50class BMediaTrack {
51protected:
52	// Use BMediaFile::ReleaseTrack() instead -- or it will go away
53	// on its own when the MediaFile is deleted.
54	virtual						~BMediaTrack();
55
56public:
57
58	// for read-only access the BMediaTrack should be instantiated
59	// through BMediaFile::TrackAt()
60
61	// for write-only access the BMediaTrack should be instantiated
62	// through BMediaFile::CreateTrack()
63
64			status_t			InitCheck() const;
65
66	// Get information about the codec being used.
67			status_t			GetCodecInfo(
68									media_codec_info* _codecInfo) const;
69
70
71	// EncodedFormat returns information about the track's
72	// "native" encoded format.
73
74			status_t			EncodedFormat(media_format* _format) const;
75
76	// DecodedFormat is used to negotiate the format that the codec will
77	// use when decoding the track's data.  You pass in the format that
78	// that you want; the codec will find and return its "best fit"
79	// format.  (inout_format is used as both the input and the returned
80	// format.)  The format is typically of the B_MEDIA_RAW_AUDIO or
81	// B_MEDIA_RAW_VIDEO flavor.
82	// The data returned through ReadFrames() will be in the format that's
83 	// returned by this function.
84
85			status_t			DecodedFormat(media_format* _format,
86									uint32 flags = 0);
87
88	// CountFrames and Duration return the total number of frame and the
89	// total duration (expressed in microseconds) of a track.
90
91			int64				CountFrames() const;
92			bigtime_t			Duration() const;
93
94	// Returns in _data hierarchical meta-data about the track.
95	// The fields in the message shall follow a defined naming-scheme,
96	// such that applications can find the same information in different
97	// types of tracks.
98			status_t			GetMetaData(BMessage* _data) const;
99
100	// CurrentFrame and CurrentTime return the current position (expressed in
101	// microseconds) within the track, expressed in frame index and time.
102
103			int64				CurrentFrame() const;
104			bigtime_t			CurrentTime() const;
105
106	// ReadFrames() fills a buffer with the next frames/samples. For a video
107	// track,  it decodes the next frame of video in the passed buffer. For
108	// an audio track, it fills the buffers with the next N samples, as
109	// negotiated by DecodedFormat().  However, if it reaches the end of the
110	// file and was not able to fill the whole  buffer, it returns a partial
111	// buffer.  Upon return, out_frameCount contains the actual number of
112	// frame/samples returned, and the start time for the frame, expressed
113	// in microseconds, is in the media_header structure.
114
115			status_t			ReadFrames(void* buffer, int64* _frameCount,
116									media_header* header = NULL);
117
118			status_t			ReadFrames(void* buffer, int64* _frameCount,
119									media_header* header,
120									media_decode_info* info);
121
122			status_t			ReplaceFrames(const void* buffer,
123									int64* _frameCount,
124									const media_header* header);
125
126
127	// SeekToTime and SeekToFrame are used for seeking to a particular
128	// position in a track, expressed in either frames or microseconds.
129	// They return whatever position they were able to seek to. For example,
130	// a video codec may not be able to seek to arbitrary frames, but only to
131	// key frames. In this case, it would return the closest key frame before
132	// the specified seek point.
133	//
134	// If you want to explicitly seek to the nearest keyframe _before_ this
135	// frame or _after_ this frame, pass B_MEDIA_SEEK_CLOSEST_FORWARD or
136	// B_MEDIA_SEEK_CLOSEST_BACKWARD as the flags field.
137
138			status_t			SeekToTime(bigtime_t* _time, int32 flags = 0);
139			status_t			SeekToFrame(int64* _frame, int32 flags = 0);
140
141			status_t			FindKeyFrameForTime(bigtime_t* _time,
142									int32 flags = 0) const;
143			status_t			FindKeyFrameForFrame(int64* _frame,
144									int32 flags = 0) const;
145
146	// ReadChunk returns, in _buffer, the next _size bytes of
147	// data from the track.  The data is not decoded -- it will be
148	// in its native encoded format (as specified by EncodedFormat()).
149	// You can not mix calling ReadChunk() and ReadFrames() -- either
150	// you access the track raw (i.e. with ReadChunk) or you access
151	// it with ReadFrames.
152
153			status_t			ReadChunk(char** _buffer, int32* _size,
154									media_header* _header = NULL);
155
156
157	//
158	// Write-only Functions
159	//
160			status_t			AddCopyright(const char* copyright);
161			status_t			AddTrackInfo(uint32 code, const void* data,
162									size_t size, uint32 flags = 0);
163
164	// Write frameCount of data to the track. This data is passed
165	// through the encoder that was specified when the MediaTrack
166	// was constructed.
167	// Pass B_MEDIA_KEY_FRAME for flags if it is.
168
169			status_t			WriteFrames(const void* data, int32 frameCount,
170									int32 flags = 0);
171			status_t			WriteFrames(const void* data, int64 frameCount,
172									media_encode_info* info);
173
174	// Write a raw chunk of (presumably already encoded data) to
175	// the file.
176	// Pass B_MEDIA_KEY_FRAME for flags if it is.
177
178			status_t			WriteChunk(const void* data, size_t size,
179									uint32 flags = 0);
180			status_t			WriteChunk(const void* data, size_t size,
181									media_encode_info* info);
182
183	// Flush all buffered encoded datas to disk. You should call it after
184	// writing the last frame to be sure all datas are flushed at the right
185	// offset into the file.
186			status_t			Flush();
187
188	// These are for controlling the underlying encoder and track parameters
189	// returns a copy of the parameter web
190			status_t			GetParameterWeb(BParameterWeb** _web);
191			status_t 			GetParameterValue(int32 id, void* value,
192									size_t* size);
193			status_t			SetParameterValue(int32 id, const void* value,
194									size_t size);
195			BView*				GetParameterView();
196
197	// This is a simplified control API, only one parameter low=0.0, high=1.0
198	// Return B_ERROR if it's not supported by the current encoder.
199			status_t			GetQuality(float* _quality);
200			status_t			SetQuality(float quality);
201
202			status_t 			GetEncodeParameters(
203									encode_parameters* parameters) const;
204			status_t 			SetEncodeParameters(
205									encode_parameters* parameters);
206
207
208	virtual	status_t			Perform(int32 code, void* data);
209
210private:
211	friend class BMediaFile;
212
213	// deprecated, but for BeOS R5 compatibility
214			BParameterWeb*	Web();
215
216	// Does nothing, returns B_ERROR, for Zeta compatiblity only
217			status_t			ControlCodec(int32 selector, void* _inOutData,
218									size_t size);
219
220	// For read-only access to a BMediaTrack
221								BMediaTrack(
222									BPrivate::media::MediaExtractor* extractor,
223									int32 streamIndex);
224
225	// For write-only access to a BMediaTrack
226								BMediaTrack(
227									BPrivate::media::MediaWriter* writer,
228									int32 streamIndex, media_format* format,
229									const media_codec_info* codecInfo);
230
231			void				SetupWorkaround();
232			bool				SetupFormatTranslation(
233									const media_format& from,
234									media_format* _to);
235
236private:
237			status_t			fInitStatus;
238			BPrivate::media::Decoder* fDecoder;
239			BPrivate::media::Decoder* fRawDecoder;
240			BPrivate::media::MediaExtractor* fExtractor;
241
242			int32				fStream;
243			int64				fCurrentFrame;
244			bigtime_t			fCurrentTime;
245
246			media_codec_info	fCodecInfo;
247
248			BPrivate::media::Encoder* fEncoder;
249			int32				fEncoderID;
250			BPrivate::media::MediaWriter* fWriter;
251			media_format		fFormat;
252
253			uint32				fWorkaroundFlags;
254
255protected:
256			int32				EncoderID() { return fEncoderID; };
257
258private:
259								BMediaTrack();
260								BMediaTrack(const BMediaTrack&);
261			BMediaTrack&		operator=(const BMediaTrack&);
262
263
264			double				_FrameRate() const;
265
266	// FBC data and virtuals
267			uint32				_reserved_BMediaTrack_[31];
268
269	virtual	status_t			_Reserved_BMediaTrack_0(int32 arg, ...);
270	virtual	status_t			_Reserved_BMediaTrack_1(int32 arg, ...);
271	virtual	status_t			_Reserved_BMediaTrack_2(int32 arg, ...);
272	virtual	status_t			_Reserved_BMediaTrack_3(int32 arg, ...);
273	virtual	status_t			_Reserved_BMediaTrack_4(int32 arg, ...);
274	virtual	status_t			_Reserved_BMediaTrack_5(int32 arg, ...);
275	virtual	status_t			_Reserved_BMediaTrack_6(int32 arg, ...);
276	virtual	status_t			_Reserved_BMediaTrack_7(int32 arg, ...);
277	virtual	status_t			_Reserved_BMediaTrack_8(int32 arg, ...);
278	virtual	status_t			_Reserved_BMediaTrack_9(int32 arg, ...);
279	virtual	status_t			_Reserved_BMediaTrack_10(int32 arg, ...);
280	virtual	status_t			_Reserved_BMediaTrack_11(int32 arg, ...);
281	virtual	status_t			_Reserved_BMediaTrack_12(int32 arg, ...);
282	virtual	status_t			_Reserved_BMediaTrack_13(int32 arg, ...);
283	virtual	status_t			_Reserved_BMediaTrack_14(int32 arg, ...);
284	virtual	status_t			_Reserved_BMediaTrack_15(int32 arg, ...);
285	virtual	status_t			_Reserved_BMediaTrack_16(int32 arg, ...);
286	virtual	status_t			_Reserved_BMediaTrack_17(int32 arg, ...);
287	virtual	status_t			_Reserved_BMediaTrack_18(int32 arg, ...);
288	virtual	status_t			_Reserved_BMediaTrack_19(int32 arg, ...);
289	virtual	status_t			_Reserved_BMediaTrack_20(int32 arg, ...);
290	virtual	status_t			_Reserved_BMediaTrack_21(int32 arg, ...);
291	virtual	status_t			_Reserved_BMediaTrack_22(int32 arg, ...);
292	virtual	status_t			_Reserved_BMediaTrack_23(int32 arg, ...);
293	virtual	status_t			_Reserved_BMediaTrack_24(int32 arg, ...);
294	virtual	status_t			_Reserved_BMediaTrack_25(int32 arg, ...);
295	virtual	status_t			_Reserved_BMediaTrack_26(int32 arg, ...);
296	virtual	status_t			_Reserved_BMediaTrack_27(int32 arg, ...);
297	virtual	status_t			_Reserved_BMediaTrack_28(int32 arg, ...);
298	virtual	status_t			_Reserved_BMediaTrack_29(int32 arg, ...);
299	virtual	status_t			_Reserved_BMediaTrack_30(int32 arg, ...);
300	virtual	status_t			_Reserved_BMediaTrack_31(int32 arg, ...);
301	virtual	status_t			_Reserved_BMediaTrack_32(int32 arg, ...);
302	virtual	status_t			_Reserved_BMediaTrack_33(int32 arg, ...);
303	virtual	status_t			_Reserved_BMediaTrack_34(int32 arg, ...);
304	virtual	status_t			_Reserved_BMediaTrack_35(int32 arg, ...);
305	virtual	status_t			_Reserved_BMediaTrack_36(int32 arg, ...);
306	virtual	status_t			_Reserved_BMediaTrack_37(int32 arg, ...);
307	virtual	status_t			_Reserved_BMediaTrack_38(int32 arg, ...);
308	virtual	status_t			_Reserved_BMediaTrack_39(int32 arg, ...);
309	virtual	status_t			_Reserved_BMediaTrack_40(int32 arg, ...);
310	virtual	status_t			_Reserved_BMediaTrack_41(int32 arg, ...);
311	virtual	status_t			_Reserved_BMediaTrack_42(int32 arg, ...);
312	virtual	status_t			_Reserved_BMediaTrack_43(int32 arg, ...);
313	virtual	status_t			_Reserved_BMediaTrack_44(int32 arg, ...);
314	virtual	status_t			_Reserved_BMediaTrack_45(int32 arg, ...);
315	virtual	status_t			_Reserved_BMediaTrack_46(int32 arg, ...);
316	virtual	status_t			_Reserved_BMediaTrack_47(int32 arg, ...);
317};
318
319#endif // _MEDIA_TRACK_H
320