mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-04-26 06:54:49 +00:00
Code Issues 1 Projects Releases Wiki Activity

design: meta: add missing markup and improve formatting and grammar

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2016-12-27 19:44:05 -08:00
parent 3b3837aa33
commit 737dced0df
1 changed files with 32 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
markdown/design/meta.md
View file

@ -34,7 +34,7 @@ Some examples of metadata:
- We should be able to negotiate metadata between elements - We should be able to negotiate metadata between elements
# Use cases ## Use cases
- **Video planes**: Video data is sometimes allocated in non-contiguous planes - **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 for the Y and the UV data. We need to be able to specify the data on a buffer
@ -52,7 +52,7 @@ blitting the image on the screen with little overhead.
## GstMeta ## GstMeta
A GstMeta is a structure as follows: A `GstMeta` is a structure as follows:
``` c ``` c
struct _GstMeta { struct _GstMeta {
@ -61,7 +61,7 @@ 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, metadata information that we can attach to a buffer. Specific metadata,
such as timing metadata, will have this structure as the first field. such as timing metadata, will have this structure as the first field.
For example: For example:
@ -81,7 +81,7 @@ Or another example for the video memory regions that consists of both
fields and methods. fields and methods.
``` c ``` c
#define GST_VIDEO_MAX_PLANES 4 #define GST_VIDEO_MAX_PLANES 4
struct GstMetaVideo { struct GstMetaVideo {
GstMeta meta; GstMeta meta;
@ -110,14 +110,14 @@ gpointer gst_meta_video_map (GstMetaVideo *meta, guint plane, gpointer * data,
gboolean gst_meta_video_unmap (GstMetaVideo *meta, guint plane, gpointer data); 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 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. 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: like this:
``` c ``` c
@ -132,39 +132,39 @@ struct _GstMetaInfo {
}; };
``` ```
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 MetaInfo will be maintained by the core. We will register some common
metadata structures in core and some media specific info for metadata structures in core and some media specific info for
audio/video/text in -base. Plugins can register additional custom audio/video/text in -base. Plugins can register additional custom
metadata. 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 In the case of metadata with a well defined API, the implementation
specific init function will setup the methods in the metadata structure. 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. type field.
Along with the metadata description we will have functions to 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 have the possibility to add a custom transform function that can be used
to modify the metadata when a transformation happens. to modify the metadata when a transformation happens.
There are no explicit methods to serialize and deserialize the metadata. 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. 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. 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 We still want quick access to the info so we need to make the buffer
metadata point to the info. 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 and provide a generic API to retrieve the metadata fields without the
need for a header file. We will not do this yet. need for a header file. We will not do this yet.
Allocation of the GstBuffer structure will result in the allocation of a Allocation of the `GstBuffer` structure will result in the allocation of a
memory region of a customizable size (512 bytes). Only the first sizeof memory region of a customizable size (512 bytes). Only the first `sizeof
(GstBuffer) bytes of this region will initially be used. The remaining (GstBuffer)` bytes of this region will initially be used. The remaining
bytes will be part of the free metadata region of the buffer. Different bytes will be part of the free metadata region of the buffer. Different
implementations are possible and are invisible in the API or ABI. implementations are possible and are invisible in the API or ABI.
@ -205,7 +205,7 @@ GstMetaVideoImpl | | ... | |
## API examples ## 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 standard fields are initialized as usual. A memory area that is bigger
than the structure size is allocated for the buffer metadata. than the structure size is allocated for the buffer metadata.
@ -216,10 +216,10 @@ than the structure size is allocated for the buffer metadata.
After creating a buffer, the application can set caps and add metadata After creating a buffer, the application can set caps and add metadata
information. 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. 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 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. The following defines can usually be found in the shared .h file.
@ -230,7 +230,7 @@ The following defines can usually be found in the shared .h file.
Adding metadata to a buffer can be done with the Adding metadata to a buffer can be done with the
`gst_buffer_add_meta()` call. This function will create new metadata `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 possible to pass a generic pointer to the `add_meta()` function that can
contain parameters to initialize the new metadata fields. contain parameters to initialize the new metadata fields.
@ -304,28 +304,28 @@ NONE in the MetaTiming structures.
The init/free functions can also be used to implement refcounting for a metadata 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. 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 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 is expected that this does not occur often and we might be able to optimize
this transparently in the future. this transparently in the future.
### free ### 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 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 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 ## 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 need a way to perform custom serialization and deserialization on the
metadata. metadata.
for this we can use the GValue transform functions. for this we can use the `GValue` transform functions.
## Transformations ## Transformations
@ -357,15 +357,15 @@ implement the actions needed to update the metadata of the subbuffer.
It might not make sense for some metadata to work with subbuffers. For 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 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. subbuffer.
## Relationship with GstCaps ## 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. 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 to functionally negotiate the format between two elements. The Metadata
should then only contain variables that can change between each buffer. should then only contain variables that can change between each buffer.