From c64dae3e1dd9cdd53a1981209c5c48ace3b941be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= Date: Thu, 25 Feb 2016 17:46:31 +0000 Subject: [PATCH] video: flesh out docs for gst_video_frame_map() --- gst-libs/gst/video/video-frame.c | 39 +++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/gst-libs/gst/video/video-frame.c b/gst-libs/gst/video/video-frame.c index 3e6f70d45d..66e1fa9166 100644 --- a/gst-libs/gst/video/video-frame.c +++ b/gst-libs/gst/video/video-frame.c @@ -186,11 +186,48 @@ invalid_size: * @buffer: the buffer to map * @flags: #GstMapFlags * - * Use @info and @buffer to fill in the values of @frame. + * Use @info and @buffer to fill in the values of @frame. @frame is usually + * allocated on the stack, and you will pass the address to the #GstVideoFrame + * structure allocated on the stack; gst_video_frame_map() will then fill in + * the structures with the various video-specific information you need to access + * the pixels of the video buffer. You can then use accessor macros such as + * GST_VIDEO_FRAME_COMP_DATA(), GST_VIDEO_FRAME_PLANE_DATA(), + * GST_VIDEO_FRAME_COMP_STRIDE(), GST_VIDEO_FRAME_PLANE_STRIDE() etc. + * to get to the pixels. + * + * |[ + * GstVideoFrame vframe; + * ... + * // set RGB pixels to black one at a time + * if (gst_video_frame_map (&vframe, video_info, video_buffer)) { + * guint8 *pixels = GST_VIDEO_FRAME_PLANE_DATA (vframe, 0); + * guint stride = GST_VIDEO_FRAME_PLANE_STRIDE (vframe, 0); + * guint pixel_stride = GST_VIDEO_FRAME_PLANE_PSTRIDE (vframe, 0); + * + * for (h = 0; h < height; ++h) { + * for (w = 0; w < width; ++w) { + * guint8 *pixel = pixels + h * stride + w * pixel_stride; + * + * memset (pixel, 0, pixel_stride); + * } + * } + * } + * ... + * ]| * * All video planes of @buffer will be mapped and the pointers will be set in * @frame->data. * + * The purpose of this function is to make it easy for you to get to the video + * pixels in a generic way, without you having to worry too much about details + * such as whether the video data is allocated in one contiguous memory chunk + * or multiple memory chunks (e.g. one for each plane); or if custom strides + * and custom plane offsets are used or not (as signalled by GstVideoMeta on + * each buffer). This function will just fill the #GstVideoFrame structure + * with the right values and if you use the accessor macros everything will + * just work and you can access the data easily. It also maps the underlying + * memory chunks for you. + * * Returns: %TRUE on success. */ gboolean