import NVIDIA-FreeBSD-x86-190.42
[nvidia.git] / doc / vdpau.h
index 110b3af..a292a81 100755 (executable)
@@ -6,7 +6,7 @@
 /*
  * This copyright notice applies to this header file:
  *
- * Copyright (c) 2008 NVIDIA Corporation
+ * Copyright (c) 2008-2009 NVIDIA Corporation
  *
  * Permission is hereby granted, free of charge, to any person
  * obtaining a copy of this software and associated documentation
@@ -1501,6 +1501,37 @@ typedef uint32_t VdpVideoSurface;
  * creation. Applications are expected to initialize any region
  * that they use, via \ref VdpDecoderRender or \ref
  * VdpVideoSurfacePutBitsYCbCr.
+ *
+ * Note that certain widths/heights are impossible for specific values of
+ * chroma_type. For example, the definition of VDP_CHROMA_TYPE_420 implies
+ * that the width must be even, since each single chroma sample covers two
+ * luma samples horizontally. A similar argument applies to surface heights,
+ * although doubly so, since interlaced pictures must be supported; each
+ * field's height must itself be a multiple of 2. Hence the overall surface's
+ * height must be a multiple of 4.
+ *
+ * Similar rules apply to other chroma_type values.
+ *
+ * Implementations may also impose additional restrictions on the surface
+ * sizes they support, potentially requiring additional rounding of actual
+ * surface sizes.
+ *
+ * In most cases, this is not an issue, since:
+ * - Video streams are encoded as an array of macro-blocks, which typically
+ *   have larger size alignment requirements than video surfaces do.
+ * - APIs such as \ref VdpVideoMixerRender allow specification of a sub-region
+ *   of the surface to read, which allows the padding data to be clipped away.
+ *
+ * However, other APIs such as \ref VdpVideoSurfaceGetBitsYCbCr and
+ * \ref VdpVideoSurfacePutBitsYCbCr do not allow a sub-region to be specified,
+ * and always operate on surface size that was actually allocated, rather
+ * than the surface size that was requested. In this case, applications need
+ * to be aware of the actual surface size, in order to allocate appropriately
+ * sized buffers for the get-/put-bits operations.
+ *
+ * For this reason, applications may need to call
+ * \ref VdpVideoSurfaceGetParameters after creation, in order to retrieve the
+ * actual surface size.
  */
 typedef VdpStatus VdpVideoSurfaceCreate(
     VdpDevice         device,
@@ -2358,6 +2389,26 @@ typedef uint32_t VdpDecoderProfile;
 #define VDP_DECODER_PROFILE_VC1_MAIN                    (VdpDecoderProfile)10
 /** \hideinitializer */
 #define VDP_DECODER_PROFILE_VC1_ADVANCED                (VdpDecoderProfile)11
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_MPEG4_PART2_SP              (VdpDecoderProfile)12
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_MPEG4_PART2_ASP             (VdpDecoderProfile)13
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_DIVX4_QMOBILE               (VdpDecoderProfile)14
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_DIVX4_MOBILE                (VdpDecoderProfile)15
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_DIVX4_HOME_THEATER          (VdpDecoderProfile)16
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_DIVX4_HD_1080P              (VdpDecoderProfile)17
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_DIVX5_QMOBILE               (VdpDecoderProfile)18
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_DIVX5_MOBILE                (VdpDecoderProfile)19
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_DIVX5_HOME_THEATER          (VdpDecoderProfile)20
+/** \hideinitializer */
+#define VDP_DECODER_PROFILE_DIVX5_HD_1080P              (VdpDecoderProfile)21
 
 /** \hideinitializer */
 #define VDP_DECODER_LEVEL_MPEG1_NA 0
@@ -2427,6 +2478,31 @@ typedef uint32_t VdpDecoderProfile;
 /** \hideinitializer */
 #define VDP_DECODER_LEVEL_VC1_ADVANCED_L4 4
 
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_SP_L0 0
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_SP_L1 1
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_SP_L2 2
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_SP_L3 3
+
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L0 0
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L1 1
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L2 2
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L3 3
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L4 4
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_MPEG4_PART2_ASP_L5 5
+
+/** \hideinitializer */
+#define VDP_DECODER_LEVEL_DIVX_NA 0
+
 /**
  * \brief Query the implementation's VdpDecoder capabilities.
  * \param[in] device The device to query.
@@ -2823,6 +2899,75 @@ typedef struct {
     uint8_t pquant;
 } VdpPictureInfoVC1;
 
+/**
+ * \brief Picture parameter information for an MPEG-4 Part 2 picture.
+ *
+ * Note: References to "copy of bitstream field" in the field descriptions
+ * may refer to data literally parsed from the bitstream, or derived from
+ * the bitstream using a mechanism described in the specification.
+ */
+typedef struct {
+    /**
+     * Reference used by B and P frames.
+     * Set to VDP_INVALID_HANDLE when not used.
+     */
+    VdpVideoSurface forward_reference;
+    /**
+     * Reference used by B frames.
+     * Set to VDP_INVALID_HANDLE when not used.
+     */
+    VdpVideoSurface backward_reference;
+
+    /** Copy of the bitstream field. */
+    int32_t trd[2];
+    /** Copy of the bitstream field. */
+    int32_t trb[2];
+    /** Copy of the bitstream field. */
+    uint16_t vop_time_increment_resolution;
+    /** Copy of the bitstream field. */
+    uint8_t vop_coding_type;
+    /** Copy of the bitstream field. */
+    uint8_t vop_fcode_forward;
+    /** Copy of the bitstream field. */
+    uint8_t vop_fcode_backward;
+    /** Copy of the bitstream field. */
+    uint8_t resync_marker_disable;
+    /** Copy of the bitstream field. */
+    uint8_t interlaced;
+    /** Copy of the bitstream field. */
+    uint8_t quant_type;
+    /** Copy of the bitstream field. */
+    uint8_t quarter_sample;
+    /** Copy of the bitstream field. */
+    uint8_t short_video_header;
+    /** Derived from vop_rounding_type bitstream field. */
+    uint8_t rounding_control;
+    /** Copy of the bitstream field. */
+    uint8_t alternate_vertical_scan_flag;
+    /** Copy of the bitstream field. */
+    uint8_t top_field_first;
+    /** Copy of the bitstream field. */
+    uint8_t intra_quantizer_matrix[64];
+    /** Copy of the bitstream field. */
+    uint8_t non_intra_quantizer_matrix[64];
+} VdpPictureInfoMPEG4Part2;
+
+/**
+ * \brief Picture parameter information for a DivX 4 picture.
+ *
+ * Due to similarites between MPEG-4 Part 2 and DivX 4, the picture
+ * parameter structure is re-used.
+ */
+typedef VdpPictureInfoMPEG4Part2 VdpPictureInfoDivX4;
+
+/**
+ * \brief Picture parameter information for a DivX 5 picture.
+ *
+ * Due to similarites between MPEG-4 Part 2 and DivX 5, the picture
+ * parameter structure is re-used.
+ */
+typedef VdpPictureInfoMPEG4Part2 VdpPictureInfoDivX5;
+
 /**
  * \brief Decode a compressed field/frame and render the result
  *        into a \ref VdpVideoSurface "VdpVideoSurface".
@@ -2993,6 +3138,84 @@ typedef uint32_t VdpVideoMixerFeature;
  * keying is performed after scaling and de-interlacing.
  */
 #define VDP_VIDEO_MIXER_FEATURE_LUMA_KEY                     (VdpVideoMixerFeature)5
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * A VDPAU implementation may support multiple scaling algorithms of
+ * differing quality, and may potentially support a different subset
+ * of algorithms on different hardware.
+ *
+ * In some cases, higher quality algorithms may require more resources
+ * (memory size, memory bandwidth, etc.) to operate. Hence, these high
+ * quality algorithms must be explicitly requested and enabled by the client
+ * application. This allows applications operating in a resource-constrained
+ * environment to have some level of control over resource usage.
+ *
+ * Basic scaling is always built into any video mixer, and is known as
+ * level 0. Scaling quality increases beginning with optional level 1,
+ * through optional level 9.
+ *
+ * If an application requests and enables multiple high quality scaling
+ * algorithms, the highest level enabled scaling algorithm will be used.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1      (VdpVideoMixerFeature)11
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L2      (VdpVideoMixerFeature)12
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L3      (VdpVideoMixerFeature)13
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L4      (VdpVideoMixerFeature)14
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L5      (VdpVideoMixerFeature)15
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L6      (VdpVideoMixerFeature)16
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L7      (VdpVideoMixerFeature)17
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L8      (VdpVideoMixerFeature)18
+/**
+ * \hideinitializer
+ * \brief A VdpVideoMixerFeature.
+ *
+ * See \ref VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L1 for details.
+ */
+#define VDP_VIDEO_MIXER_FEATURE_HIGH_QUALITY_SCALING_L9      (VdpVideoMixerFeature)19
 
 /**
  * \brief A VdpVideoMixer creation parameter.