Mercurial > mplayer.hg
changeset 28269:49ecb0f6c55f
spelling/grammar/wording/whitespace
| author | diego |
|---|---|
| date | Sun, 11 Jan 2009 19:48:51 +0000 |
| parents | dc64eca366cf |
| children | aba9a3186ce9 |
| files | DOCS/tech/libmpcodecs.txt |
| diffstat | 1 files changed, 79 insertions(+), 77 deletions(-) [+] |
line wrap: on
line diff
--- a/DOCS/tech/libmpcodecs.txt Sun Jan 11 19:48:01 2009 +0000 +++ b/DOCS/tech/libmpcodecs.txt Sun Jan 11 19:48:51 2009 +0000 @@ -12,7 +12,7 @@ [MPlayer core] | (1) - ______V_____ (2) /~~~~~~~~~~\ (3,4) |~~~~~~| + ______V______ (2) /~~~~~~~~~~\ (3,4) |~~~~~~| | | -----> | vd_XXX.c | -------> | vd.c | | dec_video | \__________/ <-(3a)-- |______| | | -----, ,.............(3a,4a).....: @@ -27,54 +27,56 @@ Short description of video path: 1. MPlayer/MEncoder core requests the decoding of a compressed video frame: - calls dec_video.c::decode_video() + calls dec_video.c::decode_video(). -2. decode_video() calls the previously ( init_video() ) selected video codec +2. decode_video() calls the video codec previously selected in init_video(). (vd_XXX.c file, where XXX == vfm name, see the 'driver' line of codecs.conf) 3. The codec should initialize the output device before decoding the first - frame, it may happen in init() or at the middle of the first decode(), see + frame. It may happen in init() or at the middle of the first decode(), see 3a. It means calling vd.c::mpcodecs_config_vo() with the image dimensions, - and the _preferred_ (mean: internal, native, best) colorspace. - NOTE: This colorspace may not be equal to the actually used colorspace, it's - just a _hint_ for the csp matching algorithm, and mainly used _only_ when - csp conversion is required, as input format of the converter. + and the _preferred_ (meaning: internal, native, best) colorspace. + NOTE: This colorspace may not be equal to the colorspace that is actually + used. It's just a _hint_ for the colorspace matching algorithm and mainly + used as input format of the converter, but _only_ when colorspace + conversion is required, 3a. Selecting the best output colorspace: The vd.c::mpcodecs_config_vo() function will go through the outfmt list - defined by codecs.conf's 'out' lines, and query both vd (codec) and vo - (output device/filter/encoder) if it's supported or not. + defined by the 'out' lines in codecs.conf and query both vd (codec) and + vo (output device/filter/encoder) if the format is supported or not. For the vo, it calls the query_format() function of vf_XXX.c or ve_XXX.c. It should return a set of feature flags, the most important ones for this - stage are: VFCAP_CSP_SUPPORTED (csp supported directly or by conversion) - and VFCAP_CSP_SUPPORTED_BY_HW (csp supported WITHOUT any conversion). + stage are: VFCAP_CSP_SUPPORTED (colorspace supported directly or by + conversion) and VFCAP_CSP_SUPPORTED_BY_HW (colorspace supported + WITHOUT any conversion). For the vd (codec), control() with VDCTRL_QUERY_FORMAT will be called. - If it doesn't implement VDCTRL_QUERY_FORMAT, (i.e. answers CONTROL_UNKNOWN - or CONTROL_NA), it will be assumed to be CONTROL_TRUE (csp supported)! + If it does not implement VDCTRL_QUERY_FORMAT, (i.e. answers CONTROL_UNKNOWN + or CONTROL_NA), it is assumed to be CONTROL_TRUE (colorspace supported)! - So, by default, if the list of supported colorspaces is constant, doesn't - depend on the actual file's/stream's header, it's enough to list them - in codecs.conf ('out' field), and don't implement VDCTRL_QUERY_FORMAT. + So, by default, if the list of supported colorspaces is constant and does + not depend on the actual file/stream header, then it is enough to list the + formats in codecs.conf ('out' field) and not implement VDCTRL_QUERY_FORMAT. This is the case for most codecs. - If the supported csp list depends on the file being decoded, list the - possible out formats (colorspaces) in codecs.conf, and implement the - VDCTRL_QUERY_FORMAT to test the availability of the given csp for the - given video file/stream. + If the supported colorspace list depends on the file being decoded, list + the possible out formats (colorspaces) in codecs.conf and implement the + VDCTRL_QUERY_FORMAT to test the availability of the given colorspace for + the given video file/stream. The vd.c core will find the best matching colorspace, depending on the - VFCAP_CSP_SUPPORTED_BY_HW flag (see vfcap.h). If no match at all, it - will try again with the 'scale' filter inserted between vd and vo. - If still no match, it will fail :( + VFCAP_CSP_SUPPORTED_BY_HW flag (see vfcap.h). If no match can be found, + it will try again with the 'scale' filter inserted between vd and vo. + If this is unsuccessful, it will fail :( 4. Requesting buffer for the decoded frame: The codec has to call mpcodecs_get_image() with proper imgtype & imgflag. It will find the optimal buffering setup (preferred stride, alignment etc) and return a pointer to the allocated and filled up mpi (mp_image_t*) struct. - The 'imgtype' controls the buffering setup, i.e. STATIC (just one buffer, - it 'remembers' its contents between frames), TEMP (write-only, full update), + The 'imgtype' controls the buffering setup, i.e. STATIC (just one buffer that + 'remembers' its content between frames), TEMP (write-only, full update), EXPORT (memory allocation is done by the codec, not recommended) and so on. The 'imgflags' set up the limits for the buffer, i.e. stride limitations, readability, remembering content etc. See mp_image.h for the short @@ -88,11 +90,11 @@ Also take care of other imgflags, like MP_IMGFLAG_PRESERVE and MP_IMGFLAG_READABLE, MP_IMGFLAG_COMMON_STRIDE and MP_IMGFLAG_COMMON_PLANE! The file mp_image.h contains flag descriptions in comments, read it! - Ask for help on dev-eng, describing the behaviour your codec, if unsure. + Ask for help on dev-eng, describing the behavior of your codec, if unsure. 4.a. buffer allocation, vd.c::mpcodecs_get_image(): If the requested buffer imgtype!=EXPORT, then vd.c will try to do - direct rendering, i.e. asks the next filter/vo for the buffer allocation. + direct rendering, i.e. ask the next filter/vo for the buffer allocation. It's done by calling get_image() of the vf_XXX.c file. If it was successful, the imgflag MP_IMGFLAG_DIRECT will be set, and one memcpy() will be saved when passing the data from vd to the next filter/vo. @@ -149,8 +151,8 @@ const char *info; // description of the filter const char *name; // short name of the filter, must be FILTERNAME - const char *author; // name and email/url of the author(s) - const char *comment; // comment, url to papers describing algo etc. + const char *author; // name and email/URL of the author(s) + const char *comment; // comment, URL to papers describing algorithm etc. int (*open)(struct vf_instance_s* vf,char* args); // pointer to the open() function: @@ -171,24 +173,25 @@ char* string. Note that encoders (ve_*) and vo wrapper (vf_vo.c) have non-string arg, but it's specially handled by MPlayer/MEncoder. - The open() function should fill the vf_instance_t structure, with the + The open() function should fill the vf_instance_t structure with the implemented functions' pointers (see below). It can optionally allocate memory for its internal data (vf_priv_t) and store the pointer in vf->priv. - The open() func should parse (or at least check syntax) of parameters, - and fail (return 0) if error. + The open() function should parse (or at least check syntax of) parameters, + and fail (return 0) on error. Sample: -static int open(vf_instance_t *vf, char* args){ - vf->query_format=query_format; - vf->config=config; - vf->put_image=put_image; +static int open(vf_instance_t *vf, char* args) +{ + vf->query_format = query_format; + vf->config = config; + vf->put_image = put_image; // allocate local storage: - vf->priv=malloc(sizeof(struct vf_priv_s)); - vf->priv->w= - vf->priv->h=-1; + vf->priv = malloc(sizeof(struct vf_priv_s)); + vf->priv->w = + vf->priv->h = -1; if(args) // parse args: if(sscanf(args, "%d:%d", &vf->priv->w, &vf->priv->h)!=2) return 0; return 1; @@ -200,8 +203,7 @@ to a default implementation. If you implement them, don't forget to set vf->FUNCNAME in your open() ! - int (*query_format)(struct vf_instance_s* vf, - unsigned int fmt); + int (*query_format)(struct vf_instance_s* vf, unsigned int fmt); The query_format() function is called one or more times before the config(), to find out the capabilities and/or support status of a given colorspace (fmt). @@ -214,7 +216,8 @@ Sample: -static int query_format(struct vf_instance_s* vf, unsigned int fmt){ +static int query_format(struct vf_instance_s* vf, unsigned int fmt) +{ switch(fmt){ case IMGFMT_YV12: case IMGFMT_I420: @@ -225,7 +228,7 @@ return 0; } -For the more complex case, when you have an N->M colorspace mapping matrix, +For the more complex case, when you have an N -> M colorspace mapping matrix, see vf_scale or vf_rgb2bgr for examples. @@ -237,7 +240,7 @@ Its parameters are already well-known from libvo: width, height: size of the coded image d_width, d_height: wanted display size (usually aspect corrected w/h) - Filters should use width,height as input image dimension, but the + Filters should use width, height as input image dimension, but the resizing filters (crop, expand, scale, rotate, etc) should update d_width/d_height (display size) to preserve the correct aspect ratio! Filters should not rely on d_width, d_height as input parameters, @@ -255,11 +258,14 @@ Sample: static int config(struct vf_instance_s* vf, - int width, int height, int d_width, int d_height, - unsigned int flags, unsigned int outfmt){ - // use d_width/d_height if not set by user: - if(vf->priv->w==-1) vf->priv->w=d_width; - if(vf->priv->h==-1) vf->priv->h=d_height; + int width, int height, int d_width, int d_height, + unsigned int flags, unsigned int outfmt) +{ + // use d_width/d_height if not set by the user: + if (vf->priv->w == -1) + vf->priv->w = d_width; + if (vf->priv->h == -1) + vf->priv->h = d_height; // initialize your filter code ... // OK now config the rest of the filter chain, with our output parameters: @@ -268,11 +274,10 @@ void (*uninit)(struct vf_instance_s* vf); -Okey, uninit() is the simplest, it's called at the end. You can free your +Okay, uninit() is the simplest, it's called at the end. You can free your private buffers etc here. - int (*put_image)(struct vf_instance_s* vf, - mp_image_t *mpi); + int (*put_image)(struct vf_instance_s* vf, mp_image_t *mpi); Ah, put_image(). This is the main filter function, it should convert/filter/ transform the image data from one format/size/color/whatever to another. @@ -286,27 +291,26 @@ If you completely copy/transform the image, then you probably want this: - dmpi=vf_get_image(vf->next,mpi->imgfmt, - MP_IMGTYPE_TEMP, MP_IMGFLAG_ACCEPT_STRIDE, - vf->priv->w, vf->priv->h); + dmpi = vf_get_image(vf->next,mpi->imgfmt, MP_IMGTYPE_TEMP, + MP_IMGFLAG_ACCEPT_STRIDE, vf->priv->w, vf->priv->h); -It will allocate a new image, and return an mp_image structure filled by +It will allocate a new image and return an mp_image structure filled by buffer pointers and stride (bytes per line) values, in size of vf->priv->w times vf->priv->h. If your filter cannot handle stride, then leave out MP_IMGFLAG_ACCEPT_STRIDE. Note that you can do this, but it isn't recommended, the whole video path is designed to use strides to get optimal throughput. -If your filter allocates output image buffers, then use MP_IMGTYPE_EXPORT, +If your filter allocates output image buffers, then use MP_IMGTYPE_EXPORT and fill the returned dmpi's planes[], stride[] with your buffer parameters. Note, it is not recommended (no direct rendering), so if you can, use vf_get_image() for buffer allocation! For other image types and flags see mp_image.h, it has comments. -If you are unsure, feel free to ask on the -dev-eng mailing list. Please +If you are unsure, feel free to ask on the dev-eng mailing list. Please describe the behavior of your filter, and its limitations, so we can suggest the optimal buffer type + flags for your code. Now that you have the input (mpi) and output (dmpi) buffers, you can do the conversion. If you didn't notice yet, mp_image has some useful info -fields, may help you a lot creating if() or for() structures: +fields. They may help you a lot creating if() or for() structures: flags: MP_IMGFLAG_PLANAR, MP_IMGFLAG_YUV, MP_IMGFLAG_SWAPPED helps you to handle various pixel formats in single code. bpp: bits per pixel @@ -317,9 +321,9 @@ It's 1 for 1bpp, 9 for YVU9, and is 12 for YV12 mode. Get it? For planar formats, you also have chroma_width, chroma_height and chroma_x_shift, chroma_y_shift too, they specify the chroma subsampling - for yuv formats: - chroma_width = luma_width >>chroma_x_shift; - chroma_height= luma_height>>chroma_y_shift; + for YUV formats: + chroma_width = luma_width >> chroma_x_shift; + chroma_height = luma_height >> chroma_y_shift; If you're done, call the rest of the filter chain to process your output image: @@ -328,24 +332,22 @@ Ok, the rest is for advanced functionality only: - int (*control)(struct vf_instance_s* vf, - int request, void* data); + int (*control)(struct vf_instance_s* vf, int request, void* data); You can control the filter at runtime from MPlayer/MEncoder/dec_video: #define VFCTRL_QUERY_MAX_PP_LEVEL 4 /* test for postprocessing support (max level) */ -#define VFCTRL_SET_PP_LEVEL 5 /* set postprocessing level */ -#define VFCTRL_SET_EQUALIZER 6 /* set color options (brightness,contrast etc) */ -#define VFCTRL_GET_EQUALIZER 8 /* get color options (brightness,contrast etc) */ -#define VFCTRL_DRAW_OSD 7 -#define VFCTRL_CHANGE_RECTANGLE 9 /* Change the rectangle boundaries */ +#define VFCTRL_SET_PP_LEVEL 5 /* set postprocessing level */ +#define VFCTRL_SET_EQUALIZER 6 /* set color options (brightness,contrast etc) */ +#define VFCTRL_GET_EQUALIZER 8 /* get color options (brightness,contrast etc) */ +#define VFCTRL_DRAW_OSD 7 +#define VFCTRL_CHANGE_RECTANGLE 9 /* Change the rectangle boundaries */ - void (*get_image)(struct vf_instance_s* vf, - mp_image_t *mpi); + void (*get_image)(struct vf_instance_s* vf, mp_image_t *mpi); This is for direct rendering support, works the same way as in libvo drivers. It makes in-place pixel modifications possible. -If you implement it (vf->get_image!=NULL) then it will be called to do the +If you implement it (vf->get_image!=NULL), then it will be called to do the buffer allocation. You SHOULD check the buffer restrictions (stride, type, readability etc) and if everything is OK, then allocate the requested buffer using the vf_get_image() function and copying the buffer pointers. @@ -357,8 +359,8 @@ it is in the mpi struct itself: mpi->priv=(void*)dmpi; - void (*draw_slice)(struct vf_instance_s* vf, - unsigned char** src, int* stride, int w,int h, int x, int y); + void (*draw_slice)(struct vf_instance_s* vf, unsigned char** src, + int* stride, int w,int h, int x, int y); It's the good old draw_slice callback, already known from libvo. If your filter can operate on partial images, you can implement this one @@ -373,8 +375,8 @@ unsigned int default_reqs; // used by default config() BTW, you should avoid using global or static variables to store filter instance -specific stuff, as filters might be used multiple times & in the future even -multiple streams might be possible +specific stuff, as filters might be used multiple times and in the future even +multiple streams might be possible. The AUDIO path: