diff --git a/docs/design/part-buffer.txt b/docs/design/part-buffer.txt index b6568ed782..81feea02ec 100644 --- a/docs/design/part-buffer.txt +++ b/docs/design/part-buffer.txt @@ -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 diff --git a/docs/design/part-bufferpool.txt b/docs/design/part-bufferpool.txt index 5bd4b8cdbf..a74f1ff611 100644 --- a/docs/design/part-bufferpool.txt +++ b/docs/design/part-bufferpool.txt @@ -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. diff --git a/docs/design/part-memory.txt b/docs/design/part-memory.txt index 981616c9de..4870662c60 100644 --- a/docs/design/part-memory.txt +++ b/docs/design/part-memory.txt @@ -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 ~~~~ diff --git a/docs/design/part-meta.txt b/docs/design/part-meta.txt index 9fd576ec19..3ea6a3e2c0 100644 --- a/docs/design/part-meta.txt +++ b/docs/design/part-meta.txt @@ -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 diff --git a/docs/design/part-overview.txt b/docs/design/part-overview.txt index a51471a51c..ddc97572dd 100644 --- a/docs/design/part-overview.txt +++ b/docs/design/part-overview.txt @@ -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 diff --git a/docs/design/part-scheduling.txt b/docs/design/part-scheduling.txt index 2633072367..a4fbdb7968 100644 --- a/docs/design/part-scheduling.txt +++ b/docs/design/part-scheduling.txt @@ -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.