gstreamermm: Gst::Memory Class Reference

gstreamermm 1.10.0

Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gst::Memory Class Reference

GstMemory is a lightweight refcounted object that wraps a region of memory. More...

`#include <gstreamermm/memory.h>`

Inheritance diagram for Gst::Memory:
[legend]

## Public Member Functions
void | reference () const
| Increment the reference count for this object. More...
void | unreference () const
| Decrement the reference count for this object. More...
GstMemory* | gobj ()
| Provides access to the underlying C instance. More...
const GstMemory* | gobj () const
| Provides access to the underlying C instance. More...
GstMemory* | gobj_copy () const
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
| Memory ()=delete
| Memory (const Memory&)=delete
Memory& | operator= (const Memory&)=delete
gsize | get_maxsize () const
| Get the maximum size allocated. More...
gsize | get_align () const
| Get the alignment of the memory. More...
gsize | get_offset () const
| Get the offset where valid data starts. More...
gsize | get_size () const
| Get the size of valid data. More...
Glib::RefPtr< Gst::Memory > | get_parent ()
| Get parent memory block. More...
Glib::RefPtr< const Gst::Memory > | get_parent () const
Glib::RefPtr< Gst::Allocator > | get_allocator ()
| Get the Gst::Allocator. More...
Glib::RefPtr< const Gst::Allocator > | get_allocator () const
bool | is_type (const Glib::ustring& mem_type) const
| Check if mem if allocated with an allocator for mem_type. More...
Glib::RefPtr< Gst::Memory > | share (gssize offset, gssize size)
| Return a shared copy of size bytes from mem starting from offset. More...
void | resize (gssize offset, gsize size)
| Resize the memory region. More...
bool | is_span (const Glib::RefPtr< Gst::Memory >& mem2, gsize& offset)
| Check if mem1 and mem2 share the memory with a common parent memory object and that the memory is contiguous. More...
bool | map (Gst::MapInfo& info, Gst::MapFlags flags)
| Fill info with the pointer and sizes of the memory in mem that can be accessed according to flags. More...
void | unmap (Gst::MapInfo& info)
| Release the memory obtained with map() More...
Glib::RefPtr< Gst::Memory > | copy (gssize offset, gssize size)
| Return a copy of size bytes from mem starting from offset. More...
void | init (Gst::MemoryFlags flags, const Glib::RefPtr< Gst::Allocator >& allocator, const Glib::RefPtr< Gst::Memory >& parent, gsize maxsize, gsize align, gsize offset, gsize size)
| Initializes a newly allocated mem with the given parameters. More...
gsize | get_sizes (gsize& offset, gsize& maxsize)
| Get the current size, offset and maxsize of mem. More...
Glib::RefPtr< Gst::Memory > | make_mapped (Gst::MapInfo& info, Gst::MapFlags flags)
| Create a Gst::Memory object that is mapped with flags. More...
Public Member Functions inherited from Gst::MiniObject
void | reference () const
| Increment the reference count for this object. More...
void | unreference () const
| Decrement the reference count for this object. More...
GstMiniObject* | gobj ()
| Provides access to the underlying C instance. More...
const GstMiniObject* | gobj () const
| Provides access to the underlying C instance. More...
GstMiniObject* | gobj_copy () const
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
| MiniObject ()=delete
| MiniObject (const MiniObject&)=delete
MiniObject& | operator= (const MiniObject&)=delete
| ~MiniObject ()
guint | get_flags () const
void | set_flags (const guint& value)
gint | get_refcount () const
gint | get_lockstate () const
bool | lock (LockFlags flags)
| Lock the mini-object with the specified access mode in flags. More...
void | unlock (LockFlags flags)
| Unlock the mini-object with the specified access mode in flags. More...
bool | is_writable () const
| If mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE lock on object is the only one, this means that changes to the object will not be visible to any other object. More...
Glib::RefPtr< MiniObject > | create_writable ()
| Checks if a mini-object is writable. More...
void | set_qdata (GQuark quark, QuarkData* data)
| This sets an opaque, named pointer on a miniobject. More...
QuarkData* | get_qdata (GQuark quark) const
| This function gets back user data pointers stored via set_qdata(). More...
QuarkData* | steal_qdata (GQuark quark)
| This function gets back user data pointers stored via set_qdata() and removes the data from object without invoking its destroy() function (if any was set). More...
void | add_finalize_notifier (const SlotFinalizer& slot)
| Adds notifier when mini object is finalized. More...
void | remove_finalize_notifier ()
| Remove finalize notifier. More...

