[VDPAU] [PATCH] Add a progressive frame flag to VdpVideoSurfaces.

[José Hiram Soltren]

Hi,

On 09/15/2015 03:10 PM, Philip Langdale wrote:
> On 2015-09-15 12:53, José Hiram Soltren wrote:
>> This change adds two top level functions to the VDPAU API:
>>
>>     VdpVideoMixerSetProgressive
>>     VdpVideoMixerGetProgressive
>>
>> Next generation codecs - such as H.265/HEVC - do not support
>> interlaced content natively. Rather, they leave it to imple-
>> mentations to decide the correct behavior for handling legacy
>> interlaced content.
>>
>> Prior to the introduction of such codecs, this specification
>> left the designation of a particular VdpVideoSurface as a
>> _TOP_FIELD, _BOTTOM_FIELD, or _FRAME to the enumeration
>> VdpVideoMixerPictureStructure, passed to VdpVideoMixerRender.
>> It is possible, and permitted by this API specification, for
>> an implementation to set internal state on the backing store
>> of a VdpVideoSurface when handling a call to VdpVideoMixerRender.
>>
>> Not all use cases of a VdpVideoSurface will involve a trip
>> through a call to VdpVideoMixerRender. It is a legal use of the
>> VDPAU API to access a VdpVideoSurface directly using
>> VdpVideoSurfaceGetBitsYCbCr and VdpVideoSurfacePutBitsYCbCr.
>> In such a situation, it is helpful to be able to specify,
>> explicitly, and from outside of the implementation, whether
>> a VdpVideoSurface contains either one full frame, or two
>> half frames.
>>
>> Without this change, implementations do not have enough
>> information to determine whether or not a VdpVideoSurface
>> should be handled as two frames or one frame.
>> ---
> 
> Just to clarify - despite being present in the client facing API, these
> calls aren't really relevant to a normal client, correct?

This is correct.

> I would assume the following would happen:
> 
> 1) Video surface is created by client (and flag defaults to false)
> 2) Video surface is passed to decoder and decoder will set flag to true
>    as it knows what kind of content it is putting in the surface
> 3) Client can pass surface to mixer or call GetBits/PutBits and the
>    implementation will respect the flag to produce correct results.
> 
> So, it would be pretty odd that a client would ever need to set or get
> the flag, right?

Not necessarily, but generally, yes.

Existing video players would require no change to continue functioning as they
always have. This was intentional. With the exception of (3), this is what
happens today in the most current releases of the NVIDIA VDPAU implementation.
Implementations could (and perhaps should, independently) implement (3) without
exposing these flags directly.

Adding these get and set functions is as much about making this distinction
explicit as anything. Plus, this is state that ends up being resident on the
(backing store of the) VdpVideoSurface anyway, so this flag reflects the
implementation reality: this property is specific to a VdpVideo Surface
explicitly and a VdpVideoMixer implicitly.

A future set of proposed changes may aim to make the distinction between
decoding functionality and post-processing functionality more explicit. It is
conceivable, for example, to create a VdpDevice that supports decode but not
post-processing, or vice-versa. In such a scenario it would not be possible to
execute VdpVideoMixer at all.

Thanks,
--José

>>  include/vdpau/vdpau.h |   32 ++++++++++++++++++++++++++++++++
>>  1 file changed, 32 insertions(+)
>>
>> diff --git a/include/vdpau/vdpau.h b/include/vdpau/vdpau.h
>> index 0bc5b60..b98d84e 100644
>> --- a/include/vdpau/vdpau.h
>> +++ b/include/vdpau/vdpau.h
>> @@ -1679,6 +1679,38 @@ typedef VdpStatus VdpVideoSurfacePutBitsYCbCr(
>>      uint32_t const *     source_pitches
>>  );
>>
>> +/**
>> + * \brief Specify that a VdpVideoSurface contains progressive, full frame,
>> + *        non-interlaced content, without top and bottom fields. When set,
>> + *        it is a violation of the specification for implementations to
>> + *        attempt operations that combine or split fields, as fields are
>> + *        undefined when this flag is set. By default, implementations shall
>> + *        set this flag to false when handling VdpVideoSurfaceCreate.
>> + * \param[in] surface The surface's handle.
>> + * \param[in] is_progressive A flag defining if implementations must treat
>> + *         this VdpVideoSurface as having progressive data, without any
>> + *         notion of top or bottom fields.
>> + * \return VdpStatus The completion status of the operation.
>> + */
>> +typedef VdpStatus VdpVideoSurfaceSetProgressive(
>> +    VdpVideoSurface      surface,
>> +    VdpBool *            is_progressive
>> +);
>> +
>> +/**
>> + * \brief Query a VdpVideoSurface, checking to see if the progressive flag
>> + *        is set.
>> + * \param[in] surface The surface's handle.
>> + * \param[out] is_progressive A flag returning the current progressive
>> + *        frame state of this VdpVideoSurface.
>> + * \return VdpStatus The completion status of the operation.
>> + */
>> +typedef VdpStatus VdpVideoSurfaceGetProgressive(
>> +    VdpVideoSurface      surface,
>> +    /* output parameters follow */
>> +    VdpBool *            is_progressive
>> +);
>> +
>>  /*@}*/
>>
>>  /**
>