[FFmpeg-devel] On obfuscated nature of public(!) API call av_dup_packet()

[Andrey Utkin]

At first, this function has uncomprehendable doc comment at
declaration, which states "something scary", but neither prohibits its
free usage, nor explains for which cases it is usable.
/**
 * @warning This is a hack - the packet memory allocation stuff is broken. The
 * packet is allocated if it was not really allocated.
 */
int av_dup_packet(AVPacket *pkt);

It gets unclear if AVPacket duplication is possible at all, or it is
very-very forbidden. Some users make up their own packet copying
function.

Ok, doc is poor - that happens. Let's check the function itself, maybe
it'll get clear how it works.
(I won't cite that code here.)
But there things are obscure, too.

First surprising thing is that duplication means copying, but there's
a single parameter: AVPacket *pkt, not two for 'source' and
'destination' as usual logics assume.
I can only guess that i can use it so
AVPacket *dup = av_mallocz(sizeof(AVPacket));
memcpy(dup, pkt, sizeof(AVPacket));
av_dup_packet(dup);
But i find this not obvious, especially for novice.

Then, first line of actual code in function checks 'destruct' function
pointer against two values - NULL (default after av_init_packet()) and
av_destruct_packet_nofree, and if one of them matches, then actions
are taken. Which other cases are possible, and why they are omitted,
is not clear to me. Why copying does not take place if destruct ==
av_destruct_packet, which is true for packets produced by
av_new_packet() and av_dup_packet()?

P. S. I work with ffmpeg and its API for more than year, and it's pity
to find places that I am "not intended to understand" :)

-- 
Andrey Utkin