mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-01-31 03:29:50 +00:00
docs: update docs
This commit is contained in:
Wim Taymans
parent
35241f35c0
commit
c1a38be6e2
6 changed files with 37 additions and 46 deletions
|
|
@ -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;
|
||||
const gchar *mem_type;
|
||||
|
||||
GstMemoryCopyFunction copy;
|
||||
GstMemoryShareFunction share;
|
||||
GstMemoryIsSpanFunction is_span;
|
||||
GstAllocatorAllocFunction alloc;
|
||||
|
||||
gpointer user_data;
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue