1/*
2 * GStreamer
3 * Copyright (C) 2015 Matthew Waters <matthew@centricular.com>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library 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 GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 */
20
21#ifndef _GST_GL_BASE_MEMORY_H_
22#define _GST_GL_BASE_MEMORY_H_
23
24#include <gst/gst.h>
25#include <gst/gstallocator.h>
26#include <gst/gstmemory.h>
27
28#include <gst/gl/gstgl_fwd.h>
29
30G_BEGIN_DECLS
31
32/**
33 * GST_TYPE_GL_BASE_MEMORY:
34 *
35 * Deprecated: 1.22: This type has no use.
36 */
37#define GST_TYPE_GL_BASE_MEMORY (gst_gl_base_memory_get_type())
38GST_GL_DEPRECATED
39GType gst_gl_base_memory_get_type(void);
40
41#define GST_TYPE_GL_BASE_MEMORY_ALLOCATOR (gst_gl_base_memory_allocator_get_type())
42GST_GL_API
43GType gst_gl_base_memory_allocator_get_type(void);
44
45#define GST_IS_GL_BASE_MEMORY_ALLOCATOR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_GL_BASE_MEMORY_ALLOCATOR))
46#define GST_IS_GL_BASE_MEMORY_ALLOCATOR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_GL_BASE_MEMORY_ALLOCATOR))
47#define GST_GL_BASE_MEMORY_ALLOCATOR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_GL_BASE_MEMORY_ALLOCATOR, GstGLBaseMemoryAllocatorClass))
48#define GST_GL_BASE_MEMORY_ALLOCATOR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_GL_BASE_MEMORY_ALLOCATOR, GstGLBaseMemoryAllocator))
49#define GST_GL_BASE_MEMORY_ALLOCATOR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_GL_BASE_MEMORY_ALLOCATOR, GstGLBaseMemoryAllocatorClass))
50#define GST_GL_BASE_MEMORY_ALLOCATOR_CAST(obj) ((GstGLBaseMemoryAllocator *)(obj))
51
52#define GST_GL_BASE_MEMORY_CAST(mem) ((GstGLBaseMemory *)mem)
53
54GST_GL_API
55GQuark gst_gl_base_memory_error_quark (void);
56/**
57 * GST_GL_BASE_MEMORY_ERROR:
58 *
59 * Error domain for GStreamer's GL memory module. Errors in this domain will be
60 * from the #GstGLBaseMemoryError enumeration
61 */
62#define GST_GL_BASE_MEMORY_ERROR (gst_gl_base_memory_error_quark ())
63
64/**
65 * GstGLBaseMemoryError:
66 * @GST_GL_BASE_MEMORY_ERROR_FAILED: generic failure
67 * @GST_GL_BASE_MEMORY_ERROR_OLD_LIBS: the implementation is too old and doesn't
68 * implement enough features
69 * @GST_GL_BASE_MEMORY_ERROR_RESOURCE_UNAVAILABLE: a resource could not be found
70 */
71typedef enum
72{
73 GST_GL_BASE_MEMORY_ERROR_FAILED,
74 GST_GL_BASE_MEMORY_ERROR_OLD_LIBS,
75 GST_GL_BASE_MEMORY_ERROR_RESOURCE_UNAVAILABLE,
76} GstGLBaseMemoryError;
77
78/**
79 * GstGLBaseMemoryTransfer:
80 * @GST_GL_BASE_MEMORY_TRANSFER_NEED_DOWNLOAD: the texture needs downloading
81 * to the data pointer
82 * @GST_GL_BASE_MEMORY_TRANSFER_NEED_UPLOAD: the data pointer needs uploading
83 * to the texture
84 */
85typedef enum
86{
87 GST_GL_BASE_MEMORY_TRANSFER_NEED_DOWNLOAD = (GST_MEMORY_FLAG_LAST << 0),
88 GST_GL_BASE_MEMORY_TRANSFER_NEED_UPLOAD = (GST_MEMORY_FLAG_LAST << 1)
89} GstGLBaseMemoryTransfer;
90
91/**
92 * GST_MAP_GL:
93 *
94 * Flag indicating that we should map the GL object instead of to system memory.
95 *
96 * Combining #GST_MAP_GL with #GST_MAP_WRITE has the same semantics as though
97 * you are writing to OpenGL. Conversely, combining #GST_MAP_GL with
98 * #GST_MAP_READ has the same semantics as though you are reading from OpenGL.
99 */
100#define GST_MAP_GL (GST_MAP_FLAG_LAST << 1)
101
102/**
103 * GstGLBaseMemory:
104 * @mem: the parent object
105 * @context: the #GstGLContext to use for GL operations
106 *
107 * Represents information about a GL memory object
108 */
109struct _GstGLBaseMemory
110{
111 GstMemory mem;
112
113 GstGLContext *context;
114
115 /*< protected >*/
116 GMutex lock;
117
118 GstMapFlags map_flags; /* cumulative map flags */
119 gint map_count;
120 gint gl_map_count;
121
122 gpointer data;
123
124 GstGLQuery *query;
125
126 /*< private >*/
127 gsize alloc_size; /* because maxsize is used for mapping */
128 gpointer alloc_data;
129
130 GDestroyNotify notify;
131 gpointer user_data;
132
133 gpointer _padding[GST_PADDING];
134};
135
136typedef struct _GstGLAllocationParams GstGLAllocationParams;
137/**
138 * GstGLAllocationParamsCopyFunc:
139 * @src: the source #GstGLAllocationParams to copy from
140 * @dest: the source #GstGLAllocationParams to copy
141 *
142 * Copies the parameters from @src into @dest. The subclass must compose copy
143 * functions from the superclass.
144 */
145typedef void (*GstGLAllocationParamsCopyFunc) (GstGLAllocationParams * src, GstGLAllocationParams * dest);
146/**
147 * GstGLAllocationParamsFreeFunc:
148 * @params: a #GstGLAllocationParams
149 *
150 * Free any dynamically allocated data. The subclass must call the superclass'
151 * free.
152 */
153typedef void (*GstGLAllocationParamsFreeFunc) (gpointer params);
154
155#define GST_TYPE_GL_ALLOCATION_PARAMS (gst_gl_allocation_params_get_type())
156GST_GL_API
157GType gst_gl_allocation_params_get_type (void);
158
159/**
160 * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_ALLOC:
161 *
162 * GL Allocation flag indicating that the implementation should allocate the
163 * necessary resources.
164 */
165#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_ALLOC (1 << 0)
166
167/**
168 * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_SYSMEM:
169 *
170 * GL Allocation flag for using the provided system memory data as storage.
171 */
172#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_SYSMEM (1 << 1)
173
174/**
175 * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE:
176 *
177 * GL Allocation flag for using the provided GPU handle as storage.
178 */
179#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE (1 << 2)
180
181/**
182 * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER:
183 *
184 * Values >= than #GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER can be used for
185 * user-defined purposes.
186 */
187#define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER (1 << 16)
188
189/**
190 * GstGLAllocationParams:
191 * @struct_size: the size of the struct (including and subclass data)
192 * @copy: a #GstGLAllocationParamsCopyFunc
193 * @free: a #GstGLAllocationParamsFreeFunc
194 * @alloc_flags: allocation flags
195 * @alloc_size: the allocation size
196 * @alloc_params: the #GstAllocationParams
197 * @context: a #GstGLContext
198 * @notify: a #GDestroyNotify
199 * @user_data: argument to call @notify with
200 * @wrapped_data: the wrapped data pointer
201 * @gl_handle: the wrapped OpenGL handle
202 */
203/* Because GstAllocationParams is not subclassable, start our own subclass
204 * chain. FIXME: 2.0 make GstAllocationParams subclassable */
205struct _GstGLAllocationParams
206{
207 gsize struct_size;
208 GstGLAllocationParamsCopyFunc copy;
209 GstGLAllocationParamsFreeFunc free;
210
211 guint alloc_flags;
212 gsize alloc_size;
213 GstAllocationParams *alloc_params;
214 GstGLContext *context;
215 GDestroyNotify notify;
216 gpointer user_data;
217
218 /* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_SYSMEM only */
219 gpointer wrapped_data;
220 /* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE only */
221 gpointer gl_handle;
222
223 /*< private >*/
224 gpointer _padding[GST_PADDING];
225};
226
227GST_GL_API
228gboolean gst_gl_allocation_params_init (GstGLAllocationParams * params,
229 gsize struct_size,
230 guint alloc_flags,
231 GstGLAllocationParamsCopyFunc copy,
232 GstGLAllocationParamsFreeFunc free,
233 GstGLContext * context,
234 gsize alloc_size,
235 const GstAllocationParams * alloc_params,
236 gpointer wrapped_data,
237 gpointer gl_handle,
238 gpointer user_data,
239 GDestroyNotify notify);
240
241/* free with gst_gl_allocation_params_free */
242GST_GL_API
243GstGLAllocationParams * gst_gl_allocation_params_copy (GstGLAllocationParams * src);
244
245GST_GL_API
246void gst_gl_allocation_params_free (GstGLAllocationParams * params);
247
248/* subclass usage */
249GST_GL_API
250void gst_gl_allocation_params_free_data (GstGLAllocationParams * params);
251
252/* subclass usage */
253GST_GL_API
254void gst_gl_allocation_params_copy_data (GstGLAllocationParams * src,
255 GstGLAllocationParams * dest);
256
257/**
258 * GstGLBaseMemoryAllocatorAllocFunction:
259 * @allocator: a #GstGLBaseMemoryAllocator
260 * @params: the #GstGLAllocationParams to allocate the memory with
261 *
262 * Note: not called with a GL context current
263 *
264 * Returns: (transfer full) (nullable): a newly allocated #GstGLBaseMemory from @allocator and @params
265 *
266 * Since: 1.8
267 */
268typedef GstGLBaseMemory * (*GstGLBaseMemoryAllocatorAllocFunction) (GstGLBaseMemoryAllocator * allocator,
269 GstGLAllocationParams * params);
270
271/**
272 * GstGLBaseMemoryAllocatorCreateFunction:
273 * @mem: a #GstGLBaseMemory
274 * @error: a #GError to use on failure
275 *
276 * As this virtual method is called with an OpenGL context current, use this
277 * function to allocate and OpenGL resources needed for your application
278 *
279 * Returns: whether the creation succeeded
280 *
281 * Since: 1.8
282 */
283typedef gboolean (*GstGLBaseMemoryAllocatorCreateFunction) (GstGLBaseMemory * mem,
284 GError ** error);
285
286/**
287 * GstGLBaseMemoryAllocatorMapFunction:
288 * @mem: a #GstGLBaseMemory
289 * @info: a #GstMapInfo to map with
290 * @maxsize: the size to map
291 *
292 * Also see gst_memory_map();
293 *
294 * Returns: the mapped pointer
295 *
296 * Since: 1.8
297 */
298typedef gpointer (*GstGLBaseMemoryAllocatorMapFunction) (GstGLBaseMemory * mem,
299 GstMapInfo * info,
300 gsize maxsize);
301/**
302 * GstGLBaseMemoryAllocatorUnmapFunction:
303 * @mem: a #GstGLBaseMemory
304 * @info: a #GstMapInfo to map with
305 *
306 * Also see gst_memory_unmap();
307 *
308 * Since: 1.8
309 */
310typedef void (*GstGLBaseMemoryAllocatorUnmapFunction) (GstGLBaseMemory * mem,
311 GstMapInfo * info);
312
313/**
314 * GstGLBaseMemoryAllocatorCopyFunction:
315 * @mem: a #GstGLBaseMemory
316 * @offset: the offset to copy from
317 * @size: the number of bytes to copy
318 *
319 * Also see gst_memory_copy();
320 *
321 * Returns: (transfer full) (nullable): the newly copied #GstGLMemory or %NULL
322 *
323 * Since: 1.8
324 */
325typedef GstGLBaseMemory * (*GstGLBaseMemoryAllocatorCopyFunction) (GstGLBaseMemory * mem,
326 gssize offset,
327 gssize size);
328
329/**
330 * GstGLBaseMemoryAllocatorDestroyFunction:
331 * @mem: a #GstGLBaseMemory
332 *
333 * Destroy any resources allocated throughout the lifetime of @mem
334 *
335 * Since: 1.8
336 */
337typedef void (*GstGLBaseMemoryAllocatorDestroyFunction) (GstGLBaseMemory * mem);
338
339/**
340 * GstGLBaseMemoryAllocator:
341 *
342 * Opaque #GstGLBaseMemoryAllocator struct
343 *
344 * Since: 1.8
345 */
346struct _GstGLBaseMemoryAllocator
347{
348 /*< private >*/
349 GstAllocator parent;
350 GstMemoryCopyFunction fallback_mem_copy;
351
352 gpointer _padding[GST_PADDING];
353};
354
355/**
356 * GstGLBaseMemoryAllocatorClass:
357 * @parent_class: the parent class
358 * @alloc: a #GstGLBaseMemoryAllocatorAllocFunction
359 * @create: a #GstGLBaseMemoryAllocatorCreateFunction
360 * @map: a #GstGLBaseMemoryAllocatorMapFunction
361 * @unmap: a #GstGLBaseMemoryAllocatorUnmapFunction
362 * @copy: a #GstGLBaseMemoryAllocatorCopyFunction
363 * @destroy: a #GstGLBaseMemoryAllocatorDestroyFunction
364 *
365 * Since: 1.8
366 */
367struct _GstGLBaseMemoryAllocatorClass
368{
369 GstAllocatorClass parent_class;
370
371 GstGLBaseMemoryAllocatorAllocFunction alloc;
372
373 GstGLBaseMemoryAllocatorCreateFunction create;
374 GstGLBaseMemoryAllocatorMapFunction map;
375 GstGLBaseMemoryAllocatorUnmapFunction unmap;
376 GstGLBaseMemoryAllocatorCopyFunction copy;
377 GstGLBaseMemoryAllocatorDestroyFunction destroy;
378
379 /*< private >*/
380 gpointer _padding[GST_PADDING];
381};
382
383#include <gst/gl/gstglconfig.h>
384#include <gst/gl/gstglformat.h>
385
386/**
387 * GST_GL_BASE_MEMORY_ALLOCATOR_NAME:
388 *
389 * The name of the GL buffer allocator
390 *
391 * Since: 1.8
392 */
393#define GST_GL_BASE_MEMORY_ALLOCATOR_NAME "GLBaseMemory"
394
395GST_GL_API
396void gst_gl_base_memory_init_once (void);
397
398GST_GL_API
399gboolean gst_is_gl_base_memory (GstMemory * mem);
400
401GST_GL_API
402void gst_gl_base_memory_init (GstGLBaseMemory * mem,
403 GstAllocator * allocator,
404 GstMemory * parent,
405 GstGLContext * context,
406 const GstAllocationParams * params,
407 gsize size,
408 gpointer user_data,
409 GDestroyNotify notify);
410
411GST_GL_API
412gboolean gst_gl_base_memory_alloc_data (GstGLBaseMemory * gl_mem);
413
414GST_GL_API
415gboolean gst_gl_base_memory_memcpy (GstGLBaseMemory * src,
416 GstGLBaseMemory * dest,
417 gssize offset,
418 gssize size);
419
420GST_GL_API
421GstGLBaseMemory * gst_gl_base_memory_alloc (GstGLBaseMemoryAllocator * allocator,
422 GstGLAllocationParams * params);
423
424G_END_DECLS
425
426#endif /* _GST_GL_BUFFER_H_ */
427

source code of include/gstreamer-1.0/gst/gl/gstglbasememory.h