VDPAU
Typedefs
VdpVideoSurface; Video Surface object
Collaboration diagram for VdpVideoSurface; Video Surface object:

Typedefs

typedef VdpStatus VdpVideoSurfaceQueryCapabilities(VdpDevice device, VdpChromaType surface_chroma_type, VdpBool *is_supported, uint32_t *max_width, uint32_t *max_height)
 Query the implementation's VdpVideoSurface capabilities. More...
 
typedef VdpStatus VdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities(VdpDevice device, VdpChromaType surface_chroma_type, VdpYCbCrFormat bits_ycbcr_format, VdpBool *is_supported)
 Query the implementation's VdpVideoSurface GetBits/PutBits capabilities. More...
 
typedef uint32_t VdpVideoSurface
 An opaque handle representing a VdpVideoSurface object. More...
 
typedef VdpStatus VdpVideoSurfaceCreate(VdpDevice device, VdpChromaType chroma_type, uint32_t width, uint32_t height, VdpVideoSurface *surface)
 Create a VdpVideoSurface. More...
 
typedef VdpStatus VdpVideoSurfaceDestroy(VdpVideoSurface surface)
 Destroy a VdpVideoSurface. More...
 
typedef VdpStatus VdpVideoSurfaceGetParameters(VdpVideoSurface surface, VdpChromaType *chroma_type, uint32_t *width, uint32_t *height)
 Retrieve the parameters used to create a VdpVideoSurface. More...
 
typedef VdpStatus VdpVideoSurfaceGetBitsYCbCr(VdpVideoSurface surface, VdpYCbCrFormat destination_ycbcr_format, void *const *destination_data, uint32_t const *destination_pitches)
 Copy image data from a VdpVideoSurface to application memory in a specified YCbCr format. More...
 
typedef VdpStatus VdpVideoSurfacePutBitsYCbCr(VdpVideoSurface surface, VdpYCbCrFormat source_ycbcr_format, void const *const *source_data, uint32_t const *source_pitches)
 Copy image data from application memory in a specific YCbCr format to a VdpVideoSurface. More...
 

Detailed Description

A VdpVideoSurface stores YCbCr data in an internal format, with a variety of possible chroma sub-sampling options.

A VdpVideoSurface may be filled with:

VdpVideoSurface content may be accessed by:

VdpVideoSurfaces are not directly displayable. They must be converted into a displayable format using VdpVideoMixer objects.

See Video Mixer Usage for additional information.

Typedef Documentation

typedef uint32_t VdpVideoSurface

An opaque handle representing a VdpVideoSurface object.

typedef VdpStatus VdpVideoSurfaceCreate(VdpDevice device, VdpChromaType chroma_type, uint32_t width, uint32_t height,VdpVideoSurface *surface)

Create a VdpVideoSurface.

Parameters
[in]deviceThe device that will contain the surface.
[in]chroma_typeThe chroma type of the new surface.
[in]widthThe width of the new surface.
[in]heightThe height of the new surface.
[out]surfaceThe new surface's handle.
Returns
VdpStatus The completion status of the operation.

The memory backing the surface may not be initialized during creation. Applications are expected to initialize any region that they use, via VdpDecoderRender or VdpVideoSurfacePutBitsYCbCr.

Note that certain widths/heights are impossible for specific values of chroma_type. For example, the definition of VDP_CHROMA_TYPE_420 implies that the width must be even, since each single chroma sample covers two luma samples horizontally. A similar argument applies to surface heights, although doubly so, since interlaced pictures must be supported; each field's height must itself be a multiple of 2. Hence the overall surface's height must be a multiple of 4.

Similar rules apply to other chroma_type values.

Implementations may also impose additional restrictions on the surface sizes they support, potentially requiring additional rounding of actual surface sizes.

In most cases, this is not an issue, since:

  • Video streams are encoded as an array of macro-blocks, which typically have larger size alignment requirements than video surfaces do.
  • APIs such as VdpVideoMixerRender allow specification of a sub-region of the surface to read, which allows the padding data to be clipped away.

