From 737dced0df79609f94a04849179ef3e717548a2c Mon Sep 17 00:00:00 2001 From: "Reynaldo H. Verdejo Pinochet" Date: Tue, 27 Dec 2016 19:44:05 -0800 Subject: [PATCH] design: meta: add missing markup and improve formatting and grammar --- markdown/design/meta.md | 64 ++++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/markdown/design/meta.md b/markdown/design/meta.md index 8e92d561c6..f6f46a4a42 100644 --- a/markdown/design/meta.md +++ b/markdown/design/meta.md @@ -34,7 +34,7 @@ Some examples of metadata: - 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 @@ -52,7 +52,7 @@ blitting the image on the screen with little overhead. ## GstMeta -A GstMeta is a structure as follows: +A `GstMeta` is a structure as follows: ``` c 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, such as timing metadata, will have this structure as the first field. For example: @@ -81,7 +81,7 @@ Or another example for the video memory regions that consists of both fields and methods. ``` c - #define GST_VIDEO_MAX_PLANES 4 +#define GST_VIDEO_MAX_PLANES 4 struct GstMetaVideo { 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); ``` -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 @@ -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 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. @@ -205,7 +205,7 @@ GstMetaVideoImpl | | ... | | ## 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. @@ -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 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. @@ -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 `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. @@ -304,28 +304,28 @@ NONE in the MetaTiming structures. 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 @@ -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 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.