docs/design/part-meta.txt

   1 GstMeta
   2 -------
   3
   4 This document describes the design for arbitrary per-buffer metadata.
   5
   6 Buffer metadata typically describes the lowlevel properties of the buffer
   7 content. These properties are typically not negotiated with caps but they are
   8 negotiated in the bufferpools.
   9
  10 Some examples of metadata:
  11
  12  - timestamp, duration
  13  - offset, offset_end
  14  - interlacing information
  15  - video alignment, cropping, panning information
  16  - extra container information such as granulepos, ...
  17  - extra global buffer properties
  18
  19
  20 Requirements
  21 ~~~~~~~~~~~~
  22
  23  - It must be fast
  24     * allocation, free, low fragmentation
  25     * access to the metadata fields, preferably not much slower than directly
  26       accessing a C structure field
  27  - It must be extensible. Elements should be able to add new arbitrary metadata
  28    without requiring much effort. Also new metadata fields should not break API
  29    or ABI.
  30  - It plays nice with subbuffers. When a subbuffer is created, the various
  31    buffer metadata should be copied/updated correctly.
  32  - We should be able to negotiate metadata between elements
  33
  34 Use cases
  35 ---------
  36
  37  * Video planes
  38
  39  Video data is sometimes allocated in non-contiguous planes for the Y and the UV
  40  data. We need to be able to specify the data on a buffer using multiple
  41  pointers in memory. We also need to be able to specify the stride for these
  42  planes.
  43
  44  * Extra buffer data
  45
  46  Some elements might need to store extra data for a buffer. This is typically
  47  done when the resources are allocated from another subsystem such as OMX or
  48  X11.
  49
  50  * Processing information
  51
  52  Pan and crop information can be added to the buffer data when the downstream
  53  element can understand and use this metadata. An imagesink can, for example,
  54  use the pan and cropping formation when it blits the image on the screen
  55  with little overhead.
  56
  57
  58 GstMeta
  59 ~~~~~~~
  60
  61 A GstMeta is a structure as follows:
  62
  63   struct _GstMeta {
  64     GstMetaFlags       flags;
  65     const GstMetaInfo *info;    /* tag and info for the meta item */
  66   };
  67
  68 The purpose of the this structure is to serve as a common header for all metadata
  69 information that we can attach to a buffer. Specific metadata, such as timing metadata,
  70 will have this structure as the first field. For example:
  71
  72   struct _GstMetaTiming {
  73     GstMeta        meta;        /* common meta header */
  74
  75     GstClockTime   dts;         /* decoding timestamp */
  76     GstClockTime   pts;         /* presentation timestamp */
  77     GstClockTime   duration;    /* duration of the data */
  78     GstClockTime   clock_rate;  /* clock rate for the above values */
  79   };
  80
  81 Or another example for the video memory regions that consists of both fields and
  82 methods.
  83
  84
  85  #define GST_VIDEO_MAX_PLANES 4
  86
  87  struct GstMetaVideo {
  88    GstMeta       meta;
  89
  90    GstBuffer         *buffer;
  91
  92    GstVideoFlags      flags;
  93    GstVideoFormat     format;
  94    guint              id
  95    guint              width;
  96    guint              height;
  97
  98    guint              n_planes;
  99    gsize              offset[GST_VIDEO_MAX_PLANES];   /* offset in the buffer memory region of the
 100                                                        * first pixel. */
 101    gint               stride[GST_VIDEO_MAX_PLANES];   /* stride of the image lines. Can be negative when
 102                                                        * the image is upside-down */
 103
 104    gpointer (*map)    (GstMetaVideo *meta, guint plane, gpointer * data, gint *stride,
 105                        GstMapFlags flags);
 106    gboolean (*unmap)  (GstMetaVideo *meta, guint plane, gpointer data);
 107  };
 108
 109  gpointer gst_meta_video_map   (GstMetaVideo *meta, guint plane, gpointer * data,
 110                                 gint *stride, GstMapflags flags);
 111  gboolean gst_meta_video_unmap (GstMetaVideo *meta, guint plane, gpointer data);
 112
 113 GstMeta derived structures define the API of the metadata. The API can consist of
 114 fields and/or methods. It is possible to have different implementations for the
 115 same GstMeta structure.
 116
 117 The implementation of the GstMeta api would typically add more fields to the
 118 public structure that allow it to implement the API.
 119
 120 GstMetaInfo will point to more information about the metadata and looks like this:
 121
 122   struct _GstMetaInfo {
 123     GType                      api;       /* api type */
 124     GType                      type;      /* implementation type */
 125     gsize                      size;      /* size of the structure */
 126
 127     GstMetaInitFunction        init_func;
 128     GstMetaFreeFunction        free_func;
 129     GstMetaTransformFunction   transform_func;
 130   };
 131
 132 api will contain a GType of the metadata api. A repository of registered MetaInfo
 133 will be maintained by the core. We will register some common metadata structures
 134 in core and some media specific info for audio/video/text in -base. Plugins can
 135 register additional custom metadata.
 136
 137 For each implementation of api, there will thus be a unique GstMetaInfo. In the
 138 case of metadata with a well defined API, the implementation specific init
 139 function will setup the methods in the metadata structure. A unique GType will
 140 be made for each implementation and stored in the type field.
 141
 142 Along with the metadata description we will have functions to initialize/free (and/or refcount)
 143 a specific GstMeta instance. We also have the possibility to add a custom
 144 transform function that can be used to modify the metadata when a transformation
 145 happens.
 146
 147 There are no explicit methods to serialize and deserialize the metadata. Since
 148 each type has a GType, we can reuse the GValue transform functions for this.
 149
 150 The purpose of the separate MetaInfo is to not have to carry the free/init functions in
 151 each buffer instance but to define them globally. We still want quick access to the info
 152 so we need to make the buffer metadata point to the info.
 153
 154 Technically we could also specify the field and types in the MetaInfo and
 155 provide a generic API to retrieve the metadata fields without the need for a
 156 header file. We will not do this yet.
 157
 158 Allocation of the GstBuffer structure will result in the allocation of a memory region
 159 of a customizable size (512 bytes). Only the first sizeof (GstBuffer) bytes of this
 160 region will initially be used. The remaining bytes will be part of the free metadata
 161 region of the buffer. Different implementations are possible and are invisible
 162 in the API or ABI.
 163
 164 The complete buffer with metadata could, for example, look as follows:
 165
 166                          +-------------------------------------+
 167 GstMiniObject            |     GType (GstBuffer)               |
 168                          |     refcount, flags, copy/disp/free |
 169                          +-------------------------------------+
 170 GstBuffer                |     pool,pts,dts,duration,offsets   |
 171                          |     <private data>                  |
 172                          +.....................................+
 173                          |     next                           ---+
 174                       +- |     info                           ------> GstMetaInfo
 175 GstMetaTiming         |  |                                     | |
 176                       |  |     dts                             | |
 177                       |  |     pts                             | |
 178                       |  |     duration                        | |
 179                       +- |     clock_rate                      | |
 180                          + . . . . . . . . . . . . . . . . . . + |
 181                          |     next                           <--+
 182 GstMetaVideo       +- +- |     info                           ------> GstMetaInfo
 183                    |  |  |                                     | |
 184                    |  |  |     flags                           | |
 185                    |  |  |     n_planes                        | |
 186                    |  |  |     planes[]                        | |
 187                    |  |  |     map                             | |
 188                    |  |  |     unmap                           | |
 189                    +- |  |                                     | |
 190                       |  |     private fields                  | |
 191 GstMetaVideoImpl      |  |     ...                             | |
 192                       |  |     ...                             | |
 193                       +- |                                     | |
 194                          + . . . . . . . . . . . . . . . . . . + .
 195                          .                                       .
 196
 197
 198 API examples
 199 ~~~~~~~~~~~~
 200
 201 Buffers are created using the normal gst_buffer_new functions. The standard fields
 202 are initialized as usual. A memory area that is bigger than the structure size
 203 is allocated for the buffer metadata.
 204
 205   gst_buffer_new ();
 206
 207 After creating a buffer, the application can set caps and add metadata
 208 information.
 209
 210 To add or retrieve metadata, a handle to a GstMetaInfo structure needs to be
 211 obtained. This defines the implementation and API of the metadata. Usually, a
 212 handle to this info structure can be obtained by calling a public _get_info()
 213 method from a shared library (for shared metadata).
 214
 215 The following defines can usually be found in the shared .h file.
 216
 217   GstMetaInfo * gst_meta_timing_get_info();
 218   #define GST_META_TIMING_INFO  (gst_meta_timing_get_info())
 219
 220 Adding metadata to a buffer can be done with the gst_buffer_add_meta() call.
 221 This function will create new metadata based on the implementation specified by
 222 the GstMetaInfo. It is also possible to pass a generic pointer to the add_meta()
 223 function that can contain parameters to initialize the new metadata fields.
 224
 225 Retrieving the metadata on a buffer can be done with the
 226 gst_buffer_meta_get() method. This function retrieves an existing metadata
 227 conforming to the API specified in the given info. When no such metadata exists,
 228 the function will return NULL.
 229
 230   GstMetaTiming *timing;
 231
 232   timing = gst_buffer_get_meta (buffer, GST_META_TIMING_INFO);
 233
 234 Once a reference to the info has been obtained, the associated metadata can be
 235 added or modified on a buffer.
 236
 237   timing->timestamp = 0;
 238   timing->duration = 20 * GST_MSECOND;
 239
 240 Other convenience macros can be made to simplify the above code:
 241
 242  #define gst_buffer_get_meta_timing(b) \
 243     ((GstMetaTiming *) gst_buffer_get_meta ((b), GST_META_TIMING_INFO)
 244
 245 This makes the code look like this:
 246
 247   GstMetaTiming *timing;
 248
 249   timing = gst_buffer_get_meta_timing (buffer);
 250   timing->timestamp = 0;
 251   timing->duration = 20 * GST_MSECOND;
 252
 253 To iterate the different metainfo structures, one can use the
 254 gst_buffer_meta_get_next() methods.
 255
 256  GstMeta *current = NULL;
 257
 258  /* passing NULL gives the first entry */
 259  current = gst_buffer_meta_get_next (buffer, current);
 260
 261  /* passing a GstMeta returns the next */
 262  current = gst_buffer_meta_get_next (buffer, current);
 263
 264
 265 Memory management
 266 ~~~~~~~~~~~~~~~~~
 267
 268 * allocation
 269
 270   We initially allocate a reasonable sized GstBuffer structure (say 512 bytes).
 271
 272   Since the complete buffer structure, including a large area for metadata, is
 273   allocated in one go, we can reduce the number of memory allocations while still
 274   providing dynamic metadata.
 275
 276   When adding metadata, we need to call the init function of the associated
 277   metadata info structure. Since adding the metadata requires the caller to pass
 278   a handle to the info, this operation does not require table lookups.
 279
 280   Per-metadata memory initialisation is needed because not all metadata is
 281   initialized in the same way. We need to, for example, set the timestamps to
 282   NONE in the MetaTiming structures.
 283
 284   The init/free functions can also be used to implement refcounting for a metadata
 285   structure. This can be useful when a structure is shared between buffers.
 286
 287   When the free_size of the GstBuffer is exhausted, we will allocate new memory
 288   for each newly added Meta and use the next pointers to point to this. It
 289   is expected that this does not occur often and we might be able to optimize
 290   this transparently in the future.
 291
 292 * free
 293
 294   When a GstBuffer is freed, we potentially might have to call a custom free
 295   function on the metadata info. In the case of the Memory metadata, we need to
 296   call the associated free function to free the memory.
 297
 298   When freeing a GstBuffer, the custom buffer free function will iterate all of
 299   the metadata in the buffer and call the associated free functions in the
 300   MetaInfo associated with the entries. Usually, this function will be NULL.
 301
 302
 303 Serialization
 304 ~~~~~~~~~~~~~
 305
 306 When buffer should be sent over the wire or be serialized in GDP, we need a way
 307 to perform custom serialization and deserialization on the metadata.
 308
 309 for this we can use the GValue transform functions.
 310
 311
 312 Transformations
 313 ~~~~~~~~~~~~~~~
 314
 315 After certain transformations, the metadata on a buffer might not be relevant
 316 anymore.
 317
 318 Consider, for example, metadata that lists certain regions of interest
 319 on the video data. If the video is scaled or rotated, the coordinates might not
 320 make sense anymore. A transform element should be able to adjust or remove the
 321 associated metadata when it becomes invalid.
 322
 323 We can make the transform element aware of the metadata so that it can adjust or
 324 remove in an intelligent way. Since we allow arbitrary metadata, we can't do
 325 this for all metadata and thus we need some other way.
 326
 327 One proposition is to tag the metadata type with keywords that specify what it
 328 functionally refers too. We could, for example, tag the metadata for the regions
 329 of interest with a tag that notes that the metadata refers to absolute pixel
 330 positions. A transform could then know that the metadata is not valid anymore
 331 when the position of the pixels changed (due to rotation, flipping, scaling and
 332 so on).
 333
 334
 335 Subbuffers
 336 ~~~~~~~~~~
 337
 338 Subbuffers are implemented with a generic copy. Parameters to the copy
 339 are the offset and size. This allows each metadata structure to implement the
 340 actions needed to update the metadata of the subbuffer.
 341
 342 It might not make sense for some metadata to work with subbuffers. For example
 343 when  we take a subbuffer of a buffer with a video frame, the GstMetaVideo
 344 simply becomes invalid and is removed from the new subbuffer.
 345
 346
 347 Relationship with GstCaps
 348 ~~~~~~~~~~~~~~~~~~~~~~~~~
 349
 350 The difference between GstCaps, used in negotiation, and the metadata is not
 351 clearly defined.
 352
 353 We would like to think of the GstCaps containing the information needed to
 354 functionally negotiate the format between two elements. The Metadata should then
 355 only contain variables that can change between each buffer.
 356
 357 For example, for video we would have width/height/framerate in the caps but then
 358 have the more technical details, such as stride, data pointers, pan/crop/zoom
 359 etc in the metadata.
 360
 361 A scheme like this would still allow us to functionally specify the desired
 362 video resolution while the implementation details would be inside the metadata.
 363
 364
 365 Compatibility
 366 ~~~~~~~~~~~~~
 367
 368 We need to make sure that elements exchange metadata that they both understand,
 369 This is particulary important when the metadata describes the data layout in
 370 memory (such as strides).
 371
 372 The ALLOCATION query is used to let upstream know what metadata we can suport.
 373
 374 It is also possible to have a bufferpool add certain metadata to the buffers
 375 from the pool. This feature is activated by enabling a buffer option when
 376 configuring the pool.
 377
 378
 379 Notes
 380 ~~~~~
 381
 382 Some structures that we need to be able to add to buffers.
 383
 384 * Clean Aperture
 385 * Arbitrary Matrix Transform
 386 * Aspect ratio
 387 * Pan/crop/zoom
 388 * Video strides
 389
 390 Some of these overlap, we need to find a minimal set of metadata structures that
 391 allows us to define all use cases.