## Static Public Member Functions
static Glib::RefPtr< Memory > | create (Gst::MemoryFlags flags, gpointer data, gsize maxsize, gsize offset, gsize size)

## Protected Member Functions
void | operator delete (void*, std::size_t)
Protected Member Functions inherited from Gst::MiniObject
void | operator delete (void*, std::size_t)

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gst::Memory > | wrap (GstMemory* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...
Related Functions inherited from Gst::MiniObject
Glib::RefPtr< Gst::MiniObject > | wrap (GstMiniObject* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Additional Inherited Members
Public Types inherited from Gst::MiniObject
typedef sigc::slot< void > | SlotFinalizer

## Detailed Description

GstMemory is a lightweight refcounted object that wraps a region of memory.

They are typically used to manage the data of a Gst::Buffer.

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.

New memory can be created with Gst::Memory::create() that wraps the memory allocated elsewhere.

The size of the memory can be retrieved and changed with get_sizes() and resize() respectively.

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

Memory can be copied with copy(), which will return a writable copy. 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 is_span() returns TRUE.

Last reviewed on 2016-06-05 (1.8.0)

## Constructor & Destructor Documentation

## ◆ Memory() [1/2]

Gst::Memory::Memory | ( |  | ) |
| delete

## ◆ Memory() [2/2]

Gst::Memory::Memory | ( | const Memory& |  | ) |
| delete

## Member Function Documentation

## ◆ copy()

Glib::RefPtr<Gst::Memory> Gst::Memory::copy | ( | 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 from offset to the end of the memory region.

Parameters

  offset | Offset to copy from.
  size | Size to copy, or -1 to copy to the end of the memory region.

Returns
  A new Gst::Memory.

## ◆ create()

static Glib::RefPtr<Memory> Gst::Memory::create | ( | Gst::MemoryFlags | flags,
|  | gpointer | data,
|  | gsize | maxsize,
|  | gsize | offset,
|  | gsize | size
| ) |  |
| static

## ◆ get_align()

gsize Gst::Memory::get_align | ( |  | ) | const

Get the alignment of the memory.

## ◆ get_allocator() [1/2]

Glib::RefPtr<Gst::Allocator> Gst::Memory::get_allocator | ( |  | ) |

Get the Gst::Allocator.

## ◆ get_allocator() [2/2]

Glib::RefPtr<const Gst::Allocator> Gst::Memory::get_allocator | ( |  | ) | const

## ◆ get_maxsize()

gsize Gst::Memory::get_maxsize | ( |  | ) | const

Get the maximum size allocated.

## ◆ get_offset()

gsize Gst::Memory::get_offset | ( |  | ) | const

Get the offset where valid data starts.

## ◆ get_parent() [1/2]

Glib::RefPtr<Gst::Memory> Gst::Memory::get_parent | ( |  | ) |

Get parent memory block.

## ◆ get_parent() [2/2]

Glib::RefPtr<const Gst::Memory> Gst::Memory::get_parent | ( |  | ) | const

## ◆ get_size()

gsize Gst::Memory::get_size | ( |  | ) | const

Get the size of valid data.

## ◆ get_sizes()

gsize Gst::Memory::get_sizes | ( | gsize & | offset,
|  | gsize & | maxsize
| ) |  |

Get the current size, offset and maxsize of mem.

Parameters

  offset | Pointer to offset.
  maxsize | Pointer to maxsize.

Returns
  The current sizes of mem.

## ◆ gobj() [1/2]

GstMemory* Gst::Memory::gobj | ( |  | ) |

Provides access to the underlying C instance.

## ◆ gobj() [2/2]

const GstMemory* Gst::Memory::gobj | ( |  | ) | const

Provides access to the underlying C instance.

## ◆ gobj_copy()

GstMemory* Gst::Memory::gobj_copy | ( |  | ) | const

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ init()

void Gst::Memory::init | ( | Gst::MemoryFlags | flags,
|  | const Glib::RefPtr< Gst::Allocator >& | allocator,
|  | const Glib::RefPtr< Gst::Memory >& | parent,
|  | gsize | maxsize,
|  | gsize | align,
|  | gsize | offset,
|  | gsize | size
| ) |  |

Initializes a newly allocated mem with the given parameters.

This function will call Gst::MiniObject::init() with the default memory parameters.

Parameters

  flags | Gst::MemoryFlags.
  allocator | The Gst::Allocator.
  parent | The parent of mem.
  maxsize | The total size of the memory.
  align | The alignment of the memory.
  offset | The offset in the memory.
  size | The size of valid data in the memory.

## ◆ is_span()

bool Gst::Memory::is_span | ( | const Glib::RefPtr< Gst::Memory >& | 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 share() on the parent object from the returned offset.

Parameters

  mem2 | A Gst::Memory.
  offset | A pointer to a result offset.

Returns
  `true` if the memory is contiguous and of a common parent.

## ◆ is_type()

bool Gst::Memory::is_type | ( | const Glib::ustring & | mem_type | ) | const

Check if mem if allocated with an allocator for mem_type.

Parameters

  mem_type | A memory type.

Returns
  `true` if mem was allocated from an allocator for mem_type.

## ◆ make_mapped()

Glib::RefPtr<Gst::Memory> Gst::Memory::make_mapped | ( | Gst::MapInfo& | info,
|  | Gst::MapFlags | flags
| ) |  |

Create a Gst::Memory 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.

Parameters

  info | Pointer for info.
  flags | Mapping flags.

Returns
  a Gst::Memory object mapped.

## ◆ map()

bool Gst::Memory::map | ( | Gst::MapInfo& | info,
|  | Gst::MapFlags | 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 unmap() is called.

For each map() call, a corresponding unmap() call should be done.

Parameters

  info | Pointer for info.
  flags | Mapping flags.

Returns
  `true` if the map operation was successful.

## ◆ operator delete()

void Gst::Memory::operator delete | ( | void * | ,
|  | std::size_t |
| ) |  |
| protected

## ◆ operator=()

Memory& Gst::Memory::operator= | ( | const Memory& |  | ) |
| delete

## ◆ reference()

void Gst::Memory::reference | ( |  | ) | const

Increment the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

## ◆ resize()

void Gst::Memory::resize | ( | 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.

Parameters

  offset | A new offset.
  size | A new size.

## ◆ share()

Glib::RefPtr<Gst::Memory> Gst::Memory::share | ( | 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 non-writable. size can be set to -1 to return a shared copy from offset to the end of the memory region.

Parameters

  offset | Offset to share from.
  size | Size to share, or -1 to share to the end of the memory region.

Returns
  A new Gst::Memory.

## ◆ unmap()

void Gst::Memory::unmap | ( | Gst::MapInfo& | info | ) |

Release the memory obtained with map()

Parameters

  info | A Gst::MapInfo.

## ◆ unreference()

void Gst::Memory::unreference | ( |  | ) | const

Decrement the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

## Friends And Related Function Documentation

## ◆ wrap()

Glib::RefPtr< Gst::Memory > wrap | ( | GstMemory * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.