From: Wim Taymans <wim.taymans@collabora.co.uk>
Date: Tue, 7 Jun 2011 16:18:27 +0000 (+0200)
Subject: docs: add beginnings of memory design doc
X-Git-Tag: RELEASE-0.11.0~140
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=9886c712cd6b272bf4e9830db7f9c773f81e0f59;p=platform%2Fupstream%2Fgstreamer.git

docs: add beginnings of memory design doc
---

diff --git a/docs/design/part-memory.txt b/docs/design/part-memory.txt
new file mode 100644
index 0000000..304cad1
--- /dev/null
+++ b/docs/design/part-memory.txt
@@ -0,0 +1,85 @@
+GstMemory
+---------
+
+This document describes the design of the memory objects.
+
+GstMemory objects are usually added to GstBuffer objects and contain the
+multimedia data passed around in the pipeline.
+
+Requirements
+~~~~~~~~~~~~
+
+ - It must be possible to have different memory allocators
+ - It must be possible to efficiently share memory objects, copy, span
+   and trim.
+
+
+Allocators
+~~~~~~~~~~
+
+ GstMemory objects are created by allocators. Allocators are registered to the
+ memory system with a set of methods contained in 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;
+  };
+
+ After an allocator is registerd, new GstMemory can be created with 
+
+   GstMemory * gst_memory_allocator_alloc (const GstMemoryAllocator * allocator,
+                                           gsize maxsize, gsize align);
+
+ The GstMemory object is a refcounted object that must be freed with
+ gst_memory_unref ().
+
+ 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);
+
+Memory layout
+~~~~~~~~~~~~~
+
+ GstMemory manages a memory region. The accesible part of the managed region is
+ defined by an offset relative to the start of the region and a size. This
+ means that the managed region can be larger than what is visible to the user of
+ GstMemory API.
+
+ Schematically, GstMemory has a pointer to a memory region of _maxsize_. The area
+ starting from _offset_ and _size_ is accessible.
+
+               memory
+    GstMemory  ->*----------------------------------------------------*
+                 ^----------------------------------------------------^ 
+                                   maxsize
+                      ^--------------------------------------^         
+                     offset            size
+
+ The current properties of the accessible memory can be retrieved with:
+
+   gsize       gst_memory_get_sizes  (GstMemory *mem, gsize *maxsize);
+
+ The offset and size can be changed with:
+
+   void        gst_memory_resize     (GstMemory *mem, gsize offset, gsize size);
+
+
+Data Access
+~~~~~~~~~~~
+
+
+
+