Commit c1a38be6 authored by Wim Taymans's avatar Wim Taymans
Browse files

docs: update docs

parent 35241f35
......@@ -74,7 +74,7 @@ Data access
The _map and _unmap function will always return the memory of all blocks as one
large contiguous region of memory. Using the _map and _unmap function might be
more convenient that accessing the individual memory blocks at the expense of
more convenient than accessing the individual memory blocks at the expense of
being more expensive because it might perform memcpy operations.
For buffers with only one GstMemory object (the most common case), _map and
......
......@@ -110,10 +110,10 @@ Allocation query
- a buffer pool when need-pool was TRUE and the peer can provide a pool.
This pool is inactive and can be configured when needed.
(out) "metadata", G_TYPE_VALUE_ARRAY of G_TYPE_STRING
(out) "metadata", G_TYPE_ARRAY of G_TYPE_STRING
- an array of metadata API strings that can be accepted.
(out) "allocator", G_TYPE_VALUE_ARRAY of G_TYPE_STRING
(out) "allocator", G_TYPE_ARRAY of G_TYPE_STRING
- an array of allocators that can be used.
......
......@@ -17,25 +17,27 @@ Requirements
Allocators
~~~~~~~~~~
GstMemory objects are created by allocators. Allocators are registered to the
memory system with a set of methods contained in a GstMemoryInfo structure.
GstMemory objects are created by allocators. Allocators are created from
a GstMemoryInfo structure.
struct _GstMemoryInfo {
GstMemoryAllocFunction alloc;
GstMemoryGetSizesFunction get_sizes;
GstMemoryResizeFunction resize;
GstMemoryMapFunction map;
GstMemoryUnmapFunction unmap;
GstMemoryFreeFunction free;
GstMemoryCopyFunction copy;
GstMemoryShareFunction share;
GstMemoryIsSpanFunction is_span;
gpointer user_data;
const gchar *mem_type;
GstAllocatorAllocFunction alloc;
GstMemoryMapFunction mem_map;
GstMemoryUnmapFunction mem_unmap;
GstMemoryFreeFunction mem_free;
GstMemoryCopyFunction mem_copy;
GstMemoryShareFunction mem_share;
GstMemoryIsSpanFunction mem_is_span;
};
After an allocator is registerd, new GstMemory can be created with
Allocators are refcounted. It is also possible to register the allocator to the
GStreamer system. This way, the allocator can be retrieved by name.
After an allocator is created, new GstMemory can be created with
GstMemory * gst_allocator_alloc (const GstAllocator * allocator,
gsize maxsize, gsize align);
......@@ -46,9 +48,11 @@ Allocators
It is also possible to create a new GstMemory object that wraps existing
memory with:
GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
GFreeFunc free_func, gsize maxsize,
gsize offset, gsize size);
GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags,
gpointer data, gsize maxsize,
gsize offset, gsize size,
gpointer user_data,
GDestroyNotify notify);
Lifecycle
~~~~~~~~~
......@@ -59,9 +63,6 @@ has a refcount of 1.
Each variable holding a reference to the GstMemory object is responsible for
updating the refcount.
The refcount determines the writability of the object. If the refcount > 1, it is
by definition used by multipled objects and thus cannot be safely written to.
When the refcount reaches 0, and thus no objects hold a reference anymore, we
can free the memory. The GstMemoryFreeFunction of the allocator will be called
to cleanup the memory.
......@@ -93,13 +94,6 @@ Memory layout
void gst_memory_resize (GstMemory *mem, gssize offset, gsize size);
The memory object is always readable. The memory block is writable when:
- the refcount is exactly 1
- the memory object has no parent, or if it has a parent, the parent is
writable.
- the memory object is not marked as READONLY.
Data Access
~~~~~~~~~~~
......@@ -109,10 +103,10 @@ Data Access
the required memory mappings when needed.
Mapping a memory region requires the caller to specify the access method: READ
and/or WRITE. For write access, the GstMemory object must be writable.
and/or WRITE.
After the data has been accessed in the object, the unmap call must be
performed. The call will update the new memory size with the specified size.
performed.
It is allowed to map multiple times with different access modes. for each of
the map calls, an corresponding unmap call needs to be made. WRITE-only memory
......@@ -127,11 +121,9 @@ Data Access
is valid until the last unmap call is done.
When the final reference on a memory object is dropped, all outstanding
mappings are automatically unmapped.
Resizing a GstMemory does not influence any current mappings an any way. Note
however that the unmap call can resize the buffer again.
mappings should have been unmapped.
Resizing a GstMemory does not influence any current mappings an any way.
Copy
~~~~
......
......@@ -120,7 +120,7 @@ public structure that allow it to implement the API.
GstMetaInfo will point to more information about the metadata and looks like this:
struct _GstMetaInfo {
GQuark api; /* api name */
GType api; /* api type */
GType type; /* implementation type */
gsize size; /* size of the structure */
......@@ -129,7 +129,7 @@ GstMetaInfo will point to more information about the metadata and looks like thi
GstMetaTransformFunction transform_func;
};
api will contain a GQuark of the metadata api. A repository of registered MetaInfo
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.
......@@ -369,11 +369,11 @@ We need to make sure that elements exchange metadata that they both understand,
This is particulary important when the metadata describes the data layout in
memory (such as strides).
We would like to use the bufferpool negotiation system to negotiate the possible
metadata that can be exchanged between elements.
The ALLOCATION query is used to let upstream know what metadata we can suport.
When deciding the allocation properties, we will also negotiate the buffer
metadata structures that we can exchange.
It is also possible to have a bufferpool add certain metadata to the buffers
from the pool. This feature is activated by enabling a buffer option when
configuring the pool.
Notes
......
......@@ -186,8 +186,8 @@ The most common dataflow is the push model. The pull model can be used in specif
circumstances by demuxer elements. The pull model can also be used by low latency
audio applications.
The data passed between pads is encapsulated in Buffers. The buffer contains a
pointer to the actual data and also metadata describing the data. This metadata
The data passed between pads is encapsulated in Buffers. The buffer contains
pointers to the actual memory and also metadata describing the memory. This metadata
includes:
- timestamp of the data, this is the time instance at which the data was captured
......@@ -208,8 +208,7 @@ Before an element pushes out a buffer, it should make sure that the peer element
can understand the buffer contents. It does this by querying the peer element
for the supported formats and by selecting a suitable common format. The selected
format is then first sent to the peer element with a CAPS event before pushing
the buffer.
the buffer (see part-negotiation.txt).
When an element pad receives a CAPS event, it has to check if it understand the
media type. The element must refuse following buffers if the media type
......
......@@ -60,7 +60,7 @@ A sinkpad can ask the upstream srcpad for its scheduling attributes. It does
this with the SCHEDULING query.
(out) "modes", G_TYPE_VALUE_ARRAY (default NULL)
(out) "modes", G_TYPE_ARRAY (default NULL)
- an array of GST_TYPE_PAD_MODE enums. Contains all the supported
scheduling modes.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment