GstMemory

## GstMemory GstMemory — refcounted wrapper for memory blocks |

## Synopsis

    #include <gst/gst.h>

    enum                GstMemoryFlags;
    #define             GST_MEMORY_FLAGS                    (mem)
    #define             GST_MEMORY_FLAG_IS_SET              (mem,
                                                             flag)
    #define             GST_MEMORY_FLAG_UNSET               (mem,
                                                             flag)
    #define             GST_MEMORY_IS_READONLY              (mem)
    #define             GST_MEMORY_IS_ZERO_PADDED           (mem)
    #define             GST_MEMORY_IS_ZERO_PREFIXED         (mem)
    struct              GstMemory;
    enum                GstMapFlags;
                        GstMapInfo;
    #define             GST_MAP_INFO_INIT
    #define             GST_MAP_READWRITE
    struct              GstAllocationParams;
    GstMemory *         (*GstAllocatorAllocFunction)        (GstAllocator *allocator,
                                                             gsize size,
                                                             GstAllocationParams *params,
                                                             gpointer user_data);
    gpointer            (*GstMemoryMapFunction)             (GstMemory *mem,
                                                             gsize maxsize,
                                                             GstMapFlags flags);
    void                (*GstMemoryUnmapFunction)           (GstMemory *mem);
    void                (*GstMemoryFreeFunction)            (GstMemory *mem);
    GstMemory *         (*GstMemoryCopyFunction)            (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);
    GstMemory *         (*GstMemoryShareFunction)           (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);
    gboolean            (*GstMemoryIsSpanFunction)          (GstMemory *mem1,
                                                             GstMemory *mem2,
                                                             gsize *offset);
    struct              GstMemoryInfo;
                        GstAllocator;
    GstAllocator *      gst_allocator_new                   (const GstMemoryInfo *info,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    const gchar *       gst_allocator_get_memory_type       (GstAllocator *allocator);
    GstAllocator *      gst_allocator_ref                   (GstAllocator *allocator);
    void                gst_allocator_unref                 (GstAllocator *allocator);
    #define             GST_ALLOCATOR_SYSMEM
    GstAllocator *      gst_allocator_find                  (const gchar *name);
    void                gst_allocator_register              (const gchar *name,
                                                             GstAllocator *allocator);
    void                gst_allocator_set_default           (GstAllocator *allocator);
    void                gst_allocation_params_init          (GstAllocationParams *params);
    GstAllocationParams * gst_allocation_params_copy        (const GstAllocationParams *params);
    void                gst_allocation_params_free          (GstAllocationParams *params);
    GstMemory *         gst_allocator_alloc                 (GstAllocator *allocator,
                                                             gsize size,
                                                             GstAllocationParams *params);
    GstMemory *         gst_memory_new_wrapped              (GstMemoryFlags flags,
                                                             gpointer data,
                                                             gsize maxsize,
                                                             gsize offset,
                                                             gsize size,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    GstMemory *         gst_memory_ref                      (GstMemory *mem);
    void                gst_memory_unref                    (GstMemory *mem);
    gboolean            gst_memory_is_exclusive             (GstMemory *mem);
    gsize               gst_memory_get_sizes                (GstMemory *mem,
                                                             gsize *offset,
                                                             gsize *maxsize);
    void                gst_memory_resize                   (GstMemory *mem,
                                                             gssize offset,
                                                             gsize size);
    GstMemory *         gst_memory_make_mapped              (GstMemory *mem,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);
    gboolean            gst_memory_map                      (GstMemory *mem,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);
    void                gst_memory_unmap                    (GstMemory *mem,
                                                             GstMapInfo *info);
    GstMemory *         gst_memory_copy                     (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);
    GstMemory *         gst_memory_share                    (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);
    gboolean            gst_memory_is_span                  (GstMemory *mem1,
                                                             GstMemory *mem2,
                                                             gsize *offset);

## Description

GstMemory is a lightweight refcounted object that wraps a region of memory. They are typically used to manage the data of a GstBuffer.

A GstMemory object has an allocated region of memory of maxsize. The maximum size does not change during the lifetime of the memory object. The memory also has an offset and size property that specifies the valid range of memory in the allocated region.

Memory is usually created by allocators with a `gst_allocator_alloc()` method call. When NULL is used as the allocator, the default allocator will be used.

New allocators can be registered with `gst_allocator_register()`. Allocators are identified by name and can be retrieved with `gst_allocator_find()`. `gst_allocator_set_default()` can be used to change the default allocator.

New memory can be created with `gst_memory_new_wrapped()` that wraps the memory allocated elsewhere.

Refcounting of the memory block is performed with `gst_memory_ref()` and `gst_memory_unref()`.

The size of the memory can be retrieved and changed with `gst_memory_get_sizes()` and `gst_memory_resize()` respectively.

Getting access to the data of the memory is performed with `gst_memory_map()`. The call will return a pointer to offset bytes into the region of memory. After the memory access is completed, `gst_memory_unmap()` should be called.

Memory can be copied with `gst_memory_copy()`, which will return a writable copy. `gst_memory_share()` will create a new memory block that shares the memory with an existing memory block at a custom offset and with a custom size.

Memory can be efficiently merged when `gst_memory_is_span()` returns TRUE.

Last reviewed on 2012-03-28 (0.11.3)

## Details

### enum GstMemoryFlags

    typedef enum {
      GST_MEMORY_FLAG_READONLY      = (1 << 0),
      GST_MEMORY_FLAG_NO_SHARE      = (1 << 1),
      GST_MEMORY_FLAG_ZERO_PREFIXED = (1 << 2),
      GST_MEMORY_FLAG_ZERO_PADDED   = (1 << 3),

      GST_MEMORY_FLAG_LAST          = (1 << 16)
    } GstMemoryFlags;

Flags for wrapped memory.

`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_ZERO_PREFIXED` | the memory prefix is filled with 0 bytes
`GST_MEMORY_FLAG_ZERO_PADDED` | the memory padding is filled with 0 bytes
`GST_MEMORY_FLAG_LAST` | first flag that can be used for custom purposes

### GST_MEMORY_FLAGS()

    #define GST_MEMORY_FLAGS(mem)  (GST_MEMORY_CAST (mem)->flags)

A flags word containing GstMemoryFlags flags set on `mem`

`mem` : | a GstMemory.

### GST_MEMORY_FLAG_IS_SET()

    #define GST_MEMORY_FLAG_IS_SET(mem,flag)   !!(GST_MEMORY_FLAGS (mem) & (flag))

Gives the status of a specific flag on a `mem`.

`mem` : | a GstMemory.
`flag` : | the GstMemoryFlags to check.

### GST_MEMORY_FLAG_UNSET()

    #define GST_MEMORY_FLAG_UNSET(mem,flag)   (GST_MEMORY_FLAGS (mem) &= ~(flag))

Clear a specific flag on a `mem`.

`mem` : | a GstMemory.
`flag` : | the GstMemoryFlags to clear.

### GST_MEMORY_IS_READONLY()

    #define GST_MEMORY_IS_READONLY(mem)        GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_READONLY)

Check if `mem` is readonly.

`mem` : | a GstMemory.

### GST_MEMORY_IS_ZERO_PADDED()

    #define GST_MEMORY_IS_ZERO_PADDED(mem)     GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_ZERO_PADDED)

Check if the padding in `mem` is 0 filled.

`mem` : | a GstMemory.

### GST_MEMORY_IS_ZERO_PREFIXED()

    #define GST_MEMORY_IS_ZERO_PREFIXED(mem)   GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_ZERO_PREFIXED)

Check if the prefix in `mem` is 0 filled.

`mem` : | a GstMemory.

### struct GstMemory

    struct GstMemory {
      GstAllocator   *allocator;

      GstMemoryFlags  flags;
      gint            refcount;
      GstMemory      *parent;
      volatile gint   state;
      gsize           maxsize;
      gsize           align;
      gsize           offset;
      gsize           size;
    };

Base structure for memory implementations. Custom memory will put this structure as the first member of their structure.

GstAllocator *`allocator`; | pointer to the GstAllocator
GstMemoryFlags `flags`; | memory flags
gint `refcount`; | refcount
GstMemory *`parent`; | parent memory block
volatile gint `state`; | private state
gsize `maxsize`; | the maximum size allocated
gsize `align`; | the alignment of the memory
gsize `offset`; | the offset where valid data starts
gsize `size`; | the size of valid data

### enum GstMapFlags

    typedef enum {
      GST_MAP_READ      = (1 << 0),
      GST_MAP_WRITE     = (1 << 1),

      GST_MAP_FLAG_LAST = (1 << 16)
    } GstMapFlags;

Flags used when mapping memory

`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

### GstMapInfo

    typedef struct {
      GstMemory *memory;
      GstMapFlags flags;
      guint8 *data;
      gsize size;
      gsize maxsize;
    } GstMapInfo;

A structure containing the result of a map operation such as `gst_memory_map()`. It contains the data and size.

GstMemory *`memory`; | a pointer to the mapped memory
GstMapFlags `flags`; | flags used when mapping the memory
guint8 *`data`; | a pointer to the mapped data
gsize `size`; | the valid size in `data`
gsize `maxsize`; | the maximum bytes in `data`

### GST_MAP_INFO_INIT

    #define GST_MAP_INFO_INIT { NULL, 0, NULL, 0, 0, }

Initializer for GstMapInfo

### GST_MAP_READWRITE

    #define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)

Map for readwrite access

### struct GstAllocationParams

    struct GstAllocationParams {
      GstMemoryFlags flags;
      gsize          align;
      gsize          prefix;
      gsize          padding;
    };

Parameters to control the allocation of memory

GstMemoryFlags `flags`; | flags to control allocation
gsize `align`; | the desired alignment of the memory
gsize `prefix`; | the disired prefix
gsize `padding`; | the desired padding

### GstAllocatorAllocFunction ()

    GstMemory *         (*GstAllocatorAllocFunction)        (GstAllocator *allocator,
                                                             gsize size,
                                                             GstAllocationParams *params,
                                                             gpointer user_data);

Allocate a new GstMemory from `allocator` that can hold at least `size` bytes (+ padding) and is aligned to (`align` + 1) bytes.

The offset and size of the memory should be set and the prefix/padding must be filled with 0 if `params` flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

`user_data` is the data that was used when creating `allocator`.

`allocator` : | a GstAllocator
`size` : | the size
`params` : | allocator params
`user_data` : | user data
Returns : | a newly allocated GstMemory. Free with `gst_memory_unref()`

### GstMemoryMapFunction ()

    gpointer            (*GstMemoryMapFunction)             (GstMemory *mem,
                                                             gsize maxsize,
                                                             GstMapFlags flags);

Get the memory of `mem` that can be accessed according to the mode specified in `flags`. The function should return a pointer that contains at least `maxsize` bytes.

`mem` : | a GstMemory
`maxsize` : | size to map
`flags` : | access mode for the memory
Returns : | a pointer to memory of which at least `maxsize` bytes can be accessed according to the access pattern in `flags`.

### GstMemoryUnmapFunction ()

    void                (*GstMemoryUnmapFunction)           (GstMemory *mem);

Return the pointer previously retrieved with `gst_memory_map()`.

`mem` : | a GstMemory
Returns : | `TRUE` on success.

### GstMemoryFreeFunction ()

    void                (*GstMemoryFreeFunction)            (GstMemory *mem);

Free the memory used by `mem`. This function is usually called when the refcount of the `mem` has reached 0.

`mem` : | a GstMemory

### GstMemoryCopyFunction ()

    GstMemory *         (*GstMemoryCopyFunction)            (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);

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.

`mem` : | a GstMemory
`offset` : | an offset
`size` : | a size or -1
Returns : | a new GstMemory object wrapping a copy of the requested region in `mem`.

### GstMemoryShareFunction ()

    GstMemory *         (*GstMemoryShareFunction)           (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);

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`.

`mem` : | a GstMemory
`offset` : | an offset
`size` : | a size or -1
Returns : | a new GstMemory object sharing the requested region in `mem`.

### GstMemoryIsSpanFunction ()

    gboolean            (*GstMemoryIsSpanFunction)          (GstMemory *mem1,
                                                             GstMemory *mem2,
                                                             gsize *offset);

Check if `mem1` and `mem2` occupy contiguous memory and return the offset of `mem1` in the parent buffer in `offset`.

`mem1` : | a GstMemory
`mem2` : | a GstMemory
`offset` : | a result offset
Returns : | `TRUE` if `mem1` and `mem2` are in contiguous memory.

### struct GstMemoryInfo

    struct GstMemoryInfo {
      const gchar              *mem_type;

      GstAllocatorAllocFunction alloc;

      GstMemoryMapFunction      mem_map;
      GstMemoryUnmapFunction    mem_unmap;
      GstMemoryFreeFunction     mem_free;

      GstMemoryCopyFunction     mem_copy;
      GstMemoryShareFunction    mem_share;
      GstMemoryIsSpanFunction   mem_is_span;
    };

The GstMemoryInfo is used to register new memory allocators and contain the implementations for various memory operations.

const gchar *`mem_type`; | the memory type this allocator provides
GstAllocatorAllocFunction `alloc`; | the implementation of the GstAllocatorAllocFunction
GstMemoryMapFunction `mem_map`; | the implementation of the GstMemoryMapFunction
GstMemoryUnmapFunction `mem_unmap`; | the implementation of the GstMemoryUnmapFunction
GstMemoryFreeFunction `mem_free`; | the implementation of the GstMemoryFreeFunction
GstMemoryCopyFunction `mem_copy`; | the implementation of the GstMemoryCopyFunction
GstMemoryShareFunction `mem_share`; | the implementation of the GstMemoryShareFunction
GstMemoryIsSpanFunction `mem_is_span`; | the implementation of the GstMemoryIsSpanFunction

### GstAllocator

    typedef struct _GstAllocator GstAllocator;

An opaque type returned from `gst_allocator_new()` or `gst_allocator_find()` that can be used to allocator memory.

### gst_allocator_new ()

    GstAllocator *      gst_allocator_new                   (const GstMemoryInfo *info,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Create a new memory allocator with `info` and `user_data`.

All functions in `info` are mandatory exept the copy and is_span functions, which will have a default implementation when left NULL.

The `user_data` will be passed to all calls of the alloc function. `notify` will be called with `user_data` when the allocator is freed.

`info` : | a GstMemoryInfo
`user_data` : | user data
`notify` : | a GDestroyNotify for `user_data`
Returns : | a new GstAllocator.

### gst_allocator_get_memory_type ()

    const gchar *       gst_allocator_get_memory_type       (GstAllocator *allocator);

Get the memory type allocated by this allocator

`allocator` : | a GstAllocator
Returns : | the memory type provided by `allocator`

### gst_allocator_ref ()

    GstAllocator *      gst_allocator_ref                   (GstAllocator *allocator);

Increases the refcount of `allocator`.

`allocator` : | a GstAllocator
Returns : | `allocator` with increased refcount

### gst_allocator_unref ()

    void                gst_allocator_unref                 (GstAllocator *allocator);

Decreases the refcount of `allocator`. When the refcount reaches 0, the notify function of `allocator` will be called and the allocator will be freed.

`allocator` : | a GstAllocator

### GST_ALLOCATOR_SYSMEM

    #define GST_ALLOCATOR_SYSMEM   "SystemMemory"

The allocator name for the default system memory allocator

### gst_allocator_find ()

    GstAllocator *      gst_allocator_find                  (const gchar *name);

Find a previously registered allocator with `name`. When `name` is NULL, the default allocator will be returned.

`name` : | the name of the allocator
Returns : | a GstAllocator or NULL when the allocator with `name` was not registered. Use `gst_allocator_unref()` to release the allocator after usage. [transfer full]

### gst_allocator_register ()

    void                gst_allocator_register              (const gchar *name,
                                                             GstAllocator *allocator);

Registers the memory `allocator` with `name`. This function takes ownership of `allocator`.

`name` : | the name of the allocator
`allocator` : | GstAllocator. [transfer full]

### gst_allocator_set_default ()

    void                gst_allocator_set_default           (GstAllocator *allocator);

Set the default allocator. This function takes ownership of `allocator`.

`allocator` : | a GstAllocator. [transfer full]

### gst_allocation_params_init ()

    void                gst_allocation_params_init          (GstAllocationParams *params);

Initialize `params` to its default values

`params` : | a GstAllocationParams

### gst_allocation_params_copy ()

    GstAllocationParams * gst_allocation_params_copy        (const GstAllocationParams *params);

Create a copy of `params`.

Free-function: gst_allocation_params_free

`params` : | a GstAllocationParams. [transfer none]
Returns : | a new #GstAllocationParams, free with `gst_allocation_params_free()`. [transfer full]

### gst_allocation_params_free ()

    void                gst_allocation_params_free          (GstAllocationParams *params);

Free `params`

`params` : | a GstAllocationParams. [in][transfer full]

### gst_allocator_alloc ()

    GstMemory *         gst_allocator_alloc                 (GstAllocator *allocator,
                                                             gsize size,
                                                             GstAllocationParams *params);

Use `allocator` to allocate a new memory block with memory that is at least `size` big.

The optional `params` can specify the prefix and padding for the memory. If NULL is passed, no flags, no extra prefix/padding and a default alignment is used.

The prefix/padding will be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

When `allocator` is NULL, the default allocator will be used.

The alignment in `params` is given as a bitmask so that `align` + 1 equals the amount of bytes to align to. For example, to align to 8 bytes, use an alignment of 7.

`allocator` : | a GstAllocator to use. [transfer none][allow-none]
`size` : | size of the visible memory area
`params` : | optional parameters. [transfer none][allow-none]
Returns : | a new GstMemory. [transfer full]

### gst_memory_new_wrapped ()

    GstMemory *         gst_memory_new_wrapped              (GstMemoryFlags flags,
                                                             gpointer data,
                                                             gsize maxsize,
                                                             gsize offset,
                                                             gsize size,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Allocate a new memory block that wraps the given `data`.

The prefix/padding must be filled with 0 if `flags` contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

`flags` : | GstMemoryFlags
`data` : | data to wrap
`maxsize` : | allocated size of `data`
`offset` : | offset in `data`
`size` : | size of valid data
`user_data` : | user_data
`notify` : | called with `user_data` when the memory is freed
Returns : | a new GstMemory.

### gst_memory_ref ()

    GstMemory *         gst_memory_ref                      (GstMemory *mem);

Increases the refcount of `mem`.

`mem` : | a GstMemory
Returns : | `mem` with increased refcount

### gst_memory_unref ()

    void                gst_memory_unref                    (GstMemory *mem);

Decreases the refcount of `mem`. When the refcount reaches 0, the free function of `mem` will be called.

`mem` : | a GstMemory

### gst_memory_is_exclusive ()

    gboolean            gst_memory_is_exclusive             (GstMemory *mem);

Check if the current ref to `mem` is exclusive, this means that no other references exist other than `mem`.

`mem` : | a GstMemory

### gst_memory_get_sizes ()

    gsize               gst_memory_get_sizes                (GstMemory *mem,
                                                             gsize *offset,
                                                             gsize *maxsize);

Get the current `size`, `offset` and `maxsize` of `mem`.

`mem` : | a GstMemory
`offset` : | pointer to offset
`maxsize` : | pointer to maxsize
Returns : | the current sizes of `mem`

### gst_memory_resize ()

    void                gst_memory_resize                   (GstMemory *mem,
                                                             gssize offset,
                                                             gsize size);

Resize the memory region. `mem` should be writable and offset + size should be less than the maxsize of `mem`.

GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED will be cleared when offset or padding is increased respectively.

`mem` : | a GstMemory
`offset` : | a new offset
`size` : | a new size

### gst_memory_make_mapped ()

    GstMemory *         gst_memory_make_mapped              (GstMemory *mem,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);

Create a GstMemory object that is mapped with `flags`. If `mem` is mappable with `flags`, this function returns the mapped `mem` directly. Otherwise a mapped copy of `mem` is returned.

This function takes ownership of old `mem` and returns a reference to a new GstMemory.

`mem` : | a GstMemory. [transfer full]
`info` : | pointer for info. [out]
`flags` : | mapping flags
Returns : | a GstMemory object mapped with `flags` or NULL when a mapping is not possible. [transfer full]

### gst_memory_map ()

    gboolean            gst_memory_map                      (GstMemory *mem,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);

Fill `info` with the pointer and sizes of the memory in `mem` that can be accessed according to `flags`.

This function can return `FALSE` for various reasons:

- the memory backed by `mem` is not accessible with the given `flags`.

- the memory was already mapped with a different mapping.

`info` and its contents remain valid for as long as `mem` is valid and until `gst_memory_unmap()` is called.

For each `gst_memory_map()` call, a corresponding `gst_memory_unmap()` call should be done.

`mem` : | a GstMemory
`info` : | pointer for info. [out]
`flags` : | mapping flags
Returns : | `TRUE` if the map operation was successful.

### gst_memory_unmap ()

    void                gst_memory_unmap                    (GstMemory *mem,
                                                             GstMapInfo *info);

Release the memory obtained with `gst_memory_map()`

`mem` : | a GstMemory
`info` : | a GstMapInfo

### gst_memory_copy ()

    GstMemory *         gst_memory_copy                     (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);

Return a copy of `size` bytes from `mem` starting from `offset`. This copy is guaranteed to be writable. `size` can be set to -1 to return a copy all bytes from `offset`.

`mem` : | a GstMemory
`offset` : | an offset to copy
`size` : | size to copy or -1 to copy all bytes from offset
Returns : | a new GstMemory.

### gst_memory_share ()

    GstMemory *         gst_memory_share                    (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);

Return a shared copy of `size` bytes from `mem` starting from `offset`. No memory copy is performed and the memory region is simply shared. The result is guaranteed to be not-writable. `size` can be set to -1 to return a share all bytes from `offset`.

`mem` : | a GstMemory
`offset` : | an offset to share
`size` : | size to share or -1 to share bytes from offset
Returns : | a new GstMemory.

### gst_memory_is_span ()

    gboolean            gst_memory_is_span                  (GstMemory *mem1,
                                                             GstMemory *mem2,
                                                             gsize *offset);

Check if `mem1` and mem2 share the memory with a common parent memory object and that the memory is contiguous.

If this is the case, the memory of `mem1` and `mem2` can be merged efficiently by performing `gst_memory_share()` on the parent object from the returned `offset`.

`mem1` : | a GstMemory
`mem2` : | a GstMemory
`offset` : | a pointer to a result offset
Returns : | `TRUE` if the memory is contiguous and of a common parent.

## See Also

GstBuffer