Mercurial > mplayer.hg
annotate DOCS/tech/libmpcodecs.txt @ 36334:c1033e9288b1
Extract audio encoding code into a separate helper function.
author | reimar |
---|---|
date | Sun, 25 Aug 2013 11:30:43 +0000 |
parents | c02ae498fb2e |
children |
rev | line source |
---|---|
25880
4df11ac927fc
clarify comments/docs about lav* being the preferred place to implement new
ivo
parents:
25872
diff
changeset
|
1 NOTE: If you want to implement a new native codec, please add it to |
4df11ac927fc
clarify comments/docs about lav* being the preferred place to implement new
ivo
parents:
25872
diff
changeset
|
2 libavcodec. libmpcodecs is considered mostly deprecated, except for wrappers |
4df11ac927fc
clarify comments/docs about lav* being the preferred place to implement new
ivo
parents:
25872
diff
changeset
|
3 around external libraries and codecs requiring binary support. |
25872
3eeaf9d4c65a
note on new demuxers and codecs, add them to lav* instead of libmp*
ivo
parents:
15624
diff
changeset
|
4 |
7397 | 5 The libMPcodecs API details, hints - by A'rpi |
6 ================================== | |
7 | |
7399 | 8 See also: colorspaces.txt, codec-devel.txt, dr-methods.txt, codecs.conf.txt |
7397 | 9 |
10 The VIDEO path: | |
11 =============== | |
12 | |
13 [MPlayer core] | |
14 | (1) | |
28269 | 15 ______V______ (2) /~~~~~~~~~~\ (3,4) |~~~~~~| |
28267
757aca6254a3
Fix decvideo vs. dec_video typo noticed by Vineeth N, nvineeth gmail com.
diego
parents:
25880
diff
changeset
|
16 | | -----> | vd_XXX.c | -------> | vd.c | |
757aca6254a3
Fix decvideo vs. dec_video typo noticed by Vineeth N, nvineeth gmail com.
diego
parents:
25880
diff
changeset
|
17 | dec_video | \__________/ <-(3a)-- |______| |
757aca6254a3
Fix decvideo vs. dec_video typo noticed by Vineeth N, nvineeth gmail com.
diego
parents:
25880
diff
changeset
|
18 | | -----, ,.............(3a,4a).....: |
757aca6254a3
Fix decvideo vs. dec_video typo noticed by Vineeth N, nvineeth gmail com.
diego
parents:
25880
diff
changeset
|
19 ~~~~~~~~~~~~~ (6) V V |
15602
d6f9191f4f82
Tab to space conversion to prevent the ASCII diagram to be messed up when a
diego
parents:
9687
diff
changeset
|
20 /~~~~~~~~\ /~~~~~~~~\ (8) |
d6f9191f4f82
Tab to space conversion to prevent the ASCII diagram to be messed up when a
diego
parents:
9687
diff
changeset
|
21 | vf_X.c | --> | vf_Y.c | ----> vf_vo.c / ve_XXX.c |
d6f9191f4f82
Tab to space conversion to prevent the ASCII diagram to be messed up when a
diego
parents:
9687
diff
changeset
|
22 \________/ \________/ |
d6f9191f4f82
Tab to space conversion to prevent the ASCII diagram to be messed up when a
diego
parents:
9687
diff
changeset
|
23 | ^ |
d6f9191f4f82
Tab to space conversion to prevent the ASCII diagram to be messed up when a
diego
parents:
9687
diff
changeset
|
24 (7) | |~~~~~~| : (7a) |
d6f9191f4f82
Tab to space conversion to prevent the ASCII diagram to be messed up when a
diego
parents:
9687
diff
changeset
|
25 `-> | vf.c |...: |
d6f9191f4f82
Tab to space conversion to prevent the ASCII diagram to be messed up when a
diego
parents:
9687
diff
changeset
|
26 |______| |
7397 | 27 |
28 Short description of video path: | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
29 1. MPlayer/MEncoder core requests the decoding of a compressed video frame: |
28269 | 30 calls dec_video.c::decode_video(). |
7397 | 31 |
28269 | 32 2. decode_video() calls the video codec previously selected in init_video(). |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
33 (vd_XXX.c file, where XXX == vfm name, see the 'driver' line of codecs.conf) |
7397 | 34 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
35 3. The codec should initialize the output device before decoding the first |
28269 | 36 frame. It may happen in init() or at the middle of the first decode(), see |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
37 3a. It means calling vd.c::mpcodecs_config_vo() with the image dimensions, |
28269 | 38 and the _preferred_ (meaning: internal, native, best) colorspace. |
39 NOTE: This colorspace may not be equal to the colorspace that is actually | |
40 used. It's just a _hint_ for the colorspace matching algorithm and mainly | |
41 used as input format of the converter, but _only_ when colorspace | |
42 conversion is required, | |
7397 | 43 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
44 3a. Selecting the best output colorspace: |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
45 The vd.c::mpcodecs_config_vo() function will go through the outfmt list |
28269 | 46 defined by the 'out' lines in codecs.conf and query both vd (codec) and |
47 vo (output device/filter/encoder) if the format is supported or not. | |
7397 | 48 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
49 For the vo, it calls the query_format() function of vf_XXX.c or ve_XXX.c. |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
50 It should return a set of feature flags, the most important ones for this |
28269 | 51 stage are: VFCAP_CSP_SUPPORTED (colorspace supported directly or by |
52 conversion) and VFCAP_CSP_SUPPORTED_BY_HW (colorspace supported | |
53 WITHOUT any conversion). | |
7397 | 54 |
55 For the vd (codec), control() with VDCTRL_QUERY_FORMAT will be called. | |
28269 | 56 If it does not implement VDCTRL_QUERY_FORMAT, (i.e. answers CONTROL_UNKNOWN |
57 or CONTROL_NA), it is assumed to be CONTROL_TRUE (colorspace supported)! | |
7397 | 58 |
28269 | 59 So, by default, if the list of supported colorspaces is constant and does |
60 not depend on the actual file/stream header, then it is enough to list the | |
61 formats in codecs.conf ('out' field) and not implement VDCTRL_QUERY_FORMAT. | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
62 This is the case for most codecs. |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
63 |
28269 | 64 If the supported colorspace list depends on the file being decoded, list |
65 the possible out formats (colorspaces) in codecs.conf and implement the | |
66 VDCTRL_QUERY_FORMAT to test the availability of the given colorspace for | |
67 the given video file/stream. | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
68 |
7397 | 69 The vd.c core will find the best matching colorspace, depending on the |
28269 | 70 VFCAP_CSP_SUPPORTED_BY_HW flag (see vfcap.h). If no match can be found, |
71 it will try again with the 'scale' filter inserted between vd and vo. | |
72 If this is unsuccessful, it will fail :( | |
7397 | 73 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
74 4. Requesting buffer for the decoded frame: |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
75 The codec has to call mpcodecs_get_image() with proper imgtype & imgflag. |
7397 | 76 It will find the optimal buffering setup (preferred stride, alignment etc) |
77 and return a pointer to the allocated and filled up mpi (mp_image_t*) struct. | |
28269 | 78 The 'imgtype' controls the buffering setup, i.e. STATIC (just one buffer that |
79 'remembers' its content between frames), TEMP (write-only, full update), | |
7397 | 80 EXPORT (memory allocation is done by the codec, not recommended) and so on. |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
81 The 'imgflags' set up the limits for the buffer, i.e. stride limitations, |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
82 readability, remembering content etc. See mp_image.h for the short |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
83 description. See dr-methods.txt for the explanation of buffer |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
84 importing and mpi imgtypes. |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
85 |
7397 | 86 Always try to implement stride support! (stride == bytes per line) |
87 If no stride support, then stride==bytes_per_pixel*image_width. | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
88 If you have stride support in your decoder, use the mpi->stride[] value |
7397 | 89 for the byte_per_line for each plane. |
90 Also take care of other imgflags, like MP_IMGFLAG_PRESERVE and | |
91 MP_IMGFLAG_READABLE, MP_IMGFLAG_COMMON_STRIDE and MP_IMGFLAG_COMMON_PLANE! | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
92 The file mp_image.h contains flag descriptions in comments, read it! |
28269 | 93 Ask for help on dev-eng, describing the behavior of your codec, if unsure. |
7397 | 94 |
95 4.a. buffer allocation, vd.c::mpcodecs_get_image(): | |
96 If the requested buffer imgtype!=EXPORT, then vd.c will try to do | |
28269 | 97 direct rendering, i.e. ask the next filter/vo for the buffer allocation. |
7397 | 98 It's done by calling get_image() of the vf_XXX.c file. |
99 If it was successful, the imgflag MP_IMGFLAG_DIRECT will be set, and one | |
100 memcpy() will be saved when passing the data from vd to the next filter/vo. | |
101 See dr-methods.txt for details and examples. | |
102 | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
103 5. Decode the frame, to the mpi structure requested in 4., then return the mpi |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
104 to decvideo.c. Return NULL if the decoding failed or skipped the frame. |
7397 | 105 |
106 6. decvideo.c::decode_video() will now pass the 'mpi' to the next filter (vf_X). | |
107 | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
108 7. The filter's (vf_X) put_image() then requests a new mpi buffer by calling |
7397 | 109 vf.c::vf_get_image(). |
110 | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
111 7.a. vf.c::vf_get_image() will try to get direct rendering by asking the |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
112 next filter to do the buffer allocation (calls vf_Y's get_image()). |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
113 If it fails, it will fall back on normal system memory allocation. |
7397 | 114 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
115 8. When we're past the whole filter chain (multiple filters can be connected, |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
116 even the same filter multiple times) then the last, 'leaf' filters will be |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
117 called. The only difference between leaf and non-leaf filters is that leaf |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
118 filters have to implement the whole filter API. |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
119 Currently leaf filters are: vf_vo.c (wrapper over libvo) and ve_XXX.c |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
120 (video encoders used by MEncoder). |
9687 | 121 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
122 |
9687 | 123 Video Filters |
124 ============= | |
125 | |
126 Video filters are plugin-like code modules implementing the interface | |
127 defined in vf.h. | |
128 | |
129 Basically it means video output manipulation, i.e. these plugins can | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
130 modify the image and the image properties (size, colorspace, etc) between |
9687 | 131 the video decoders (vd.h) and the output layer (libvo or video encoders). |
132 | |
133 The actual API is a mixture of the video decoder (vd.h) and libvo | |
134 (video_out.h) APIs. | |
135 | |
136 main differences: | |
137 - vf plugins may be "loaded" multiple times, with different parameters | |
138 and context - it's new in MPlayer, old APIs weren't reentrant. | |
139 - vf plugins don't have to implement all functions - all functions have a | |
140 'fallback' version, so the plugins only override these if wanted. | |
141 - Each vf plugin has its own get_image context, and they can interchange | |
142 images/buffers using these get_image/put_image calls. | |
143 | |
144 | |
8001 | 145 The VIDEO FILTER API: |
146 ===================== | |
147 filename: vf_FILTERNAME.c | |
148 | |
149 vf_info_t* info; | |
150 pointer to the filter description structure: | |
151 | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
152 const char *info; // description of the filter |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
153 const char *name; // short name of the filter, must be FILTERNAME |
28269 | 154 const char *author; // name and email/URL of the author(s) |
155 const char *comment; // comment, URL to papers describing algorithm etc. | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
156 int (*open)(struct vf_instance *vf,char* args); |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
157 // pointer to the open() function: |
8001 | 158 |
8020 | 159 Sample: |
160 | |
161 vf_info_t vf_info_foobar = { | |
162 "Universal Foo and Bar filter", | |
163 "foobar", | |
164 "Ms. Foo Bar", | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
165 "based on algorithm described at http://www.foo-bar.org", |
8020 | 166 open |
167 }; | |
168 | |
8001 | 169 The open() function: |
170 | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
171 open() is called when the filter is appended/inserted in the filter chain. |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
172 It'll receive the handler (vf) and the optional filter parameters as |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
173 char* string. Note that encoders (ve_*) and vo wrapper (vf_vo.c) have |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
174 non-string arg, but it's specially handled by MPlayer/MEncoder. |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
175 |
28269 | 176 The open() function should fill the vf_instance_t structure with the |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
177 implemented functions' pointers (see below). |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
178 It can optionally allocate memory for its internal data (vf_priv_t) and |
8001 | 179 store the pointer in vf->priv. |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
180 |
28269 | 181 The open() function should parse (or at least check syntax of) parameters, |
182 and fail (return 0) on error. | |
8001 | 183 |
184 Sample: | |
185 | |
28269 | 186 static int open(vf_instance_t *vf, char* args) |
187 { | |
188 vf->query_format = query_format; | |
189 vf->config = config; | |
190 vf->put_image = put_image; | |
8001 | 191 // allocate local storage: |
28269 | 192 vf->priv = malloc(sizeof(struct vf_priv_s)); |
193 vf->priv->w = | |
194 vf->priv->h = -1; | |
8001 | 195 if(args) // parse args: |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
196 if(sscanf(args, "%d:%d", &vf->priv->w, &vf->priv->h)!=2) return 0; |
8001 | 197 return 1; |
198 } | |
199 | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
200 Functions in struct vf_instance: |
8001 | 201 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
202 NOTE: All these are optional, their function pointer is either NULL or points |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
203 to a default implementation. If you implement them, don't forget to set |
8001 | 204 vf->FUNCNAME in your open() ! |
205 | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
206 int (*query_format)(struct vf_instance *vf, unsigned int fmt); |
8001 | 207 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
208 The query_format() function is called one or more times before the config(), |
8001 | 209 to find out the capabilities and/or support status of a given colorspace (fmt). |
210 For the return values, see vfcap.h! | |
211 Normally, a filter should return at least VFCAP_CSP_SUPPORTED for all supported | |
8020 | 212 colorspaces it accepts as input, and 0 for the unsupported ones. |
213 If your filter does linear conversion, it should query the next filter, | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
214 and merge in its capability flags. Note: You should always ensure that the |
8020 | 215 next filter will accept at least one of your possible output colorspaces! |
8001 | 216 |
217 Sample: | |
218 | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
219 static int query_format(struct vf_instance *vf, unsigned int fmt) |
28269 | 220 { |
8001 | 221 switch(fmt){ |
222 case IMGFMT_YV12: | |
223 case IMGFMT_I420: | |
224 case IMGFMT_IYUV: | |
225 case IMGFMT_422P: | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
226 return vf_next_query_format(vf,IMGFMT_YUY2) & (~VFCAP_CSP_SUPPORTED_BY_HW); |
8001 | 227 } |
228 return 0; | |
229 } | |
230 | |
28269 | 231 For the more complex case, when you have an N -> M colorspace mapping matrix, |
31284 | 232 see vf_scale or vf_format for examples. |
8020 | 233 |
8001 | 234 |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
235 int (*config)(struct vf_instance *vf, |
8001 | 236 int width, int height, int d_width, int d_height, |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
237 unsigned int flags, unsigned int outfmt); |
8001 | 238 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
239 The config() is called to initialize/configure the filter before using it. |
8001 | 240 Its parameters are already well-known from libvo: |
241 width, height: size of the coded image | |
242 d_width, d_height: wanted display size (usually aspect corrected w/h) | |
28269 | 243 Filters should use width, height as input image dimension, but the |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
244 resizing filters (crop, expand, scale, rotate, etc) should update |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
245 d_width/d_height (display size) to preserve the correct aspect ratio! |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
246 Filters should not rely on d_width, d_height as input parameters, |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
247 the only exception is when a filter replaces some libvo functionality |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
248 (like -vf scale with -zoom, or OSD rendering with -vf expand). |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
249 flags: the "good" old libvo flag set: |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
250 0x01 - force fullscreen (-fs) |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
251 0x02 - allow mode switching (-vm) |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
252 0x04 - allow software scaling (-zoom) |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
253 0x08 - flipping (-flip) |
8001 | 254 (Usually you don't have to worry about flags, just pass it to next config.) |
255 outfmt: the selected colorspace/pixelformat. You'll receive images in this | |
256 format. | |
257 | |
258 Sample: | |
259 | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
260 static int config(struct vf_instance *vf, |
28269 | 261 int width, int height, int d_width, int d_height, |
262 unsigned int flags, unsigned int outfmt) | |
263 { | |
264 // use d_width/d_height if not set by the user: | |
265 if (vf->priv->w == -1) | |
266 vf->priv->w = d_width; | |
267 if (vf->priv->h == -1) | |
268 vf->priv->h = d_height; | |
8001 | 269 // initialize your filter code |
270 ... | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
271 // OK now config the rest of the filter chain, with our output parameters: |
8001 | 272 return vf_next_config(vf,vf->priv->w,vf->priv->h,d_width,d_height,flags,outfmt); |
273 } | |
274 | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
275 void (*uninit)(struct vf_instance *vf); |
8001 | 276 |
28269 | 277 Okay, uninit() is the simplest, it's called at the end. You can free your |
8001 | 278 private buffers etc here. |
279 | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
280 int (*put_image)(struct vf_instance *vf, mp_image_t *mpi); |
8001 | 281 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
282 Ah, put_image(). This is the main filter function, it should convert/filter/ |
8001 | 283 transform the image data from one format/size/color/whatever to another. |
284 Its input parameter is an mpi (mplayer image) structure, see mp_image.h. | |
285 Your filter has to request a new image buffer for the output, using the | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
286 vf_get_image() function. NOTE: Even if you don't want to modify the image, |
8001 | 287 just pass it to the next filter, you have to either |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
288 - not implement put_image() at all - then it will be skipped |
8001 | 289 - request a new image with type==EXPORT and copy the pointers |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
290 NEVER pass the mpi as-is, it's local to the filters and may cause trouble. |
8001 | 291 |
292 If you completely copy/transform the image, then you probably want this: | |
293 | |
28269 | 294 dmpi = vf_get_image(vf->next,mpi->imgfmt, MP_IMGTYPE_TEMP, |
295 MP_IMGFLAG_ACCEPT_STRIDE, vf->priv->w, vf->priv->h); | |
8001 | 296 |
28269 | 297 It will allocate a new image and return an mp_image structure filled by |
8001 | 298 buffer pointers and stride (bytes per line) values, in size of vf->priv->w |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
299 times vf->priv->h. If your filter cannot handle stride, then leave out |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
300 MP_IMGFLAG_ACCEPT_STRIDE. Note that you can do this, but it isn't recommended, |
8001 | 301 the whole video path is designed to use strides to get optimal throughput. |
28269 | 302 If your filter allocates output image buffers, then use MP_IMGTYPE_EXPORT |
8001 | 303 and fill the returned dmpi's planes[], stride[] with your buffer parameters. |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
304 Note, it is not recommended (no direct rendering), so if you can, use |
8001 | 305 vf_get_image() for buffer allocation! |
306 For other image types and flags see mp_image.h, it has comments. | |
28269 | 307 If you are unsure, feel free to ask on the dev-eng mailing list. Please |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
308 describe the behavior of your filter, and its limitations, so we can |
8001 | 309 suggest the optimal buffer type + flags for your code. |
310 | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
311 Now that you have the input (mpi) and output (dmpi) buffers, you can do |
8001 | 312 the conversion. If you didn't notice yet, mp_image has some useful info |
28269 | 313 fields. They may help you a lot creating if() or for() structures: |
8001 | 314 flags: MP_IMGFLAG_PLANAR, MP_IMGFLAG_YUV, MP_IMGFLAG_SWAPPED |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
315 helps you to handle various pixel formats in single code. |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
316 bpp: bits per pixel |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
317 WARNING! It's number of bits _allocated_ to store a pixel, |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
318 it is not the number of bits actually used to keep colors! |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
319 So it's 16 for both 15 and 16 bit color depth, and is 32 for |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
320 32bpp (actually 24 bit color depth) mode! |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
321 It's 1 for 1bpp, 9 for YVU9, and is 12 for YV12 mode. Get it? |
8001 | 322 For planar formats, you also have chroma_width, chroma_height and |
8020 | 323 chroma_x_shift, chroma_y_shift too, they specify the chroma subsampling |
28269 | 324 for YUV formats: |
325 chroma_width = luma_width >> chroma_x_shift; | |
326 chroma_height = luma_height >> chroma_y_shift; | |
8001 | 327 |
328 If you're done, call the rest of the filter chain to process your output | |
329 image: | |
330 return vf_next_put_image(vf,dmpi); | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
331 |
8001 | 332 |
333 Ok, the rest is for advanced functionality only: | |
334 | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
335 int (*control)(struct vf_instance *vf, int request, void* data); |
8001 | 336 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
337 You can control the filter at runtime from MPlayer/MEncoder/dec_video: |
8001 | 338 #define VFCTRL_QUERY_MAX_PP_LEVEL 4 /* test for postprocessing support (max level) */ |
28269 | 339 #define VFCTRL_SET_PP_LEVEL 5 /* set postprocessing level */ |
340 #define VFCTRL_SET_EQUALIZER 6 /* set color options (brightness,contrast etc) */ | |
341 #define VFCTRL_GET_EQUALIZER 8 /* get color options (brightness,contrast etc) */ | |
342 #define VFCTRL_DRAW_OSD 7 | |
343 #define VFCTRL_CHANGE_RECTANGLE 9 /* Change the rectangle boundaries */ | |
8001 | 344 |
8020 | 345 |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
346 void (*get_image)(struct vf_instance *vf, mp_image_t *mpi); |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
347 |
8001 | 348 This is for direct rendering support, works the same way as in libvo drivers. |
349 It makes in-place pixel modifications possible. | |
28269 | 350 If you implement it (vf->get_image!=NULL), then it will be called to do the |
8001 | 351 buffer allocation. You SHOULD check the buffer restrictions (stride, type, |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
352 readability etc) and if everything is OK, then allocate the requested buffer |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
353 using the vf_get_image() function and copying the buffer pointers. |
8001 | 354 |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
355 NOTE: You HAVE TO save the dmpi pointer, as you'll need it in put_image() |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
356 later on. It is not guaranteed that you'll get the same mpi for put_image() as |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
357 in get_image() (think of out-of-order decoding, get_image is called in decoding |
8020 | 358 order, while put_image is called for display) so the only safe place to save |
359 it is in the mpi struct itself: mpi->priv=(void*)dmpi; | |
360 | |
361 | |
30642
a972c1a4a012
cosmetics: Rename struct vf_instance_s --> vf_instance.
diego
parents:
28269
diff
changeset
|
362 void (*draw_slice)(struct vf_instance *vf, unsigned char** src, |
28269 | 363 int* stride, int w,int h, int x, int y); |
8001 | 364 |
365 It's the good old draw_slice callback, already known from libvo. | |
8020 | 366 If your filter can operate on partial images, you can implement this one |
8001 | 367 to improve performance (cache utilization). |
368 | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
369 Ah, and there are two sets of capability/requirement flags (vfcap.h type) |
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
370 in vf_instance_t, used by the default query_format() implementation, and by |
8001 | 371 the automatic colorspace/stride matching code (vf_next_config()). |
372 | |
373 // caps: | |
374 unsigned int default_caps; // used by default query_format() | |
375 unsigned int default_reqs; // used by default config() | |
376 | |
15624
cf7bbc26cb3d
Spelling/wording/grammar fixes, convert mixed tabs and spaces indentation to
diego
parents:
15602
diff
changeset
|
377 BTW, you should avoid using global or static variables to store filter instance |
28269 | 378 specific stuff, as filters might be used multiple times and in the future even |
379 multiple streams might be possible. | |
7397 | 380 |
9687 | 381 |
7397 | 382 The AUDIO path: |
383 =============== | |
384 TODO!!! |