GstVaapiSurface

GstVaapiSurface — VA surface abstraction

Synopsis

enum                GstVaapiChromaType;
enum                GstVaapiSurfaceStatus;
enum                GstVaapiSurfaceRenderFlags;
                    GstVaapiSurface;
GstVaapiSurface *   gst_vaapi_surface_new               (GstVaapiDisplay *display,
                                                         GstVaapiChromaType chroma_type,
                                                         guint width,
                                                         guint height);
GstVaapiSurface *   gst_vaapi_surface_new_with_format   (GstVaapiDisplay *display,
                                                         GstVideoFormat format,
                                                         guint width,
                                                         guint height);
GstVaapiID          gst_vaapi_surface_get_id            (GstVaapiSurface *surface);
GstVaapiChromaType  gst_vaapi_surface_get_chroma_type   (GstVaapiSurface *surface);
GstVideoFormat      gst_vaapi_surface_get_format        (GstVaapiSurface *surface);
guint               gst_vaapi_surface_get_width         (GstVaapiSurface *surface);
guint               gst_vaapi_surface_get_height        (GstVaapiSurface *surface);
void                gst_vaapi_surface_get_size          (GstVaapiSurface *surface,
                                                         guint *pwidth,
                                                         guint *pheight);
GstVaapiImage *     gst_vaapi_surface_derive_image      (GstVaapiSurface *surface);
gboolean            gst_vaapi_surface_get_image         (GstVaapiSurface *surface,
                                                         GstVaapiImage *image);
gboolean            gst_vaapi_surface_put_image         (GstVaapiSurface *surface,
                                                         GstVaapiImage *image);
gboolean            gst_vaapi_surface_associate_subpicture
                                                        (GstVaapiSurface *surface,
                                                         GstVaapiSubpicture *subpicture,
                                                         const GstVaapiRectangle *src_rect,
                                                         const GstVaapiRectangle *dst_rect);
gboolean            gst_vaapi_surface_deassociate_subpicture
                                                        (GstVaapiSurface *surface,
                                                         GstVaapiSubpicture *subpicture);
gboolean            gst_vaapi_surface_sync              (GstVaapiSurface *surface);
gboolean            gst_vaapi_surface_query_status      (GstVaapiSurface *surface,
                                                         GstVaapiSurfaceStatus *pstatus);

Description

Details

enum GstVaapiChromaType

typedef enum {
    GST_VAAPI_CHROMA_TYPE_YUV420 = 1,
    GST_VAAPI_CHROMA_TYPE_YUV422,
    GST_VAAPI_CHROMA_TYPE_YUV444,
    GST_VAAPI_CHROMA_TYPE_YUV411,
    GST_VAAPI_CHROMA_TYPE_YUV410,
    GST_VAAPI_CHROMA_TYPE_YUV400,
    GST_VAAPI_CHROMA_TYPE_RGB32,
    GST_VAAPI_CHROMA_TYPE_RGB16
} GstVaapiChromaType;

The set of all chroma types for GstVaapiSurface.

GST_VAAPI_CHROMA_TYPE_YUV420

YUV 4:2:0 chroma format

GST_VAAPI_CHROMA_TYPE_YUV422

YUV 4:2:2 chroma format

GST_VAAPI_CHROMA_TYPE_YUV444

YUV 4:4:4 chroma format

GST_VAAPI_CHROMA_TYPE_YUV411

YUV 4:1:1 chroma format

GST_VAAPI_CHROMA_TYPE_YUV410

YUV 4:1:0 chroma format

GST_VAAPI_CHROMA_TYPE_YUV400

YUV 4:0:0 chroma format (grayscale)

GST_VAAPI_CHROMA_TYPE_RGB32

32-bit RGB chroma format

GST_VAAPI_CHROMA_TYPE_RGB16

16-bit RGB chroma format

enum GstVaapiSurfaceStatus

typedef enum {
    GST_VAAPI_SURFACE_STATUS_IDLE       = 1 << 0,
    GST_VAAPI_SURFACE_STATUS_RENDERING  = 1 << 1,
    GST_VAAPI_SURFACE_STATUS_DISPLAYING = 1 << 2,
    GST_VAAPI_SURFACE_STATUS_SKIPPED    = 1 << 3
} GstVaapiSurfaceStatus;

The set of all surface status for GstVaapiSurface.

GST_VAAPI_SURFACE_STATUS_IDLE

the surface is not being rendered or displayed

GST_VAAPI_SURFACE_STATUS_RENDERING

the surface is used for rendering (decoding to the surface in progress)

GST_VAAPI_SURFACE_STATUS_DISPLAYING

