subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasememory.h

   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
  30 G_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())
  38 GST_GL_DEPRECATED
  39 GType gst_gl_base_memory_get_type(void);
  40
  41 #define GST_TYPE_GL_BASE_MEMORY_ALLOCATOR (gst_gl_base_memory_allocator_get_type())
  42 GST_GL_API
  43 GType 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
  54 GST_GL_API
  55 GQuark 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  */
  71 typedef 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  */
  85 typedef 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  */
 109 struct _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
 136 typedef 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  */
 145 typedef 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  */
 153 typedef void    (*GstGLAllocationParamsFreeFunc)    (gpointer params);
 154
 155 #define GST_TYPE_GL_ALLOCATION_PARAMS (gst_gl_allocation_params_get_type())
 156 GST_GL_API
 157 GType 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 */
 205 struct _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
 227 GST_GL_API
 228 gboolean                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 */
 242 GST_GL_API
 243 GstGLAllocationParams * gst_gl_allocation_params_copy       (GstGLAllocationParams * src);
 244
 245 GST_GL_API
 246 void                    gst_gl_allocation_params_free       (GstGLAllocationParams * params);
 247
 248 /* subclass usage */
 249 GST_GL_API
 250 void                    gst_gl_allocation_params_free_data  (GstGLAllocationParams * params);
 251
 252 /* subclass usage */
 253 GST_GL_API
 254 void                    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: a newly allocated #GstGLBaseMemory from @allocator and @params
 265  *
 266  * Since: 1.8
 267  */
 268 typedef 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  */
 283 typedef 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  */
 298 typedef 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  */
 310 typedef 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: the newly copied #GstGLMemory or %NULL
 322  *
 323  * Since: 1.8
 324  */
 325 typedef 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  */
 337 typedef void                (*GstGLBaseMemoryAllocatorDestroyFunction)      (GstGLBaseMemory * mem);
 338
 339 /**
 340  * GstGLBaseMemoryAllocator:
 341  *
 342  * Opaque #GstGLBaseMemoryAllocator struct
 343  *
 344  * Since: 1.8
 345  */
 346 struct _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  */
 367 struct _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
 395 GST_GL_API
 396 void          gst_gl_base_memory_init_once (void);
 397
 398 GST_GL_API
 399 gboolean      gst_is_gl_base_memory        (GstMemory * mem);
 400
 401 GST_GL_API
 402 void          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
 411 GST_GL_API
 412 gboolean      gst_gl_base_memory_alloc_data (GstGLBaseMemory * gl_mem);
 413
 414 GST_GL_API
 415 gboolean      gst_gl_base_memory_memcpy     (GstGLBaseMemory * src,
 416                                              GstGLBaseMemory * dest,
 417                                              gssize offset,
 418                                              gssize size);
 419
 420 GST_GL_API
 421 GstGLBaseMemory *   gst_gl_base_memory_alloc    (GstGLBaseMemoryAllocator * allocator,
 422                                                  GstGLAllocationParams * params);
 423
 424 G_END_DECLS
 425
 426 #endif /* _GST_GL_BUFFER_H_ */