[MPlayer-dev-eng] [PATCH] Documentation of XviD options in man page

[Diego Biurrun]

Guillaume POIRIER writes:
> Diego Biurrun wrote:
> > It would
> > be great if you could review and update all of them.  At the moment
> > they are in a sad state of neglect and very low on my TODO-list.  So
> > if you could tackle this area it would be very much appreciated.
> Ok. I added/updated all the documentation that needed to, or for which I
> could find some informations.
> There's one more that I'd like to add, but I haven't tested it yet. I'll 
> keep you posted.

Good news :-)

> > As said above, please start new sentences on a new line.  Extra points
> > for avoiding trailing whitespace.
> Ok, I think I've got it right now

Yes.  I have a couple more remarks, but this is looking very good
already.

>  .B interlacing
> -enable support for interlaced content (default=off)
> +For interlaced video material, turn this option to on.
> +NB this option does not deinterlace video, it encodes it field-based
> +(default: off)

Hmm, what is NB?

>  .B 4mv\ \ \ \ 
>  use 4 motion vectors per macro-block, might give better compression at the
> -cost of a slower encoding (default=off)
> +cost of a slower encoding (default: off)
> +.br
> +.I
> +WARNING:
> +This option isn't compatible with XviD-1.0.x

.I and WARNING should be on the same line.

How is this option incompatible with 1.0.x?  There is a different set
of options for XviD 1.0.

>  .B greyscale
> -encode in black & white (default=off)
> +XviD discard chroma planes bitstream so the encoded video is greyscale only.
> +Note that this does not speed up encoding, that just prevent chroma data
> +from being written in the last stage of encoding.
> +This setting enable Chroma color discarding.
> +(default: off)

Dunno what happened here, but your grammar suffered a blackout in this
paragraph.  Also the last sentence seems redundant.  Here is what I
would suggest (I hope it is still correct):

  Make XviD discard chroma planes so the encoded video is greyscale only.
  Note that this does not speed up encoding, it just prevents chroma data
  from being written in the last stage of encoding.

>  .B keyframe_boost=<0\-1000>
> -(default=0, 2pass mode only)
> +This setting tells how many additional amount of bits, Intra Frames are
> +supposed to be given (this "boosting" amount of bits is compensated by
> +subtracting the same amount of bits from other frame types pool)

If it's countable you say many, otherwise you say much.  I would
suggest the following, hopefully clearer and still correct version:

  Shift some bits from the pool for other frame types to intra frames.

>  .B kfthreshold=<value>
> -(default=10, 2pass mode only)
> +Distance between two ivops so that it is not decresed its bit allocation
> +by the ivop reduction mechanism.

decreAsed

That sentence does not really make sense.  Unfortunately I'm not quite
sure what you are trying to say and thus cannot really suggest an
alternative.

>  .B kfreduction=<0\-100>
> -(default=30, 2pass mode only)
> +This reduction factor is the maximum allowed keyframe penalty applied to a
> +frame in a ivop sequence.

an

> +The more the frame is distant from the last ivop in the consecutive ivop
> +sequence, the more penalty it is applied.

The higher the distance from the last ivop in the consecutive ivop
sequence, the higher the penalty that is applied.

> +This ensures a maximum bitrate allocation to the last ivop, thus favorizing

favoring

> +This option usually results in sharper image.

in a

> +Unfortunately it has great impact on bitrate and sometimes the higher use of
> +bitrate will prevent it from giving a better image quality at a fixed bitrate.

  Unfortunately it has a great impact on bitrate and sometimes the
  higher bitrate use will prevent it from giving a better image
  quality at a fixed bitrate.

> +The better is to test w and w/o it and choose after this test, if it's
> +worth activting it.

  It's better to test with and without this option and see whether it
  is worth activating.

>  .B gmc\ \ \ \ 
> -enable global motion compensation, may save bits on panning scenes (default=off)
> +Enable Global Motion Compensation, which makes XviD generates Sprite Frame

generate

Sprite FrameS ?

> +which describe best Pan/Zoom/Rotating images.

best describe ?

> +Deciding whether or not you must activate to save bits depends highly on the
> +video material.

  The decision whether to activate this option or not to save bits
  depends highly on the video material.

> +Its impact on quality is good, and if VHQ uses too much CPU for you, this
> +setting can be a good alternative to save a few bits (and gain quality at 
> +fixed bitrate) at a minimum expense than VHQ (default: off)

  Its impact on quality is good, and if VHQ uses too much CPU for you, this
  setting can be a good alternative to save a few bits (and gain quality at
  fixed bitrate) at a lesser cost than with VHQ (default: off).

> +However for some video material, using the chromatic planes can help find

chroma

> +This setting turns on/off the use of chroma planes for Motion Estimation
> +(default: off)

  This setting toggles the use of chroma planes for motion estimation
  (default: off).

>  .B bf_threshold=<-255\-255>
> -change the probability of a frame to be a bframe (default=0)
> +Sometimes BFrames do not look good, and introduce artefacts when most of

B frames, artIfacts

> +the frame is static and some small zones have high motion (a static scene

in a static

> +This setting allow you to favorize or not, the use of bframes.
> +The higher the value, the more a bframe has chance to be used.

  The higher the value, the higher the probability of B frames being
  used.

>  .B hq_ac\ \ 
> -enable a better prediction of AC component (default=off)
> +Activates High Quality AC coefficient prediction from neighboor blocks.
> +(default:off)

neighbor

> +Activating this setting, XviD will also use the frequency domain (DCT) to
> +search a motion vector that minimizes not only the spatial difference but
> +also the encoding length of the block.

  With this setting activated, XviD will also use the frequency domain (DCT) to
  search for a motion vector that minimizes not only the spatial difference but
  also the encoding length of the block.

> +Faster to slower:

  Fastest to slowest:

Please send in an updated version, I'll apply it.
Thanks

Diego