VDPAU: VdpVideoSurface; Video Surface object

VDPAU

Typedefs
VdpVideoSurface; Video Surface object
Core API
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.
typedef VdpStatus | VdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities(VdpDevice device, VdpChromaType surface_chroma_type, VdpYCbCrFormat bits_ycbcr_format, VdpBool *is_supported)
| Query the implementation's VdpVideoSurface GetBits/PutBits capabilities.
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.
typedef VdpStatus | VdpVideoSurfaceDestroy(VdpVideoSurface surface)
| Destroy a VdpVideoSurface.
typedef VdpStatus | VdpVideoSurfaceGetParameters(VdpVideoSurface surface, VdpChromaType *chroma_type, uint32_t *width, uint32_t *height)
| Retrieve the parameters used to create a VdpVideoSurface.
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.
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.

## 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:

- Data provided by the CPU via VdpVideoSurfacePutBitsYCbCr (i.e. software decode.)
- The result of applying a VdpDecoder to compressed video data.

VdpVideoSurface content may be accessed by:

- The application via VdpVideoSurfaceGetBitsYCbCr
- The Hardware that implements VdpOutputSurface rendering functionality.
- The Hardware the implements VdpVideoMixer functionality.

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

## ◆ VdpVideoSurface

typedef uint32_t VdpVideoSurface

An opaque handle representing a VdpVideoSurface object.

## ◆ VdpVideoSurfaceCreate

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

Create a VdpVideoSurface.

Parameters

  [in] | device | The device that will contain the surface.
  [in] | chroma_type | The chroma type of the new surface.
  [in] | width | The width of the new surface.
  [in] | height | The height of the new surface.
  [out] | surface | The 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.

## ◆ VdpVideoSurfaceDestroy

typedef VdpStatus VdpVideoSurfaceDestroy(VdpVideoSurface surface)

Destroy a VdpVideoSurface.

Parameters

  [in] | surface | The surface's handle.

Returns
  VdpStatus The completion status of the operation.

## ◆ VdpVideoSurfaceGetBitsYCbCr

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] | surface | The surface's handle.
  [in] | destination_ycbcr_format | The format of the application's data buffers.
  [in] | destination_data | Pointers 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_pitches | Pointers 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.

## ◆ VdpVideoSurfaceGetParameters

typedef VdpStatus VdpVideoSurfaceGetParameters(VdpVideoSurface surface, VdpChromaType *chroma_type, uint32_t *width, uint32_t *height)

Retrieve the parameters used to create a VdpVideoSurface.

Parameters

  [in] | surface | The surface's handle.
  [out] | chroma_type | The chroma type of the surface.
  [out] | width | The width of the surface.
  [out] | height | The height of the surface.

Returns
  VdpStatus The completion status of the operation.

## ◆ VdpVideoSurfacePutBitsYCbCr

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] | surface | The surface's handle.
  [in] | source_ycbcr_format | The format of the application's data buffers.
  [in] | source_data | Pointers 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_pitches | Pointers 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.

## ◆ VdpVideoSurfaceQueryCapabilities

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] | device | The device to query.
  [in] | surface_chroma_type | The type of chroma type for which information is requested.
  [out] | is_supported | Is this chroma type supported?
  [out] | max_width | The maximum supported surface width for this chroma type.
  [out] | max_height | The maximum supported surface height for this chroma type.

Returns
  VdpStatus The completion status of the operation.

## ◆ VdpVideoSurfaceQueryGetPutBitsYCbCrCapabilities

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] | device | The device to query.
  [in] | surface_chroma_type | The type of chroma type for which information is requested.
  [in] | bits_ycbcr_format | The format of application "bits" buffer for which information is requested.
  [out] | is_supported | Is this chroma type supported?

Returns
  VdpStatus The completion status of the operation.