After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 754650 - Docs for GstVideoFormatUnpack requires clarification
Docs for GstVideoFormatUnpack requires clarification
Status: RESOLVED FIXED
Product: GStreamer
Classification: Platform
Component: documentation
1.4.5
Other Mac OS
: Normal enhancement
: 1.5.91
Assigned To: GStreamer Maintainers
GStreamer Maintainers
Depends on:
Blocks:
 
 
Reported: 2015-09-06 20:35 UTC by minfrin
Modified: 2015-09-06 23:23 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description minfrin 2015-09-06 20:35:09 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);
Comment 1 Tim-Philipp Müller 2015-09-06 23:23:18 UTC
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