[FFmpeg-devel] [PATCH] Some documentation for swscale.h

Michael Niedermayer michaelni
Tue Feb 10 02:06:40 CET 2009


On Tue, Feb 10, 2009 at 01:19:03AM +0100, Stefano Sabatini wrote:
> On date Sunday 2009-02-08 16:21:01 +0100, Michael Niedermayer encoded:
> > On Sat, Feb 07, 2009 at 10:45:47PM +0100, Stefano Sabatini wrote:
> > > Hi all, no hurry for reviewing this since I'm still in the process of
> > > learning how to use properly swscale and there is quite some
> > > sofistication involved in it, anyway some review would be welcome, and
> > > I can commit by little steps the various parts as long as they are
> > > OKed.
> > > 
> > > Regards.
> > > -- 
> > > FFmpeg = Fundamental and Foolish Mysterious Portable Enhanced Governor
> > 
> > > Index: libswscale/swscale.h
> > > ===================================================================
> > > --- libswscale/swscale.h	(revision 28480)
> > > +++ libswscale/swscale.h	(working copy)
> > > @@ -98,8 +98,8 @@
> > >  // when used for filters they must have an odd number of elements
> > >  // coeffs cannot be shared between vectors
> > >  typedef struct {
> > > -    double *coeff;
> > > -    int length;
> > > +    double *coeff;              ///< pointers to the list of coefficients
> > > +    int length;                 ///< number of coefficients in the vector
> > >  } SwsVector;
> > >  
> > >  // vectors can be shared
> > 
> > ok
> 
> Applied.
>  
> > [...]
> > 
> > > +
> > > +/**
> > > + * Scales the image slice in \p src and puts the resulting scaled
> > > + * slice in \p dst. An 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 image (just one pointer in case of packed data)
> > > + * @param srcStride the pointer to the array containing the strides or
> > > + * linesizes of the source image for each plane (in the case of packed
> > > + * image formats there is only one linesize).
> > > + * @param srcSliceY the position of the source slice to process, that
> > > + * is the number of the first row of the slice
> > > + * @param srcSliceH the heigth of the slice, that is the number of
> > > + * rows of the slice
> > > + * @param dst the pointer to the array containing the pointers to the
> > > + * data planes of the image (just one pointer in case of packed data)
> > > + * @param srcStride the pointer to the array containing the strides or
> > > + * linesizes of the destination image for each plane (in the case of
> > > + * packed image formats there is only one linesize).
> > > + * @return the height of the output slice
> > 
> > trytoaddsomewhitespaceplease
> > 
> > 
> > > + */
> > >  int sws_scale(struct SwsContext *context, uint8_t* src[], int srcStride[], int srcSliceY,
> > >                int srcSliceH, uint8_t* dst[], int dstStride[]);
> > 
> > > +
> > > +/**
> > > + * @deprecated Use sws_scale() instead.
> > > + */
> > >  int sws_scale_ordered(struct SwsContext *context, uint8_t* src[], int srcStride[], int srcSliceY,
> > >                        int srcSliceH, uint8_t* dst[], int dstStride[]) attribute_deprecated;
> > 
> > wrong patch
> > 
> > 
> > >  
> > > +/**
> > > + * @param inv_table the yuv2rgb coefficients, normally Inverse_Table_6_9[x]
> > 
> > > + * @param fullRange if 1 then the luma range is 0..255, if 0 it is 16..235
> > 
> > and the chroma range ...
> > 
> > 
> > > + * @return -1 if not supported
> > > + */
> > 
> > the return is always negative for errors non negative no error,
> > thats the case for nearly all of libav!
> > 
> > 
> > > +int sws_setColorspaceDetails(struct SwsContext *c, const int inv_table[4], int srcRange, const int table[4], int dstRange, int brightness, int contrast, int saturation);
> > >  
> > > -int sws_setColorspaceDetails(struct SwsContext *c, const int inv_table[4], int srcRange, const int table[4], int dstRange, int brightness, int contrast, int saturation);
> > 
> > ?
> > 
> > 
> > [...]
> > >                                  float chromaHShift, float chromaVShift,
> > >                                  int verbose);
> > > +
> > >  void sws_freeFilter(SwsFilter *filter);
> > 
> > huh?
> > 
> > 
> > >  
> > > +/**
> > > + * Checks if context is valid or reallocs a new one instead.  If
> > > + * context is NULL, just calls sws_getContext() to get a new one.
> > > + * Otherwise, checks if the parameters are the ones already saved in
> > > + * context.  If that is the case, returns the current context.
> > > + * Otherwise, frees context and gets a new one.
> > > + *
> > > + * Be warned that \p srcFilter and \p dstFilter are not checked, they
> > > + * are assumed to remain valid.
> > > + */
> > >  struct SwsContext *sws_getCachedContext(struct SwsContext *context,
> > >                                          int srcW, int srcH, int srcFormat,
> > >                                          int dstW, int dstH, int dstFormat, int flags,
> > [...]
> > > @@ -3166,16 +3166,6 @@
> > >      av_free(c);
> > >  }
> > >  
> > > -/**
> > > - * Checks if context is valid or reallocs a new one instead.
> > > - * If context is NULL, just calls sws_getContext() to get a new one.
> > > - * Otherwise, checks if the parameters are the ones already saved in context.
> > > - * If that is the case, returns the current context.
> > > - * Otherwise, frees context and gets a new one.
> > > - *
> > > - * Be warned that srcFilter, dstFilter are not checked, they are
> > > - * asumed to remain valid.
> > > - */
> > >  struct SwsContext *sws_getCachedContext(struct SwsContext *context,
> > 
> > moving of comments and changes MUST be in seperate patches.
> > and i must say ive edited this now a few times to not sound too rude but
> > this isnt the first time that doxy patches from you are such a mess.
> 
> Sorry, I split part of the patch into small patches, hope they are
> more acceptable now.
> 
> Summary:
> 
> * sws-scale-ordered-is-deprecated.patch
>   Add a notice telling sws_scale_ordered() is deprecated.
> 
> * sws-remove-sws-scale-ordered-docs.patch
>   Remove pointless comment on sws_scale_ordered() (at least I cannot
>   interpret it).
> 
> * sws-move-getcached-context-doc.patch
>   Move the already existing doc for getCachedContext() from swscale.c to
>   swscale.h.
> 
> * sws-fix-getcached-context-doc.patch
>   Add \p for params, fix some typos and perform some rewording.
> 
> * sws-document-getconstvec.patch
>   Document sws_getConstVec().
> 
> * sws-document-getidentityvec.patch
>   Document sws_getIdentityVec().
> 
> * sws-document-scalevec.patch
>   Document sws_getScaleVec().
> 
> * sws-document-clonevec.patch
>   Document sws_cloneVec().
> 
> * sws-document-printvec.patch
>   Document sws_printVec().
> 
> Regards.
> -- 
> FFmpeg = Furious & Faboulous Mythic Problematic Ecstatic Genius

> Index: ffmpeg/libswscale/swscale.h
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.h	2009-02-10 00:41:23.000000000 +0100
> +++ ffmpeg/libswscale/swscale.h	2009-02-10 00:41:57.000000000 +0100
> @@ -119,6 +119,9 @@
>  int sws_scale(struct SwsContext *context, uint8_t* src[], int srcStride[], int srcSliceY,
>                int srcSliceH, uint8_t* dst[], int dstStride[]);
>  #if LIBSWSCALE_VERSION_MAJOR < 1
> +/**
> + * @deprecated Use sws_scale() instead.
> + */
>  int sws_scale_ordered(struct SwsContext *context, uint8_t* src[], int srcStride[], int srcSliceY,
>                        int srcSliceH, uint8_t* dst[], int dstStride[]) attribute_deprecated;
>  #endif

ok


> Index: ffmpeg/libswscale/swscale.c
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.c	2009-02-10 00:43:16.000000000 +0100
> +++ ffmpeg/libswscale/swscale.c	2009-02-10 01:08:52.000000000 +0100
> @@ -2821,9 +2821,6 @@
>  }
>  
>  #if LIBSWSCALE_VERSION_MAJOR < 1
> -/**
> - * swscale wrapper, so we don't need to export the SwsContext.
> - */
>  int sws_scale_ordered(SwsContext *c, uint8_t* src[], int srcStride[], int srcSliceY,
>                        int srcSliceH, uint8_t* dst[], int dstStride[]){
>      return sws_scale(c, src, srcStride, srcSliceY, srcSliceH, dst, dstStride);

ok


> Index: ffmpeg/libswscale/swscale.c
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.c	2009-02-10 00:45:12.000000000 +0100
> +++ ffmpeg/libswscale/swscale.c	2009-02-10 00:45:25.000000000 +0100
> @@ -3165,16 +3165,6 @@
>      av_free(c);
>  }
>  
> -/**
> - * Checks if context is valid or reallocs a new one instead.
> - * If context is NULL, just calls sws_getContext() to get a new one.
> - * Otherwise, checks if the parameters are the ones already saved in context.
> - * If that is the case, returns the current context.
> - * Otherwise, frees context and gets a new one.
> - *
> - * Be warned that srcFilter, dstFilter are not checked, they are
> - * asumed to remain valid.
> - */
>  struct SwsContext *sws_getCachedContext(struct SwsContext *context,
>                                          int srcW, int srcH, enum PixelFormat srcFormat,
>                                          int dstW, int dstH, enum PixelFormat dstFormat, int flags,
> Index: ffmpeg/libswscale/swscale.h
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.h	2009-02-10 00:45:12.000000000 +0100
> +++ ffmpeg/libswscale/swscale.h	2009-02-10 00:45:33.000000000 +0100
> @@ -149,6 +149,16 @@
>                                  int verbose);
>  void sws_freeFilter(SwsFilter *filter);
>  
> +/**
> + * Checks if context is valid or reallocs a new one instead.
> + * If context is NULL, just calls sws_getContext() to get a new one.
> + * Otherwise, checks if the parameters are the ones already saved in context.
> + * If that is the case, returns the current context.
> + * Otherwise, frees context and gets a new one.
> + *
> + * Be warned that srcFilter, dstFilter are not checked, they are
> + * asumed to remain valid.
> + */
>  struct SwsContext *sws_getCachedContext(struct SwsContext *context,
>                                          int srcW, int srcH, enum PixelFormat srcFormat,
>                                          int dstW, int dstH, enum PixelFormat dstFormat, int flags,

ok


[...]
> Index: ffmpeg/libswscale/swscale.h
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.h	2009-02-10 01:09:42.000000000 +0100
> +++ ffmpeg/libswscale/swscale.h	2009-02-10 01:11:45.000000000 +0100
> @@ -130,6 +130,11 @@
>  int sws_setColorspaceDetails(struct SwsContext *c, const int inv_table[4], int srcRange, const int table[4], int dstRange, int brightness, int contrast, int saturation);
>  int sws_getColorspaceDetails(struct SwsContext *c, int **inv_table, int *srcRange, int **table, int *dstRange, int *brightness, int *contrast, int *saturation);
>  SwsVector *sws_getGaussianVec(double variance, double quality);
> +
> +/**
> + * Allocates and returns a vector with \p lenght coefficients, all
> + * with the same value \p c.
> + */
>  SwsVector *sws_getConstVec(double c, int length);
>  SwsVector *sws_getIdentityVec(void);
>  void sws_scaleVec(SwsVector *a, double scalar);

ok


> Index: ffmpeg/libswscale/swscale.h
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.h	2009-02-10 01:11:45.000000000 +0100
> +++ ffmpeg/libswscale/swscale.h	2009-02-10 01:12:45.000000000 +0100
> @@ -136,6 +136,11 @@
>   * with the same value \p c.
>   */
>  SwsVector *sws_getConstVec(double c, int length);
> +
> +/**
> + * Allocates and returns a vector with just one coefficient set to
> + * 1.0.
> + */
>  SwsVector *sws_getIdentityVec(void);
>  void sws_scaleVec(SwsVector *a, double scalar);
>  void sws_normalizeVec(SwsVector *a, double height);

how many coeffs does this vector have?


> Index: ffmpeg/libswscale/swscale.h
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.h	2009-02-10 00:54:54.000000000 +0100
> +++ ffmpeg/libswscale/swscale.h	2009-02-10 01:08:42.000000000 +0100
> @@ -141,6 +141,10 @@
>   * Gets a vector with just one coefficient set to 1.0.
>   */
>  SwsVector *sws_getIdentityVec(void);
> +
> +/**
> + * Scales all the coefficients of \p a by the \p scalar value.
> + */
>  void sws_scaleVec(SwsVector *a, double scalar);
>  void sws_normalizeVec(SwsVector *a, double height);
>  void sws_convVec(SwsVector *a, SwsVector *b);

ok


> Index: ffmpeg/libswscale/swscale.h
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.h	2009-02-10 01:13:23.000000000 +0100
> +++ ffmpeg/libswscale/swscale.h	2009-02-10 01:14:14.000000000 +0100
> @@ -152,6 +152,11 @@
>  void sws_addVec(SwsVector *a, SwsVector *b);
>  void sws_subVec(SwsVector *a, SwsVector *b);
>  void sws_shiftVec(SwsVector *a, int shift);
> +
> +/**
> + * Allocates and returns a clone of the vector \p a, that is a vector
> + * with the same coefficients as \p a.
> + */
>  SwsVector *sws_cloneVec(SwsVector *a);
>  
>  void sws_printVec(SwsVector *a);

ok


> Index: ffmpeg/libswscale/swscale.h
> ===================================================================
> --- ffmpeg.orig/libswscale/swscale.h	2009-02-10 01:14:14.000000000 +0100
> +++ ffmpeg/libswscale/swscale.h	2009-02-10 01:17:18.000000000 +0100
> @@ -159,6 +159,10 @@
>   */
>  SwsVector *sws_cloneVec(SwsVector *a);
>  
> +/**
> + * Prints with av_log() a textual representation of the vector \p a if
> + * av_log_level >= AV_LOG_DEBUG.
> + */
>  void sws_printVec(SwsVector *a);
>  void sws_freeVec(SwsVector *a);
>  

:/ i dont like what this function does ...
it should at least take a level & context

[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

I hate to see young programmers poisoned by the kind of thinking
Ulrich Drepper puts forward since it is simply too narrow -- Roman Shaposhnik
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20090210/d285a7bf/attachment.pgp>



More information about the ffmpeg-devel mailing list