mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-02 20:55:55 +00:00
80f4716a61
Count how many mappings are currently active and also with what access pattern. Update the design doc with restrictions on the access patterns for nested mappings. Check if nested mappings obey the access mode restrictions of the design doc. Add various unit tests to check the desired behaviour.
314 lines
9.9 KiB
C
314 lines
9.9 KiB
C
/* GStreamer
|
|
* Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
|
|
*
|
|
* gstmemory.h: Header for memory blocks
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Library General Public
|
|
* License as published by the Free Software Foundation; either
|
|
* version 2 of the License, or (at your option) any later version.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Library General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Library General Public
|
|
* License along with this library; if not, write to the
|
|
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
|
* Boston, MA 02111-1307, USA.
|
|
*/
|
|
|
|
|
|
#ifndef __GST_MEMORY_H__
|
|
#define __GST_MEMORY_H__
|
|
|
|
#include <gst/gstconfig.h>
|
|
|
|
#include <glib-object.h>
|
|
|
|
G_BEGIN_DECLS
|
|
|
|
#define GST_TYPE_MEMORY (gst_memory_get_type())
|
|
GType gst_memory_get_type(void);
|
|
|
|
typedef struct _GstMemory GstMemory;
|
|
typedef struct _GstMemoryInfo GstMemoryInfo;
|
|
typedef struct _GstAllocator GstAllocator;
|
|
|
|
GST_EXPORT gsize gst_memory_alignment;
|
|
|
|
/**
|
|
* GstMemoryFlags:
|
|
* @GST_MEMORY_FLAG_READONLY: memory is readonly. It is not allowed to map the
|
|
* memory with #GST_MAP_WRITE.
|
|
* @GST_MEMORY_FLAG_NO_SHARE: memory must not be shared. Copies will have to be
|
|
* made when this memory needs to be shared between buffers.
|
|
* @GST_MEMORY_FLAG_LAST: first flag that can be used for custom purposes
|
|
*
|
|
* Flags for wrapped memory.
|
|
*/
|
|
typedef enum {
|
|
GST_MEMORY_FLAG_READONLY = (1 << 0),
|
|
GST_MEMORY_FLAG_NO_SHARE = (1 << 1),
|
|
|
|
GST_MEMORY_FLAG_LAST = (1 << 16)
|
|
} GstMemoryFlags;
|
|
|
|
/**
|
|
* GST_MEMORY_IS_WRITABLE:
|
|
* @mem: a #GstMemory
|
|
*
|
|
* Check if @mem is writable.
|
|
*/
|
|
#define GST_MEMORY_IS_WRITABLE(mem) (((mem)->refcount == 1) && \
|
|
(((mem)->parent == NULL) || ((mem)->parent->refcount == 1)) && \
|
|
(((mem)->flags & GST_MEMORY_FLAG_READONLY) == 0))
|
|
|
|
/**
|
|
* GstMemory:
|
|
* @allocator: pointer to the #GstAllocator
|
|
* @flags: memory flags
|
|
* @refcount: refcount
|
|
* @parent: parent memory block
|
|
* @state: private state
|
|
*
|
|
* Base structure for memory implementations. Custom memory will put this structure
|
|
* as the first member of their structure.
|
|
*/
|
|
struct _GstMemory {
|
|
const GstAllocator *allocator;
|
|
|
|
GstMemoryFlags flags;
|
|
gint refcount;
|
|
GstMemory *parent;
|
|
volatile gint state;
|
|
};
|
|
|
|
/**
|
|
* GstMapFlags:
|
|
* @GST_MAP_READ: map for read access
|
|
* @GST_MAP_WRITE: map for write access
|
|
* @GST_MAP_FLAG_LAST: first flag that can be used for custom purposes
|
|
*
|
|
* Flags used when mapping memory
|
|
*/
|
|
typedef enum {
|
|
GST_MAP_READ = (1 << 0),
|
|
GST_MAP_WRITE = (1 << 1),
|
|
|
|
GST_MAP_FLAG_LAST = (1 << 16)
|
|
} GstMapFlags;
|
|
|
|
/**
|
|
* GST_MAP_READWRITE:
|
|
*
|
|
* Map for readwrite access
|
|
*/
|
|
#define GST_MAP_READWRITE (GST_MAP_READ | GST_MAP_WRITE)
|
|
|
|
/**
|
|
* GST_ALLOCATOR_SYSMEM:
|
|
*
|
|
* The allocator name for the default system memory allocator
|
|
*/
|
|
#define GST_ALLOCATOR_SYSMEM "SystemMemory"
|
|
|
|
/**
|
|
* GstMemoryAllocFunction:
|
|
* @allocator: a #GstAllocator
|
|
* @maxsize: the maxsize
|
|
* @align: the alignment
|
|
* @user_data: user data
|
|
*
|
|
* Allocate a new #GstMemory from @allocator that can hold at least @maxsize bytes
|
|
* and is aligned to (@align + 1) bytes.
|
|
*
|
|
* @user_data is the data that was used when registering @allocator.
|
|
*
|
|
* Returns: a newly allocated #GstMemory. Free with gst_memory_unref()
|
|
*/
|
|
typedef GstMemory * (*GstMemoryAllocFunction) (const GstAllocator *allocator,
|
|
gsize maxsize, gsize align,
|
|
gpointer user_data);
|
|
|
|
/**
|
|
* GstMemoryGetSizesFunction:
|
|
* @mem: a #GstMemory
|
|
* @offset: result pointer for offset
|
|
* @maxsize: result pointer for maxsize
|
|
*
|
|
* Retrieve the size, offset and maxsize of @mem.
|
|
*
|
|
* Returns: the size of @mem, the offset and the maximum allocated size in @maxsize.
|
|
*/
|
|
typedef gsize (*GstMemoryGetSizesFunction) (GstMemory *mem, gsize *offset, gsize *maxsize);
|
|
|
|
/**
|
|
* GstMemoryResizeFunction:
|
|
* @mem: a #GstMemory
|
|
* @offset: the offset adjustement
|
|
* @size: the new size or -1 to just adjust the offset
|
|
*
|
|
* Adjust the size and offset of @mem. @offset bytes will be adjusted from the
|
|
* current first byte in @mem as retrieved with gst_memory_map() and the new
|
|
* size will be set to @size.
|
|
*
|
|
* @size can be set to -1, which will only adjust the offset.
|
|
*/
|
|
typedef void (*GstMemoryResizeFunction) (GstMemory *mem, gssize offset, gssize size);
|
|
|
|
/**
|
|
* GstMemoryMapFunction:
|
|
* @mem: a #GstMemory
|
|
* @size: pointer for the size
|
|
* @maxsize: pointer for the maxsize
|
|
* @flags: access mode for the memory
|
|
*
|
|
* Get the memory of @mem that can be accessed according to the mode specified
|
|
* in @flags. @size and @maxsize will respectively contain the current amount of
|
|
* valid bytes in the returned memory and the maximum allocated memory.
|
|
* @size and @maxsize can optionally be set to NULL.
|
|
*
|
|
* Returns: a pointer to memory. @size bytes are currently used from the
|
|
* returned pointer and @maxsize bytes can potentially be used.
|
|
*/
|
|
typedef gpointer (*GstMemoryMapFunction) (GstMemory *mem, gsize *size, gsize *maxsize,
|
|
GstMapFlags flags);
|
|
|
|
/**
|
|
* GstMemoryUnmapFunction:
|
|
* @mem: a #GstMemory
|
|
* @data: the data pointer
|
|
* @size: the new size, or -1 to not modify the size
|
|
*
|
|
* Return the pointer previously retrieved with gst_memory_map() and adjust the
|
|
* size of the memory with @size. @size can optionally be set to -1 to not
|
|
* modify the size.
|
|
*
|
|
* Returns: %TRUE on success.
|
|
*/
|
|
typedef gboolean (*GstMemoryUnmapFunction) (GstMemory *mem, gpointer data, gssize size);
|
|
|
|
/**
|
|
* GstMemoryFreeFunction:
|
|
* @mem: a #GstMemory
|
|
*
|
|
* Free the memory used by @mem. This function is usually called when the
|
|
* refcount of the @mem has reached 0.
|
|
*/
|
|
typedef void (*GstMemoryFreeFunction) (GstMemory *mem);
|
|
|
|
/**
|
|
* GstMemoryCopyFunction:
|
|
* @mem: a #GstMemory
|
|
* @offset: an offset
|
|
* @size: a size or -1
|
|
*
|
|
* Copy @size bytes from @mem starting at @offset and return them wrapped in a
|
|
* new GstMemory object.
|
|
* If @size is set to -1, all bytes starting at @offset are copied.
|
|
*
|
|
* Returns: a new #GstMemory object wrapping a copy of the requested region in
|
|
* @mem.
|
|
*/
|
|
typedef GstMemory * (*GstMemoryCopyFunction) (GstMemory *mem, gssize offset, gssize size);
|
|
|
|
/**
|
|
* GstMemoryShareFunction:
|
|
* @mem: a #GstMemory
|
|
* @offset: an offset
|
|
* @size: a size or -1
|
|
*
|
|
* Share @size bytes from @mem starting at @offset and return them wrapped in a
|
|
* new GstMemory object. If @size is set to -1, all bytes starting at @offset are
|
|
* shared. This function does not make a copy of the bytes in @mem.
|
|
*
|
|
* Returns: a new #GstMemory object sharing the requested region in @mem.
|
|
*/
|
|
typedef GstMemory * (*GstMemoryShareFunction) (GstMemory *mem, gssize offset, gssize size);
|
|
|
|
/**
|
|
* GstMemoryIsSpanFunction:
|
|
* @mem1: a #GstMemory
|
|
* @mem2: a #GstMemory
|
|
* @offset: a result offset
|
|
*
|
|
* Check if @mem1 and @mem2 occupy contiguous memory and return the offset of
|
|
* @mem1 in the parent buffer in @offset.
|
|
*
|
|
* Returns: %TRUE if @mem1 and @mem2 are in contiguous memory.
|
|
*/
|
|
typedef gboolean (*GstMemoryIsSpanFunction) (GstMemory *mem1, GstMemory *mem2, gsize *offset);
|
|
|
|
/**
|
|
* GstMemoryInfo:
|
|
* @alloc: the implementation of the GstMemoryAllocFunction
|
|
* @get_sizes: the implementation of the GstMemoryGetSizesFunction
|
|
* @resize: the implementation of the GstMemoryResizeFunction
|
|
* @map: the implementation of the GstMemoryMapFunction
|
|
* @unmap: the implementation of the GstMemoryUnmapFunction
|
|
* @free: the implementation of the GstMemoryFreeFunction
|
|
* @copy: the implementation of the GstMemoryCopyFunction
|
|
* @share: the implementation of the GstMemoryShareFunction
|
|
* @is_span: the implementation of the GstMemoryIsSpanFunction
|
|
* @user_data: generic user data for the allocator
|
|
*
|
|
* The #GstMemoryInfo is used to register new memory allocators and contain
|
|
* the implementations for various memory operations.
|
|
*/
|
|
struct _GstMemoryInfo {
|
|
GstMemoryAllocFunction alloc;
|
|
GstMemoryGetSizesFunction get_sizes;
|
|
GstMemoryResizeFunction resize;
|
|
GstMemoryMapFunction map;
|
|
GstMemoryUnmapFunction unmap;
|
|
GstMemoryFreeFunction free;
|
|
|
|
GstMemoryCopyFunction copy;
|
|
GstMemoryShareFunction share;
|
|
GstMemoryIsSpanFunction is_span;
|
|
|
|
gpointer user_data;
|
|
|
|
/*< private >*/
|
|
gpointer _gst_reserved[GST_PADDING];
|
|
};
|
|
|
|
/* allocators */
|
|
const GstAllocator * gst_allocator_register (const gchar *name, const GstMemoryInfo *info);
|
|
const GstAllocator * gst_allocator_find (const gchar *name);
|
|
|
|
void gst_allocator_set_default (const GstAllocator * allocator);
|
|
|
|
/* allocating memory blocks */
|
|
GstMemory * gst_allocator_alloc (const GstAllocator * allocator,
|
|
gsize maxsize, gsize align);
|
|
|
|
GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data, GFreeFunc free_func,
|
|
gsize maxsize, gsize offset, gsize size);
|
|
|
|
/* refcounting */
|
|
GstMemory * gst_memory_ref (GstMemory *mem);
|
|
void gst_memory_unref (GstMemory *mem);
|
|
|
|
/* getting/setting memory properties */
|
|
gsize gst_memory_get_sizes (GstMemory *mem, gsize *offset, gsize *maxsize);
|
|
void gst_memory_resize (GstMemory *mem, gssize offset, gsize size);
|
|
|
|
/* retrieving data */
|
|
gpointer gst_memory_map (GstMemory *mem, gsize *size, gsize *maxsize,
|
|
GstMapFlags flags);
|
|
gboolean gst_memory_unmap (GstMemory *mem, gpointer data, gssize size);
|
|
|
|
/* copy and subregions */
|
|
GstMemory * gst_memory_copy (GstMemory *mem, gssize offset, gssize size);
|
|
GstMemory * gst_memory_share (GstMemory *mem, gssize offset, gssize size);
|
|
|
|
/* span memory */
|
|
gboolean gst_memory_is_span (GstMemory *mem1, GstMemory *mem2, gsize *offset);
|
|
|
|
G_END_DECLS
|
|
|
|
#endif /* __GST_MEMORY_H__ */
|