From c3247cea37ea7702703826df6b68a9754f9b8984 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Reinhard=20Ni=C3=9Fl?= Date: Sun, 2 Mar 2008 20:24:27 +0100 Subject: Provide safe and convenient implementations of xine_get_current_frame(). xine_get_current_frame() relies on the caller to provide a sufficiently sized buffer. To calculate the required size of the buffer, one has to call xine_get_current_frame() to retrieve the necessary parameters. But as the image can change between two successive calls one has to pause the stream for consistency. To improve the situation, xine_get_current_frame_s() has been introduced which requires to specify the buffer size when an image is going to be retrieved. Furthermore, it will return the required/used buffer size. In that way, it can prevent copying data into a too small buffer and therefore can be considered safe. For convenience, xine_get_current_frame_alloc() is provided which takes care to allocate a sufficiently sized buffer. This function avoids pausing the stream as the image will be returned in a single call. --- include/xine.h.in | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/xine.h.in b/include/xine.h.in index ceb87780a..979094779 100644 --- a/include/xine.h.in +++ b/include/xine.h.in @@ -418,14 +418,38 @@ int xine_get_param (xine_stream_t *stream, int param) XINE_PROTECTED; * image format can be YUV 4:2:0 or 4:2:2 * will copy the image data into memory that points to * (interleaved for yuv 4:2:2 or planary for 4:2:0) + * + * xine_get_current_frame() requires that must be able + * to hold the image data. Use a NULL pointer to retrieve the + * necessary parameters for calculating the buffer size. Be + * aware that the image can change between two successive calls + * so you better pause the stream. + * + * xine_get_current_frame_s() requires to specify the buffer + * size and it returns the needed / used size. It won't copy + * image data into a too small buffer. + * + * xine_get_current_frame_alloc() takes care of allocating + * a buffer on it's own, so image data can be retrieved by + * a single call without the need to pause the stream. * - * returns 1 on success, 0 failure. + * all functions return 1 on success, 0 failure. */ int xine_get_current_frame (xine_stream_t *stream, int *width, int *height, int *ratio_code, int *format, uint8_t *img) XINE_PROTECTED; +int xine_get_current_frame_s (xine_stream_t *stream, + int *width, int *height, + int *ratio_code, int *format, + uint8_t *img, int *size) XINE_PROTECTED; + +int xine_get_current_frame_alloc (xine_stream_t *stream, + int *width, int *height, + int *ratio_code, int *format, + uint8_t **img, int *size) XINE_PROTECTED; + /* xine image formats */ #define XINE_IMGFMT_YV12 (('2'<<24)|('1'<<16)|('V'<<8)|'Y') #define XINE_IMGFMT_YUY2 (('2'<<24)|('Y'<<16)|('U'<<8)|'Y') -- cgit v1.2.3