the surface is being displayed to screen

GST_VAAPI_SURFACE_STATUS_SKIPPED

indicates a skipped frame during encode

enum GstVaapiSurfaceRenderFlags

typedef enum {
    /* Picture structure */
    GST_VAAPI_PICTURE_STRUCTURE_TOP_FIELD       = 0x01 << 0,
    GST_VAAPI_PICTURE_STRUCTURE_BOTTOM_FIELD    = 0x02 << 0,
    GST_VAAPI_PICTURE_STRUCTURE_FRAME           = 0x03 << 0,
    GST_VAAPI_PICTURE_STRUCTURE_MASK            = 0x00000003, /* 2 bits */

    /* Color standard */
    GST_VAAPI_COLOR_STANDARD_ITUR_BT_601        = 0x01 << 2,
    GST_VAAPI_COLOR_STANDARD_ITUR_BT_709        = 0x02 << 2,
    GST_VAAPI_COLOR_STANDARD_ITUR_BT_470M       = 0x03 << 2,
    GST_VAAPI_COLOR_STANDARD_ITUR_BT_470BG      = 0x04 << 2,
    GST_VAAPI_COLOR_STANDARD_SMPTE_170M         = 0x05 << 2,
    GST_VAAPI_COLOR_STANDARD_SMPTE_240M         = 0x06 << 2,
    GST_VAAPI_COLOR_STANDARD_MASK               = 0x0000003c, /* 4 bits */
} GstVaapiSurfaceRenderFlags;

The set of all render flags for gst_vaapi_window_put_surface().

GST_VAAPI_PICTURE_STRUCTURE_TOP_FIELD

selects the top field of the surface

GST_VAAPI_PICTURE_STRUCTURE_BOTTOM_FIELD

selects the bottom field of the surface

GST_VAAPI_PICTURE_STRUCTURE_FRAME

selects the entire surface

GST_VAAPI_PICTURE_STRUCTURE_MASK

GST_VAAPI_COLOR_STANDARD_ITUR_BT_601

uses ITU-R BT.601 standard for color space conversion

GST_VAAPI_COLOR_STANDARD_ITUR_BT_709

uses ITU-R BT.709 standard for color space conversion

GST_VAAPI_COLOR_STANDARD_ITUR_BT_470M

uses ITU-R BT.470-2 System M standard for color space conversion

GST_VAAPI_COLOR_STANDARD_ITUR_BT_470BG

uses ITU-R BT.470-2 System B, G standard for color space conversion

GST_VAAPI_COLOR_STANDARD_SMPTE_170M

uses SMPTE-170M standard for color space conversion

GST_VAAPI_COLOR_STANDARD_SMPTE_240M

uses SMPTE-240M standard for color space conversion

GST_VAAPI_COLOR_STANDARD_MASK


GstVaapiSurface

typedef struct {
} GstVaapiSurface;

A VA surface wrapper.


gst_vaapi_surface_new ()

GstVaapiSurface *   gst_vaapi_surface_new               (GstVaapiDisplay *display,
                                                         GstVaapiChromaType chroma_type,
                                                         guint width,
                                                         guint height);

Creates a new GstVaapiSurface with the specified chroma format and dimensions.

display :

a GstVaapiDisplay

chroma_type :

the surface chroma format

width :

the requested surface width

height :

the requested surface height

Returns :

the newly allocated GstVaapiSurface object

gst_vaapi_surface_new_with_format ()

GstVaapiSurface *   gst_vaapi_surface_new_with_format   (GstVaapiDisplay *display,
                                                         GstVideoFormat format,
                                                         guint width,
                                                         guint height);

Creates a new GstVaapiSurface with the specified pixel format and dimensions.

display :

a GstVaapiDisplay

format :

the surface format

width :

the requested surface width

height :

the requested surface height

Returns :

the newly allocated GstVaapiSurface object, or NULL if creation of VA surface with explicit pixel format is not supported or failed.

gst_vaapi_surface_get_id ()

GstVaapiID          gst_vaapi_surface_get_id            (GstVaapiSurface *surface);

Returns the underlying VASurfaceID of the surface.

surface :

a GstVaapiSurface

Returns :

the underlying VA surface id

gst_vaapi_surface_get_chroma_type ()

GstVaapiChromaType  gst_vaapi_surface_get_chroma_type   (GstVaapiSurface *surface);

Returns the GstVaapiChromaType the surface was created with.

surface :

a GstVaapiSurface

Returns :

the GstVaapiChromaType

gst_vaapi_surface_get_format ()

GstVideoFormat      gst_vaapi_surface_get_format        (GstVaapiSurface *surface);

