[Bug 754650] New: Docs for GstVideoFormatUnpack requires clarification

[GStreamer (GNOME Bugzilla)]

https://bugzilla.gnome.org/show_bug.cgi?id=754650

            Bug ID: 754650
           Summary: Docs for GstVideoFormatUnpack requires clarification
    Classification: Platform
           Product: GStreamer
           Version: 1.4.5
                OS: Mac OS
            Status: NEW
          Severity: normal
          Priority: Normal
         Component: documentation
          Assignee: gstreamer-bugs at lists.freedesktop.org
          Reporter: minfrin at sharp.fm
        QA Contact: gstreamer-bugs at lists.freedesktop.org
     GNOME version: ---

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);

-- 
You are receiving this mail because:
You are the QA Contact for the bug.
You are the assignee for the bug.