diff --git a/ChangeLog b/ChangeLog index a96b1557..67bec6ca 100644 --- a/ChangeLog +++ b/ChangeLog @@ -24,6 +24,7 @@ - move im_spatres() to almostdeprecated - done gtk-doc for other - --vips-progress tells you about nthreads, tile size, nlines +- gtk-doc for interpolate 30/11/10 started 7.24.0 - bump for new stable diff --git a/doc/reference/libvips-docs.sgml.in b/doc/reference/libvips-docs.sgml.in index ec7ff4c3..af3ff48d 100644 --- a/doc/reference/libvips-docs.sgml.in +++ b/doc/reference/libvips-docs.sgml.in @@ -42,6 +42,7 @@ + @@ -53,7 +54,6 @@ - diff --git a/libvips/include/vips/internal.h b/libvips/include/vips/internal.h index b2ad6730..de92c3b3 100644 --- a/libvips/include/vips/internal.h +++ b/libvips/include/vips/internal.h @@ -284,6 +284,10 @@ PEL *im__vector_to_ink( const char *domain, IMAGE *im, int n, double *vec ); IMAGE *im__inplace_base( const char *domain, IMAGE *main, IMAGE *sub, IMAGE *out ); +/* Register base vips interpolators, called during startup. + */ +void vips__interpolate_init( void ); + #ifdef __cplusplus } #endif /*__cplusplus*/ diff --git a/libvips/include/vips/interpolate.h b/libvips/include/vips/interpolate.h index 62116ef8..f202df9a 100644 --- a/libvips/include/vips/interpolate.h +++ b/libvips/include/vips/interpolate.h @@ -60,7 +60,7 @@ typedef struct _VipsInterpolate { * function for it to speed up dispatch. Write to the memory at "out", * interpolate the value at position (x, y) in "in". */ -typedef void (*VipsInterpolateMethod)( VipsInterpolate *, +typedef void (*VipsInterpolateMethod)( VipsInterpolate *interpolate, PEL *out, REGION *in, double x, double y ); typedef struct _VipsInterpolateClass { @@ -89,7 +89,7 @@ typedef struct _VipsInterpolateClass { GType vips_interpolate_get_type( void ); void vips_interpolate( VipsInterpolate *interpolate, PEL *out, REGION *in, double x, double y ); -VipsInterpolateMethod vips_interpolate_get_method( VipsInterpolate * ); +VipsInterpolateMethod vips_interpolate_get_method( VipsInterpolate *interpolate ); int vips_interpolate_get_window_size( VipsInterpolate *interpolate ); int vips_interpolate_get_window_offset( VipsInterpolate *interpolate ); @@ -111,17 +111,12 @@ int vips_interpolate_get_window_offset( VipsInterpolate *interpolate ); */ VipsInterpolate *vips_interpolate_nearest_static( void ); VipsInterpolate *vips_interpolate_bilinear_static( void ); -VipsInterpolate *vips_interpolate_bicubic_static( void ); /* Convenience: make an interpolator from a nickname. g_object_unref() when * you're done with it. */ VipsInterpolate *vips_interpolate_new( const char *nickname ); -/* Register base vips types, called during startup. - */ -void vips__interpolate_init( void ); - #ifdef __cplusplus } #endif /*__cplusplus*/ diff --git a/libvips/resample/interpolate.c b/libvips/resample/interpolate.c index f2d4f6b6..72dee26c 100644 --- a/libvips/resample/interpolate.c +++ b/libvips/resample/interpolate.c @@ -12,6 +12,8 @@ * (thanks Nicolas Robidoux) * 12/1/11 * - faster, more accuarate uchar bilinear (thanks Nicolas) + * 2/2/11 + * - gtk-doc */ /* @@ -71,6 +73,59 @@ G_DEFINE_ABSTRACT_TYPE( VipsInterpolate, vips_interpolate, VIPS_TYPE_OBJECT ); +/** + * VipsInterpolateMethod: + * @interpolate: the interpolator + * @out: write the interpolated pixel here + * @in: read source pixels from here + * @x: interpolate value at this position + * @y: interpolate value at this position + * + * An interpolation function. It should read source pixels from @in with + * IM_REGION_ADDR(), it can look left and up from (x, y) by @window_offset + * pixels and it can access pixels in a window of size @window_size. + * + * The interpolated value should be written to the pixel pointed to by @out. + * + * See also: #VipsInterpolateClass. + */ + +/** + * VipsInterpolateClass: + * @interpolate: the interpolation method + * @get_window_size: return the size of the window needed by this method + * @window_size: or just set this for a constant window size + * @get_window_offset: return the window offset for this method + * @window_offset: or just set this for a constant window offset + * + * The abstract base class for the various VIPS interpolation functions. + * Use "vips --list classes" to see all the interpolators available. + * + * An interpolator consists of a function to perform the interpolation, plus + * some extra data fields which tell vips how to call the function and what + * data it needs. + * + * @window_size is the size of the window that the interpolator needs. For + * example, a bicubic interpolator needs to see a window of 4x4 pixels to be + * able to interpolate a value. + * + * You can either have a function in @get_window_size which returns the window + * that a specific interpolator needs, or you can leave @get_window_size %NULL + * and set a constant value in @window_size. + * + * @window_offset is how much to offset the window up and left of (x, y). For + * example, a bicubic interpolator will want a @window_offset of 1. + * + * You can either have a function in @get_window_offset which returns the + * offset that a specific interpolator needs, or you can leave + * @get_window_offset %NULL and set a constant value in @window_offset. + * + * You also need to set @nickname and @description in #VipsObject. + * + * See also: #VipsInterpolateMethod, #VipsObject, + * vips_interpolate_bilinear_static(). + */ + #ifdef DEBUG static void vips_interpolate_finalize( GObject *gobject ) @@ -138,8 +193,19 @@ vips_interpolate_init( VipsInterpolate *interpolate ) #endif /*DEBUG*/ } -/* Set the point out_x, out_y in REGION out to be the point interpolated at - * in_x, in_y in REGION in. Don't do this as a signal for speed. +/** + * vips_interpolate: + * @interpolate: interpolator to use + * @out: write result here + * @in: read source data from here + * @x: interpolate value at this position + * @y: interpolate value at this position + * + * Look up the @interpolate method in the class and call it. Use + * vips_interpolate_get_method() to get a direct pointer to the function and + * avoid the lookup overhead. + * + * You need to set @in and @out up correctly. */ void vips_interpolate( VipsInterpolate *interpolate, @@ -152,8 +218,14 @@ vips_interpolate( VipsInterpolate *interpolate, class->interpolate( interpolate, out, in, x, y ); } -/* As above, but return the function pointer. Use this to cache method - * dispatch. +/** + * vips_interpolate_get_method: + * @interpolate: interpolator to use + * + * Look up the @interpolate method in the class and return it. Use this + * instead of vips_interpolate() to cache method dispatch. + * + * Returns: a pointer to the interpolation function */ VipsInterpolateMethod vips_interpolate_get_method( VipsInterpolate *interpolate ) @@ -165,7 +237,13 @@ vips_interpolate_get_method( VipsInterpolate *interpolate ) return( class->interpolate ); } -/* Get this interpolator's required window size. +/** + * vips_interpolate_get_window_size: + * @interpolate: interpolator to use + * + * Look up an interpolators desired window size. + * + * Returns: the interpolators required window size */ int vips_interpolate_get_window_size( VipsInterpolate *interpolate ) @@ -177,7 +255,13 @@ vips_interpolate_get_window_size( VipsInterpolate *interpolate ) return( class->get_window_size( interpolate ) ); } -/* Get this interpolator's required window offset. +/** + * vips_interpolate_get_window_offset: + * @interpolate: interpolator to use + * + * Look up an interpolators desired window offset. + * + * Returns: the interpolators required window offset */ int vips_interpolate_get_window_offset( VipsInterpolate *interpolate ) @@ -189,6 +273,32 @@ vips_interpolate_get_window_offset( VipsInterpolate *interpolate ) return( class->get_window_offset( interpolate ) ); } +/** + * VIPS_TRANSFORM_SHIFT: + * + * Many of the vips interpolators use fixed-point arithmetic for coordinate + * calculation. This is how many bits of precision they use. + */ + +/** + * VIPS_TRANSFORM_SCALE: + * + * #VIPS_TRANSFORM_SHIFT as a multiplicative constant. + */ + +/** + * VIPS_INTERPOLATE_SHIFT: + * + * Many of the vips interpolators use fixed-point arithmetic for value + * calcualtion. This is how many bits of precision they use. + */ + +/** + * VIPS_INTERPOLATE_SCALE: + * + * #VIPS_INTERPOLATE_SHIFT as a multiplicative constant. + */ + /* VipsInterpolateNearest class */ @@ -268,7 +378,13 @@ vips_interpolate_nearest_new( void ) VIPS_TYPE_INTERPOLATE_NEAREST, NULL, NULL, NULL ) ) ); } -/* Convenience: return a static nearest you don't need to free. +/** + * vips_interpolate_nearest_static: + * + * A convenience function that returns a nearest-neighbour interpolator you + * don't need to free. + * + * Returns: a nearest-neighbour interpolator */ VipsInterpolate * vips_interpolate_nearest_static( void ) @@ -432,7 +548,13 @@ vips_interpolate_bilinear_new( void ) VIPS_TYPE_INTERPOLATE_BILINEAR, NULL, NULL, NULL ) ) ); } -/* Convenience: return a static bilinear you don't need to free. +/** + * vips_interpolate_bilinear_static: + * + * A convenience function that returns a bilinear interpolator you + * don't need to free. + * + * Returns: a bilinear interpolator */ VipsInterpolate * vips_interpolate_bilinear_static( void ) @@ -466,7 +588,16 @@ vips__interpolate_init( void ) #endif /*ENABLE_CXX*/ } -/* Make an interpolator from a nickname. +/** + * vips_interpolate_new: + * @nickname: nickname for interpolator + * + * Look up an interpolator from a nickname and make one. You need to free the + * result with g_object_unref() when you're done with it. + * + * See also: vips_type_find(). + * + * Returns: an interpolator, or %NULL on error. */ VipsInterpolate * vips_interpolate_new( const char *nickname )