[Libva] [PATCH 1/3] API: add vaQuerySurfaceAttributes().

[Gwenole Beauchesne]

vaQuerySurfaceAttributes() is the recommended way to query the driver for
all surface attributes that are supported by the underlying hardware. This
is more useful than guessing the attribute values and testing them through
vaGetSurfaceAttributes().

The older vaGetSurfaceAttributes() function is hereby removed. However, the
relevant VA driver hook is kept for now, and will be removed/replaced for a
future update.

Signed-off-by: Gwenole Beauchesne <gwenole.beauchesne at intel.com>
---
 va/va.c         |   10 +++++-----
 va/va.h         |   41 ++++++++++++++++++++++++++---------------
 va/va_backend.h |    9 +++++++++
 3 files changed, 40 insertions(+), 20 deletions(-)

diff --git a/va/va.c b/va/va.c
index 0644ba6..cfe2997 100644
--- a/va/va.c
+++ b/va/va.c
@@ -676,11 +676,11 @@ VAStatus vaQueryConfigAttributes (
 }
 
 VAStatus
-vaGetSurfaceAttributes(
+vaQuerySurfaceAttributes(
     VADisplay           dpy,
     VAConfigID          config,
     VASurfaceAttrib    *attrib_list,
-    unsigned int        num_attribs
+    unsigned int       *num_attribs
 )
 {
     VADriverContextP ctx;
@@ -691,11 +691,11 @@ vaGetSurfaceAttributes(
     if (!ctx)
         return VA_STATUS_ERROR_INVALID_DISPLAY;
 
-    if (!ctx->vtable->vaGetSurfaceAttributes)
+    if (!ctx->vtable->vaQuerySurfaceAttributes)
         return VA_STATUS_ERROR_UNIMPLEMENTED;
 
-    vaStatus = ctx->vtable->vaGetSurfaceAttributes(ctx, config,
-                                                   attrib_list, num_attribs);
+    vaStatus = ctx->vtable->vaQuerySurfaceAttributes(ctx, config,
+        attrib_list, num_attribs);
     return vaStatus;
 }
 
diff --git a/va/va.h b/va/va.h
index 990addb..ec3f973 100644
--- a/va/va.h
+++ b/va/va.h
@@ -763,37 +763,48 @@ typedef struct _VASurfaceAttribExternalBuffers {
 /**@}*/
 
 /**
- * \brief Get surface attributes for the supplied config.
+ * \brief Queries surface attributes for the supplied config.
  *
- * This function retrieves the surface attributes matching the supplied
- * config. The caller shall provide an \c attrib_list with all attributes
- * to be retrieved. Upon successful return, the attributes in \c attrib_list
- * are updated with the requested value. Unknown attributes or attributes
- * that are not supported for the given config will have their \c flags
- * field set to \c VA_SURFACE_ATTRIB_NOT_SUPPORTED.
+ * Unlike vaGetSurfaceAttributes(), this function queries for all
+ * supported attributes for the supplied VA @config. In particular, if
+ * the underlying hardware supports the creation of VA surfaces in
+ * various formats, then this function will enumerate all pixel
+ * formats that are supported.
+ *
+ * The \c attrib_list array is allocated by the user and \c
+ * num_attribs shall be initialized to the number of allocated
+ * elements in that array. Upon successful return, the actual number
+ * of attributes will be overwritten into \c num_attribs. Otherwise,
+ * \c VA_STATUS_ERROR_MAX_NUM_EXCEEDED is returned and \c num_attribs
+ * is adjusted to the number of elements that would be returned if
+ * enough space was available.
+ *
+ * Note: it is perfectly valid to pass NULL to the \c attrib_list
+ * argument when vaQuerySurfaceAttributes() is used to determine the
+ * actual number of elements that need to be allocated.
  *
  * @param[in] dpy               the VA display
  * @param[in] config            the config identifying a codec or a video
  *     processing pipeline
- * @param[in,out] attrib_list   the list of attributes on input, with at
- *     least \c type fields filled in, and possibly \c value fields whenever
- *     necessary. The updated list of attributes and flags on output
- * @param[in] num_attribs       the number of attributes supplied in the
- *     \c attrib_list array
+ * @param[out] attrib_list      the output array of #VASurfaceAttrib elements
+ * @param[in,out] num_attribs   the number of elements allocated on
+ *      input, the number of elements actually filled in output
  */
 VAStatus
-vaGetSurfaceAttributes(
+vaQuerySurfaceAttributes(
     VADisplay           dpy,
     VAConfigID          config,
     VASurfaceAttrib    *attrib_list,
-    unsigned int        num_attribs
+    unsigned int       *num_attribs
 );
 
 /**
  * \brief Creates an array of surfaces
  *
  * Creates an array of surfaces. The optional list of attributes shall
- * be constructed and verified through vaGetSurfaceAttributes().
+ * be constructed and validated through vaGetSurfaceAttributes() or
+ * constructed based based on what the underlying hardware could
+ * expose through vaQuerySurfaceAttributes().
  *
  * @param[in] dpy               the VA display
  * @param[in] format            the desired surface format. See \c VA_RT_FORMAT_*
diff --git a/va/va_backend.h b/va/va_backend.h
index 2d7cfc7..875ea34 100644
--- a/va/va_backend.h
+++ b/va/va_backend.h
@@ -392,6 +392,7 @@ struct VADriverVTable
                 VASurfaceID surface
         );
 
+        /* DEPRECATED */
         VAStatus
         (*vaGetSurfaceAttributes)(
             VADriverContextP    dpy,
@@ -411,6 +412,14 @@ struct VADriverVTable
             VASurfaceAttrib    *attrib_list,
             unsigned int        num_attribs
         );
+
+        VAStatus
+        (*vaQuerySurfaceAttributes)(
+            VADriverContextP    dpy,
+            VAConfigID          config,
+            VASurfaceAttrib    *attrib_list,
+            unsigned int       *num_attribs
+        );
 };
 
 struct VADriverContext
-- 
1.7.9.5