GNOME Bugzilla – Bug 754650
Docs for GstVideoFormatUnpack requires clarification
Last modified: 2015-09-06 23:23:18 UTC
The docs for the function definition GstVideoFormatUnpack at the URL below state as below: http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gst-plugins-base-libs-gstvideo.html#GstVideoFormatUnpack "Unpacks width pixels from the given planes and strides containing data of format info . The pixels will be unpacked into dest which each component interleaved. dest should at least be big enough to hold width * n_components * size(unpack_format) bytes." This is not complete enough to be useful. - "The pixels will be unpacked into dest which each component interleaved" - this doesn't fully make sense to the person coming to this as a new user, as it doesn't explicitly state what "interleaved" means exactly. From reverse engineering the code it appears that what unpack is actually doing is converting a given format to a format with just a single plane - but it isn't explicitly stated. - "dest should at least be big enough to hold width * n_components * size(unpack_format) bytes." - Nowhere is it stated where n_components comes from. Reverse engineering the code suggests that n_components comes from the format of the original frame, or perhaps the unpack_format of the original frame, but this isn't explicitly stated. "size(unpack_format)" remains undefined. Reverse engineering the code suggests that unpack_format refers to the enum GstVideoFormat, and "sizeof" in this case makes no sense. Could "sizeof" be referring to the "bits" field? Unfortunately existing code ignores the formal definition and hard codes the size to what looks like an arbitrarily chosen worst case scenario in gst-plugins-good/gst/videomixer/videoconvert.c: convert->tmplines[i] = g_malloc (sizeof (guint16) * (width + 8) * 4);
Hope this helps: commit 86a1092e5923805e17ad09a0c7b1aa10197a4b97 Author: Tim-Philipp Müller <tim@centricular.com> Date: Mon Sep 7 00:19:09 2015 +0100 video: improve GstVideoFormatUnpack docs https://bugzilla.gnome.org/show_bug.cgi?id=754650