1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.Memory;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gstreamer.Allocator;
31 private import gstreamer.c.functions;
32 public  import gstreamer.c.types;
33 public  import gstreamerc.gstreamertypes;
34 
35 
36 /**
37  * GstMemory is a lightweight refcounted object that wraps a region of memory.
38  * They are typically used to manage the data of a #GstBuffer.
39  * 
40  * A GstMemory object has an allocated region of memory of maxsize. The maximum
41  * size does not change during the lifetime of the memory object. The memory
42  * also has an offset and size property that specifies the valid range of memory
43  * in the allocated region.
44  * 
45  * Memory is usually created by allocators with a gst_allocator_alloc()
46  * method call. When %NULL is used as the allocator, the default allocator will
47  * be used.
48  * 
49  * New allocators can be registered with gst_allocator_register().
50  * Allocators are identified by name and can be retrieved with
51  * gst_allocator_find(). gst_allocator_set_default() can be used to change the
52  * default allocator.
53  * 
54  * New memory can be created with gst_memory_new_wrapped() that wraps the memory
55  * allocated elsewhere.
56  * 
57  * Refcounting of the memory block is performed with gst_memory_ref() and
58  * gst_memory_unref().
59  * 
60  * The size of the memory can be retrieved and changed with
61  * gst_memory_get_sizes() and gst_memory_resize() respectively.
62  * 
63  * Getting access to the data of the memory is performed with gst_memory_map().
64  * The call will return a pointer to offset bytes into the region of memory.
65  * After the memory access is completed, gst_memory_unmap() should be called.
66  * 
67  * Memory can be copied with gst_memory_copy(), which will return a writable
68  * copy. gst_memory_share() will create a new memory block that shares the
69  * memory with an existing memory block at a custom offset and with a custom
70  * size.
71  * 
72  * Memory can be efficiently merged when gst_memory_is_span() returns %TRUE.
73  */
74 public class Memory
75 {
76 	/** the main Gtk struct */
77 	protected GstMemory* gstMemory;
78 	protected bool ownedRef;
79 
80 	/** Get the main Gtk struct */
81 	public GstMemory* getMemoryStruct(bool transferOwnership = false)
82 	{
83 		if (transferOwnership)
84 			ownedRef = false;
85 		return gstMemory;
86 	}
87 
88 	/** the main Gtk struct as a void* */
89 	protected void* getStruct()
90 	{
91 		return cast(void*)gstMemory;
92 	}
93 
94 	/**
95 	 * Sets our main struct and passes it to the parent class.
96 	 */
97 	public this (GstMemory* gstMemory, bool ownedRef = false)
98 	{
99 		this.gstMemory = gstMemory;
100 		this.ownedRef = ownedRef;
101 	}
102 
103 
104 	/** */
105 	public static GType getType()
106 	{
107 		return gst_memory_get_type();
108 	}
109 
110 	/**
111 	 * Allocate a new memory block that wraps the given @data.
112 	 *
113 	 * The prefix/padding must be filled with 0 if @flags contains
114 	 * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
115 	 *
116 	 * Params:
117 	 *     flags = #GstMemoryFlags
118 	 *     data = data to
119 	 *         wrap
120 	 *     maxsize = allocated size of @data
121 	 *     offset = offset in @data
122 	 *     userData = user_data
123 	 *     notify = called with @user_data when the memory is freed
124 	 *
125 	 * Returns: a new #GstMemory.
126 	 *
127 	 * Throws: ConstructionException GTK+ fails to create the object.
128 	 */
129 	public this(GstMemoryFlags flags, ubyte[] data, size_t maxsize, size_t offset, void* userData, GDestroyNotify notify)
130 	{
131 		auto p = gst_memory_new_wrapped(flags, data.ptr, maxsize, offset, cast(size_t)data.length, userData, notify);
132 
133 		if(p is null)
134 		{
135 			throw new ConstructionException("null returned by new_wrapped");
136 		}
137 
138 		this(cast(GstMemory*) p);
139 	}
140 
141 	/**
142 	 * Return a copy of @size bytes from @mem starting from @offset. This copy is
143 	 * guaranteed to be writable. @size can be set to -1 to return a copy
144 	 * from @offset to the end of the memory region.
145 	 *
146 	 * Params:
147 	 *     offset = offset to copy from
148 	 *     size = size to copy, or -1 to copy to the end of the memory region
149 	 *
150 	 * Returns: a new #GstMemory.
151 	 */
152 	public Memory copy(ptrdiff_t offset, ptrdiff_t size)
153 	{
154 		auto p = gst_memory_copy(gstMemory, offset, size);
155 
156 		if(p is null)
157 		{
158 			return null;
159 		}
160 
161 		return ObjectG.getDObject!(Memory)(cast(GstMemory*) p, true);
162 	}
163 
164 	/**
165 	 * Get the current @size, @offset and @maxsize of @mem.
166 	 *
167 	 * Params:
168 	 *     offset = pointer to offset
169 	 *     maxsize = pointer to maxsize
170 	 *
171 	 * Returns: the current sizes of @mem
172 	 */
173 	public size_t getSizes(out size_t offset, out size_t maxsize)
174 	{
175 		return gst_memory_get_sizes(gstMemory, &offset, &maxsize);
176 	}
177 
178 	/**
179 	 * Initializes a newly allocated @mem with the given parameters. This function
180 	 * will call gst_mini_object_init() with the default memory parameters.
181 	 *
182 	 * Params:
183 	 *     flags = #GstMemoryFlags
184 	 *     allocator = the #GstAllocator
185 	 *     parent = the parent of @mem
186 	 *     maxsize = the total size of the memory
187 	 *     alig = the alignment of the memory
188 	 *     offset = The offset in the memory
189 	 *     size = the size of valid data in the memory
190 	 */
191 	public void init(GstMemoryFlags flags, Allocator allocator, Memory parent, size_t maxsize, size_t alig, size_t offset, size_t size)
192 	{
193 		gst_memory_init(gstMemory, flags, (allocator is null) ? null : allocator.getAllocatorStruct(), (parent is null) ? null : parent.getMemoryStruct(), maxsize, alig, offset, size);
194 	}
195 
196 	/**
197 	 * Check if @mem1 and mem2 share the memory with a common parent memory object
198 	 * and that the memory is contiguous.
199 	 *
200 	 * If this is the case, the memory of @mem1 and @mem2 can be merged
201 	 * efficiently by performing gst_memory_share() on the parent object from
202 	 * the returned @offset.
203 	 *
204 	 * Params:
205 	 *     mem2 = a #GstMemory
206 	 *     offset = a pointer to a result offset
207 	 *
208 	 * Returns: %TRUE if the memory is contiguous and of a common parent.
209 	 */
210 	public bool isSpan(Memory mem2, out size_t offset)
211 	{
212 		return gst_memory_is_span(gstMemory, (mem2 is null) ? null : mem2.getMemoryStruct(), &offset) != 0;
213 	}
214 
215 	/**
216 	 * Check if @mem if allocated with an allocator for @mem_type.
217 	 *
218 	 * Params:
219 	 *     memType = a memory type
220 	 *
221 	 * Returns: %TRUE if @mem was allocated from an allocator for @mem_type.
222 	 *
223 	 * Since: 1.2
224 	 */
225 	public bool isType(string memType)
226 	{
227 		return gst_memory_is_type(gstMemory, Str.toStringz(memType)) != 0;
228 	}
229 
230 	/**
231 	 * Create a #GstMemory object that is mapped with @flags. If @mem is mappable
232 	 * with @flags, this function returns the mapped @mem directly. Otherwise a
233 	 * mapped copy of @mem is returned.
234 	 *
235 	 * This function takes ownership of old @mem and returns a reference to a new
236 	 * #GstMemory.
237 	 *
238 	 * Params:
239 	 *     info = pointer for info
240 	 *     flags = mapping flags
241 	 *
242 	 * Returns: a #GstMemory object mapped
243 	 *     with @flags or %NULL when a mapping is not possible.
244 	 */
245 	public Memory makeMapped(out GstMapInfo info, GstMapFlags flags)
246 	{
247 		auto p = gst_memory_make_mapped(gstMemory, &info, flags);
248 
249 		if(p is null)
250 		{
251 			return null;
252 		}
253 
254 		return ObjectG.getDObject!(Memory)(cast(GstMemory*) p, true);
255 	}
256 
257 	/**
258 	 * Fill @info with the pointer and sizes of the memory in @mem that can be
259 	 * accessed according to @flags.
260 	 *
261 	 * This function can return %FALSE for various reasons:
262 	 * - the memory backed by @mem is not accessible with the given @flags.
263 	 * - the memory was already mapped with a different mapping.
264 	 *
265 	 * @info and its contents remain valid for as long as @mem is valid and
266 	 * until gst_memory_unmap() is called.
267 	 *
268 	 * For each gst_memory_map() call, a corresponding gst_memory_unmap() call
269 	 * should be done.
270 	 *
271 	 * Params:
272 	 *     info = pointer for info
273 	 *     flags = mapping flags
274 	 *
275 	 * Returns: %TRUE if the map operation was successful.
276 	 */
277 	public bool map(out GstMapInfo info, GstMapFlags flags)
278 	{
279 		return gst_memory_map(gstMemory, &info, flags) != 0;
280 	}
281 
282 	/**
283 	 * Resize the memory region. @mem should be writable and offset + size should be
284 	 * less than the maxsize of @mem.
285 	 *
286 	 * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED will be
287 	 * cleared when offset or padding is increased respectively.
288 	 *
289 	 * Params:
290 	 *     offset = a new offset
291 	 *     size = a new size
292 	 */
293 	public void resize(ptrdiff_t offset, size_t size)
294 	{
295 		gst_memory_resize(gstMemory, offset, size);
296 	}
297 
298 	/**
299 	 * Return a shared copy of @size bytes from @mem starting from @offset. No
300 	 * memory copy is performed and the memory region is simply shared. The result
301 	 * is guaranteed to be non-writable. @size can be set to -1 to return a shared
302 	 * copy from @offset to the end of the memory region.
303 	 *
304 	 * Params:
305 	 *     offset = offset to share from
306 	 *     size = size to share, or -1 to share to the end of the memory region
307 	 *
308 	 * Returns: a new #GstMemory.
309 	 */
310 	public Memory share(ptrdiff_t offset, ptrdiff_t size)
311 	{
312 		auto p = gst_memory_share(gstMemory, offset, size);
313 
314 		if(p is null)
315 		{
316 			return null;
317 		}
318 
319 		return ObjectG.getDObject!(Memory)(cast(GstMemory*) p, true);
320 	}
321 
322 	/**
323 	 * Release the memory obtained with gst_memory_map()
324 	 *
325 	 * Params:
326 	 *     info = a #GstMapInfo
327 	 */
328 	public void unmap(GstMapInfo* info)
329 	{
330 		gst_memory_unmap(gstMemory, info);
331 	}
332 }