Class (GI Struct)

Gst-1.0 ▶ Gst ▶ Buffer

Buffers are the basic unit of data transfer in GStreamer. They contain the timing and offset along with other arbitrary metadata that is associated with the Gst.Memory blocks that the buffer contains.

Buffers are usually created with gst_buffer_new(). After a buffer has been created one will typically allocate memory for it and add it to the buffer. The following example creates a buffer that can hold a given video frame with a given width, height and bits per plane.

  GstBuffer *buffer;
  GstMemory *memory;
  gint size, width, height, bpp;
  ...
  size = width * height * bpp;
  buffer = gst_buffer_new ();
  memory = gst_allocator_alloc (NULL, size, NULL);
  gst_buffer_insert_memory (buffer, -1, memory);
  ...

Alternatively, use gst_buffer_new_allocate() to create a buffer with preallocated data of a given size.

Buffers can contain a list of Gst.Memory objects. You can retrieve how many memory objects with gst_buffer_n_memory() and you can get a pointer to memory with gst_buffer_peek_memory()

A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to #GST_CLOCK_TIME_NONE). Whenever a meaningful value can be given for these, they should be set. The timestamps and duration are measured in nanoseconds (they are Gst.ClockTime values).

The buffer DTS refers to the timestamp when the buffer should be decoded and is usually monotonically increasing. The buffer PTS refers to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing.

A buffer can also have one or both of a start and an end offset. These are media-type specific. For video buffers, the start offset will generally be the frame number. For audio buffers, it will be the number of samples produced so far. For compressed data, it could be the byte offset in a source or destination file. Likewise, the end offset will be the offset of the end of the buffer. These can only be meaningfully interpreted if you know the media type of the buffer (the preceding CAPS event). Either or both can be set to #GST_BUFFER_OFFSET_NONE.

gst_buffer_ref() is used to increase the refcount of a buffer. This must be done when you want to keep a handle to the buffer after pushing it to the next element. The buffer refcount determines the writability of the buffer, a buffer is only writable when the refcount is exactly 1, i.e. when the caller has the only reference to the buffer.

To efficiently create a smaller buffer out of an existing one, you can use gst_buffer_copy_region(). This method tries to share the memory objects between the two buffers.

If a plug-in wants to modify the buffer data or metadata in-place, it should first obtain a buffer that is safe to modify by using gst_buffer_make_writable(). This function is optimized so that a copy will only be made when it is necessary.

Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET() and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test if a certain Gst.BufferFlags flag is set.

Buffers can be efficiently merged into a larger buffer with gst_buffer_append(). Copying of memory will only be done when absolutely needed.

Arbitrary extra metadata can be set on a buffer with gst_buffer_add_meta(). Metadata can be retrieved with gst_buffer_get_meta(). See also Gst.Meta.

An element should either unref the buffer or push it out on a src pad using gst_pad_push() (see Gst.Pad).

Buffers are usually freed by unreffing them with gst_buffer_unref(). When the refcount drops to 0, any memory and metadata pointed to by the buffer is unreffed as well. Buffers allocated from a Gst.BufferPool will be returned to the pool when the refcount drops to 0.

The Gst.ParentBufferMeta is a meta which can be attached to a Gst.Buffer to hold a reference to another buffer that is only released when the child Gst.Buffer is released.

Typically, Gst.ParentBufferMeta is used when the child buffer is directly using the Gst.Memory of the parent buffer, and wants to prevent the parent buffer from being returned to a buffer pool until the Gst.Memory is available for re-use. (Since: 1.6)

Index

Constructors

constructor

Properties

dts duration offset offset_end pool pts $gtype

Methods

add_custom_meta add_meta add_parent_buffer_meta add_protection_meta add_reference_timestamp_meta append append_memory append_region copy_deep copy_into copy_region extract extract_dup fill find_memory foreach_meta get_all_memory get_custom_meta get_flags get_memory get_memory_range get_meta get_n_meta get_reference_timestamp_meta get_size get_sizes get_sizes_range has_flags insert_memory is_all_memory_writable is_memory_range_writable map map_range memcmp memset n_memory peek_memory prepend_memory remove_all_memory remove_memory remove_memory_range remove_meta replace_all_memory replace_memory replace_memory_range resize resize_range set_flags set_size unmap unset_flags get_max_memory new new_allocate new_memdup new_wrapped new_wrapped_bytes new_wrapped_full

Constructors

  • Parameters

    • Optionalproperties: Partial<
          {
              dts: ClockTime;
              duration: ClockTime;
              mini_object: MiniObject;
              offset: number;
              offset_end: number;
              pts: ClockTime;
          },
      >

    Returns Gst.Buffer

Properties

dts: number
duration: number
offset: number
offset_end: number
pool: Gst.BufferPool
pts: number
$gtype: GType<Gst.Buffer>