Returns the GstVideoFormat the surface was created with.

surface :

a GstVaapiSurface

Returns :

the GstVideoFormat, or GST_VIDEO_FORMAT_ENCODED if the surface was not created with an explicit video format, or if the underlying video format could not be determined

gst_vaapi_surface_get_width ()

guint               gst_vaapi_surface_get_width         (GstVaapiSurface *surface);

Returns the surface width.

surface :

a GstVaapiSurface

Returns :

the surface width, in pixels

gst_vaapi_surface_get_height ()

guint               gst_vaapi_surface_get_height        (GstVaapiSurface *surface);

Returns the surface height.

surface :

a GstVaapiSurface

Returns :

the surface height, in pixels.

gst_vaapi_surface_get_size ()

void                gst_vaapi_surface_get_size          (GstVaapiSurface *surface,
                                                         guint *pwidth,
                                                         guint *pheight);

Retrieves the dimensions of a GstVaapiSurface.

surface :

a GstVaapiSurface

pwidth :

return location for the width, or NULL

pheight :

return location for the height, or NULL

gst_vaapi_surface_derive_image ()

GstVaapiImage *     gst_vaapi_surface_derive_image      (GstVaapiSurface *surface);

Derives a GstVaapiImage from the surface. This image buffer can then be mapped/unmapped for direct CPU access. This operation is only possible if the underlying implementation supports direct rendering capabilities and internal surface formats that can be represented with a GstVaapiImage.

When the operation is not possible, the function returns NULL and the user should then fallback to using gst_vaapi_surface_get_image() or gst_vaapi_surface_put_image() to accomplish the same task in an indirect manner (additional copy).

An image created with gst_vaapi_surface_derive_image() should be unreferenced when it's no longer needed. The image and image buffer data structures will be destroyed. However, the surface contents will remain unchanged until destroyed through the last call to gst_vaapi_object_unref().

surface :

a GstVaapiSurface

Returns :

the newly allocated GstVaapiImage object, or NULL on failure

gst_vaapi_surface_get_image ()

gboolean            gst_vaapi_surface_get_image         (GstVaapiSurface *surface,
                                                         GstVaapiImage *image);

Retrieves surface data into a GstVaapiImage. The image must have a format supported by the surface.

surface :

a GstVaapiSurface

image :

a GstVaapiImage

Returns :

TRUE on success

gst_vaapi_surface_put_image ()

gboolean            gst_vaapi_surface_put_image         (GstVaapiSurface *surface,
                                                         GstVaapiImage *image);

Copies data from a GstVaapiImage into a surface. The image must have a format supported by the surface.

surface :

a GstVaapiSurface

image :

a GstVaapiImage

Returns :

TRUE on success

gst_vaapi_surface_associate_subpicture ()

gboolean            gst_vaapi_surface_associate_subpicture
                                                        (GstVaapiSurface *surface,
                                                         GstVaapiSubpicture *subpicture,
                                                         const GstVaapiRectangle *src_rect,
                                                         const GstVaapiRectangle *dst_rect);

Associates the subpicture with the surface. The src_rect coordinates and size are relative to the source image bound to subpicture. The dst_rect coordinates and size are relative to the target surface. Note that the surface holds an additional reference to the subpicture.

surface :

a GstVaapiSurface

subpicture :

a GstVaapiSubpicture

src_rect :

the sub-rectangle of the source subpicture image to extract and process. If NULL, the entire image will be used.

dst_rect :

the sub-rectangle of the destination surface into which the image is rendered. If NULL, the entire surface will be used.

Returns :

TRUE on success

gst_vaapi_surface_deassociate_subpicture ()

gboolean            gst_vaapi_surface_deassociate_subpicture
                                                        (GstVaapiSurface *surface,
                                                         GstVaapiSubpicture *subpicture);

Deassociates subpicture from surface. Other associations are kept.

surface :

a GstVaapiSurface

subpicture :

a GstVaapiSubpicture

Returns :

TRUE on success

gst_vaapi_surface_sync ()

gboolean            gst_vaapi_surface_sync              (GstVaapiSurface *surface);

Blocks until all pending operations on the surface have been completed.

surface :

a GstVaapiSurface

Returns :

TRUE on success

gst_vaapi_surface_query_status ()

gboolean            gst_vaapi_surface_query_status      (GstVaapiSurface *surface,
                                                         GstVaapiSurfaceStatus *pstatus);

Finds out any pending operations on the surface. The GstVaapiSurfaceStatus flags are returned into pstatus.

surface :

a GstVaapiSurface

pstatus :

return location for the GstVaapiSurfaceStatus

Returns :

TRUE on success