diff options
| author | Aaron Plattner <aplattner@nvidia.com> | 2014-11-20 13:25:05 -0800 |
|---|---|---|
| committer | Aaron Plattner <aplattner@nvidia.com> | 2014-12-08 21:05:59 -0800 |
| commit | 3e191f7d4524a077adce5e54742347ffa49fee24 (patch) | |
| tree | d66e89300adf455dbb4c03c3dc32bd7e01a5f0a0 | |
| parent | 3162456bb876ffe4bd606968071857e87226d76f (diff) | |
vdpau.h: define a more strict ABI policy
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@nvidia.com>
Reviewed-by: Christian König <christian.koenig@amd.com>
| -rw-r--r-- | include/vdpau/vdpau.h | 23 |
1 files changed, 19 insertions, 4 deletions
diff --git a/include/vdpau/vdpau.h b/include/vdpau/vdpau.h index 4444de3..41bdf2d 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 * |