However, other APIs such as VdpVideoSurfaceGetBitsYCbCr and VdpVideoSurfacePutBitsYCbCr do not allow a sub-region to be specified, and always operate on surface size that was actually allocated, rather than the surface size that was requested. In this case, applications need to be aware of the actual surface size, in order to allocate appropriately sized buffers for the get-/put-bits operations.

For this reason, applications may need to call VdpVideoSurfaceGetParameters after creation, in order to retrieve the actual surface size.

typedef VdpStatus VdpVideoSurfaceDestroy(VdpVideoSurface surface)

Destroy a VdpVideoSurface.

Parameters
[in]surfaceThe surface's handle.
Returns
VdpStatus The completion status of the operation.
typedef VdpStatus VdpVideoSurfaceGetBitsYCbCr(VdpVideoSurface surface, VdpYCbCrFormat destination_ycbcr_format, void *const *destination_data, uint32_t const *destination_pitches)

Copy image data from a VdpVideoSurface to application memory in a specified YCbCr format.

Parameters
[in]surfaceThe surface's handle.
[in]destination_ycbcr_formatThe format of the application's data buffers.
[in]destination_dataPointers to the application data buffers into which the image data will be written. Note that this is an array of pointers, one per plane. The destination_format parameter will define how many planes are required.
[in]destination_pitchesPointers to the pitch values for the application data buffers. Note that this is an array of pointers, one per plane. The destination_format parameter will define how many planes are required.
Returns
VdpStatus The completion status of the operation.
typedef VdpStatus VdpVideoSurfaceGetParameters(VdpVideoSurface surface,VdpChromaType *chroma_type, uint32_t *width, uint32_t *height)

Retrieve the parameters used to create a VdpVideoSurface.

Parameters
[in]surfaceThe surface's handle.
[out]chroma_typeThe chroma type of the surface.
[out]widthThe width of the surface.
[out]heightThe height of the surface.
Returns
VdpStatus The completion status of the operation.
typedef VdpStatus VdpVideoSurfacePutBitsYCbCr(VdpVideoSurface surface, VdpYCbCrFormat source_ycbcr_format, void const *const *source_data, uint32_t const *source_pitches)

Copy image data from application memory in a specific YCbCr format to a VdpVideoSurface.

Parameters
[in]surfaceThe surface's handle.
[in]source_ycbcr_formatThe format of the application's data buffers.
[in]source_dataPointers to the application data buffers from which the image data will be copied. Note that this is an array of pointers, one per plane. The source_format parameter will define how many planes are required.
[in]source_pitchesPointers to the pitch values for the application data buffers. Note that this is an array of pointers, one per plane. The source_format parameter will define how many planes are required.
Returns
VdpStatus The completion status of the operation.
typedef VdpStatus VdpVideoSurfaceQueryCapabilities(VdpDevice device, VdpChromaType surface_chroma_type,VdpBool *is_supported, uint32_t *max_width, uint32_t *max_height)

Query the implementation's VdpVideoSurface capabilities.

Parameters
[in]deviceThe device to query.
[in]surface_chroma_typeThe type of chroma type for which information is requested.
[out]is_supportedIs this chroma type supported?
[out]max_widthThe maximum supported surface width for this chroma type.
[out]max_heightThe maximum supported surface height for this chroma type.
Returns
VdpStatus The completion status of the operation.
typedef VdpStatus VdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities(VdpDevice device, VdpChromaType surface_chroma_type, VdpYCbCrFormat bits_ycbcr_format,VdpBool *is_supported)

Query the implementation's VdpVideoSurface GetBits/PutBits capabilities.

Parameters
[in]deviceThe device to query.
[in]surface_chroma_typeThe type of chroma type for which information is requested.
[in]bits_ycbcr_formatThe format of application "bits" buffer for which information is requested.
[out]is_supportedIs this chroma type supported?
Returns
VdpStatus The completion status of the operation.