- We should be able to negotiate metadata between elements
-# Use cases
+## Use cases
- **Video planes**: Video data is sometimes allocated in non-contiguous planes
for the Y and the UV data. We need to be able to specify the data on a buffer
## GstMeta
-A GstMeta is a structure as follows:
+A `GstMeta` is a structure as follows:
``` c
struct _GstMeta {
};
```
-The purpose of the this structure is to serve as a common header for all
+The purpose of 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:
fields and methods.
``` c
- #define GST_VIDEO_MAX_PLANES 4
+#define GST_VIDEO_MAX_PLANES 4
struct GstMetaVideo {
GstMeta meta;
gboolean gst_meta_video_unmap (GstMetaVideo *meta, guint plane, gpointer data);
```
-GstMeta derived structures define the API of the metadata. The API can
+`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.
+implementations for the same `GstMeta` structure.
-The implementation of the GstMeta API would typically add more fields to
+The implementation of the `GstMeta` API would typically add more fields to
the public structure that allow it to implement the API.
-GstMetaInfo will point to more information about the metadata and looks
+`GstMetaInfo` will point to more information about the metadata and looks
like this:
``` c
};
```
-api will contain a GType of the metadata API. A repository of registered
+api will contain a `GType` 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.
+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.
-A unique GType will be made for each implementation and stored in the
+A unique `GType` will be made for each implementation and stored in the
type field.
Along with the metadata description we will have functions to
-initialize/free (and/or refcount) a specific GstMeta instance. We also
+initialize/free (and/or refcount) a specific `GstMeta` instance. We also
have the possibility to add a custom transform function that can be used
to modify the metadata when a transformation happens.
There are no explicit methods to serialize and deserialize the metadata.
-Since each type has a GType, we can reuse the GValue transform functions
+Since each type has a `GType`, we can reuse the `GValue` transform functions
for this.
-The purpose of the separate MetaInfo is to not have to carry the
+The purpose of the separate `MetaInfo` is to not have to carry the
free/init functions in each buffer instance but to define them globally.
We still want quick access to the info so we need to make the buffer
metadata point to the info.
-Technically we could also specify the field and types in the MetaInfo
+Technically we could also specify the field and types in the `MetaInfo`
and provide a generic API to retrieve the metadata fields without the
need for a header file. We will not do this yet.
-Allocation of the GstBuffer structure will result in the allocation of a
-memory region of a customizable size (512 bytes). Only the first sizeof
-(GstBuffer) bytes of this region will initially be used. The remaining
+Allocation of the `GstBuffer` structure will result in the allocation of a
+memory region of a customizable size (512 bytes). Only the first `sizeof
+(GstBuffer)` bytes of this region will initially be used. The remaining
bytes will be part of the free metadata region of the buffer. Different
implementations are possible and are invisible in the API or ABI.
## API examples
-Buffers are created using the normal gst\_buffer\_new functions. The
+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.
After creating a buffer, the application can set caps and add metadata
information.
-To add or retrieve metadata, a handle to a GstMetaInfo structure needs
+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 calling a
-public `_get\_info()` method from a shared library (for shared metadata).
+public `_get_info()` method from a shared library (for shared metadata).
The following defines can usually be found in the shared .h file.
Adding metadata to a buffer can be done with the
`gst_buffer_add_meta()` call. This function will create new metadata
-based on the implementation specified by the GstMetaInfo. It is also
+based on the implementation specified by the `GstMetaInfo`. It is also
possible to pass a generic pointer to the `add_meta()` function that can
contain parameters to initialize the new metadata fields.
The init/free functions can also be used to implement refcounting for a metadata
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
+When the `free_size` of the `GstBuffer` is exhausted, we will allocate new memory
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.
### free
-When a GstBuffer is freed, we potentially might have to call a custom free
+When a `GstBuffer` is freed, we potentially might have to call a custom `free()`
function on the metadata info. In the case of the Memory metadata, we need to
-call the associated free function to free the memory.
+call the associated `free()` function to free the memory.
-When freeing a GstBuffer, the custom buffer free function will iterate all of
+When freeing a `GstBuffer`, the custom buffer free function will iterate all of
the metadata in the buffer and call the associated free functions in the
-MetaInfo associated with the entries. Usually, this function will be NULL.
+`MetaInfo` associated with the entries. Usually, this function will be NULL.
## Serialization
-When buffer should be sent over the wire or be serialized in GDP, we
+When a buffer should be sent over the wire or be serialized in GDP, we
need a way to perform custom serialization and deserialization on the
metadata.
-for this we can use the GValue transform functions.
+for this we can use the `GValue` transform functions.
## Transformations
It might not make sense for some metadata to work with subbuffers. For
example when we take a subbuffer of a buffer with a video frame, the
-GstMetaVideo simply becomes invalid and is removed from the new
+`GstMetaVideo` simply becomes invalid and is removed from the new
subbuffer.
## Relationship with GstCaps
-The difference between GstCaps, used in negotiation, and the metadata is
+The difference between `GstCaps`, used in negotiation, and the metadata is
not clearly defined.
-We would like to think of the GstCaps containing the information needed
+We would like to think of the `GstCaps` containing the information needed
to functionally negotiate the format between two elements. The Metadata
should then only contain variables that can change between each buffer.
projects / platform / upstream / gstreamer.git / commitdiff