A VdpVideoSurface stores YCbCr data in an internal format, with a variety of possible chroma sub-sampling options. More...
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:
- 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.
