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.

1 files changed, 25 insertions, 1 deletions

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 <img> points to
  * (interleaved for yuv 4:2:2 or planary for 4:2:0)
+ * 
+ * xine_get_current_frame() requires that <img> 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')