2 * Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
4 * gstmemory.h: Header for memory blocks
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
23 #ifndef __GST_MEMORY_H__
24 #define __GST_MEMORY_H__
26 #include <gst/gstconfig.h>
28 #include <glib-object.h>
32 #define GST_TYPE_MEMORY (gst_memory_get_type())
33 GType gst_memory_get_type(void);
35 typedef struct _GstMemory GstMemory;
36 typedef struct _GstMemoryInfo GstMemoryInfo;
37 typedef struct _GstAllocator GstAllocator;
39 extern gsize gst_memory_alignment;
43 * @GST_MEMORY_FLAG_READONLY: memory is readonly. It is not allowed to map the
44 * memory with #GST_MAP_WRITE.
45 * @GST_MEMORY_FLAG_NO_SHARE: memory must not be shared. Copies will have to be
46 * made when this memory needs to be shared between buffers.
47 * @GST_MEMORY_FLAG_LAST: first flag that can be used for custom purposes
49 * Flags for wrapped memory.
52 GST_MEMORY_FLAG_READONLY = (1 << 0),
53 GST_MEMORY_FLAG_NO_SHARE = (1 << 1),
55 GST_MEMORY_FLAG_LAST = (1 << 24)
59 * GST_MEMORY_IS_WRITABLE:
62 * Check if @mem is writable.
64 #define GST_MEMORY_IS_WRITABLE(mem) (((mem)->refcount == 1) && \
65 (((mem)->parent == NULL) || ((mem)->parent->refcount == 1)) && \
66 (((mem)->flags & GST_MEMORY_FLAG_READONLY) == 0))
70 * @allocator: pointer to the #GstAllocator
71 * @flags: memory flags
73 * @parent: parent memory block
75 * Base structure for memory implementations. Custom memory will put this structure
76 * as the first member of their structure.
79 const GstAllocator *allocator;
88 * @GST_MAP_READ: map for read access
89 * @GST_MAP_WRITE: map for write access
91 * Flags used when mapping memory
94 GST_MAP_READ = (1 << 0),
95 GST_MAP_WRITE = (1 << 1),
101 * Map for readwrite access
103 #define GST_MAP_READWRITE (GST_MAP_READ | GST_MAP_WRITE)
106 * GST_ALLOCATOR_SYSMEM:
108 * The allocator name for the default system memory allocator
110 #define GST_ALLOCATOR_SYSMEM "SystemMemory"
113 * GstMemoryAllocFunction:
114 * @allocator: a #GstAllocator
115 * @maxsize: the maxsize
116 * @align: the alignment
117 * @user_data: user data
119 * Allocate a new #GstMemory from @allocator that can hold at least @maxsize bytes
120 * and is aligned to (@align + 1) bytes.
122 * @user_data is the data that was used when registering @allocator.
124 * Returns: a newly allocated #GstMemory. Free with gst_memory_unref()
126 typedef GstMemory * (*GstMemoryAllocFunction) (const GstAllocator *allocator,
127 gsize maxsize, gsize align,
131 * GstMemoryGetSizesFunction:
133 * @offset: result pointer for offset
134 * @maxsize: result pointer for maxsize
136 * Retrieve the size, offset and maxsize of @mem.
138 * Returns: the size of @mem, the offset and the maximum allocated size in @maxsize.
140 typedef gsize (*GstMemoryGetSizesFunction) (GstMemory *mem, gsize *offset, gsize *maxsize);
143 * GstMemoryResizeFunction:
145 * @offset: the offset adjustement
146 * @size: the new size or -1 to just adjust the offset
148 * Adjust the size and offset of @mem. @offset bytes will be adjusted from the
149 * current first byte in @mem as retrieved with gst_memory_map() and the new
150 * size will be set to @size.
152 * @size can be set to -1, which will only adjust the offset.
154 typedef void (*GstMemoryResizeFunction) (GstMemory *mem, gssize offset, gssize size);
157 * GstMemoryMapFunction:
159 * @size: pointer for the size
160 * @maxsize: pointer for the maxsize
161 * @flags: access mode for the memory
163 * Get the memory of @mem that can be accessed according to the mode specified
164 * in @flags. @size and @maxsize will respectively contain the current amount of
165 * valid bytes in the returned memory and the maximum allocated memory.
166 * @size and @maxsize can optionally be set to NULL.
168 * Returns: a pointer to memory. @size bytes are currently used from the
169 * returned pointer and @maxsize bytes can potentially be used.
171 typedef gpointer (*GstMemoryMapFunction) (GstMemory *mem, gsize *size, gsize *maxsize,
175 * GstMemoryUnmapFunction:
177 * @data: the data pointer
178 * @size: the new size, or -1 to not modify the size
180 * Return the pointer previously retrieved with gst_memory_map() and adjust the
181 * size of the memory with @size. @size can optionally be set to -1 to not
184 * Returns: %TRUE on success.
186 typedef gboolean (*GstMemoryUnmapFunction) (GstMemory *mem, gpointer data, gssize size);
189 * GstMemoryFreeFunction:
192 * Free the memory used by @mem. This function is usually called when the
193 * refcount of the @mem has reached 0.
195 typedef void (*GstMemoryFreeFunction) (GstMemory *mem);
198 * GstMemoryCopyFunction:
201 * @size: a size or -1
203 * Copy @size bytes from @mem starting at @offset and return them wrapped in a
204 * new GstMemory object.
205 * If @size is set to -1, all bytes starting at @offset are copied.
207 * Returns: a new #GstMemory object wrapping a copy of the requested region in
210 typedef GstMemory * (*GstMemoryCopyFunction) (GstMemory *mem, gssize offset, gssize size);
213 * GstMemoryShareFunction:
216 * @size: a size or -1
218 * Share @size bytes from @mem starting at @offset and return them wrapped in a
219 * new GstMemory object. If @size is set to -1, all bytes starting at @offset are
220 * shared. This function does not make a copy of the bytes in @mem.
222 * Returns: a new #GstMemory object sharing the requested region in @mem.
224 typedef GstMemory * (*GstMemoryShareFunction) (GstMemory *mem, gssize offset, gssize size);
227 * GstMemoryIsSpanFunction:
228 * @mem1: a #GstMemory
229 * @mem2: a #GstMemory
230 * @offset: a result offset
232 * Check if @mem1 and @mem2 occupy contiguous memory and return the offset of
233 * @mem1 in the parent buffer in @offset.
235 * Returns: %TRUE if @mem1 and @mem2 are in contiguous memory.
237 typedef gboolean (*GstMemoryIsSpanFunction) (GstMemory *mem1, GstMemory *mem2, gsize *offset);
241 * @alloc: the implementation of the GstMemoryAllocFunction
242 * @get_sizes: the implementation of the GstMemoryGetSizesFunction
243 * @resize: the implementation of the GstMemoryResizeFunction
244 * @map: the implementation of the GstMemoryMapFunction
245 * @unmap: the implementation of the GstMemoryUnmapFunction
246 * @free: the implementation of the GstMemoryFreeFunction
247 * @copy: the implementation of the GstMemoryCopyFunction
248 * @share: the implementation of the GstMemoryShareFunction
249 * @is_span: the implementation of the GstMemoryIsSpanFunction
250 * @user_data: generic user data for the allocator
252 * The #GstMemoryInfo is used to register new memory allocators and contain
253 * the implementations for various memory operations.
255 struct _GstMemoryInfo {
256 GstMemoryAllocFunction alloc;
257 GstMemoryGetSizesFunction get_sizes;
258 GstMemoryResizeFunction resize;
259 GstMemoryMapFunction map;
260 GstMemoryUnmapFunction unmap;
261 GstMemoryFreeFunction free;
263 GstMemoryCopyFunction copy;
264 GstMemoryShareFunction share;
265 GstMemoryIsSpanFunction is_span;
270 gpointer _gst_reserved[GST_PADDING];
274 const GstAllocator * gst_allocator_register (const gchar *name, const GstMemoryInfo *info);
275 const GstAllocator * gst_allocator_find (const gchar *name);
277 void gst_allocator_set_default (const GstAllocator * allocator);
279 /* allocating memory blocks */
280 GstMemory * gst_allocator_alloc (const GstAllocator * allocator,
281 gsize maxsize, gsize align);
283 GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data, GFreeFunc free_func,
284 gsize maxsize, gsize offset, gsize size);
287 GstMemory * gst_memory_ref (GstMemory *mem);
288 void gst_memory_unref (GstMemory *mem);
290 /* getting/setting memory properties */
291 gsize gst_memory_get_sizes (GstMemory *mem, gsize *offset, gsize *maxsize);
292 void gst_memory_resize (GstMemory *mem, gssize offset, gsize size);
294 /* retrieving data */
295 gpointer gst_memory_map (GstMemory *mem, gsize *size, gsize *maxsize,
297 gboolean gst_memory_unmap (GstMemory *mem, gpointer data, gssize size);
299 /* copy and subregions */
300 GstMemory * gst_memory_copy (GstMemory *mem, gssize offset, gssize size);
301 GstMemory * gst_memory_share (GstMemory *mem, gssize offset, gssize size);
304 gboolean gst_memory_is_span (GstMemory *mem1, GstMemory *mem2, gsize *offset);
308 #endif /* __GST_MEMORY_H__ */