st/vdpau: Add documentation from the VDPAU API and update some traces

Signed-off-by: Emeric Grange <[email protected]>
Reviewed-by: Christian König <[email protected]>

10 files changed, 235 insertions, 20 deletions

diff --git a/src/gallium/state_trackers/vdpau/bitmap.c b/src/gallium/state_trackers/vdpau/bitmap.c
index 730cc11cb82..8c7dbe529e8 100644
--- a/src/gallium/state_trackers/vdpau/bitmap.c
+++ b/src/gallium/state_trackers/vdpau/bitmap.c
@@ -29,6 +29,9 @@
 
 #include "vdpau_private.h"
 
+/**
+ * Create a VdpBitmapSurface.
+ */
 VdpStatus
 vlVdpBitmapSurfaceCreate(VdpDevice device,
                          VdpRGBAFormat rgba_format,
@@ -43,12 +46,18 @@ vlVdpBitmapSurfaceCreate(VdpDevice device,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Destroy a VdpBitmapSurface.
+ */
 VdpStatus
 vlVdpBitmapSurfaceDestroy(VdpBitmapSurface surface)
 {
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Retrieve the parameters used to create a VdpBitmapSurface.
+ */
 VdpStatus
 vlVdpBitmapSurfaceGetParameters(VdpBitmapSurface surface,
                                 VdpRGBAFormat *rgba_format,
@@ -61,6 +70,10 @@ vlVdpBitmapSurfaceGetParameters(VdpBitmapSurface surface,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Copy image data from application memory in the surface's native format to
+ * a VdpBitmapSurface.
+ */
 VdpStatus
 vlVdpBitmapSurfacePutBitsNative(VdpBitmapSurface surface,
                                 void const *const *source_data,
diff --git a/src/gallium/state_trackers/vdpau/decode.c b/src/gallium/state_trackers/vdpau/decode.c
index 719f8d8d0d4..aacb9ea28dd 100644
--- a/src/gallium/state_trackers/vdpau/decode.c
+++ b/src/gallium/state_trackers/vdpau/decode.c
@@ -31,6 +31,9 @@
 
 #include "vdpau_private.h"
 
+/**
+ * Create a VdpDecoder.
+ */
 VdpStatus
 vlVdpDecoderCreate(VdpDevice device,
                    VdpDecoderProfile profile,
@@ -129,6 +132,9 @@ error_decoder:
    return ret;
 }
 
+/**
+ * Destroy a VdpDecoder.
+ */
 VdpStatus
 vlVdpDecoderDestroy(VdpDecoder decoder)
 {
@@ -154,6 +160,9 @@ vlVdpDecoderDestroy(VdpDecoder decoder)
    return VDP_STATUS_OK;
 }
 
+/**
+ * Retrieve the parameters used to create a VdpBitmapSurface.
+ */
 VdpStatus
 vlVdpDecoderGetParameters(VdpDecoder decoder,
                           VdpDecoderProfile *profile,
@@ -162,7 +171,7 @@ vlVdpDecoderGetParameters(VdpDecoder decoder,
 {
    vlVdpDecoder *vldecoder;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] decoder get parameters called\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Decoder get parameters called\n");
 
    vldecoder = (vlVdpDecoder *)vlGetDataHTAB(decoder);
    if (!vldecoder)
@@ -175,6 +184,9 @@ vlVdpDecoderGetParameters(VdpDecoder decoder,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Decode a mpeg 1/2 video.
+ */
 static VdpStatus
 vlVdpDecoderRenderMpeg12(struct pipe_video_decoder *decoder,
                          VdpPictureInfoMPEG1Or2 *picture_info,
@@ -186,7 +198,7 @@ vlVdpDecoderRenderMpeg12(struct pipe_video_decoder *decoder,
    struct pipe_video_buffer *ref_frames[2];
    unsigned i;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Decoding MPEG2\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Decoding MPEG12\n");
 
    i = 0;
 
@@ -242,6 +254,9 @@ vlVdpDecoderRenderMpeg12(struct pipe_video_decoder *decoder,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Decode a compressed field/frame and render the result into a VdpVideoSurface.
+ */
 VdpStatus
 vlVdpDecoderRender(VdpDecoder decoder,
                    VdpVideoSurface target,
@@ -272,7 +287,7 @@ vlVdpDecoderRender(VdpDecoder decoder,
       // TODO: Recreate decoder with correct chroma
       return VDP_STATUS_INVALID_CHROMA_TYPE;
 
-   // TODO: Right now only mpeg 1 & 2 is supported.
+   // TODO: Right now only mpeg 1 & 2 videos are supported.
    switch (vldecoder->decoder->profile) {
    case PIPE_VIDEO_PROFILE_MPEG1:
    case PIPE_VIDEO_PROFILE_MPEG2_SIMPLE:
diff --git a/src/gallium/state_trackers/vdpau/device.c b/src/gallium/state_trackers/vdpau/device.c
index 77dacf42a1b..cc49bd470df 100644
--- a/src/gallium/state_trackers/vdpau/device.c
+++ b/src/gallium/state_trackers/vdpau/device.c
@@ -34,6 +34,9 @@
 
 #include "vdpau_private.h"
 
+/**
+ * Create a VdpDevice object for use with X11.
+ */
 PUBLIC VdpStatus
 vdp_imp_device_create_x11(Display *display, int screen, VdpDevice *device,
                           VdpGetProcAddress **get_proc_address)
@@ -92,6 +95,9 @@ no_htab:
    return ret;
 }
 
+/**
+ * Create a VdpPresentationQueueTarget for use with X11.
+ */
 PUBLIC VdpStatus
 vlVdpPresentationQueueTargetCreateX11(VdpDevice device, Drawable drawable,
                                       VdpPresentationQueueTarget *target)
@@ -128,6 +134,9 @@ no_handle:
    return ret;
 }
 
+/**
+ * Destroy a VdpPresentationQueueTarget.
+ */
 VdpStatus
 vlVdpPresentationQueueTargetDestroy(VdpPresentationQueueTarget presentation_queue_target)
 {
@@ -145,10 +154,13 @@ vlVdpPresentationQueueTargetDestroy(VdpPresentationQueueTarget presentation_queu
    return VDP_STATUS_OK;
 }
 
+/**
+ * Destroy a VdpDevice.
+ */
 VdpStatus
 vlVdpDeviceDestroy(VdpDevice device)
 {
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Destroying destroy\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Destroying device\n");
 
    vlVdpDevice *dev = vlGetDataHTAB(device);
    if (!dev)
@@ -161,11 +173,14 @@ vlVdpDeviceDestroy(VdpDevice device)
    FREE(dev);
    vlDestroyHTAB();
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Device destroyed succesfully\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Device destroyed successfully\n");
 
    return VDP_STATUS_OK;
 }
 
+/**
+ * Retrieve a VDPAU function pointer.
+ */
 VdpStatus
 vlVdpGetProcAddress(VdpDevice device, VdpFuncId function_id, void **function_pointer)
 {
@@ -186,6 +201,9 @@ vlVdpGetProcAddress(VdpDevice device, VdpFuncId function_id, void **function_poi
 
 #define _ERROR_TYPE(TYPE,STRING) case TYPE: return STRING;
 
+/**
+ * Retrieve a string describing an error code.
+ */
 char const *
 vlVdpGetErrorString (VdpStatus status)
 {
diff --git a/src/gallium/state_trackers/vdpau/mixer.c b/src/gallium/state_trackers/vdpau/mixer.c
index 11baffc1e0a..8728157e8a5 100644
--- a/src/gallium/state_trackers/vdpau/mixer.c
+++ b/src/gallium/state_trackers/vdpau/mixer.c
@@ -34,6 +34,9 @@
 
 #include "vdpau_private.h"
 
+/**
+ * Create a VdpVideoMixer.
+ */
 VdpStatus
 vlVdpVideoMixerCreate(VdpDevice device,
                       uint32_t feature_count,
@@ -84,6 +87,9 @@ no_handle:
    return ret;
 }
 
+/**
+ * Destroy a VdpVideoMixer.
+ */
 VdpStatus
 vlVdpVideoMixerDestroy(VdpVideoMixer mixer)
 {
@@ -102,6 +108,9 @@ vlVdpVideoMixerDestroy(VdpVideoMixer mixer)
    return VDP_STATUS_OK;
 }
 
+/**
+ * Enable or disable features.
+ */
 VdpStatus
 vlVdpVideoMixerSetFeatureEnables(VdpVideoMixer mixer,
                                  uint32_t feature_count,
@@ -124,6 +133,9 @@ vlVdpVideoMixerSetFeatureEnables(VdpVideoMixer mixer,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Perform a video post-processing and compositing operation.
+ */
 VdpStatus vlVdpVideoMixerRender(VdpVideoMixer mixer,
                                 VdpOutputSurface background_surface,
                                 VdpRect const *background_source_rect,
@@ -166,6 +178,9 @@ VdpStatus vlVdpVideoMixerRender(VdpVideoMixer mixer,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Set attribute values.
+ */
 VdpStatus
 vlVdpVideoMixerSetAttributeValues(VdpVideoMixer mixer,
                                   uint32_t attribute_count,
@@ -186,6 +201,9 @@ vlVdpVideoMixerSetAttributeValues(VdpVideoMixer mixer,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Retrieve whether features were requested at creation time.
+ */
 VdpStatus
 vlVdpVideoMixerGetFeatureSupport(VdpVideoMixer mixer,
                                  uint32_t feature_count,
@@ -195,6 +213,9 @@ vlVdpVideoMixerGetFeatureSupport(VdpVideoMixer mixer,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Retrieve whether features are enabled.
+ */
 VdpStatus
 vlVdpVideoMixerGetFeatureEnables(VdpVideoMixer mixer,
                                  uint32_t feature_count,
@@ -204,6 +225,9 @@ vlVdpVideoMixerGetFeatureEnables(VdpVideoMixer mixer,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Retrieve parameter values given at creation time.
+ */
 VdpStatus
 vlVdpVideoMixerGetParameterValues(VdpVideoMixer mixer,
                                   uint32_t parameter_count,
@@ -213,6 +237,9 @@ vlVdpVideoMixerGetParameterValues(VdpVideoMixer mixer,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Retrieve current attribute values.
+ */
 VdpStatus
 vlVdpVideoMixerGetAttributeValues(VdpVideoMixer mixer,
                                   uint32_t attribute_count,
@@ -222,6 +249,9 @@ vlVdpVideoMixerGetAttributeValues(VdpVideoMixer mixer,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Generate a color space conversion matrix.
+ */
 VdpStatus
 vlVdpGenerateCSCMatrix(VdpProcamp *procamp,
                        VdpColorStandard standard,
diff --git a/src/gallium/state_trackers/vdpau/output.c b/src/gallium/state_trackers/vdpau/output.c
index 9392f4856b1..0d2f35a433c 100644
--- a/src/gallium/state_trackers/vdpau/output.c
+++ b/src/gallium/state_trackers/vdpau/output.c
@@ -35,6 +35,9 @@
 
 #include "vdpau_private.h"
 
+/**
+ * Create a VdpOutputSurface.
+ */
 VdpStatus
 vlVdpOutputSurfaceCreate(VdpDevice device,
                          VdpRGBAFormat rgba_format,
@@ -114,6 +117,9 @@ vlVdpOutputSurfaceCreate(VdpDevice device,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Destroy a VdpOutputSurface.
+ */
 VdpStatus
 vlVdpOutputSurfaceDestroy(VdpOutputSurface surface)
 {
@@ -134,6 +140,9 @@ vlVdpOutputSurfaceDestroy(VdpOutputSurface surface)
    return VDP_STATUS_OK;
 }
 
+/**
+ * Retrieve the parameters used to create a VdpOutputSurface.
+ */
 VdpStatus
 vlVdpOutputSurfaceGetParameters(VdpOutputSurface surface,
                                 VdpRGBAFormat *rgba_format,
@@ -141,7 +150,7 @@ vlVdpOutputSurfaceGetParameters(VdpOutputSurface surface,
 {
    vlVdpOutputSurface *vlsurface;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] getting surface parameters\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Getting output surface parameters\n");
         
    vlsurface = vlGetDataHTAB(surface);
    if (!vlsurface)
@@ -154,6 +163,10 @@ vlVdpOutputSurfaceGetParameters(VdpOutputSurface surface,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Copy image data from a VdpOutputSurface to application memory in the
+ * surface's native format.
+ */
 VdpStatus
 vlVdpOutputSurfaceGetBitsNative(VdpOutputSurface surface,
                                 VdpRect const *source_rect,
@@ -163,6 +176,10 @@ vlVdpOutputSurfaceGetBitsNative(VdpOutputSurface surface,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Copy image data from application memory in the surface's native format to
+ * a VdpOutputSurface.
+ */
 VdpStatus
 vlVdpOutputSurfacePutBitsNative(VdpOutputSurface surface,
                                 void const *const *source_data,
@@ -172,6 +189,10 @@ vlVdpOutputSurfacePutBitsNative(VdpOutputSurface surface,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Copy image data from application memory in a specific indexed format to
+ * a VdpOutputSurface.
+ */
 VdpStatus
 vlVdpOutputSurfacePutBitsIndexed(VdpOutputSurface surface,
                                  VdpIndexedFormat source_indexed_format,
@@ -195,7 +216,7 @@ vlVdpOutputSurfacePutBitsIndexed(VdpOutputSurface surface,
    struct pipe_box box;
    struct pipe_video_rect dst_rect;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] uploading indexed output surface\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Uploading indexed output surface\n");
 
    vlsurface = vlGetDataHTAB(surface);
    if (!vlsurface)
@@ -304,6 +325,10 @@ error_resource:
    return VDP_STATUS_RESOURCES;
 }
 
+/**
+ * Copy image data from application memory in a specific YCbCr format to
+ * a VdpOutputSurface.
+ */
 VdpStatus
 vlVdpOutputSurfacePutBitsYCbCr(VdpOutputSurface surface,
                                VdpYCbCrFormat source_ycbcr_format,
@@ -404,6 +429,10 @@ BlenderToPipe(struct pipe_context *context,
    return context->create_blend_state(context, &blend);
 }
 
+/**
+ * Composite a sub-rectangle of a VdpOutputSurface into a sub-rectangle of
+ * another VdpOutputSurface; Output Surface object VdpOutputSurface.
+ */
 VdpStatus
 vlVdpOutputSurfaceRenderOutputSurface(VdpOutputSurface destination_surface,
                                       VdpRect const *destination_rect,
@@ -424,7 +453,7 @@ vlVdpOutputSurfaceRenderOutputSurface(VdpOutputSurface destination_surface,
 
    void *blend;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] composing output surfaces\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Composing output surfaces\n");
 
    dst_vlsurface = vlGetDataHTAB(destination_surface);
    if (!dst_vlsurface)
@@ -454,6 +483,10 @@ vlVdpOutputSurfaceRenderOutputSurface(VdpOutputSurface destination_surface,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Composite a sub-rectangle of a VdpBitmapSurface into a sub-rectangle of
+ * a VdpOutputSurface; Output Surface object VdpOutputSurface.
+ */
 VdpStatus
 vlVdpOutputSurfaceRenderBitmapSurface(VdpOutputSurface destination_surface,
                                       VdpRect const *destination_rect,
diff --git a/src/gallium/state_trackers/vdpau/preemption.c b/src/gallium/state_trackers/vdpau/preemption.c
index 75933c11329..67a3ce663b7 100644
--- a/src/gallium/state_trackers/vdpau/preemption.c
+++ b/src/gallium/state_trackers/vdpau/preemption.c
@@ -27,11 +27,18 @@
 
 #include <vdpau/vdpau.h>
 
+/**
+ * A callback to notify the client application that a device's display has
+ * been preempted.
+ */
 void vlVdpPreemptionCallback(VdpDevice device, void *context)
 {
    /* TODO: Implement preemption */
 }
 
+/**
+ * Configure the display preemption callback.
+ */
 VdpStatus vlVdpPreemptionCallbackRegister(VdpDevice device,
                                           VdpPreemptionCallback callback,
                                           void *context)
diff --git a/src/gallium/state_trackers/vdpau/presentation.c b/src/gallium/state_trackers/vdpau/presentation.c
index ba5a15a3f63..927350ba980 100644
--- a/src/gallium/state_trackers/vdpau/presentation.c
+++ b/src/gallium/state_trackers/vdpau/presentation.c
@@ -34,6 +34,9 @@
 
 #include "vdpau_private.h"
 
+/**
+ * Create a VdpPresentationQueue.
+ */
 VdpStatus
 vlVdpPresentationQueueCreate(VdpDevice device,
                              VdpPresentationQueueTarget presentation_queue_target,
@@ -84,6 +87,9 @@ no_compositor:
    return ret;
 }
 
+/**
+ * Destroy a VdpPresentationQueue.
+ */
 VdpStatus
 vlVdpPresentationQueueDestroy(VdpPresentationQueue presentation_queue)
 {
@@ -103,13 +109,16 @@ vlVdpPresentationQueueDestroy(VdpPresentationQueue presentation_queue)
    return VDP_STATUS_OK;
 }
 
+/**
+ * Configure the background color setting.
+ */
 VdpStatus
 vlVdpPresentationQueueSetBackgroundColor(VdpPresentationQueue presentation_queue,
                                          VdpColor *const background_color)
 {
    vlVdpPresentationQueue *pq;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Setting Background Color\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Setting background color\n");
 
    if (!background_color)
       return VDP_STATUS_INVALID_POINTER;
@@ -123,26 +132,39 @@ vlVdpPresentationQueueSetBackgroundColor(VdpPresentationQueue presentation_queue
    return VDP_STATUS_OK;
 }
 
+/**
+ * Retrieve the current background color setting.
+ */
 VdpStatus
 vlVdpPresentationQueueGetBackgroundColor(VdpPresentationQueue presentation_queue,
                                          VdpColor *const background_color)
 {
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Getting background color\n");
+
    if (!background_color)
       return VDP_STATUS_INVALID_POINTER;
 
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Retrieve the presentation queue's "current" time.
+ */
 VdpStatus
 vlVdpPresentationQueueGetTime(VdpPresentationQueue presentation_queue,
                               VdpTime *current_time)
 {
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Getting queue time\n");
+
    if (!current_time)
       return VDP_STATUS_INVALID_POINTER;
 
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Enter a surface into the presentation queue.
+ */
 VdpStatus
 vlVdpPresentationQueueDisplay(VdpPresentationQueue presentation_queue,
                               VdpOutputSurface surface,
@@ -198,6 +220,9 @@ vlVdpPresentationQueueDisplay(VdpPresentationQueue presentation_queue,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Wait for a surface to finish being displayed.
+ */
 VdpStatus
 vlVdpPresentationQueueBlockUntilSurfaceIdle(VdpPresentationQueue presentation_queue,
                                             VdpOutputSurface surface,
@@ -210,6 +235,9 @@ vlVdpPresentationQueueBlockUntilSurfaceIdle(VdpPresentationQueue presentation_qu
    return VDP_STATUS_OK;
 }
 
+/**
+ * Poll the current queue status of a surface.
+ */
 VdpStatus
 vlVdpPresentationQueueQuerySurfaceStatus(VdpPresentationQueue presentation_queue,
                                          VdpOutputSurface surface,
diff --git a/src/gallium/state_trackers/vdpau/query.c b/src/gallium/state_trackers/vdpau/query.c
index 8cb95ae3338..191e163af8e 100644
--- a/src/gallium/state_trackers/vdpau/query.c
+++ b/src/gallium/state_trackers/vdpau/query.c
@@ -34,7 +34,9 @@
 #include "pipe/p_defines.h"
 #include "util/u_debug.h"
 
-
+/**
+ * Retrieve the VDPAU version implemented by the backend.
+ */
 VdpStatus
 vlVdpGetApiVersion(uint32_t *api_version)
 {
@@ -45,6 +47,10 @@ vlVdpGetApiVersion(uint32_t *api_version)
    return VDP_STATUS_OK;
 }
 
+/**
+ * Retrieve an implementation-specific string description of the implementation.
+ * This typically includes detailed version information.
+ */
 VdpStatus
 vlVdpGetInformationString(char const **information_string)
 {
@@ -55,6 +61,9 @@ vlVdpGetInformationString(char const **information_string)
    return VDP_STATUS_OK;
 }
 
+/**
+ * Query the implementation's VdpVideoSurface capabilities.
+ */
 VdpStatus
 vlVdpVideoSurfaceQueryCapabilities(VdpDevice device, VdpChromaType surface_chroma_type,
                                    VdpBool *is_supported, uint32_t *max_width, uint32_t *max_height)
@@ -63,7 +72,7 @@ vlVdpVideoSurfaceQueryCapabilities(VdpDevice device, VdpChromaType surface_chrom
    struct pipe_screen *pscreen;
    uint32_t max_2d_texture_level;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying video surfaces\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpVideoSurface capabilities\n");
 
    if (!(is_supported && max_width && max_height))
       return VDP_STATUS_INVALID_POINTER;
@@ -91,6 +100,9 @@ vlVdpVideoSurfaceQueryCapabilities(VdpDevice device, VdpChromaType surface_chrom
    return VDP_STATUS_OK;
 }
 
+/**
+ * Query the implementation's VdpVideoSurface GetBits/PutBits capabilities.
+ */
 VdpStatus
 vlVdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities(VdpDevice device, VdpChromaType surface_chroma_type,
                                                   VdpYCbCrFormat bits_ycbcr_format,
@@ -99,7 +111,7 @@ vlVdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities(VdpDevice device, VdpChromaTyp
    vlVdpDevice *dev;
    struct pipe_screen *pscreen;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying get put video surfaces\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpVideoSurface get/put bits YCbCr capabilities\n");
 
    if (!is_supported)
       return VDP_STATUS_INVALID_POINTER;
@@ -122,6 +134,9 @@ vlVdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities(VdpDevice device, VdpChromaTyp
    return VDP_STATUS_OK;
 }
 
+/**
+ * Query the implementation's VdpDecoder capabilities.
+ */
 VdpStatus
 vlVdpDecoderQueryCapabilities(VdpDevice device, VdpDecoderProfile profile,
                               VdpBool *is_supported, uint32_t *max_level, uint32_t *max_macroblocks,
@@ -131,7 +146,7 @@ vlVdpDecoderQueryCapabilities(VdpDevice device, VdpDecoderProfile profile,
    struct pipe_screen *pscreen;
    enum pipe_video_profile p_profile;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying decoder\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpDecoder capabilities\n");
 
    if (!(is_supported && max_level && max_macroblocks && max_width && max_height))
       return VDP_STATUS_INVALID_POINTER;
@@ -166,6 +181,9 @@ vlVdpDecoderQueryCapabilities(VdpDevice device, VdpDecoderProfile profile,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Query the implementation's VdpOutputSurface capabilities.
+ */
 VdpStatus
 vlVdpOutputSurfaceQueryCapabilities(VdpDevice device, VdpRGBAFormat surface_rgba_format,
                                     VdpBool *is_supported, uint32_t *max_width, uint32_t *max_height)
@@ -173,16 +191,20 @@ vlVdpOutputSurfaceQueryCapabilities(VdpDevice device, VdpRGBAFormat surface_rgba
    if (!(is_supported && max_width && max_height))
       return VDP_STATUS_INVALID_POINTER;
 
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying ouput surfaces\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpOutputSurface capabilities\n");
 
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's capability to perform a PutBits operation using
+ * application data matching the surface's format.
+ */
 VdpStatus
 vlVdpOutputSurfaceQueryGetPutBitsNativeCapabilities(VdpDevice device, VdpRGBAFormat surface_rgba_format,
                                                     VdpBool *is_supported)
 {
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying output surfaces get put native cap\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpOutputSurface get/put bits native capabilities\n");
 
    if (!is_supported)
       return VDP_STATUS_INVALID_POINTER;
@@ -190,6 +212,10 @@ vlVdpOutputSurfaceQueryGetPutBitsNativeCapabilities(VdpDevice device, VdpRGBAFor
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's capability to perform a PutBits operation using
+ * application data in a specific indexed format.
+ */
 VdpStatus
 vlVdpOutputSurfaceQueryPutBitsIndexedCapabilities(VdpDevice device,
                                                   VdpRGBAFormat surface_rgba_format,
@@ -197,7 +223,7 @@ vlVdpOutputSurfaceQueryPutBitsIndexedCapabilities(VdpDevice device,
                                                   VdpColorTableFormat color_table_format,
                                                   VdpBool *is_supported)
 {
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying output surfaces get put indexed cap\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpOutputSurface put bits indexed capabilities\n");
 
    if (!is_supported)
       return VDP_STATUS_INVALID_POINTER;
@@ -205,40 +231,56 @@ vlVdpOutputSurfaceQueryPutBitsIndexedCapabilities(VdpDevice device,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's capability to perform a PutBits operation using
+ * application data in a specific YCbCr/YUB format.
+ */
 VdpStatus
 vlVdpOutputSurfaceQueryPutBitsYCbCrCapabilities(VdpDevice device, VdpRGBAFormat surface_rgba_format,
                                                 VdpYCbCrFormat bits_ycbcr_format,
                                                 VdpBool *is_supported)
 {
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying output surfaces put ycrcb cap\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpOutputSurface put bits YCbCr capabilities\n");
+
    if (!is_supported)
       return VDP_STATUS_INVALID_POINTER;
 
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's VdpBitmapSurface capabilities.
+ */
 VdpStatus
 vlVdpBitmapSurfaceQueryCapabilities(VdpDevice device, VdpRGBAFormat surface_rgba_format,
                                     VdpBool *is_supported, uint32_t *max_width, uint32_t *max_height)
 {
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying bitmap surfaces\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpBitmapSurface capabilities\n");
+
    if (!(is_supported && max_width && max_height))
       return VDP_STATUS_INVALID_POINTER;
 
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's support for a specific feature.
+ */
 VdpStatus
 vlVdpVideoMixerQueryFeatureSupport(VdpDevice device, VdpVideoMixerFeature feature,
                                    VdpBool *is_supported)
 {
-   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying mixer feature support\n");
+   VDPAU_MSG(VDPAU_TRACE, "[VDPAU] Querying VdpVideoMixer feature support\n");
+
    if (!is_supported)
       return VDP_STATUS_INVALID_POINTER;
 
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's support for a specific parameter.
+ */
 VdpStatus
 vlVdpVideoMixerQueryParameterSupport(VdpDevice device, VdpVideoMixerParameter parameter,
                                      VdpBool *is_supported)
@@ -249,6 +291,9 @@ vlVdpVideoMixerQueryParameterSupport(VdpDevice device, VdpVideoMixerParameter pa
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's supported for a specific parameter.
+ */
 VdpStatus
 vlVdpVideoMixerQueryParameterValueRange(VdpDevice device, VdpVideoMixerParameter parameter,
                                         void *min_value, void *max_value)
@@ -259,6 +304,9 @@ vlVdpVideoMixerQueryParameterValueRange(VdpDevice device, VdpVideoMixerParameter
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's support for a specific attribute.
+ */
 VdpStatus
 vlVdpVideoMixerQueryAttributeSupport(VdpDevice device, VdpVideoMixerAttribute attribute,
                                      VdpBool *is_supported)
@@ -269,6 +317,9 @@ vlVdpVideoMixerQueryAttributeSupport(VdpDevice device, VdpVideoMixerAttribute at
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Query the implementation's supported for a specific attribute.
+ */
 VdpStatus
 vlVdpVideoMixerQueryAttributeValueRange(VdpDevice device, VdpVideoMixerAttribute attribute,
                                         void *min_value, void *max_value)
diff --git a/src/gallium/state_trackers/vdpau/surface.c b/src/gallium/state_trackers/vdpau/surface.c
index 4f73c40a06b..77503cfff49 100644
--- a/src/gallium/state_trackers/vdpau/surface.c
+++ b/src/gallium/state_trackers/vdpau/surface.c
@@ -36,6 +36,9 @@
 
 #include "vdpau_private.h"
 
+/**
+ * Create a VdpVideoSurface.
+ */
 VdpStatus
 vlVdpVideoSurfaceCreate(VdpDevice device, VdpChromaType chroma_type,
                         uint32_t width, uint32_t height,
@@ -97,6 +100,9 @@ inv_size:
    return ret;
 }
 
+/**
+ * Destroy a VdpVideoSurface.
+ */
 VdpStatus
 vlVdpVideoSurfaceDestroy(VdpVideoSurface surface)
 {
@@ -113,6 +119,9 @@ vlVdpVideoSurfaceDestroy(VdpVideoSurface surface)
    return VDP_STATUS_OK;
 }
 
+/**
+ * Retrieve the parameters used to create a VdpVideoSurface.
+ */
 VdpStatus
 vlVdpVideoSurfaceGetParameters(VdpVideoSurface surface,
                                VdpChromaType *chroma_type,
@@ -132,6 +141,10 @@ vlVdpVideoSurfaceGetParameters(VdpVideoSurface surface,
    return VDP_STATUS_OK;
 }
 
+/**
+ * Copy image data from a VdpVideoSurface to application memory in a specified
+ * YCbCr format.
+ */
 VdpStatus
 vlVdpVideoSurfaceGetBitsYCbCr(VdpVideoSurface surface,
                               VdpYCbCrFormat destination_ycbcr_format,
@@ -152,6 +165,10 @@ vlVdpVideoSurfaceGetBitsYCbCr(VdpVideoSurface surface,
    return VDP_STATUS_NO_IMPLEMENTATION;
 }
 
+/**
+ * Copy image data from application memory in a specific YCbCr format to
+ * a VdpVideoSurface.
+ */
 VdpStatus
 vlVdpVideoSurfacePutBitsYCbCr(VdpVideoSurface surface,
                               VdpYCbCrFormat source_ycbcr_format,
diff --git a/src/gallium/state_trackers/vdpau/vdpau_private.h b/src/gallium/state_trackers/vdpau/vdpau_private.h
index c43fdfdac9b..68c3840f041 100644
--- a/src/gallium/state_trackers/vdpau/vdpau_private.h
+++ b/src/gallium/state_trackers/vdpau/vdpau_private.h
@@ -41,6 +41,9 @@
 
 #include "vl_winsys.h"
 
+/* Full VDPAU API documentation available at :
+ * ftp://download.nvidia.com/XFree86/vdpau/doxygen/html/index.html */
+
 #define INFORMATION G3DVL VDPAU Driver Shared Library version VER_MAJOR.VER_MINOR
 #define QUOTEME(x) #x
 #define TOSTRING(x) QUOTEME(x)
@@ -119,7 +122,7 @@ PipeToFormatYCBCR(enum pipe_format p_format)
       //case PIPE_FORMAT_YUVA:
         // return VDP_YCBCR_FORMAT_Y8U8V8A8;
       case PIPE_FORMAT_VUYA:
-	 return VDP_YCBCR_FORMAT_V8U8Y8A8;
+         return VDP_YCBCR_FORMAT_V8U8Y8A8;
       default:
          assert(0);
    }