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