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);
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
~~~~~~~~~
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.
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
~~~~~~~~~~~
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
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
~~~~
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 */
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.
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
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
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
projects / platform / upstream / gstreamer.git / commitdiff