Mercurial > mplayer.hg
annotate DOCS/tech/libmpcodecs.txt @ 33263:5f527a9a9521
Add an exit function.
This function will allow performing clean-up operations.
(MPlayer calls guiDone() before exiting, but only if the GUI has been
initialized, i.e. if guiInit() has been called successfully. Any
exit_player()/exit_player_with_rc() after GUI's cfg_read() until
guiInit(), or any exit_player() during guiInit() itself will end the GUI
without calling guiDone(). This exit function will at least handle
abortions during guiInit() itself. It will be called twice in case of an
guiExit() after GUI initialization - first directly, next by guiDone()
via MPlayer's exit_player_with_rc().)
author | ib |
---|---|
date | Tue, 03 May 2011 12:19:22 +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!!! |