[VDPAU] [PATCH] vdpau.h: define a more strict ABI policy

[Aaron Plattner]

Because structures defined in vdpau.h may be used outside of the libvdpau
interface itself, it's important for them to not change, even to add new fields
to the end.  Clarify this by tightening the restriction on how structures can be
modified.

This means that we can also *relax* the restriction on versioned structures that
says that they can only be extended by adding fields to the end.  As long as
uint32_t struct_version is the first field of the structure, the implementation
can look at that to determine the complete layout of the rest of the fields.

Signed-off-by: Aaron Plattner <aplattner at nvidia.com>
---
There was some discussion recently about whether or not it's acceptable to
extend existing structures by adding fields to the end.  There was some debate
within NVIDIA about this and the conclusion we reached was that the size of each
structure should be included as part of the ABI.  This change attempts to
describe that and provide guidelines about how existing structures should be
extended.

 include/vdpau/vdpau.h | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/include/vdpau/vdpau.h b/include/vdpau/vdpau.h
index 4444de35b876..41bdf2d75325 100644
--- a/include/vdpau/vdpau.h
+++ b/include/vdpau/vdpau.h
@@ -707,10 +707,25 @@
  *
  * A few structures are considered plausible candidates for future extension.
  * Such structures include a version number as the first field, indicating the
- * exact layout of the client-provided data. Such structures may only be
- * modified by adding new fields to the end of the structure, so that the
- * original structure definition is completely compatible with a leading
- * subset of fields of the extended structure.
+ * exact layout of the client-provided data. When changing such structures, the
+ * old structure must be preserved and a new structure created. This allows
+ * applications built against the old version of the structure to continue to
+ * interoperate. For example, to extend the VdpProcamp structure, define a new
+ * VdpProcamp1 and update VdpGenerateCSCMatrix to take the new structure as an
+ * argument. Document in a comment that the caller must fill the struct_version
+ * field with the value 1. VDPAU implementations should use the struct_version
+ * field to determine which version of the structure the application was built
+ * against.  Note that you cannot simply increment the value of
+ * VDP_PROCAMP_VERSION because applications recompiled against a newer version
+ * of vdpau.h but that have not been updated to use the new structure must still
+ * report that they're using version 0.
+ *
+ * Note that the layouts of VdpPictureInfo structures are defined by their
+ * corresponding VdpDecoderProfile numbers, so no struct_version field is
+ * needed for them. This layout includes the size of the structure, so new
+ * profiles that extend existing functionality may incorporate the old
+ * VdpPictureInfo as a substructure, but may not modify existing VdpPictureInfo
+ * structures.
  *
  * \subsection extend_functions Functions
  *
-- 
2.1.3