mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-04-23 17:14:23 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs: update docs

Browse source
This commit is contained in:
Wim Taymans 2012-03-09 14:30:01 +01:00
parent 35241f35c0
commit c1a38be6e2
6 changed files with 37 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/design/part-buffer.txt
View file

@ -74,7 +74,7 @@ Data access
The _map and _unmap function will always return the memory of all blocks as one 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 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. being more expensive because it might perform memcpy operations.
For buffers with only one GstMemory object (the most common case), _map and For buffers with only one GstMemory object (the most common case), _map and

4
docs/design/part-bufferpool.txt
View file

@ -110,10 +110,10 @@ Allocation query
- a buffer pool when need-pool was TRUE and the peer can provide a pool. - 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. 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. - 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. - an array of allocators that can be used.

56
docs/design/part-memory.txt
View file

@ -17,25 +17,27 @@ Requirements
Allocators Allocators
~~~~~~~~~~ ~~~~~~~~~~
GstMemory objects are created by allocators. Allocators are registered to the GstMemory objects are created by allocators. Allocators are created from
memory system with a set of methods contained in a GstMemoryInfo structure. a GstMemoryInfo structure.
struct _GstMemoryInfo { struct _GstMemoryInfo {
GstMemoryAllocFunction alloc; const gchar *mem_type;
GstMemoryGetSizesFunction get_sizes;
GstMemoryResizeFunction resize;
GstMemoryMapFunction map;
GstMemoryUnmapFunction unmap;
GstMemoryFreeFunction free;
GstMemoryCopyFunction copy; GstAllocatorAllocFunction alloc;
GstMemoryShareFunction share;
GstMemoryIsSpanFunction is_span;
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, GstMemory * gst_allocator_alloc (const GstAllocator * allocator,
gsize maxsize, gsize align); gsize maxsize, gsize align);
@ -46,9 +48,11 @@ Allocators
It is also possible to create a new GstMemory object that wraps existing It is also possible to create a new GstMemory object that wraps existing
memory with: memory with:
GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data, GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags,
GFreeFunc free_func, gsize maxsize, gpointer data, gsize maxsize,
gsize offset, gsize size); gsize offset, gsize size,
gpointer user_data,
GDestroyNotify notify);
Lifecycle Lifecycle
~~~~~~~~~ ~~~~~~~~~
@ -59,9 +63,6 @@ has a refcount of 1.
Each variable holding a reference to the GstMemory object is responsible for Each variable holding a reference to the GstMemory object is responsible for
updating the refcount. 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 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 can free the memory. The GstMemoryFreeFunction of the allocator will be called
to cleanup the memory. to cleanup the memory.
@ -93,13 +94,6 @@ Memory layout
void gst_memory_resize (GstMemory *mem, gssize offset, gsize size); 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 Data Access
~~~~~~~~~~~ ~~~~~~~~~~~
@ -109,10 +103,10 @@ Data Access
the required memory mappings when needed. the required memory mappings when needed.
Mapping a memory region requires the caller to specify the access method: READ 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 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 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 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. is valid until the last unmap call is done.
When the final reference on a memory object is dropped, all outstanding When the final reference on a memory object is dropped, all outstanding
mappings are automatically unmapped. mappings should have been unmapped.
Resizing a GstMemory does not influence any current mappings an any way. Note
however that the unmap call can resize the buffer again.
Resizing a GstMemory does not influence any current mappings an any way.
Copy Copy
~~~~ ~~~~

12
docs/design/part-meta.txt
View file

@ -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: GstMetaInfo will point to more information about the metadata and looks like this:
struct _GstMetaInfo { struct _GstMetaInfo {
GQuark api; /* api name */ GType api; /* api type */
GType type; /* implementation type */ GType type; /* implementation type */
gsize size; /* size of the structure */ 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; 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 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 in core and some media specific info for audio/video/text in -base. Plugins can
register additional custom metadata. 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 This is particulary important when the metadata describes the data layout in
memory (such as strides). memory (such as strides).
We would like to use the bufferpool negotiation system to negotiate the possible The ALLOCATION query is used to let upstream know what metadata we can suport.
metadata that can be exchanged between elements.
When deciding the allocation properties, we will also negotiate the buffer It is also possible to have a bufferpool add certain metadata to the buffers
metadata structures that we can exchange. from the pool. This feature is activated by enabling a buffer option when
configuring the pool.
Notes Notes

7
docs/design/part-overview.txt
View file

@ -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 circumstances by demuxer elements. The pull model can also be used by low latency
audio applications. audio applications.
The data passed between pads is encapsulated in Buffers. The buffer contains a The data passed between pads is encapsulated in Buffers. The buffer contains
pointer to the actual data and also metadata describing the data. This metadata pointers to the actual memory and also metadata describing the memory. This metadata
includes: includes:
- timestamp of the data, this is the time instance at which the data was captured - 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 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 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 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 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 media type. The element must refuse following buffers if the media type

2
docs/design/part-scheduling.txt
View file

@ -60,7 +60,7 @@ A sinkpad can ask the upstream srcpad for its scheduling attributes. It does
this with the SCHEDULING query. 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 - an array of GST_TYPE_PAD_MODE enums. Contains all the supported
scheduling modes. scheduling modes.