Skip to content

GitLab

gstreamer
gstreamer
Commit 800def04 authored by Wim Taymans's avatar Wim Taymans
Browse files
Options

docs: update documentation

parent ebb14d95
Hide whitespace changes
Inline Side-by-side
Showing with 386 additions and 75 deletions
docs/gst/gstreamer-docs.sgml
View file @ 800def04
......@@ -79,6 +79,7 @@ Windows. It is released under the GNU Library General Public License
<xi:include href="xml/gstindex.xml" />
<xi:include href="xml/gstindexfactory.xml" />
<xi:include href="xml/gstiterator.xml" />
<xi:include href="xml/gstmemory.xml" />
<xi:include href="xml/gstmessage.xml" />
<xi:include href="xml/gstmeta.xml" />
<xi:include href="xml/gstminiobject.xml" />
......
docs/gst/gstreamer-sections.txt
View file @ 800def04
......@@ -1228,6 +1228,49 @@ gst_iterator_result_get_type
</SECTION>
<SECTION>
<FILE>gstmemory</FILE>
<TITLE>GstMemory</TITLE>
GstMemory
GstMemoryInfo
GstMemoryImpl
GST_MEMORY_IS_WRITABLE
GstMemoryFlags
GstMapFlags
GST_MAP_READWRITE
GstMemoryGetSizesFunction
GstMemoryResizeFunction
GstMemoryMapFunction
GstMemoryUnmapFunction
GstMemoryFreeFunction
GstMemoryCopyFunction
GstMemoryShareFunction
GstMemoryIsSpanFunction
gst_memory_new_wrapped
gst_memory_new_alloc
gst_memory_new_copy
gst_memory_ref
gst_memory_unref
gst_memory_get_sizes
gst_memory_resize
gst_memory_map
gst_memory_unmap
gst_memory_copy
gst_memory_share
gst_memory_is_span
gst_memory_span
gst_memory_register
gst_memory_get_info
<SUBSECTION Standard>
GST_MEMORY_TRACE_NAME
</SECTION>
<SECTION>
<FILE>gstmessage</FILE>
<TITLE>GstMessage</TITLE>
......
docs/plugins/gstreamer-plugins.hierarchy
View file @ 800def04
GObject
GstObject
GstBus
GstClock
GstElement
GstBaseSink
GstFakeSink
GstFdSink
GstFileSink
GstBaseSrc
GstFakeSrc
GstFileSrc
GstPushSrc
GstFdSrc
GstBaseTransform
GstCapsFilter
GstIdentity
GstBin
GstPipeline
GstInputSelector
GstMultiQueue
GstOutputSelector
GstQueue
GstQueue2
GstTee
GstTypeFindElement
GstValve
GstIndex
GstFileIndex
GstMemIndex
GstPad
GstPadTemplate
GstPlugin
GstPluginFeature
GstElementFactory
GstIndexFactory
GstTypeFindFactory
GstRegistry
GstTask
GstTaskPool
GstSignalObject
GInitiallyUnowned
GstObject
GstPad
GstPadTemplate
GstPluginFeature
GstElementFactory
GstTypeFindFactory
GstIndexFactory
GstElement
GstBin
GstPipeline
GstBaseTransform
GstCapsFilter
GstIdentity
GstBaseSrc
GstFakeSrc
GstPushSrc
GstFdSrc
GstFileSrc
GstBaseSink
GstFakeSink
GstFdSink
GstFileSink
GstInputSelector
GstOutputSelector
GstQueue
GstQueue2
GstTee
GstTypeFindElement
GstMultiQueue
GstValve
GstBus
GstTask
GstTaskPool
GstClock
GstPlugin
GstRegistry
GstIndex
GstMemIndex
GstFileIndex
GInterface
GTypePlugin
GstChildProxy
......
gst/gstmemory.c
View file @ 800def04
......@@ -19,12 +19,43 @@
* Boston, MA 02111-1307, USA.
*/
#include "config.h"
/**
* SECTION:gstmemory
* @short_description: refcounted wrapper for memory blocks
* @see_also: #GstBuffer
*
* GstMemory is a lightweight refcounted object that wraps a region of memory.
* They are typically used to manage the data of a #GstBuffer.
*
* New memory can be created with gst_memory_new_wrapped() that wraps the memory
* allocated elsewhere and gst_memory_new_alloc() that creates a new GstMemory
* and the memory inside it.
*
* Refcounting of the memory block is performed with gst_memory_ref() and
* gst_memory_unref().
*
* The size of the memory can be retrieved and changed with
* gst_memory_get_sizes() and gst_memory_resize() respectively.
*
* Getting access to the data of the memory is performed with gst_memory_map().
* After the memory access is completed, gst_memory_unmap() should be called.
*
* Memory can be copied with gst_memory_copy(), which will returnn a writable
* copy. gst_memory_share() will create a new memory block that shares the
* memory with an existing memory block at a custom offset and with a custom
* size.
*
* Memory can be efficiently merged when gst_memory_is_span() returns TRUE and
* with the function gst_memory_span().
*
* Last reviewed on 2011-03-30 (0.11.0)
*/
#include "config.h"
#include "gst_private.h"
#include "gstmemory.h"
struct _GstMemoryImpl
{
GQuark name;
......@@ -32,6 +63,7 @@ struct _GstMemoryImpl
GstMemoryInfo info;
};
/* default memory implementation */
typedef struct
{
GstMemory mem;
......@@ -46,6 +78,7 @@ typedef struct
static const GstMemoryImpl *_default_mem_impl;
static const GstMemoryImpl *_default_share_impl;
/* initialize the fields */
static void
_default_mem_init (GstMemoryDefault * mem, GstMemoryFlags flags,
GstMemory * parent, gsize slice_size, gpointer data,
......@@ -63,6 +96,7 @@ _default_mem_init (GstMemoryDefault * mem, GstMemoryFlags flags,
mem->size = size;
}
/* create a new memory block that manages the given memory */
static GstMemoryDefault *
_default_mem_new (GstMemoryFlags flags, GstMemory * parent, gpointer data,
GFreeFunc free_func, gsize maxsize, gsize offset, gsize size)
......@@ -79,6 +113,7 @@ _default_mem_new (GstMemoryFlags flags, GstMemory * parent, gpointer data,
return mem;
}
/* allocate the memory and structure in one block */
static GstMemoryDefault *
_default_mem_new_block (gsize maxsize, gsize align, gsize offset, gsize size)
{
......@@ -153,7 +188,8 @@ _default_share_map (GstMemoryDefault * mem, gsize * size, gsize * maxsize,
static gboolean
_default_mem_unmap (GstMemoryDefault * mem, gpointer data, gsize size)
{
mem->size = size;
if (size != -1)
mem->size = size;
return TRUE;
}
......@@ -163,7 +199,10 @@ _default_share_unmap (GstMemoryDefault * mem, gpointer data, gsize size)
gboolean res;
guint8 *ptr = data;
mem->size = size;
if (size != -1)
mem->size = size;
else
size = mem->size - mem->offset;
res =
gst_memory_unmap (mem->mem.parent, ptr - mem->offset, size + mem->offset);
......@@ -190,6 +229,7 @@ _default_mem_copy (GstMemoryDefault * mem, gsize offset, gsize size)
if (size == -1)
size = mem->size > offset ? mem->size - offset : 0;
copy = _default_mem_new_block (mem->maxsize, 0, mem->offset + offset, size);
memcpy (copy->data, mem->data, mem->maxsize);
......@@ -294,10 +334,13 @@ _gst_memory_init (void)
/**
* gst_memory_register:
* @name:
* @info:
* @name: the name of the implementation
* @info: #GstMemoryInfo
*
* Registers the memory implementation with @name and implementation functions
* @info.
*
* Returns:
* Returns: a new #GstMemoryImpl.
*/
const GstMemoryImpl *
gst_memory_register (const gchar * name, const GstMemoryInfo * info)
......@@ -334,17 +377,43 @@ gst_memory_register (const gchar * name, const GstMemoryInfo * info)
return impl;
}
/**
* gst_memory_new_wrapped:
* @flags: #GstMemoryFlags
* @data: data to wrap
* @free_func: function to free @data
* @maxsize: allocated size of @data
* @offset: offset in @data
* @size: size of valid data
*
* Allocate a new memory block that wraps the given @data.
*
* Returns: a new #GstMemory.
*/
GstMemory *
gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
GFreeFunc free_func, gsize maxsize, gsize offset, gsize size)
{
GstMemoryDefault *mem;
g_return_val_if_fail (data != NULL, NULL);
g_return_val_if_fail (offset + size <= maxsize, NULL);
mem = _default_mem_new (flags, NULL, data, free_func, maxsize, offset, size);
return (GstMemory *) mem;
}
/**
* gst_memory_new_alloc:
* @maxsize: allocated size of @data
* @align: alignment for the data
*
* Allocate a new memory block with memory that is at least @maxsize big and las
* the given alignment.
*
* Returns: a new #GstMemory.
*/
GstMemory *
gst_memory_new_alloc (gsize maxsize, gsize align)
{
......@@ -355,22 +424,12 @@ gst_memory_new_alloc (gsize maxsize, gsize align)
return (GstMemory *) mem;
}
GstMemory *
gst_memory_new_copy (gsize maxsize, gsize align, gpointer data,
gsize offset, gsize size)
{
GstMemoryDefault *mem;
mem = _default_mem_new_block (maxsize, align, offset, size);
memcpy (mem->data, data, maxsize);
return (GstMemory *) mem;
}
/**
* gst_memory_ref:
* @mem: a #GstMemory
*
* Increases the refcount of @mem.
*
* Returns: @mem with increased refcount
*/
GstMemory *
......@@ -386,6 +445,9 @@ gst_memory_ref (GstMemory * mem)
/**
* gst_memory_unref:
* @mem: a #GstMemory
*
* Decreases the refcount of @mem. When the refcount reaches 0, the free
* function of @mem will be called.
*/
void
gst_memory_unref (GstMemory * mem)
......@@ -402,7 +464,9 @@ gst_memory_unref (GstMemory * mem)
* @mem: a #GstMemory
* @maxsize: pointer to maxsize
*
* Returns: the current size of @mem
* Get the current @size and @maxsize of @mem.
*
* Returns: the current sizes of @mem
*/
gsize
gst_memory_get_sizes (GstMemory * mem, gsize * maxsize)
......@@ -412,15 +476,61 @@ gst_memory_get_sizes (GstMemory * mem, gsize * maxsize)
return mem->impl->info.get_sizes (mem, maxsize);
}
/**
* gst_memory_resize:
* @mem: a #GstMemory
* @offset: a new offset
* @size: a new size
*
* Resize the memory region. @mem should be writable and offset + size should be
* less than the maxsize of @mem.
*/
void
gst_memory_resize (GstMemory * mem, gsize offset, gsize size)
{
g_return_if_fail (mem != NULL);
g_return_if_fail (GST_MEMORY_IS_WRITABLE (mem));
mem->impl->info.resize (mem, offset, size);
}
/**
* gst_memory_map:
* @mem: a #GstMemory
* @size: pointer for size
* @maxsize: pointer for maxsize
* @flags: mapping flags
*
* Get a pointer to the memory of @mem that can be accessed according to @flags.
*
* @size and @maxsize will contain the size of the memory and the maximum
* allocated memory of @mem respectively. They can be set to NULL.
*
* Returns: a pointer to the memory of @mem.
*/
gpointer
gst_memory_map (GstMemory * mem, gsize * size, gsize * maxsize,
GstMapFlags flags)
{
g_return_val_if_fail (mem != NULL, NULL);
g_return_val_if_fail (!(flags & GST_MAP_WRITE) ||
GST_MEMORY_IS_WRITABLE (mem), NULL);
return mem->impl->info.map (mem, size, maxsize, flags);
}
/**
* gst_memory_unmap:
* @mem: a #GstMemory
* @data: data to unmap
* @size: new size of @mem
*
* Release the memory pointer obtained with gst_memory_map() and set the size of
* the memory to @size. @size can be set to -1 when the size should not be
* updated.
*
* Returns: TRUE when the memory was release successfully.
*/
gboolean
gst_memory_unmap (GstMemory * mem, gpointer data, gsize size)
{
......@@ -429,6 +539,18 @@ gst_memory_unmap (GstMemory * mem, gpointer data, gsize size)
return mem->impl->info.unmap (mem, data, size);
}
/**
* gst_memory_copy:
* @mem: a #GstMemory
* @offset: an offset to copy
* @size: size to copy
*
* Return a copy of @size bytes from @mem starting from @offset. This copy is
* guaranteed to be writable. @size can be set to -1 to return a copy all bytes
* from @offset.
*
* Returns: a new #GstMemory.
*/
GstMemory *
gst_memory_copy (GstMemory * mem, gsize offset, gsize size)
{
......@@ -437,14 +559,19 @@ gst_memory_copy (GstMemory * mem, gsize offset, gsize size)
return mem->impl->info.copy (mem, offset, size);
}
void
gst_memory_resize (GstMemory * mem, gsize offset, gsize size)
{
g_return_if_fail (mem != NULL);
mem->impl->info.resize (mem, offset, size);
}
/**
* gst_memory_share:
* @mem: a #GstMemory
* @offset: an offset to share
* @size: size to share
*
* Return a shared copy of @size bytes from @mem starting from @offset. No memory
* copy is performed and the memory region is simply shared. The result is
* guaranteed to be not-writable. @size can be set to -1 to return a share all bytes
* from @offset.
*
* Returns: a new #GstMemory.
*/
GstMemory *
gst_memory_share (GstMemory * mem, gsize offset, gsize size)
{
......@@ -453,6 +580,21 @@ gst_memory_share (GstMemory * mem, gsize offset, gsize size)
return mem->impl->info.share (mem, offset, size);
}
/**
* gst_memory_is_span:
* @mem1: a #GstMemory
* @mem2: a #GstMemory
* @offset: a pointer to a result offset
*
* Check if @mem1 and mem2 share the memory with a common parent memory object
* and that the memory is contiguous.
*
* If this is the case, the memory of @mem1 and @mem2 can be merged
* efficiently by performing gst_memory_share() on the parent object from
* the returned @offset.
*
* Returns: %TRUE if the memory is contiguous and of a common parent.
*/
gboolean
gst_memory_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
{
......
gst/gstmemory.h
View file @ 800def04
......@@ -33,11 +33,22 @@ typedef struct _GstMemory GstMemory;
typedef struct _GstMemoryInfo GstMemoryInfo;
typedef struct _GstMemoryImpl GstMemoryImpl;
/**
* GstMemoryFlags:
* @GST_MEMORY_FLAG_READONLY: memory is readonly
*
* Flags for wrapped memory.
*/
typedef enum {
GST_MEMORY_FLAG_READONLY = (1 << 0)
} GstMemoryFlags;
/**
* GST_MEMORY_IS_WRITABLE:
* @mem: a #GstMemory
*
* Check if @mem is writable.
*/
#define GST_MEMORY_IS_WRITABLE(mem) (((mem)->refcount == 1) && \
(((mem)->parent == NULL) || ((mem)->parent->refcount == 1)) && \
(((mem)->flags & GST_MEMORY_FLAG_READONLY) == 0))
......@@ -45,6 +56,7 @@ typedef enum {
/**
* GstMemory:
* @impl: pointer to the #GstMemoryImpl
* @flags: memory flags
* @refcount: refcount
* @parent: parent memory block
*
......@@ -59,11 +71,23 @@ struct _GstMemory {
GstMemory *parent;
};
/**
* GstMapFlags:
* @GST_MAP_READ: map for read access
* @GST_MAP_WRITE: map for write access
*
* Flags used when mapping memory
*/
typedef enum {
GST_MAP_READ = (1 << 0),
GST_MAP_WRITE = (1 << 1),
} GstMapFlags;
/**
* GST_MAP_READWRITE:
*
* Map for readwrite access
*/
#define GST_MAP_READWRITE (GST_MAP_READ | GST_MAP_WRITE)
/**
......@@ -73,23 +97,127 @@ typedef enum {
*/
#define GST_MEMORY_TRACE_NAME "GstMemory"
/**
* GstMemoryGetSizesFunction:
* @mem: a #GstMemory
* @maxsize: result pointer for maxsize
*
* Retrieve the size and maxsize of @mem.
*
* Returns: the size of @mem and the maximum allocated size in @maxsize.
*/
typedef gsize (*GstMemoryGetSizesFunction) (GstMemory *mem, gsize *maxsize);
/**
* GstMemoryResizeFunction:
* @mem: a #GstMemory
* @offset: the new offset
* @size: the new size
*
* Adjust the size and offset of @mem. @offset bytes will be skipped from the
* current first byte in @mem as retrieved with gst_memory_map() and the new
* size will be set to @size.
*
* @size can be set to -1, which will only adjust the offset.
*/
typedef void (*GstMemoryResizeFunction) (GstMemory *mem, gsize offset, gsize size);
/**
* GstMemoryMapFunction:
* @mem: a #GstMemory
* @size: pointer for the size
* @maxsize: pointer for the maxsize
* @flags: access mode for the memory
*
* Get the memory of @mem that can be accessed according to the mode specified
* in @flags. @size and @maxsize will respectively contain the current amount of
* valid bytes in the returned memory and the maximum allocated memory.
* @size and @maxsize can optionally be set to NULL.
*
* Returns: a pointer to memory. @size bytes are currently used from the
* returned pointer and @maxsize bytes can potentially be used.
*/
typedef gpointer (*GstMemoryMapFunction) (GstMemory *mem, gsize *size, gsize *maxsize,
GstMapFlags flags);
/**
* GstMemoryUnmapFunction:
* @mem: a #GstMemory
* @data: the data pointer
* @size: the new size
*
* Return the pointer previously retrieved with gst_memory_map() and adjust the
* size of the memory with @size. @size can optionally be set to -1 to not
* modify the size.
*
* Returns: %TRUE on success.
*/
typedef gboolean (*GstMemoryUnmapFunction) (GstMemory *mem, gpointer data, gsize size);
/**
* GstMemoryFreeFunction:
* @mem: a #GstMemory
*
* Free the memory used by @mem. This function is usually called when the
* refcount of the @mem has reached 0.
*/
typedef void (*GstMemoryFreeFunction) (GstMemory *mem);
/**
* GstMemoryCopyFunction:
* @mem: a #GstMemory
* @offset: an offset
* @size: a size
*
* Copy @size bytes from @mem starting at @offset and return them wrapped in a
* new GstMemory object.
* If @size is set to -1, all bytes starting at @offset are copied.
*
* Returns: a new #GstMemory object wrapping a copy of the requested region in
* @mem.
*/
typedef GstMemory * (*GstMemoryCopyFunction) (GstMemory *mem, gsize offset, gsize size);
/**
* GstMemoryShareFunction:
* @mem: a #GstMemory
* @offset: an offset
* @size: a size
*
* Share @size bytes from @mem starting at @offset and return them wrapped in a
* new GstMemory object. If @size is set to -1, all bytes starting at @offset are
* shared. This function does not make a copy of the bytes in @mem.
*
* Returns: a new #GstMemory object sharing the requested region in @mem.
*/
typedef GstMemory * (*GstMemoryShareFunction) (GstMemory *mem, gsize offset, gsize size);
/**
* GstMemoryIsSpanFunction:
* @mem1: a #GstMemory
* @mem1: a #GstMemory
* @offset: a result offset
*
* Check if @mem1 and @mem2 occupy contiguous memory and return the offset of
* @mem1 in the parent buffer in @offset.
*
* Returns: %TRUE if @mem1 and @mem2 are in contiguous memory.
*/
typedef gboolean (*GstMemoryIsSpanFunction) (GstMemory *mem1, GstMemory *mem2, gsize *offset);
/**
* GstMemoryInfo:
* @get_sizes: