[FFmpeg-devel] [PATCH] Document sws_scale()

[Stefano Sabatini]

On date Wednesday 2009-02-18 01:13:55 +0100, Stefano Sabatini encoded:
> On date Tuesday 2009-02-17 03:26:17 +0100, Michael Niedermayer encoded:
> > On Tue, Feb 17, 2009 at 01:50:18AM +0100, Stefano Sabatini wrote:
> > > On date Tuesday 2009-02-17 01:37:43 +0100, Michael Niedermayer encoded:
> > > > On Tue, Feb 17, 2009 at 01:15:53AM +0100, Stefano Sabatini wrote:
> > > [...]
> > > > > +/**
> > > > > + * Scales the image slice in \p src and puts the resulting scaled
> > > > > + * slice in the image in \p dst. A slice is a sequence of consecutive
> > > > > + * rows in an image.
> > > > > + *
> > > > > + * @param context the scaling context previously created with
> > > > > + *                sws_getContext()
> > > > > + * @param src     the pointer to the array of pointers to the planes
> > > > > + *                of the source slice (just one pointer in case of
> > > > > + *                packed image formats)
> > > >                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > [...]
> > > 
> > > Sorry, I didn't got you meant to remove *also* those.
> > > 
> > > New round.
> > 
> > ok
> 
> Sorry, I read again the patch and found it quite unsatisfying, I fixed
> some things (
> the pointer to the array of pointers to the planes ->
> the array containing the pointers to the planes)
> 
> and rearranged spacing, but there is still something I don't like.
> 
> The srcSliceY definition:
>  * @param srcSliceY the position in the source image of the source
>  *                  slice to process, that is the number in the image
>  *                  of the first row of the slice
> 
> maybe s/number/offset/ may help, or to mention that the numbering
> starts with 0.
> 
> Then the expression "the strides or linesizes" is ambiguous, it's not
> clear if the two names refer to the same thing or to two distinct
> things. I tought about something like:
> "strides (that is linesizes)"
> or
> "strides (also called linesizes)"
> 
> but they both seem quite ugly, the third option was to remove the
> reference to the term "linesize", but that would make the
> documentation less helpful since linesize is a term already used at
> least in lavc and so it may result more familiar to the user than
> "stride" (term which is only used in libsws).
> 
> Suggestions are welcome, otherwise I'll try to figure out what to do
> and will post another patch.

I believe it should be somehow better now, removed ambiguous mention
to the term "linesize", maybe it should be documented somewhere else
(or maybe as a @note?).

Regards.
-- 
FFmpeg = Fantastic Fostering Merciful Problematic Extroverse Guru
-------------- next part --------------
A non-text attachment was scrubbed...
Name: document-sws-scale.patch
Type: text/x-diff
Size: 1803 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20090218/0553780f/attachment.patch>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: move-src-src-slice.patch
Type: text/x-diff
Size: 1409 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20090218/0553780f/attachment-0001.patch>