or ABI.
- It plays nice with subbuffers. When a subbuffer is created, the various
buffer metadata should be copied/updated correctly.
- - We should be able to pass metadata in pad_alloc() and get_range() functions
- to specify extra allocation parameters.
- - We should be able to attach statically allocated metadata to a buffer. This
- is for metadata that does not change much.
+ - We should be able to negotiate metadata between elements
Use cases
---------
/* refcounting */
gint refcount;
guint flags;
+ gsize size;
GstMiniObjectCopyFunction copy;
+ GstMiniObjectDisposeFunction dispose;
GstMiniObjectFreeFunction free;
}
struct _GstBuffer {
GstMiniObject mini_object;
- gsize free_size;
-
GstCaps *caps;
GstBuffer *parent;
metadata structures in order to optimize access to the memory.
-GstBufferMeta
-~~~~~~~~~~~~~
+GstMeta
+~~~~~~~
-A GstBufferMeta is a structure as follows:
+A GstMeta is a structure as follows:
- struct _GstBufferMeta {
- GstBufferMetaInfo *info; /* tag and info for the meta item */
+ struct _GstMeta {
+ GstMetaInfo *info; /* tag and info for the meta item */
};
The purpose of the this structure is to serve as a common header for all metadata
information that we can attach to a buffer. Specific metadata, such as timing metadata,
will have this structure as the first field. For example:
- struct _GstBufferMetaTiming {
- GstBufferMeta meta; /* common meta header */
+ struct _GstMetaTiming {
+ GstMeta meta; /* common meta header */
GstClockTime dts; /* decoding timestamp */
GstClockTime pts; /* presentation timestamp */
GstClockTime clock_rate; /* clock rate for the above values */
};
-Or another example for the buffer memory region
+Or another example for the buffer memory region that consists of some methods
+only.
- struct _GstBufferMetaMemory {
- GstBufferMeta meta;
+ struct _GstMetaMemory {
+ GstMeta meta;
+
+ GstMetaMemoryMap mmap_func;
+ GstMetaMemoryUnmap munmap_func;
+ };
+
+ gpointer gst_meta_memory_map (GstMetaMemory *, guint offset, guint *size, GstBufferMapFlags);
+ gboolean gst_meta_memory_unmap (GstMetaMemory *, gpointer data, guint size);
+
+
+GstMeta derived structures define the API of the metadata. The API can consist of
+fields and/or methods. It is possible to have different implementations for the
+same GstMeta structure.
+
+The implementation of the GstMeta api would typically add more fields to the
+public structure that allow it to implement the API. For example:
+
+ struct _GstMetaMemoryImpl {
+ GstMetaMemory memory;
- /* pointer to data and its size */
gpointer *data;
guint size;
gpointer *data_orig;
gpointer data_user;
};
-GstBufferMetaInfo will point to more information about the metadata and looks like this:
- struct _GstBufferMetaInfo {
+GstMetaInfo will point to more information about the metadata and looks like this:
+
+ struct _GstMetaInfo {
GQuark api; /* api name */
GQuark impl; /* implementation name */
gsize size; /* size of the structure */
- GstBufferMetaInfo *parent /* parent info */
GstMetaInitFunction init_func;
GstMetaFreeFunction free_func;
GstMetaConvFunction conv_func;
};
-Tag will contain a GQuark of the metadata name. We will be able to refer to specific
-metadata by name or by its (cached) GQuark. A repository of registered MetaInfo
+api will contain a GQuark of the metadata api. A repository of registered MetaInfo
will be maintained by the core. We will register some common metadata structures
in core and some media specific info for audio/video/text in -base. Plugins can
register additional custom metadata.
+For each implementation of api, there will thus be a unique GstMetaInfo. In the
+case of metadata with a well defined API, the implementation specific init
+function will setup the methods in the metadata structure.
+
Along with the metadata description we will have functions to initialize/free (and/or refcount)
-a specific GstBufferMeta instance. We also have the possibility to add a custom subbuffer
+a specific GstMeta instance. We also have the possibility to add a custom subbuffer
function that can be used to modify the metadata when a subbuffer is taken.
We also add serialize and deserialize function for the metadata in case we need special
+-------------------------------------+
GstMiniObject | GType (GstBuffer) |
- | refcount, flags, copy/free |
+ | refcount, flags, copy/disp/free |
+-------------------------------------+
-GstBuffer | caps, parent, subfunc |
+GstBuffer | caps, parent |
+.....................................+
| next ---+
- | parent ------> NULL
- +- | info ------> GstBufferMetaInfo
-GstBufferMetaTiming | | | |
+ +- | info ------> GstMetaInfo
+GstMetaTiming | | | |
| | dts | |
| | pts | |
| | duration | |
+- | clock_rate | |
+ . . . . . . . . . . . . . . . . . . + |
| next <--+
- | parent ------> NULL
-GstBufferMetaMemory +- | info ------> GstBufferMetaInfo
- | | | |
+GstMetaMemory +- +- | info ------> GstMetaInfo
+ | | | | |
+ | | | mmap | |
+ | | | munmap | |
+ +- | | | |
| | data | |
- | | size | |
+GstMetaMemoryImpl | | size | |
| | mallocdata | |
| | data_free | |
+- | data_user | |
Buffers are created using the normal gst_buffer_new functions. The standard fields
are initialized as usual. A memory area that is bigger than the structure size
-is allocated for the buffer metadata. The remaining free area is stored in the
-free_size field.
+is allocated for the buffer metadata.
gst_buffer_new ();
-After creating a buffer, the application can set caps. and add other metadata
+After creating a buffer, the application can set caps and add metadata
information.
-In order to modify metadata, a reference to the MetaInfo should be obtained.
-This can be done like this:
+To add or retrieve metadata, a handle to a GstMetaInfo structure needs to be
+obtained. This defines the implementation and API of the metadata. Usually, a
+handle to this info structure can be obtained by callnig a public _get_info()
+method from a shared library (for shared metadata).
- GstBufferMetaInfo *info;
+The following defines can usually be found in the shared .h file.
- info = gst_buffer_meta_get_info (GQuark tag);
+ GstMetaInfo * gst_meta_timing_get_info();
+ #define GST_META_TIMING_INFO (gst_meta_timing_get_info())
-Usually the info will be obtained only once in order to avoid lock contention on
-the global pool of meta info. The core will also provide convenience functions
-for the core metainfo.
+Retrieving and/or creating the metadata on a buffer can be done with the
+gst_buffer_meta_get() method. This function retrieves an existing metadata
+conforming to the API spcified in the given info. When no such metadata exists
+and the last gboolean argument is true, a new metadata item will be created from
+the info and added to the buffer.
-Once a reference to the info has been obtained, the associated metadata can be
-added or modified on a buffer.
+ GstMetaTiming *timing;
-For example, to modify the timing info on a buffer, one could use the following
-sequence:
+ timing = gst_buffer_get_meta (buffer, GST_META_TIMING_INFO, TRUE);
- GstBufferMetaInfo *info;
- GstBufferMetaTiming *timing;
+Once a reference to the info has been obtained, the associated metadata can be
+added or modified on a buffer.
- info = gst_buffer_meta_get_info (GST_META_TIMING_QUARK);
-
- timing = gst_buffer_get_meta (buffer, info, TRUE); /* TRUE = create if absent */
timing->timestamp = 0;
timing->duration = 20 * GST_MSECOND;
-The _get_meta() function returns a pointer to the metadata structure associated
-with the GST_META_TIMING_QUARK info.
+Other convenience macros can be made to simplify the above code:
+
+ #define gst_buffer_get_meta_timing(b,c) \
+ ((GstMetaTiming *) gst_buffer_get_meta ((b), GST_META_TIMING_INFO, (c))
-For the core meta info, we will provide convenience code that uses the cached
-GstBufferMetaInfo, making the above code a little more simple.
+This makes the code look like this:
- GstBufferMetaTiming *timing;
+ GstMetaTiming *timing;
timing = gst_buffer_get_meta_timing (buffer, TRUE); /* TRUE = create if absent */
timing->timestamp = 0;
timing->duration = 20 * GST_MSECOND;
-Note that for each of the metadata that we will add to buffers, we need a struct
-definition and a registered MetaInfo.
-
We will also provide an API to iterate the different metainfo structures. A
possible simple API would look like this:
- GstBufferMeta *current = NULL;
+ GstMeta *current = NULL;
/* passing NULL gives the first entry */
current = gst_buffer_meta_get_next (buffer, current);
- /* passing a GstBufferMeta returns the next */
+ /* passing a GstMeta returns the next */
current = gst_buffer_meta_get_next (buffer, current);
* allocation
We will initially allocate a reasonable sized GstBuffer structure (say 512
- bytes) and we will set the free_size to the maximum amount of metadata we can
- store.
+ bytes).
Since the complete buffer structure, including a large area for metadata, is
allocated in one go, we can reduce the number of memory allocations while still
structure. This can be useful when a structure is shared between buffers.
When the free_size of the GstBuffer is exhausted, we will allocate new memory
- for each newly added BufferMeta and use the next pointers to point to this. It
+ for each newly added Meta and use the next pointers to point to this. It
is expected that this does not occur often and we might be able to optimize
this transparently in the future.
Other use cases
~~~~~~~~~~~~~~~
-Making the GstBufferMetaMemory (for making the buffer point to the associated
+Making the GstMetaMemory (for making the buffer point to the associated
memory region) as metadata on a GstBuffer, as opposed to making it an integral
part of GstBuffer, allows for some more interesting ways to transfer data.
-We could for example make a new GstBufferMetaIOVec metadata structure like this:
+We could for example make a new GstMetaIOVec metadata structure like this:
- struct _GstBufferMetaIOVec {
- GstBufferMeta meta;
+ struct _GstMetaIOVec {
+ GstMeta meta;
/* pointer to data and its size */
GFreeFunc data_free;
This is particulary important when the metadata describes the data layout in
memory (such as strides).
-Currently the only way to communicate buffer formats between elements is by
-using caps. We would like to use the caps system to negotiate the metadata that
-will be put on buffers.
-
-We would like to add to the caps on the buffer (and pad) an array of metadata
-structures (as strings) that is on the buffer. This way, an element can
-quickly know what metadata to look for.
+We would like to use the bufferpool negotiation system to negotiate the possible
+metadata that can be exchanged between elements.
-In order to remain compatibility with older plugins we need to convert buffers
-that use metadata to specify a non-standard data layout to the old format. We
-need to do this before handing buffers to old elements. We will require elements
-that are metadata aware to set a flag on their pads; any buffer passed on that
-pad will be converted to the old layout when the flag is not set.
+When deciding the allocation properties, we will also negotiate the buffer
+metadata structures that we can exchange.
Notes
};
struct GstBufferVideoMeta {
- GstBufferMeta meta
+ GstMeta meta
GstBufferVideoFlags flags
projects / platform / upstream / gstreamer.git / commitdiff