GstVaapiSurface: GStreamer VA-API Plugins 1.6 Library Reference Manual

## GstVaapiSurface GstVaapiSurface — VA surface abstraction |

## Functions

GstVaapiSurface * | gst_vaapi_surface_new ()
GstVaapiSurface * | gst_vaapi_surface_new_with_format ()
GstVaapiID | gst_vaapi_surface_get_id ()
GstVaapiChromaType | gst_vaapi_surface_get_chroma_type ()
GstVideoFormat | gst_vaapi_surface_get_format ()
guint | gst_vaapi_surface_get_width ()
guint | gst_vaapi_surface_get_height ()
void | gst_vaapi_surface_get_size ()
GstVaapiImage * | gst_vaapi_surface_derive_image ()
gboolean | gst_vaapi_surface_get_image ()
gboolean | gst_vaapi_surface_put_image ()
gboolean | gst_vaapi_surface_associate_subpicture ()
gboolean | gst_vaapi_surface_deassociate_subpicture ()
gboolean | gst_vaapi_surface_sync ()
gboolean | gst_vaapi_surface_query_status ()

## Types and Values

enum | GstVaapiChromaType
enum | GstVaapiSurfaceStatus
enum | GstVaapiSurfaceRenderFlags
| GstVaapiSurface

## Description

## Functions

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

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

surface | a GstVaapiSurface |

#### Returns

the surface height, in pixels.

### gst_vaapi_surface_get_size ()

    void
    gst_vaapi_surface_get_size (GstVaapiSurface *surface,
                                guint *width_ptr,
                                guint *height_ptr);

Retrieves the dimensions of a GstVaapiSurface.

#### Parameters

surface | a GstVaapiSurface |
width_ptr | return location for the width, or `NULL` |
height_ptr | 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()`.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

surface | a GstVaapiSurface |
pstatus | return location for the GstVaapiSurfaceStatus |

#### Returns

`TRUE` on success

## Types and Values

### enum GstVaapiChromaType

The set of all chroma types for GstVaapiSurface.

#### Members

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

The set of all surface status for GstVaapiSurface.

#### Members

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

The set of all render flags for `gst_vaapi_window_put_surface()`.

#### Members

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.