From 2fe9e460ee0e48101df5d50ab768b8c9225587e0 Mon Sep 17 00:00:00 2001 From: Aaron Plattner Date: Sun, 15 Mar 2009 11:58:32 -0700 Subject: vdpau.h: Document exact bitstream data requirements --- include/vdpau/vdpau.h | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 87 insertions(+), 1 deletion(-) diff --git a/include/vdpau/vdpau.h b/include/vdpau/vdpau.h index 9c2206c..f4840b0 100644 --- a/include/vdpau/vdpau.h +++ b/include/vdpau/vdpau.h @@ -340,7 +340,93 @@ * precise pixel layout is included with the documentation of * each surface type. For example, see \ref * VDP_RGBA_FORMAT_B8G8R8A8. - * + * + * \section video_decoder_usage Video Decoder Usage + * + * VDPAU is a slice-level API. Put another way, VDPAU implementations accept + * "slice" data from the bitstream, and perform all required processing of + * those slices (e.g VLD decoding, IDCT, motion compensation, in-loop + * deblocking, etc.). + * + * The client application is responsible for: + * + * - Extracting the slices from the bitstream (e.g. parsing/demultiplexing + * container formats, scanning the data to determine slice start positions + * and slice sizes). + * - Parsing various bitstream headers/structures (e.g. sequence header, + * sequence parameter set, picture parameter set, entry point structures, + * etc.) Various fields from the parsed header structures needs to be + * provided to VDPAU alongside the slice bitstream in a "picture info" + * structure. + * - Surface management (e.g. H.264 DPB processing, display re-ordering) + * + * It is recommended that applications pass solely the slice data to VDPAU; + * specifically that any header data structures be excluded from the portion + * of the bitstream passed to VDPAU. VDPAU implementations must operate + * correctly if non-slice data is included, at least for formats employing + * start codes to delimit slice data. However, any extra data may need + * to be uploaded to hardware for parsing thus lowering performance, and/or, + * in the worst case, may even overflow internal buffers that are sized solely + * for slice data. + * + * The exact data that should be passed to VDPAU is detailed below for each + * supported format: + * + * \subsection MPEG-1 and MPEG-2 + * + * Include all slices beginning with start codes 0x00000101 through + * 0x000001AF. The slice start code must be included for all slices. + * + * \subsection H.264 + * + * Include all NALs with nal_unit_type of 1 or 5 (coded slice of non-IDR/IDR + * picture respectively). The complete slice start code (including 0x000001 + * prefix) must be included for all slices, even when the prefix is not + * included in the bitstream. + * + * Note that if desired: + * + * - The slice start code prefix may be included in a separate bitstream + * buffer array entry to the actual slice data extracted from the bitstream. + * - Multiple bitstream buffer array entries (e.g. one per slice) may point at + * the same physical data storage for the slice start code prefix. + * + * \subsection VC-1 Simple and Main Profile + * + * VC-1 simple/main profile bitstreams always consist of a single slice per + * picture, and do not use start codes to delimit pictures. Instead, the + * container format must indicate where each picture begins/ends. + * + * As such, no slice start codes should be included in the data passed to + * VDPAU; simply pass in the exact data from the bitstream. + * + * Header information contained in the bitstream should be parsed by the + * application and passed to VDPAU using the "picture info" data structure; + * this header information explicitly must not be included in the bitstream + * data passed to VDPAU for this encoding format. + * + * \subsection VC-1 Advanced Profile + * + * Include all slices beginning with start codes 0x0000010D (frame), + * 0x0000010C (field) or 0x0000010B (slice). The slice start code should be + * included in all cases. + * + * Some VC-1 advanced profile streams do not contain slice start codes; again, + * the container format must indicate where picture data begins and ends. In + * this case, pictures are assumed to be progressive and to contain a single + * slice. It is highly recommended that applications detect this condition, + * and add the missing start codes to the bitstream passed to VDPAU. However, + * VDPAU implementations must allow bitstreams with missing start codes, and + * act as if a 0x0000010D (frame) start code had been present. + * + * Note that pictures containing multiple slices, or interlace streams, must + * contain a complete set of slice start codes in the original bitstream; + * without them, it is not possible to correctly parse and decode the stream. + * + * The bitstream passed to VDPAU should contain all original emulation + * prevention bytes present in the original bitstream; do not remove these + * from the bitstream. + * * \section video_mixer_usage Video Mixer Usage * * \subsection video_surface_content VdpVideoSurface Content -- cgit v1.2.3