Methods

  • Appends the memory block mem to buffer. This function takes ownership of mem and thus doesn't increase its refcount.

    This function is identical to gst_buffer_insert_memory() with an index of -1. See gst_buffer_insert_memory() for more details.

    Parameters

    Returns void

  • Appends size bytes at offset from buf2 to buf1. The result buffer will contain a concatenation of the memory of buf1 and the requested region of buf2.

    Parameters

    • buf2: Gst.Buffer

      the second source Gst.Buffer to append.

    • offset: number

      the offset in buf2

    • size: number

      the size or -1 of buf2

    Returns Gst.Buffer

    the new Gst.Buffer that contains the memory of the two source buffers.

  • Creates a copy of the given buffer. This will make a newly allocated copy of the data the source buffer contains.

    Returns Gst.Buffer

    a new copy of buf if the copy succeeded, null otherwise.

  • Copies the information from src into dest.

    If dest already contains memory and flags contains GST_BUFFER_COPY_MEMORY, the memory from src will be appended to dest.

    flags indicate which fields will be copied.

    Parameters

    • src: Gst.Buffer

      a source Gst.Buffer

    • flags: Gst.BufferCopyFlags

      flags indicating what metadata fields should be copied.

    • offset: number

      offset to copy from

    • size: number

      total size to copy. If -1, all data is copied.

    Returns boolean

    true if the copying succeeded, false otherwise.

  • Creates a sub-buffer from parent at offset and size. This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp fields when the offset is 0. If not, they will be set to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. If offset equals 0 and size equals the total size of buffer, the duration and offset end fields are also copied. If not they will be set to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE.

    Parameters

    Returns Gst.Buffer

    the new Gst.Buffer or null if copying failed.

  • Copies size bytes starting from offset in buffer to dest.

    Parameters

    • offset: number

      the offset to extract

    Returns [number, Uint8Array<ArrayBufferLike>]

    The amount of bytes extracted. This value can be lower than size when buffer did not contain enough data.

  • Extracts a copy of at most size bytes the data at offset into newly-allocated memory. dest must be freed using g_free() when done.

    Parameters

    • offset: number

      the offset to extract

    • size: number

      the size to extract

    Returns Uint8Array

  • Copies size bytes from src to buffer at offset.

    Parameters

    • offset: number

      the offset to fill

    • src: string | Uint8Array<ArrayBufferLike>

      the source address

    Returns number

    The amount of bytes copied. This value can be lower than size when buffer did not contain enough data.

  • Finds the memory blocks that span size bytes starting from offset in buffer.

    When this function returns true, idx will contain the index of the first memory block where the byte for offset can be found and length contains the number of memory blocks containing the size remaining bytes. skip contains the number of bytes to skip in the memory block at idx to get to the byte for offset.

    size can be -1 to get all the memory blocks after idx.

    Parameters

    • offset: number

      an offset

    • size: number

      a size

    Returns [boolean, number, number, number]

    true when size bytes starting from offset could be found in buffer and idx, length and skip will be filled.

  • Calls func with user_data for each meta in buffer.

    func can modify the passed meta pointer or its contents. The return value of func defines if this function returns or if the remaining metadata items in the buffer should be skipped.

    Parameters

    Returns boolean

    false when func returned false for one of the metadata.

  • Gets length memory blocks in buffer starting at idx. The memory blocks will be merged into one large Gst.Memory.

    If length is -1, all memory starting from idx is merged.

    Parameters

    • idx: number

      an index

    • length: number

      a length

    Returns Memory

    a Gst.Memory that contains the merged data of length blocks starting at idx.

  • Gets the metadata for api on buffer. When there is no such metadata, null is returned. If multiple metadata with the given api are attached to this buffer only the first one is returned. To handle multiple metadata with a given API use gst_buffer_iterate_meta() or gst_buffer_foreach_meta() instead and check the meta->info.api member for the API type.

    Parameters

    Returns Meta

    the metadata for api on buffer.

  • Gets the total size of the memory blocks in buffer.

    Returns number

    total size of the memory blocks in buffer.

  • Gets the total size of the memory blocks in buffer.

    When not null, offset will contain the offset of the data in the first memory block in buffer and maxsize will contain the sum of the size and offset and the amount of extra padding on the last memory block. offset and maxsize can be used to resize the buffer memory blocks with gst_buffer_resize().

    Returns [number, number, number]

    total size of the memory blocks in buffer.

  • Gets the total size of length memory blocks stating from idx in buffer.

    When not null, offset will contain the offset of the data in the memory block in buffer at idx and maxsize will contain the sum of the size and offset and the amount of extra padding on the memory block at idx + length -1. offset and maxsize can be used to resize the buffer memory blocks with gst_buffer_resize_range().

    Parameters

    • idx: number

      an index

    • length: number

      a length

    Returns [number, number, number]

    total size of length memory blocks starting at idx in buffer.

  • Inserts the memory block mem into buffer at idx. This function takes ownership of mem and thus doesn't increase its refcount.

    Only gst_buffer_get_max_memory() can be added to a buffer. If more memory is added, existing memory blocks will automatically be merged to make room for the new memory.

    Parameters

    • idx: number

      the index to add the memory at, or -1 to append it to the end

    • mem: Memory

      a Gst.Memory.

    Returns void

  • Checks if all memory blocks in buffer are writable.

    Note that this function does not check if buffer is writable, use gst_buffer_is_writable() to check that if needed.

    Returns boolean

    true if all memory blocks in buffer are writable

  • Checks if length memory blocks in buffer starting from idx are writable.

    length can be -1 to check all the memory blocks after idx.

    Note that this function does not check if buffer is writable, use gst_buffer_is_writable() to check that if needed.

    Parameters

    • idx: number

      an index

    • length: number

      a length, should not be 0

    Returns boolean

    true if the memory range is writable

  • Fills info with the Gst.MapInfo of all merged memory blocks in buffer.

    flags describe the desired access of the memory. When flags is #GST_MAP_WRITE, buffer should be writable (as returned from gst_buffer_is_writable()).

    When buffer is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

    The memory in info should be unmapped with gst_buffer_unmap() after usage.

    Parameters

    Returns [boolean, MapInfo]

    true if the map succeeded and info contains valid data.

  • Fills info with the Gst.MapInfo of length merged memory blocks starting at idx in buffer. When length is -1, all memory blocks starting from idx are merged and mapped.

    flags describe the desired access of the memory. When flags is #GST_MAP_WRITE, buffer should be writable (as returned from gst_buffer_is_writable()).

    When buffer is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

    The memory in info should be unmapped with gst_buffer_unmap() after usage.

    Parameters

    • idx: number

      an index

    • length: number

      a length

    • flags: Gst.MapFlags

      flags for the mapping

    Returns [boolean, MapInfo]

    true if the map succeeded and info contains valid data.

  • Compares size bytes starting from offset in buffer with the memory in mem.

    Parameters

    • offset: number

      the offset in buffer

    • mem: string | Uint8Array<ArrayBufferLike>

      the memory to compare

    Returns number

    0 if the memory is equal.

  • Fills buf with size bytes with val starting from offset.

    Parameters

    • offset: number

      the offset in buffer

    • val: number

      the value to set

    • size: number

      the size to set

    Returns number

    The amount of bytes filled. This value can be lower than size when buffer did not contain enough data.

  • Gets the amount of memory blocks that this buffer has. This amount is never larger than what gst_buffer_get_max_memory() returns.

    Returns number

    the number of memory blocks this buffer is made of.

  • Gets the memory block at idx in buffer. The memory block stays valid until the memory block in buffer is removed, replaced or merged, typically with any call that modifies the memory in buffer.

    Parameters

    • idx: number

      an index

    Returns Memory

    the Gst.Memory at idx.

  • Prepends the memory block mem to buffer. This function takes ownership of mem and thus doesn't increase its refcount.

    This function is identical to gst_buffer_insert_memory() with an index of 0. See gst_buffer_insert_memory() for more details.

    Parameters

    Returns void

  • Removes the memory block in b at index i.

    Parameters

    • idx: number

      an index

    Returns void

  • Removes length memory blocks in buffer starting from idx.

    length can be -1, in which case all memory starting from idx is removed.

    Parameters

    • idx: number

      an index

    • length: number

      a length

    Returns void

  • Removes the metadata for meta on buffer.

    Parameters

    Returns boolean

    true if the metadata existed and was removed, false if no such metadata was on buffer.

  • Replaces length memory blocks in buffer starting at idx with mem.

    If length is -1, all memory starting from idx will be removed and replaced with mem.

    buffer should be writable.

    Parameters

    • idx: number

      an index

    • length: number

      a length, should not be 0

    • mem: Memory

      a Gst.Memory

    Returns void

  • Sets the offset and total size of the memory blocks in buffer.

    Parameters

    • offset: number

      the offset adjustment

    • size: number

      the new size or -1 to just adjust the offset

    Returns void

  • Sets the total size of the length memory blocks starting at idx in buffer

    Parameters

    • idx: number

      an index

    • length: number

      a length

    • offset: number

      the offset adjustment

    • size: number

      the new size or -1 to just adjust the offset

    Returns boolean

    true if resizing succeeded, false otherwise.

  • Sets the total size of the memory blocks in buffer.

    Parameters

    • size: number

      the new size

    Returns void

  • Gets the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function.

    When more memory blocks are added, existing memory blocks will be merged together to make room for the new block.

    Returns number