1/* GStreamer
2 * Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
3 *
4 * gstmemory.h: Header for memory blocks
5 *
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.
10 *
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.
15 *
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., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22
23#ifndef __GST_MEMORY_H__
24#define __GST_MEMORY_H__
25
26#include <gst/gstconfig.h>
27
28#include <glib-object.h>
29#include <gst/gstminiobject.h>
30#include <gst/gstobject.h>
31
32G_BEGIN_DECLS
33
34GST_API GType _gst_memory_type;
35#define GST_TYPE_MEMORY (_gst_memory_type)
36
37GST_API
38GType gst_memory_get_type(void);
39
40typedef struct _GstMemory GstMemory;
41typedef struct _GstAllocator GstAllocator;
42
43#define GST_MEMORY_CAST(mem) ((GstMemory *)(mem))
44
45/**
46 * GstMemoryFlags:
47 * @GST_MEMORY_FLAG_READONLY: memory is readonly. It is not allowed to map the
48 * memory with #GST_MAP_WRITE.
49 * @GST_MEMORY_FLAG_NO_SHARE: memory must not be shared. Copies will have to be
50 * made when this memory needs to be shared between buffers.
51 * @GST_MEMORY_FLAG_ZERO_PREFIXED: the memory prefix is filled with 0 bytes
52 * @GST_MEMORY_FLAG_ZERO_PADDED: the memory padding is filled with 0 bytes
53 * @GST_MEMORY_FLAG_PHYSICALLY_CONTIGUOUS: the memory is physically contiguous. (Since 1.2)
54 * @GST_MEMORY_FLAG_NOT_MAPPABLE: the memory can't be mapped via gst_memory_map() without any preconditions. (Since 1.2)
55 * @GST_MEMORY_FLAG_LAST: first flag that can be used for custom purposes
56 *
57 * Flags for wrapped memory.
58 */
59typedef enum {
60 GST_MEMORY_FLAG_READONLY = GST_MINI_OBJECT_FLAG_LOCK_READONLY,
61 GST_MEMORY_FLAG_NO_SHARE = (GST_MINI_OBJECT_FLAG_LAST << 0),
62 GST_MEMORY_FLAG_ZERO_PREFIXED = (GST_MINI_OBJECT_FLAG_LAST << 1),
63 GST_MEMORY_FLAG_ZERO_PADDED = (GST_MINI_OBJECT_FLAG_LAST << 2),
64 GST_MEMORY_FLAG_PHYSICALLY_CONTIGUOUS = (GST_MINI_OBJECT_FLAG_LAST << 3),
65 GST_MEMORY_FLAG_NOT_MAPPABLE = (GST_MINI_OBJECT_FLAG_LAST << 4),
66
67 GST_MEMORY_FLAG_LAST = (GST_MINI_OBJECT_FLAG_LAST << 16)
68} GstMemoryFlags;
69
70/**
71 * GST_MEMORY_FLAGS:
72 * @mem: a #GstMemory.
73 *
74 * A flags word containing #GstMemoryFlags flags set on @mem
75 */
76#define GST_MEMORY_FLAGS(mem) GST_MINI_OBJECT_FLAGS (mem)
77/**
78 * GST_MEMORY_FLAG_IS_SET:
79 * @mem: a #GstMemory.
80 * @flag: the #GstMemoryFlags to check.
81 *
82 * Gives the status of a specific flag on a @mem.
83 */
84#define GST_MEMORY_FLAG_IS_SET(mem,flag) GST_MINI_OBJECT_FLAG_IS_SET (mem,flag)
85/**
86 * GST_MEMORY_FLAG_UNSET:
87 * @mem: a #GstMemory.
88 * @flag: the #GstMemoryFlags to clear.
89 *
90 * Clear a specific flag on a @mem.
91 */
92#define GST_MEMORY_FLAG_UNSET(mem,flag) GST_MINI_OBJECT_FLAG_UNSET (mem, flag)
93
94/**
95 * GST_MEMORY_IS_READONLY:
96 * @mem: a #GstMemory.
97 *
98 * Check if @mem is readonly.
99 */
100#define GST_MEMORY_IS_READONLY(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_READONLY)
101/**
102 * GST_MEMORY_IS_NO_SHARE:
103 * @mem: a #GstMemory.
104 *
105 * Check if @mem cannot be shared between buffers
106 */
107#define GST_MEMORY_IS_NO_SHARE(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_NO_SHARE)
108/**
109 * GST_MEMORY_IS_ZERO_PREFIXED:
110 * @mem: a #GstMemory.
111 *
112 * Check if the prefix in @mem is 0 filled.
113 */
114#define GST_MEMORY_IS_ZERO_PREFIXED(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_ZERO_PREFIXED)
115/**
116 * GST_MEMORY_IS_ZERO_PADDED:
117 * @mem: a #GstMemory.
118 *
119 * Check if the padding in @mem is 0 filled.
120 */
121#define GST_MEMORY_IS_ZERO_PADDED(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_ZERO_PADDED)
122
123/**
124 * GST_MEMORY_IS_PHYSICALLY_CONTIGUOUS:
125 * @mem: a #GstMemory.
126 *
127 * Check if @mem is physically contiguous.
128 *
129 * Since: 1.2
130 */
131#define GST_MEMORY_IS_PHYSICALLY_CONTIGUOUS(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_PHYSICALLY_CONTIGUOUS)
132
133/**
134 * GST_MEMORY_IS_NOT_MAPPABLE:
135 * @mem: a #GstMemory.
136 *
137 * Check if @mem can't be mapped via gst_memory_map() without any preconditions
138 *
139 * Since: 1.2
140 */
141#define GST_MEMORY_IS_NOT_MAPPABLE(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_NOT_MAPPABLE)
142
143/**
144 * GstMemory:
145 * @mini_object: parent structure
146 * @allocator: pointer to the #GstAllocator
147 * @parent: parent memory block
148 * @maxsize: the maximum size allocated
149 * @align: the alignment of the memory
150 * @offset: the offset where valid data starts
151 * @size: the size of valid data
152 *
153 * Base structure for memory implementations. Custom memory will put this structure
154 * as the first member of their structure.
155 */
156struct _GstMemory {
157 GstMiniObject mini_object;
158
159 GstAllocator *allocator;
160
161 GstMemory *parent;
162 gsize maxsize;
163 gsize align;
164 gsize offset;
165 gsize size;
166};
167
168/**
169 * GstMapFlags:
170 * @GST_MAP_READ: map for read access
171 * @GST_MAP_WRITE: map for write access
172 * @GST_MAP_FLAG_LAST: first flag that can be used for custom purposes
173 *
174 * Flags used when mapping memory
175 */
176typedef enum {
177 GST_MAP_READ = GST_LOCK_FLAG_READ,
178 GST_MAP_WRITE = GST_LOCK_FLAG_WRITE,
179
180 GST_MAP_FLAG_LAST = (1 << 16)
181} GstMapFlags;
182
183/**
184 * GST_MAP_READWRITE: (value 3) (type GstMapFlags)
185 *
186 * GstMapFlags value alias for GST_MAP_READ | GST_MAP_WRITE
187 */
188#define GST_MAP_READWRITE ((GstMapFlags) (GST_MAP_READ | GST_MAP_WRITE))
189
190
191/**
192 * GstMapInfo:
193 * @memory: a pointer to the mapped memory
194 * @flags: flags used when mapping the memory
195 * @data: (array length=size): a pointer to the mapped data
196 * @size: the valid size in @data
197 * @maxsize: the maximum bytes in @data
198 * @user_data: extra private user_data that the implementation of the memory
199 * can use to store extra info.
200 *
201 * A structure containing the result of a map operation such as
202 * gst_memory_map(). It contains the data and size.
203 */
204typedef struct {
205 GstMemory *memory;
206 GstMapFlags flags;
207 guint8 *data;
208 gsize size;
209 gsize maxsize;
210 /*< protected >*/
211 gpointer user_data[4];
212
213 /*< private >*/
214 gpointer _gst_reserved[GST_PADDING];
215} GstMapInfo;
216
217/**
218 * GST_MAP_INFO_INIT:
219 *
220 * Initializer for #GstMapInfo
221 */
222#define GST_MAP_INFO_INIT { NULL, (GstMapFlags) 0, NULL, 0, 0, { NULL, NULL, NULL, NULL}, {NULL, NULL, NULL, NULL}}
223
224/**
225 * GstMemoryMapFunction:
226 * @mem: a #GstMemory
227 * @maxsize: size to map
228 * @flags: access mode for the memory
229 *
230 * Get the memory of @mem that can be accessed according to the mode specified
231 * in @flags. The function should return a pointer that contains at least
232 * @maxsize bytes.
233 *
234 * Returns: a pointer to memory of which at least @maxsize bytes can be
235 * accessed according to the access pattern in @flags.
236 */
237typedef gpointer (*GstMemoryMapFunction) (GstMemory *mem, gsize maxsize, GstMapFlags flags);
238
239/**
240 * GstMemoryMapFullFunction:
241 * @mem: a #GstMemory
242 * @info: the #GstMapInfo to map with
243 * @maxsize: size to map
244 *
245 * Get the memory of @mem that can be accessed according to the mode specified
246 * in @info's flags. The function should return a pointer that contains at least
247 * @maxsize bytes.
248 *
249 * Returns: a pointer to memory of which at least @maxsize bytes can be
250 * accessed according to the access pattern in @info's flags.
251 */
252typedef gpointer (*GstMemoryMapFullFunction) (GstMemory *mem, GstMapInfo * info, gsize maxsize);
253
254/**
255 * GstMemoryUnmapFunction:
256 * @mem: a #GstMemory
257 *
258 * Return the pointer previously retrieved with gst_memory_map().
259 */
260typedef void (*GstMemoryUnmapFunction) (GstMemory *mem);
261
262/**
263 * GstMemoryUnmapFullFunction:
264 * @mem: a #GstMemory
265 * @info: a #GstMapInfo
266 *
267 * Return the pointer previously retrieved with gst_memory_map() with @info.
268 */
269typedef void (*GstMemoryUnmapFullFunction) (GstMemory *mem, GstMapInfo * info);
270
271/**
272 * GstMemoryCopyFunction:
273 * @mem: a #GstMemory
274 * @offset: an offset
275 * @size: a size or -1
276 *
277 * Copy @size bytes from @mem starting at @offset and return them wrapped in a
278 * new GstMemory object.
279 * If @size is set to -1, all bytes starting at @offset are copied.
280 *
281 * Returns: a new #GstMemory object wrapping a copy of the requested region in
282 * @mem.
283 */
284typedef GstMemory * (*GstMemoryCopyFunction) (GstMemory *mem, gssize offset, gssize size);
285
286/**
287 * GstMemoryShareFunction:
288 * @mem: a #GstMemory
289 * @offset: an offset
290 * @size: a size or -1
291 *
292 * Share @size bytes from @mem starting at @offset and return them wrapped in a
293 * new GstMemory object. If @size is set to -1, all bytes starting at @offset are
294 * shared. This function does not make a copy of the bytes in @mem.
295 *
296 * Returns: a new #GstMemory object sharing the requested region in @mem.
297 */
298typedef GstMemory * (*GstMemoryShareFunction) (GstMemory *mem, gssize offset, gssize size);
299
300/**
301 * GstMemoryIsSpanFunction:
302 * @mem1: a #GstMemory
303 * @mem2: a #GstMemory
304 * @offset: a result offset
305 *
306 * Check if @mem1 and @mem2 occupy contiguous memory and return the offset of
307 * @mem1 in the parent buffer in @offset.
308 *
309 * Returns: %TRUE if @mem1 and @mem2 are in contiguous memory.
310 */
311typedef gboolean (*GstMemoryIsSpanFunction) (GstMemory *mem1, GstMemory *mem2, gsize *offset);
312
313GST_API
314void gst_memory_init (GstMemory *mem, GstMemoryFlags flags,
315 GstAllocator *allocator, GstMemory *parent,
316 gsize maxsize, gsize align,
317 gsize offset, gsize size);
318GST_API
319gboolean gst_memory_is_type (GstMemory *mem, const gchar *mem_type);
320
321/* refcounting */
322/**
323 * gst_memory_ref:
324 * @memory: The memory to refcount
325 *
326 * Increase the refcount of this memory.
327 *
328 * Returns: (transfer full): @memory (for convenience when doing assignments)
329 */
330static inline GstMemory *
331gst_memory_ref (GstMemory * memory)
332{
333 return (GstMemory *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (memory));
334}
335
336/**
337 * gst_memory_unref:
338 * @memory: (transfer full): the memory to refcount
339 *
340 * Decrease the refcount of an memory, freeing it if the refcount reaches 0.
341 */
342static inline void
343gst_memory_unref (GstMemory * memory)
344{
345 gst_mini_object_unref (GST_MINI_OBJECT_CAST (memory));
346}
347
348/* getting/setting memory properties */
349
350GST_API
351gsize gst_memory_get_sizes (GstMemory *mem, gsize *offset, gsize *maxsize);
352
353GST_API
354void gst_memory_resize (GstMemory *mem, gssize offset, gsize size);
355
356#define gst_memory_lock(m,f) gst_mini_object_lock (GST_MINI_OBJECT_CAST (m), (f))
357#define gst_memory_unlock(m,f) gst_mini_object_unlock (GST_MINI_OBJECT_CAST (m), (f))
358#define gst_memory_is_writable(m) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (m))
359#define gst_memory_make_writable(m) GST_MEMORY_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (m)))
360
361/* retrieving data */
362
363GST_API
364GstMemory * gst_memory_make_mapped (GstMemory *mem, GstMapInfo *info, GstMapFlags flags) G_GNUC_WARN_UNUSED_RESULT;
365
366GST_API
367gboolean gst_memory_map (GstMemory *mem, GstMapInfo *info, GstMapFlags flags);
368
369GST_API
370void gst_memory_unmap (GstMemory *mem, GstMapInfo *info);
371
372/* copy and subregions */
373
374GST_API
375GstMemory * gst_memory_copy (GstMemory *mem, gssize offset, gssize size) G_GNUC_WARN_UNUSED_RESULT;
376
377GST_API
378GstMemory * gst_memory_share (GstMemory *mem, gssize offset, gssize size) G_GNUC_WARN_UNUSED_RESULT;
379
380/* span memory */
381
382GST_API
383gboolean gst_memory_is_span (GstMemory *mem1, GstMemory *mem2, gsize *offset);
384
385#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
386G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstMemory, gst_memory_unref)
387#endif
388
389#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
390G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAllocator, gst_object_unref)
391#endif
392
393G_END_DECLS
394
395#endif /* __GST_MEMORY_H__ */
396