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