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