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 typedef struct _GstMemory GstMemory;
33 typedef struct _GstMemoryInfo GstMemoryInfo;
34 typedef struct _GstAllocator GstAllocator;
36 extern gsize gst_memory_alignment;
40 * @GST_MEMORY_FLAG_READONLY: memory is readonly. It is not allowed to map the
41 * memory with #GST_MAP_WRITE.
42 * @GST_MEMORY_FLAG_NO_SHARE: memory must not be shared. Copies will have to be
43 * made when this memory needs to be shared between buffers.
44 * @GST_MEMORY_FLAG_LAST: first flag that can be used for custom purposes
46 * Flags for wrapped memory.
49 GST_MEMORY_FLAG_READONLY = (1 << 0),
50 GST_MEMORY_FLAG_NO_SHARE = (1 << 1),
52 GST_MEMORY_FLAG_LAST = (1 << 24)
56 * GST_MEMORY_IS_WRITABLE:
59 * Check if @mem is writable.
61 #define GST_MEMORY_IS_WRITABLE(mem) (((mem)->refcount == 1) && \
62 (((mem)->parent == NULL) || ((mem)->parent->refcount == 1)) && \
63 (((mem)->flags & GST_MEMORY_FLAG_READONLY) == 0))
67 * @allocator: pointer to the #GstAllocator
68 * @flags: memory flags
70 * @parent: parent memory block
72 * Base structure for memory implementations. Custom memory will put this structure
73 * as the first member of their structure.
76 const GstAllocator *allocator;
85 * @GST_MAP_READ: map for read access
86 * @GST_MAP_WRITE: map for write access
88 * Flags used when mapping memory
91 GST_MAP_READ = (1 << 0),
92 GST_MAP_WRITE = (1 << 1),
98 * Map for readwrite access
100 #define GST_MAP_READWRITE (GST_MAP_READ | GST_MAP_WRITE)
103 * GST_ALLOCATOR_SYSMEM:
105 * The allocator name for the default system memory allocator
107 #define GST_ALLOCATOR_SYSMEM "SystemMemory"
110 * GstMemoryAllocFunction:
111 * @allocator: a #GstAllocator
112 * @maxsize: the maxsize
113 * @align: the alignment
114 * @user_data: user data
116 * Allocate a new #GstMemory from @allocator that can hold at least @maxsize bytes
117 * and is aligned to (@align + 1) bytes.
119 * @user_data is the data that was used when registering @allocator.
121 * Returns: a newly allocated #GstMemory. Free with gst_memory_unref()
123 typedef GstMemory * (*GstMemoryAllocFunction) (const GstAllocator *allocator,
124 gsize maxsize, gsize align,
128 * GstMemoryGetSizesFunction:
130 * @offset: result pointer for offset
131 * @maxsize: result pointer for maxsize
133 * Retrieve the size, offset and maxsize of @mem.
135 * Returns: the size of @mem, the offset and the maximum allocated size in @maxsize.
137 typedef gsize (*GstMemoryGetSizesFunction) (GstMemory *mem, gsize *offset, gsize *maxsize);
140 * GstMemoryResizeFunction:
142 * @offset: the offset adjustement
143 * @size: the new size
145 * Adjust the size and offset of @mem. @offset bytes will be adjusted from the
146 * current first byte in @mem as retrieved with gst_memory_map() and the new
147 * size will be set to @size.
149 * @size can be set to -1, which will only adjust the offset.
151 typedef void (*GstMemoryResizeFunction) (GstMemory *mem, gssize offset, gsize size);
154 * GstMemoryMapFunction:
156 * @size: pointer for the size
157 * @maxsize: pointer for the maxsize
158 * @flags: access mode for the memory
160 * Get the memory of @mem that can be accessed according to the mode specified
161 * in @flags. @size and @maxsize will respectively contain the current amount of
162 * valid bytes in the returned memory and the maximum allocated memory.
163 * @size and @maxsize can optionally be set to NULL.
165 * Returns: a pointer to memory. @size bytes are currently used from the
166 * returned pointer and @maxsize bytes can potentially be used.
168 typedef gpointer (*GstMemoryMapFunction) (GstMemory *mem, gsize *size, gsize *maxsize,
172 * GstMemoryUnmapFunction:
174 * @data: the data pointer
175 * @size: the new size
177 * Return the pointer previously retrieved with gst_memory_map() and adjust the
178 * size of the memory with @size. @size can optionally be set to -1 to not
181 * Returns: %TRUE on success.
183 typedef gboolean (*GstMemoryUnmapFunction) (GstMemory *mem, gpointer data, gsize size);
186 * GstMemoryFreeFunction:
189 * Free the memory used by @mem. This function is usually called when the
190 * refcount of the @mem has reached 0.
192 typedef void (*GstMemoryFreeFunction) (GstMemory *mem);
195 * GstMemoryCopyFunction:
200 * Copy @size bytes from @mem starting at @offset and return them wrapped in a
201 * new GstMemory object.
202 * If @size is set to -1, all bytes starting at @offset are copied.
204 * Returns: a new #GstMemory object wrapping a copy of the requested region in
207 typedef GstMemory * (*GstMemoryCopyFunction) (GstMemory *mem, gssize offset, gsize size);
210 * GstMemoryShareFunction:
215 * Share @size bytes from @mem starting at @offset and return them wrapped in a
216 * new GstMemory object. If @size is set to -1, all bytes starting at @offset are
217 * shared. This function does not make a copy of the bytes in @mem.
219 * Returns: a new #GstMemory object sharing the requested region in @mem.
221 typedef GstMemory * (*GstMemoryShareFunction) (GstMemory *mem, gssize offset, gsize size);
224 * GstMemoryIsSpanFunction:
225 * @mem1: a #GstMemory
226 * @mem2: a #GstMemory
227 * @offset: a result offset
229 * Check if @mem1 and @mem2 occupy contiguous memory and return the offset of
230 * @mem1 in the parent buffer in @offset.
232 * Returns: %TRUE if @mem1 and @mem2 are in contiguous memory.
234 typedef gboolean (*GstMemoryIsSpanFunction) (GstMemory *mem1, GstMemory *mem2, gsize *offset);
238 * @alloc: the implementation of the GstMemoryAllocFunction
239 * @get_sizes: the implementation of the GstMemoryGetSizesFunction
240 * @resize: the implementation of the GstMemoryResizeFunction
241 * @map: the implementation of the GstMemoryMapFunction
242 * @unmap: the implementation of the GstMemoryUnmapFunction
243 * @free: the implementation of the GstMemoryFreeFunction
244 * @copy: the implementation of the GstMemoryCopyFunction
245 * @share: the implementation of the GstMemoryShareFunction
246 * @is_span: the implementation of the GstMemoryIsSpanFunction
247 * @user_data: generic user data for the allocator
249 * The #GstMemoryInfo is used to register new memory allocators and contain
250 * the implementations for various memory operations.
252 struct _GstMemoryInfo {
253 GstMemoryAllocFunction alloc;
254 GstMemoryGetSizesFunction get_sizes;
255 GstMemoryResizeFunction resize;
256 GstMemoryMapFunction map;
257 GstMemoryUnmapFunction unmap;
258 GstMemoryFreeFunction free;
260 GstMemoryCopyFunction copy;
261 GstMemoryShareFunction share;
262 GstMemoryIsSpanFunction is_span;
267 void _gst_memory_init (void);
270 const GstAllocator * gst_allocator_register (const gchar *name, const GstMemoryInfo *info);
271 const GstAllocator * gst_allocator_find (const gchar *name);
273 void gst_allocator_set_default (const GstAllocator * allocator);
275 /* allocating memory blocks */
276 GstMemory * gst_allocator_alloc (const GstAllocator * allocator,
277 gsize maxsize, gsize align);
279 GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data, GFreeFunc free_func,
280 gsize maxsize, gsize offset, gsize size);
283 GstMemory * gst_memory_ref (GstMemory *mem);
284 void gst_memory_unref (GstMemory *mem);
286 /* getting/setting memory properties */
287 gsize gst_memory_get_sizes (GstMemory *mem, gsize *offset, gsize *maxsize);
288 void gst_memory_resize (GstMemory *mem, gssize offset, gsize size);
290 /* retrieving data */
291 gpointer gst_memory_map (GstMemory *mem, gsize *size, gsize *maxsize,
293 gboolean gst_memory_unmap (GstMemory *mem, gpointer data, gsize size);
295 /* copy and subregions */
296 GstMemory * gst_memory_copy (GstMemory *mem, gssize offset, gsize size);
297 GstMemory * gst_memory_share (GstMemory *mem, gssize offset, gsize size);
300 gboolean gst_memory_is_span (GstMemory *mem1, GstMemory *mem2, gsize *offset);
304 #endif /* __GST_MEMORY_H__ */