docs/design/draft-va.txt

   1 Video Acceleration
   2 ------------------
   3
   4 Status:
   5
   6   DRAFT.
   7
   8 Purpose:
   9
  10   Provide an standardized generic way to introduce Video Acceleration APIs in
  11   already available elements instead of duplicating those into specialized ones.
  12
  13   Provide a mechanism for a light GstBuffer subclassing in order to be able
  14   exchange VA related context and surfaces between elements.
  15
  16   Provide some basic primitives to be used in the elements keeping
  17   the implementation of those in the backends of the helper library.
  18
  19   The motivation of this proposal is:
  20     - to avoid multiple duplicty of code
  21     - to avoid the use of GstBuffer subclassing and be more close to GstBuffer2
  22     - to avoid the overhead that's introduced with subclassing/GType checks
  23     - to permit multiple elements interact having a common standard
  24
  25 Proposal:
  26
  27    video/x-raw-va
  28
  29    Light subclassing embedding an structure in the data field of a standard
  30    GstBuffer.
  31
  32    struct {
  33      context;
  34      surface;
  35      flags;
  36      subpicture, x, y, w, h;
  37      parent *
  38      ...
  39    } VASurface
  40
  41    GstVA helper library
  42    --------------------
  43
  44    Common API that it's implemented by a backend for each VA API.
  45
  46    +-------+      +---------------+
  47    |       |----> | VDPAU backend |
  48    | GstVA |      +---------------+
  49    |       |      +---------------+
  50    |       |----> | VAAPI backend |
  51    +-------+      +---------------+
  52
  53    gst_va_init () : Iterate in the backends and try to initialize those, stops
  54    when a backend is able to be created.
  55
  56    bool gst_va_available() : permit to query if there's VA available in runtime.
  57
  58    GstBuffer * gst_va_buffer_new (vacontext, vasurface, vaflags, parent*,
  59      free_func*):
  60    Create a new GstBuffer with the proper light subclass and store on it
  61    the provided context, surface, flags...
  62    - parent* and free_func* to implement a mechanism to return surfaces in
  63      the pool driven by parent.
  64
  65    gst_va_buffer_get_context (GstBuffer *)
  66    gst_va_buffer_get_surface (GstBuffer *)
  67    gst_va_buffer_get_flags (GstBuffer *)
  68    ....
  69    Some public/private? accessors to be able recover fields from a VA GstBuffer
  70    internal structure.
  71
  72    Primitives:
  73
  74    gst_va_render_display (GstBuffer * va, display, x, y, w, h, ...)
  75    Put a surface in the screen at the specified position.
  76
  77    gst_va_render_pixmap (GstBuffer * va, pixmap *, w, h, ...)
  78    Put a surface in a pixmap, to be used paired with GLX_texture_from_pixmap to
  79    upload into a OpenGL texture.
  80
  81    gst_va_render_memory (GstBuffer * va, planes *, strides *, w, h, ...)
  82    To pull back into main memory a VA surface.
  83
  84    gst_va_buffer_associate_subpicture (GstBuffer * va, GstBuffer * subpicture,
  85       x, y, w, h,...)
  86    Take a reference of subpicture and keep it in va internal structure.
  87
  88 Use cases:
  89
  90    Instead of create a new specialized element for each API just change
  91    a generic element once.
  92
  93    To add support for a new API just have to create a new backend.
  94
  95    xvimagesink
  96    -----------
  97
  98    - In _setcaps negotiate accept VA kind of stream when gst_va_init and
  99      gst_va_available tell us that we have hardware capable of it.
 100
 101    - In _render when the buffers have the VA flag render display it with
 102      gst_va_render_display()
 103
 104    videomixer, dvdspu, textoverlay, ...
 105    ------------------------------------
 106
 107    - In _setcaps negotiate accept VA kind of stream when gst_va_init and
 108      gst_va_available tell us that we have hardware capable of it.
 109
 110    - Use gst_va_buffer_associate_subpicture () where necessary.
 111